backtest2live 0.2.0__py3-none-any.whl

backtest2live/fillgap/sim.py

@@ -0,0 +1,192 @@
+"""Queue-proxy fill simulation for resting limit orders on L1 book + trade prints.
+
+Deterministic, numpy only. All times are int64 microseconds; all prices are
+int64 ticks. Buy logic is written once: sell orders are mirrored by negating
+prices, so "the bid" is the order's own side and "below P" means through it.
+
+Per order, in the window (active, end]:
+  - marketable: the limit crosses the opposite touch at arrival. A taker
+    order, out of scope for the maker comparison.
+  - queue ahead: 0 if the order improves the touch; the displayed size if it
+    joins the touch; if it rests behind the touch, the displayed size when the
+    touch first reaches its price (0 if the touch jumps past it).
+  - proxy fill: passive-side volume printed at exactly its price reaches
+    queue ahead + own size, or a passive-side trade prints through its price.
+  - touch fill (the naive backtest rule): any passive-side print at or
+    through its price after arrival.
+"""
+
+import numpy as np
+
+# status codes
+NO_DATA, MARKETABLE, NEVER_REACHED, ACTIVE = 0, 1, 2, 3
+STATUS_NAMES = {NO_DATA: "no_data", MARKETABLE: "marketable",
+                NEVER_REACHED: "never_reached", ACTIVE: "active"}
+
+
+def _side_arrays(book, trades, buy):
+    s = 1 if buy else -1
+    own_px = book["bid_px"] if buy else -book["ask_px"]
+    own_qty = book["bid_qty"] if buy else book["ask_qty"]
+    opp_px = book["ask_px"] if buy else -book["bid_px"]
+    # A resting buy is hit by aggressive sells, a resting sell by aggressive buys.
+    hit = trades["sell_aggr"] if buy else ~trades["sell_aggr"]
+    return own_px, own_qty, opp_px, trades["t"][hit], s * trades["px"][hit], trades["qty"][hit]
+
+
+def _first_through(ht, hp, t_from, t_to, P, idx):
+    """For orders idx: time of the first hit trade with price < P in (t_from, t_to], else -1."""
+    out = np.full(len(P), -1, dtype=np.int64)
+    a = np.searchsorted(ht, t_from, "right")
+    b = np.searchsorted(ht, t_to, "right")
+    for j in idx:
+        if b[j] <= a[j]:
+            continue
+        seg = hp[a[j]:b[j]]
+        m = seg < P[j]
+        if m.any():
+            out[j] = ht[a[j] + int(m.argmax())]
+    return out
+
+
+def simulate_side(book, trades, t_arr, t_end, P_raw, size, buy):
+    """Simulate orders of one side. Returns dict of per-order arrays."""
+    n = len(t_arr)
+    own_px, own_qty, opp_px, ht, hp, hq = _side_arrays(book, trades, buy)
+    P = P_raw if buy else -P_raw
+    bt = book["t"]
+
+    status = np.full(n, NO_DATA, dtype=np.int8)
+    queue = np.zeros(n, dtype=np.float64)
+    t_act = np.full(n, -1, dtype=np.int64)
+
+    i = np.searchsorted(bt, t_arr, "right") - 1
+    covered = (i >= 0) & (t_arr <= bt[-1]) & (t_end >= t_arr) if len(bt) else np.zeros(n, bool)
+    ic = np.clip(i, 0, max(len(bt) - 1, 0))
+
+    marketable = covered & (P >= opp_px[ic])
+    improve = covered & ~marketable & (P > own_px[ic])
+    at_touch = covered & ~marketable & (P == own_px[ic])
+    behind = covered & ~marketable & (P < own_px[ic])
+
+    status[marketable] = MARKETABLE
+    status[improve | at_touch] = ACTIVE
+    t_act[improve | at_touch] = t_arr[improve | at_touch]
+    queue[at_touch] = own_qty[ic[at_touch]]
+
+    # Behind the touch: wait until the touch comes to the order's price.
+    i_end = np.searchsorted(bt, t_end, "right") - 1
+    status[behind] = NEVER_REACHED
+    for j in np.flatnonzero(behind):
+        seg = own_px[ic[j] + 1:i_end[j] + 1]
+        m = seg <= P[j]
+        if m.any():
+            k = ic[j] + 1 + int(m.argmax())
+            status[j] = ACTIVE
+            t_act[j] = bt[k]
+            queue[j] = own_qty[k] if own_px[k] == P[j] else 0.0
+
+    active = status == ACTIVE
+    live = covered & ~marketable
+    idx_live = np.flatnonzero(live)
+
+    # --- volume printed at exactly P, sorted by (price, time) ---
+    t_fill_at = np.full(n, -1, dtype=np.int64)
+    t_touch_at = np.full(n, -1, dtype=np.int64)
+    if len(ht):
+        t0 = min(int(ht.min()), int(t_arr.min())) - 1
+        span = max(int(ht.max()), int(t_end.max())) - t0 + 2
+        B = 1 << int(span).bit_length()
+        pmin = min(int(hp.min()), int(P.min()))
+        pmax = max(int(hp.max()), int(P.max()))
+        if (pmax - pmin + 1) * B >= (1 << 62):
+            raise SystemExit("error: price range × time span too large for one pass; split the input by day")
+        key = (hp - pmin) * B + (ht - t0)
+        o = np.argsort(key, kind="stable")
+        key, ts, cs = key[o], ht[o], np.r_[0.0, np.cumsum(hq[o])]
+        base = (P - pmin) * B - t0
+
+        # touch rule: any print at P after arrival
+        lo_n = np.searchsorted(key, base + t_arr, "right")
+        hi = np.searchsorted(key, base + t_end, "right")
+        has = live & (hi > lo_n)
+        t_touch_at[has] = ts[lo_n[has]]
+
+        # proxy: cumulative volume at P after activation covers queue + own size
+        ta = np.where(active, t_act, t_end)
+        lo = np.searchsorted(key, base + ta, "right")
+        k = np.searchsorted(cs, cs[lo] + queue + size - 1e-12, "left")
+        ok = active & (k > lo) & (k <= hi)
+        t_fill_at[ok] = ts[k[ok] - 1]
+
+    # --- prints through P (the level was cleared) ---
+    t_through = _first_through(ht, hp, t_arr, t_end, P, idx_live)
+
+    def first(a, b):
+        both = (a >= 0) & (b >= 0)
+        return np.where(both, np.minimum(a, b), np.maximum(a, b))
+
+    t_touch = first(t_touch_at, t_through)
+    # A print through P clears every order resting at P since arrival, so the
+    # through leg applies from t_arr, also to orders the book never showed at
+    # the touch (the sweep and the book row can share a ms, or the print can
+    # lead the row).
+    t_through_proxy = np.where(live, t_through, -1)
+    t_proxy = first(t_fill_at, t_through_proxy)
+    status[(status == NEVER_REACHED) & (t_proxy >= 0)] = ACTIVE
+
+    return {"status": status, "queue": queue, "t_act": t_act,
+            "touch": t_touch >= 0, "t_touch": t_touch,
+            "proxy": t_proxy >= 0, "t_proxy": t_proxy}
+
+
+def simulate(book, trades, orders, latency_us=0):
+    """orders: dict t, t_end, buy (bool), px (ticks), size. Returns per-order arrays in input order."""
+    n = len(orders["t"])
+    out = {
+        "status": np.zeros(n, np.int8), "queue": np.zeros(n), "t_act": np.full(n, -1, np.int64),
+        "touch": np.zeros(n, bool), "t_touch": np.full(n, -1, np.int64),
+        "proxy": np.zeros(n, bool), "t_proxy": np.full(n, -1, np.int64),
+    }
+    t_arr = orders["t"] + int(latency_us)
+    for buy in (True, False):
+        m = orders["buy"] == buy
+        if not m.any():
+            continue
+        r = simulate_side(book, trades, t_arr[m], orders["t_end"][m], orders["px"][m],
+                          orders["size"][m], buy)
+        for k, v in r.items():
+            out[k][m] = v
+    out["t_arr"] = t_arr
+    return out
+
+
+def trailing_range_bps(book, t_query, window_us=300_000_000, bin_us=60_000_000):
+    """Trailing realized range of the mid (max-min over the previous 5 one-minute bins, bps of the min)."""
+    bt = book["t"]
+    mid = (book["bid_px"] + book["ask_px"]) / 2.0
+    t0 = bt[0]
+    b = (bt - t0) // bin_us
+    nb = int(b[-1]) + 1
+    mx = np.full(nb, np.nan)
+    mn = np.full(nb, np.nan)
+    np.fmax.at(mx, b, mid)
+    np.fmin.at(mn, b, mid)
+    # carry the last value through empty bins
+    for arr in (mx, mn):
+        idx = np.where(np.isnan(arr), 0, np.arange(nb))
+        np.maximum.accumulate(idx, out=idx)
+        arr[:] = arr[idx]
+    w = int(window_us // bin_us)
+    rmx, rmn = _rolling(mx, w, np.fmax), _rolling(mn, w, np.fmin)
+    rng = (rmx - rmn) / rmn * 1e4
+    q = np.clip((t_query - t0) // bin_us - 1, 0, nb - 1)  # the window before the order
+    return np.where(t_query >= t0, rng[q], np.nan)
+
+
+def _rolling(a, w, f):
+    """Trailing w-bin reduction: out[i] = f over a[i-w+1..i]."""
+    out = a.copy()
+    for s in range(1, w):
+        out[s:] = f(out[s:], a[:-s])
+    return out

backtest2live-0.2.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: backtest2live
+Version: 0.2.0
+Summary: Check a backtest against what live execution would do: convergence, fill-gap, and more, run locally.
+Project-URL: Homepage, https://martianmobile.com
+Project-URL: Source, https://github.com/martianmobile/backtest2live
+Project-URL: Issues, https://github.com/martianmobile/backtest2live/issues
+Author-email: Martian Mobile <martin@martianmobile.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtest,execution,fill-rate,overfitting,quant,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Provides-Extra: data
+Requires-Dist: numpy>=1.23; extra == 'data'
+Requires-Dist: pandas>=1.5; extra == 'data'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# backtest2live
+
+[![CI](https://github.com/martianmobile/backtest2live/actions/workflows/ci.yml/badge.svg)](https://github.com/martianmobile/backtest2live/actions/workflows/ci.yml)
+
+**Check a backtest against what live execution would do.** Evaluators run locally on your own files and public data, and each one returns a verdict with the numbers behind it.
+
+Use it three ways: as a Python CLI (`bt2live`), as a library, or as a Claude Code plugin where the agent runs the CLI and interprets the verdict.
+
+This is the public, MIT-licensed version of checks used in live crypto trading research at [Martian Mobile](https://martianmobile.com).
+
+---
+
+## Evaluators
+
+| Command | Status | What it does |
+|---------|--------|--------------|
+| **`bt2live convergence`** | shipped | Read a variant parameter sweep → measure dispersion, IS/OOS rank stability, and parameter-plateau structure → verdict: **CONVERGED / ITERATE / KILL**. |
+| **`bt2live fill-gap`** | shipped | Re-run your backtest's resting orders under a queue proxy on top-of-book and trades → your fill rate vs the proxy's: **CONSISTENT / OVERSTATED**. |
+
+Roadmap: [ROADMAP.md](ROADMAP.md) and the [milestones](https://github.com/martianmobile/backtest2live/milestones).
+
+---
+
+## Install
+
+```bash
+pip install backtest2live
+```
+
+The core has no runtime dependencies (Python 3.9+). `fill-gap` needs numpy and pandas:
+
+```bash
+pip install 'backtest2live[data]'
+```
+
+**Claude Code plugin.** This repo is also a plugin marketplace. From inside Claude Code:
+
+```
+/plugin marketplace add martianmobile/backtest2live
+/plugin install backtest2live@martianmobile
+```
+
+Then ask *"are these variants converged?"* or run `/convergence results.csv --metric sharpe_oos`. The skill installs the CLI if it is missing.
+
+---
+
+## `fill-gap`: do your backtest's passive fills survive a queue?
+
+A backtest that fills a resting order whenever price touches it counts fills a live order would never get: the order sits behind the queue already displayed at that price. `fill-gap` re-runs each resting order in your order log against top-of-book and trade prints, and grants a fill only when:
+
+- the volume printed at exactly your price, after you joined, covers the queue ahead of you plus your own size, or
+- a trade prints through your price, which means the level was cleared.
+
+```bash
+bt2live fill-gap examples/orders_btcusdt_2024-03-30.csv --venue binance-um --pair BTCUSDT
+```
+
+```
+## Verdict: OVERSTATED
+
+**Your backtest fills 95.2% of its resting orders; the queue proxy fills 66.2%.
+30.4% of the counted fills (834 of 2,740) are not granted on this data.**
+```
+
+The report continues with fill rates by rule, median time to fill, misses by volatility tercile and by UTC hour, and P&L on missed fills if your log has a `pnl` column. `--json` gives the same result machine-readable. Exit code: `0` CONSISTENT, `1` OVERSTATED (more than `--tolerance`, default 10%, of your fills not granted), `3` error.
+
+### Your order log
+
+CSV, one row per order. Column names are matched case-insensitively:
+
+| Role | Accepted names | Required |
+|------|----------------|----------|
+| time | `ts`, `timestamp`, `time`, `datetime`, `created_at` | yes (epoch s/ms/µs/ns or ISO-8601, UTC) |
+| side | `side` (`buy`/`sell`) | yes |
+| price | `price`, `px`, `limit_price` | yes |
+| size | `size`, `qty`, `quantity`, `amount` | yes (base units) |
+| backtest's fill | `filled` (true/false, 1/0) or `fill_qty` | no: without it, the touch rule is the baseline |
+| end of life | `end_ts`, `cancel_ts`, `expire_ts` | no: default `--max-rest 60` seconds |
+| P&L | `pnl` | no |
+| id | `order_id` | no |
+
+Orders marketable at arrival are taker orders and are skipped. `--latency-ms` delays every order's arrival at the book.
+
+### Market data
+
+- **`--venue binance-um --pair BTCUSDT`** downloads Binance's public USDT-M futures archive (`bookTicker` + `aggTrades`) for the days your orders cover, checks the published SHA-256, and caches it under `~/.cache/backtest2live` (`BT2LIVE_CACHE` overrides). About 100 MB per day for BTCUSDT. Binance stopped publishing `bookTicker` after **2024-03-30**, so this source covers orders up to that day.
+- **`--book l1.csv --trades trades.csv`** uses your own recorded data, any venue and any date. Book: `ts, bid_px, bid_qty, ask_px, ask_qty` (every change of the best bid/ask). Trades: `ts, price, qty` plus `is_buyer_maker` (true when a seller hit the bid) or the taker's `side`.
+
+### What the proxy cannot see
+
+The touch rule is an upper bound: a resting order fills only if something trades at or through its price. The proxy is an estimate below it. Hidden size, your latency and your own impact make it too generous. Cancels ahead of you, and a queue position read from the size shown when the price reached you, make it too strict. How that nets out depends on venue, size and regime. Only your own live fills settle it; [Martian Mobile](https://martianmobile.com/fill-autopsy?utm_source=github&utm_medium=readme&utm_campaign=fill-gap) runs that check against live fills.
+
+---
+
+## `convergence`: has your variant sweep converged?
+
+Given one row per variant (parameters + metrics), it measures:
+
+- **Top-K dispersion** — are the best variants clustered, or is one a lucky outlier?
+- **IS↔OOS rank stability** — does the in-sample ordering survive out-of-sample? (Spearman)
+- **Parameter-space structure** — do winners sit on a plateau, or are they isolated points (overfit)? Is the best variant pinned to the edge of the swept range?
+- **Sample sufficiency** — are any top variants below a trade-count floor?
+
+…then returns a verdict:
+
+| Verdict | Meaning |
+|---------|---------|
+| **CONVERGED** | Tight, OOS-stable, plateau region. Ship the representative variant. |
+| **ITERATE** | Some criteria unmet (edge peak, weak stability, high dispersion). Suggested next sweep included. |
+| **KILL** | No stable edge — IS doesn't survive OOS, or best ≈ median. Abandon or rethink. |
+
+---
+
+### Usage
+
+```bash
+bt2live convergence examples/results_converged.csv --metric sharpe_oos
+bt2live convergence examples/results_converged.csv --json    # machine-readable verdict
+python -m backtest2live convergence results.csv              # same, without the script shim
+```
+
+Exit code encodes the verdict: `0` CONVERGED · `1` ITERATE · `2` KILL · `3` error (bad input or usage), so a CI job can gate on it.
+
+### Input format
+
+A CSV with one row per variant:
+
+```
+variant_id, lookback, threshold, sharpe_is, sharpe_oos, n_trades
+v001, 20, 0.5, 1.82, 1.61, 412
+v002, 25, 0.5, 1.85, 1.58, 401
+...
+```
+
+Column roles are inferred from names/types. IS/OOS pairs are detected by suffix (`_is`/`_oos`, `_in`/`_out`, `_train`/`_test`). For Parquet/SQLite, export to CSV first.
+
+### Flags
+
+| Flag | Default | Purpose |
+|------|---------|---------|
+| `--metric` | auto | Ranking metric column |
+| `--top-k` | 5 | Top variants to assess |
+| `--dispersion-threshold` | 0.05 | Max relative dispersion for CONVERGED |
+| `--min-samples` | 200 | Sample floor per variant |
+| `--rank-threshold` | 0.6 | Min IS/OOS Spearman for CONVERGED |
+| `--lower-is-better` / `--higher-is-better` | auto | Metric direction override |
+| `--id-column` / `--sample-column` | auto | Column-role overrides |
+| `--save` | off | Also write `iteration_check_<timestamp>.md` in the current directory |
+| `--json` | off | Print the verdict and numbers as JSON instead of Markdown |
+
+---
+
+### Example output
+
+```
+# Iteration Check | results_converged.csv | 2026-06-06
+
+## Verdict: CONVERGED
+
+**Top-5 cluster tightly (1.7% dispersion) on a parameter plateau, OOS-stable (ρ=0.99) — ship `v10`.**
+
+## Convergence Analysis
+| Metric             | Top-K Mean | Top-K Std | Dispersion | Threshold |
+|--------------------|-----------|-----------|------------|-----------|
+| sharpe_oos (rank)  | 1.58      | 0.03      | 1.7%       | < 5% ✓    |
+| sharpe_is          | 1.82      | 0.02      | 1.3%       | < 5% ✓    |
+
+IS→OOS rank stability (Spearman): 0.99 (threshold > 0.60 ✓)
+
+## Parameter-Space Check
+- lookback: top-K at [20, 25, 30] — contiguous
+- threshold: top-K at [0.5, 0.6] — contiguous
+[x] Plateau region — robust, safe to deploy
+```
+
+---
+
+## Limitations
+
+- **Not a backtester.** It analyzes results you already have; it does not run strategies.
+- **Not a live monitor.** Research-phase tooling — live trading needs different rails.
+- **Metric-agnostic, not metric-smart.** It checks dispersion of whatever metric you point at; it doesn't know whether that metric is the right one.
+- **Convergence ≠ profit.** Convergent variants can converge on losing strategies. The verdict reports convergence, not edge.
+
+---
+
+## Why this exists
+
+In real quant research, the failure mode isn't running too few backtests — it's calling one lucky variant a "winner" when its neighbors perform completely differently. Convergence-across-variants is the only honest signal that the parameter region has structure. This tool enforces the discipline — and gives the same treatment to the other ways a strategy can look better than it is.
+
+---
+
+Built by [Martian Mobile](https://martianmobile.com). MIT licensed — see [LICENSE](LICENSE).

backtest2live-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+backtest2live/__init__.py,sha256=GpgnZ13hfLQ0ucK96cdrUkA2qEMhYMMGCd5Csu5l-no,408
+backtest2live/__main__.py,sha256=YE-HyD3F1x67BzDT-6eyjmLYEXdxApdz5Tn2TsGsqr0,65
+backtest2live/cli.py,sha256=y2vMzHu_1atKrbGZd9ySTxlIyyd-9hX1QKpP6tWZuQ0,2166
+backtest2live/convergence.py,sha256=D2d-FX2hvUM0rBMIKo46cknwvHJKt4oZory1vbOsCIk,22555
+backtest2live/fillgap/__init__.py,sha256=EvESvauiip1wA0l4QH-we-hffgymTl--YnHiYmdSopw,2923
+backtest2live/fillgap/data.py,sha256=YAZU7RDK83OmApNPaCS1tmuGh1ztmkEOOeBqzR_rRYA,11721
+backtest2live/fillgap/engine.py,sha256=vjQWNliqOYOvne3QCUlNqy01Jpwop9wqBkevqeJa2Nc,6916
+backtest2live/fillgap/report.py,sha256=wid11xK63RYVMB9rWsrqrFIg83w6HPDBvLpHKojs8aI,5126
+backtest2live/fillgap/sim.py,sha256=VRthq_LV-NJaGk2lwahL3dgim3zVghn2Wjsk-uiTBfg,7842
+backtest2live-0.2.0.dist-info/METADATA,sha256=2cw9n9-LtTdE3s_iUQHmdaNyTPX4DIHd9tRFD7KokBA,10250
+backtest2live-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+backtest2live-0.2.0.dist-info/entry_points.txt,sha256=IEZ2Cn3k11iTejY8CAaxBtKWjKpKRDJA8dkk8UDWpdU,51
+backtest2live-0.2.0.dist-info/licenses/LICENSE,sha256=ESmBtKQy0a1E-dcresmJrP7DJEr-0eRHTfcmgWd1zjo,1071
+backtest2live-0.2.0.dist-info/RECORD,,

backtest2live-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

backtest2live-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bt2live = backtest2live.cli:main

backtest2live-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martian Mobile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.