lobkit 0.2.1__py3-none-any.whl

lobkit/__init__.py

@@ -0,0 +1,18 @@
+"""lobkit: limit order book reconstruction, order-flow analytics and market making."""
+
+from lobkit.analysis import (
+    MicroPrice, RegressionResult, cross_venue_impact, estimate_microprice, impact_by_depth, imbalance_next_move,
+    lead_lag, microprice_forecast_error, multi_level_impact, ofi_price_impact, predictive_r2,
+)
+from lobkit.book import BinanceDepthSync, OrderBook, SequenceGap
+from lobkit.features import bucket_features, l1_features, multi_level_ofi, order_flow_imbalance
+from lobkit.market_making import ASParams, ASResult, optimal_spread, reservation_price, simulate_as
+from lobkit.simulator import SimulationResult, simulate_lob
+
+__all__ = [
+    "ASParams", "ASResult", "BinanceDepthSync", "MicroPrice", "OrderBook", "RegressionResult", "SequenceGap",
+    "SimulationResult", "bucket_features", "cross_venue_impact", "estimate_microprice", "imbalance_next_move",
+    "impact_by_depth", "l1_features", "lead_lag", "microprice_forecast_error", "multi_level_impact",
+    "multi_level_ofi", "ofi_price_impact", "optimal_spread", "order_flow_imbalance", "predictive_r2",
+    "reservation_price", "simulate_as", "simulate_lob",
+]

lobkit/analysis.py

@@ -0,0 +1,262 @@
+"""Price impact and short-horizon predictability."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class RegressionResult:
+    alpha: float
+    beta: float
+    t_stat: float
+    r2: float
+    n: int
+
+
+def _ols(x, y) -> RegressionResult:
+    x, y = np.asarray(x, dtype=float), np.asarray(y, dtype=float)
+    X = np.column_stack([np.ones_like(x), x])
+    coef, *_ = np.linalg.lstsq(X, y, rcond=None)
+    resid = y - X @ coef
+    n = len(y)
+    s2 = resid @ resid / (n - 2)
+    se = np.sqrt(s2 * np.linalg.inv(X.T @ X)[1, 1])
+    r2 = 1 - resid @ resid / np.sum((y - y.mean()) ** 2)
+    return RegressionResult(float(coef[0]), float(coef[1]), float(coef[1] / se), float(r2), n)
+
+
+def ofi_price_impact(buckets: pd.DataFrame) -> RegressionResult:
+    """Contemporaneous regression d_mid = alpha + beta * OFI (Cont et al. 2014, eq. 3)."""
+    return _ols(buckets["ofi"], buckets["d_mid"])
+
+
+def impact_by_depth(buckets: pd.DataFrame, n_groups: int = 5) -> tuple[pd.DataFrame, RegressionResult]:
+    """Impact coefficient per depth quantile, and beta regressed on 1/depth.
+
+    Cont et al. find beta is inversely proportional to market depth: the same
+    order flow moves a thin book further.
+    """
+    b = buckets.assign(group=pd.qcut(buckets["depth"], n_groups, labels=False, duplicates="drop"))
+    rows = []
+    for g, s in b.groupby("group"):
+        r = _ols(s["ofi"], s["d_mid"])
+        rows.append({"group": g, "mean_depth": s["depth"].mean(), "beta": r.beta, "r2": r.r2, "n": r.n})
+    table = pd.DataFrame(rows)
+    return table, _ols(1 / table["mean_depth"], table["beta"])
+
+
+def predictive_r2(buckets: pd.DataFrame, features: list[str], horizon: int = 1,
+                  train_frac: float = 0.7) -> dict:
+    """Predict the NEXT bucket's mid change from this bucket's features.
+
+    Chronological split; out-of-sample R^2 is measured against the training
+    mean, so a positive value means genuine predictive content.
+    """
+    df = buckets[features].assign(target=buckets["d_mid"].shift(-horizon)).dropna()
+    split = int(len(df) * train_frac)
+    train, test = df.iloc[:split], df.iloc[split:]
+    X_tr = np.column_stack([np.ones(len(train)), train[features]])
+    X_te = np.column_stack([np.ones(len(test)), test[features]])
+    coef, *_ = np.linalg.lstsq(X_tr, train["target"], rcond=None)
+    pred = X_te @ coef
+    y = test["target"].to_numpy()
+    sse, sst = np.sum((y - pred) ** 2), np.sum((y - train["target"].mean()) ** 2)
+    moving = y != 0
+    hit = np.mean(np.sign(pred[moving]) == np.sign(y[moving])) if moving.any() else np.nan
+    return {"oos_r2": float(1 - sse / sst), "hit_rate": float(hit), "n_test": len(test),
+            "coef": dict(zip(["const", *features], map(float, coef), strict=True))}
+
+
+def imbalance_next_move(features: pd.DataFrame, n_bins: int = 10) -> pd.DataFrame:
+    """P(next mid move is up | queue imbalance), as in Gould & Bonart (2016)."""
+    sign = np.sign(features["mid"].diff())
+    next_sign = sign.where(sign != 0).shift(-1).bfill()
+    df = pd.DataFrame({"imbalance": features["imbalance"], "next_up": next_sign > 0,
+                       "valid": next_sign.notna()})
+    df = df[df["valid"]]
+    df["bin"] = pd.cut(df["imbalance"], np.linspace(0, 1, n_bins + 1), include_lowest=True)
+    out = df.groupby("bin", observed=True).agg(p_up=("next_up", "mean"), n=("next_up", "size"))
+    out["imbalance_mid"] = [iv.mid for iv in out.index]
+    return out.reset_index(drop=True)
+
+
+def multi_level_impact(buckets: pd.DataFrame, train_frac: float = 0.7) -> pd.DataFrame:
+    """Explain d_mid with the OFI of the best 1, 2, ..., M levels (Xu, Gould & Howison 2019).
+
+    In-sample R^2 can only rise as levels are added, so the fair comparison is
+    the out-of-sample R^2 on a chronological split.
+    """
+    cols = sorted((c for c in buckets.columns if c.startswith("ofi_")), key=lambda c: int(c[4:]))
+    y = buckets["d_mid"].to_numpy(dtype=float)
+    split = int(len(y) * train_frac)
+    rows = []
+    for m in range(1, len(cols) + 1):
+        X = np.column_stack([np.ones(len(y)), buckets[cols[:m]]])
+        coef, *_ = np.linalg.lstsq(X, y, rcond=None)
+        r2 = 1 - np.sum((y - X @ coef) ** 2) / np.sum((y - y.mean()) ** 2)
+        coef, *_ = np.linalg.lstsq(X[:split], y[:split], rcond=None)
+        oos = 1 - np.sum((y[split:] - X[split:] @ coef) ** 2) / np.sum((y[split:] - y[:split].mean()) ** 2)
+        rows.append({"levels": m, "r2": float(r2), "oos_r2": float(oos)})
+    return pd.DataFrame(rows)
+
+
+def microprice_forecast_error(features: pd.DataFrame, horizons=(1, 10, 100, 1000),
+                              predictors=("microprice",), clock: str = "updates") -> pd.DataFrame:
+    """Do the predictor columns forecast the future mid better than the mid itself?
+
+    clock="updates": the mid h book updates ahead.
+    clock="moves":   the mid just after the h-th future mid change, the horizon
+                     Stoikov's (2018) micro-price is built for.
+    improvement_<p>_pct > 0 means a lower mean squared error than the mid.
+    """
+    if clock not in ("updates", "moves"):
+        raise ValueError("clock must be 'updates' or 'moves'")
+    mid = features["mid"].to_numpy(dtype=float)
+    rows_idx = np.arange(len(mid))
+    changes = np.flatnonzero(np.diff(mid) != 0) + 1
+    next_change = np.searchsorted(changes, rows_idx, side="right")
+    rows = []
+    for h in horizons:
+        if clock == "updates":
+            target = rows_idx + h
+            ok = target < len(mid)
+            future = mid[target[ok]]
+        else:
+            j = next_change + h - 1
+            ok = j < len(changes)
+            future = mid[changes[j[ok]]]
+        mse_mid = np.mean((future - mid[ok]) ** 2)
+        row = {f"horizon_{clock}": h, "mse_mid": mse_mid}
+        for c in predictors:
+            mse = np.mean((future - features[c].to_numpy(dtype=float)[ok]) ** 2)
+            row[f"mse_{c}"], row[f"improvement_{c}_pct"] = mse, 100 * (1 - mse / mse_mid)
+        rows.append(row)
+    return pd.DataFrame(rows)
+
+
+@dataclass(frozen=True)
+class MicroPrice:
+    """Fitted Stoikov (2018) micro-price: mid + adjustment[spread - 1, imbalance bucket].
+
+    States never seen in the fitting data (NaN) or with a spread outside
+    1..n_spread ticks get no adjustment (the mid).
+    """
+    adjustment: np.ndarray    # (n_spread, n_imb), in price units
+    tick: float
+
+    def __call__(self, features: pd.DataFrame) -> pd.Series:
+        n_spread, n_imb = self.adjustment.shape
+        s = np.rint(features["spread"].to_numpy() / self.tick).astype(int)
+        b = _imbalance_bucket(features["imbalance"].to_numpy(), n_imb)
+        ok = (s >= 1) & (s <= n_spread) & np.isfinite(features["imbalance"].to_numpy())   # NaN: an empty book
+        adj = np.where(ok, np.nan_to_num(self.adjustment)[np.clip(s, 1, n_spread) - 1, b], 0.0)
+        return features["mid"] + adj
+
+
+def _imbalance_bucket(imb: np.ndarray, n_imb: int) -> np.ndarray:
+    """Equal-width buckets with bucket(1 - x) == n_imb - 1 - bucket(x), so symmetrisation is exact."""
+    imb = np.nan_to_num(imb, nan=0.5)                 # callers mask NaN rows; this only keeps the index valid
+    lo = np.minimum((imb * n_imb).astype(int), n_imb - 1)
+    hi = n_imb - 1 - np.minimum(((1 - imb) * n_imb).astype(int), n_imb - 1)
+    return np.where(imb < 0.5, lo, hi)
+
+
+def estimate_microprice(features: pd.DataFrame, tick: float = 1.0, n_imb: int = 11, n_spread: int = 2,
+                        n_iter: int = 6) -> MicroPrice:
+    """Stoikov (2018), "The micro-price", Sections 3-4.
+
+    The state is (spread in ticks, imbalance bucket). Consecutive updates give
+    transitions that either leave the mid unchanged (Q) or move it by
+    K = (-1, -1/2, 1/2, 1) ticks (R1, landing in a new state R2). Then
+        g1 = (I - Q)^-1 R1 K       expected next mid move
+        B  = (I - Q)^-1 R2         state just after that move
+        g  = g1 + B g1 + ... + B^(n_iter-1) g1
+    The data is symmetrised (imbalance -> 1 - imbalance, move -> -move), as in
+    the paper, so the estimate has no drift. Larger moves and wider spreads are
+    dropped. n_imb is odd so a balanced book (imbalance 0.5, common when queues
+    are small integers) gets its own centre bucket.
+    """
+    s = np.rint(features["spread"].to_numpy() / tick).astype(int)
+    imb = features["imbalance"].to_numpy()
+    dm = np.rint(2 * np.diff(features["mid"].to_numpy()) / tick) / 2     # half-tick resolution
+    keep = (s[:-1] >= 1) & (s[:-1] <= n_spread) & (s[1:] >= 1) & (s[1:] <= n_spread) & (np.abs(dm) <= 1)
+    keep &= np.isfinite(imb[:-1]) & np.isfinite(imb[1:])
+    s0, s1, i0, i1, dm = s[:-1][keep], s[1:][keep], imb[:-1][keep], imb[1:][keep], dm[keep]
+    s0, s1 = np.r_[s0, s0], np.r_[s1, s1]
+    i0, i1, dm = np.r_[i0, 1 - i0], np.r_[i1, 1 - i1], np.r_[dm, -dm]
+
+    n = n_spread * n_imb
+    x0 = (s0 - 1) * n_imb + _imbalance_bucket(i0, n_imb)
+    x1 = (s1 - 1) * n_imb + _imbalance_bucket(i1, n_imb)
+    K = np.array([-1.0, -0.5, 0.5, 1.0])
+    move = dm != 0
+    Q, R1, R2 = np.zeros((n, n)), np.zeros((n, 4)), np.zeros((n, n))
+    np.add.at(Q, (x0[~move], x1[~move]), 1)
+    np.add.at(R1, (x0[move], np.searchsorted(K, dm[move])), 1)
+    np.add.at(R2, (x0[move], x1[move]), 1)
+    total = Q.sum(axis=1) + R1.sum(axis=1)
+    norm = np.where(total > 0, total, 1.0)[:, None]                     # unvisited states: no adjustment
+    Q, R1, R2 = Q / norm, R1 / norm, R2 / norm
+
+    inv = np.linalg.pinv(np.eye(n) - Q)     # = inv() unless a sparse state never leads to a move
+    g1, B = inv @ R1 @ K, inv @ R2
+    g, term = g1.copy(), g1
+    for _ in range(n_iter - 1):
+        term = B @ term
+        g += term
+    g[total == 0] = np.nan                                              # never observed
+    return MicroPrice((g * tick).reshape(n_spread, n_imb), tick)
+
+
+def lead_lag(a: pd.DataFrame, b: pd.DataFrame, step: str = "50ms", max_lag: int = 40) -> pd.DataFrame:
+    """Cross-correlation of two venues' mid returns, corr(r_a(t), r_b(t + lag)).
+
+    a and b need columns ts (seconds, one shared clock) and mid. Both are
+    sampled on a common grid of `step`; a peak at a positive lag means venue a
+    moves first and b follows lag seconds later (Hayashi & Yoshida 2005 avoid
+    the grid; at these sampling rates a fine grid is a close approximation).
+    """
+    def sampled(f):
+        s = pd.Series(np.log(f["mid"].to_numpy()), index=pd.to_datetime(f["ts"], unit="s"))
+        return s[~s.index.duplicated(keep="last")]
+
+    sa, sb = sampled(a), sampled(b)
+    grid = pd.date_range(max(sa.index[0], sb.index[0]).ceil(step), min(sa.index[-1], sb.index[-1]), freq=step)
+    ra = sa.reindex(sa.index.union(grid)).ffill().reindex(grid).diff().to_numpy()[1:]
+    rb = sb.reindex(sb.index.union(grid)).ffill().reindex(grid).diff().to_numpy()[1:]
+    dt = pd.Timedelta(step).total_seconds()
+    rows = []
+    for lag in range(-max_lag, max_lag + 1):
+        x, y = (ra[:len(ra) - lag], rb[lag:]) if lag >= 0 else (ra[-lag:], rb[:len(rb) + lag])
+        rows.append({"lag_s": lag * dt, "corr": float(np.corrcoef(x, y)[0, 1])})
+    return pd.DataFrame(rows)
+
+
+def cross_venue_impact(buckets_a: pd.DataFrame, buckets_b: pd.DataFrame, names=("a", "b"),
+                       train_frac: float = 0.7) -> pd.DataFrame:
+    """Whose order flow moves whose price, now and one bucket ahead.
+
+    For each venue as the target: in-sample R^2 of its d_mid on its own OFI, the
+    other venue's OFI, and both (contemporaneous); and out-of-sample R^2 of its
+    NEXT bucket's d_mid from the other venue's OFI and d_mid in this bucket. If
+    one venue leads, its flow and returns predict the other's next move.
+    """
+    j = buckets_a[["ofi", "d_mid"]].add_suffix("_a").join(buckets_b[["ofi", "d_mid"]].add_suffix("_b"), how="inner")
+    rows = []
+    for tgt, oth, tname in (("a", "b", names[0]), ("b", "a", names[1])):
+        y = j[f"d_mid_{tgt}"].to_numpy(dtype=float)
+        row = {"target": tname}
+        for label, cols in (("own_ofi", [f"ofi_{tgt}"]), ("other_ofi", [f"ofi_{oth}"]),
+                            ("both_ofi", [f"ofi_{tgt}", f"ofi_{oth}"])):
+            X = np.column_stack([np.ones(len(j)), j[cols]])
+            coef, *_ = np.linalg.lstsq(X, y, rcond=None)
+            row[f"r2_{label}"] = float(1 - np.sum((y - X @ coef) ** 2) / np.sum((y - y.mean()) ** 2))
+        lead = j.rename(columns={f"d_mid_{tgt}": "d_mid", f"ofi_{oth}": "other_ofi", f"d_mid_{oth}": "other_d_mid"})
+        for feats in (["other_ofi"], ["other_d_mid"]):
+            row[f"next_oos_r2_{feats[0]}"] = predictive_r2(lead, feats, train_frac=train_frac)["oos_r2"]
+        rows.append(row)
+    return pd.DataFrame(rows)

lobkit/book.py

@@ -0,0 +1,113 @@
+"""Level-2 order book and Binance depth-stream synchronisation.
+
+Binance publishes a REST snapshot plus a stream of diffs carrying absolute
+quantities per price level. A correct local book needs the sequence rules
+(from the Binance spot API docs):
+
+1. Buffer stream events, then fetch a snapshot with `lastUpdateId`.
+2. Drop events with u <= lastUpdateId.
+3. The first applied event must satisfy U <= lastUpdateId + 1 <= u.
+4. Every later event must have U == previous u + 1, otherwise resync.
+5. A quantity of 0 removes the level.
+"""
+
+from __future__ import annotations
+
+
+class SequenceGap(Exception):
+    """An update was missed; the local book is no longer trustworthy."""
+
+
+class OrderBook:
+    def __init__(self) -> None:
+        self.bids: dict[float, float] = {}
+        self.asks: dict[float, float] = {}
+
+    def apply(self, side: str, price: float, qty: float) -> None:
+        book = self.bids if side == "bid" else self.asks
+        if qty == 0:
+            book.pop(price, None)    # removing an unknown level is normal on Binance
+        else:
+            book[price] = qty
+
+    def load_snapshot(self, bids, asks) -> None:
+        self.bids.clear()
+        self.asks.clear()
+        for p, q in bids:
+            self.apply("bid", float(p), float(q))
+        for p, q in asks:
+            self.apply("ask", float(p), float(q))
+
+    def best_bid(self) -> tuple[float, float] | None:
+        if not self.bids:
+            return None
+        p = max(self.bids)
+        return p, self.bids[p]
+
+    def best_ask(self) -> tuple[float, float] | None:
+        if not self.asks:
+            return None
+        p = min(self.asks)
+        return p, self.asks[p]
+
+    def levels(self, side: str, n: int = 10) -> list[tuple[float, float]]:
+        book = self.bids if side == "bid" else self.asks
+        prices = sorted(book, reverse=(side == "bid"))[:n]
+        return [(p, book[p]) for p in prices]
+
+    @property
+    def mid(self) -> float | None:
+        bb, ba = self.best_bid(), self.best_ask()
+        return None if bb is None or ba is None else 0.5 * (bb[0] + ba[0])
+
+    @property
+    def is_crossed(self) -> bool:
+        bb, ba = self.best_bid(), self.best_ask()
+        return bb is not None and ba is not None and bb[0] >= ba[0]
+
+
+class BinanceDepthSync:
+    """Maintains an OrderBook from a Binance diff-depth stream plus REST snapshot."""
+
+    def __init__(self) -> None:
+        self.book = OrderBook()
+        self.last_update_id: int | None = None
+        self.prev_u: int | None = None
+        self.buffer: list[dict] = []
+
+    @property
+    def synced(self) -> bool:
+        return self.last_update_id is not None
+
+    def on_event(self, event: dict) -> bool:
+        """Feed one diff event (keys U, u, b, a). Returns True if it changed the book."""
+        if not self.synced:
+            self.buffer.append(event)
+            return False
+        return self._apply(event)
+
+    def on_snapshot(self, snapshot: dict) -> bool:
+        """Install a REST snapshot. Returns False if it is too old and must be refetched."""
+        if self.buffer and snapshot["lastUpdateId"] < self.buffer[0]["U"]:
+            return False
+        self.book.load_snapshot(snapshot["bids"], snapshot["asks"])
+        self.last_update_id, self.prev_u = snapshot["lastUpdateId"], None
+        pending, self.buffer = self.buffer, []
+        for ev in pending:
+            self._apply(ev)
+        return True
+
+    def _apply(self, ev: dict) -> bool:
+        if ev["u"] <= self.last_update_id:
+            return False                                   # already in the snapshot
+        if self.prev_u is None:
+            if not ev["U"] <= self.last_update_id + 1 <= ev["u"]:
+                raise SequenceGap(f"first event U={ev['U']} u={ev['u']} vs snapshot {self.last_update_id}")
+        elif ev["U"] != self.prev_u + 1:
+            raise SequenceGap(f"expected U={self.prev_u + 1}, got U={ev['U']}")
+        for p, q in ev["b"]:
+            self.book.apply("bid", float(p), float(q))
+        for p, q in ev["a"]:
+            self.book.apply("ask", float(p), float(q))
+        self.prev_u = self.last_update_id = ev["u"]
+        return True

lobkit/features.py

@@ -0,0 +1,85 @@
+"""Top-of-book features and order-flow imbalance (Cont, Kukanov & Stoikov 2014).
+
+Input quotes: columns ts (seconds), bid_px, bid_sz, ask_px, ask_sz, one row
+per book update; deeper levels, if any, as bid_px_2, bid_sz_2, ask_px_2, ...
+Trades: ts, price, qty, side (+1 buyer-initiated).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def order_flow_imbalance(quotes: pd.DataFrame) -> np.ndarray:
+    """Per-update OFI contribution e_n.
+
+    e_n =  1{Pb_n >= Pb_n-1} qb_n - 1{Pb_n <= Pb_n-1} qb_n-1
+         - 1{Pa_n <= Pa_n-1} qa_n + 1{Pa_n >= Pa_n-1} qa_n-1
+
+    Positive values mean net buying pressure: bids added or asks removed.
+    """
+    pb, qb = quotes["bid_px"].to_numpy(), quotes["bid_sz"].to_numpy()
+    pa, qa = quotes["ask_px"].to_numpy(), quotes["ask_sz"].to_numpy()
+    e = np.zeros(len(quotes))
+    e[1:] = ((pb[1:] >= pb[:-1]) * qb[1:] - (pb[1:] <= pb[:-1]) * qb[:-1]
+             - (pa[1:] <= pa[:-1]) * qa[1:] + (pa[1:] >= pa[:-1]) * qa[:-1])
+    return e
+
+
+def multi_level_ofi(quotes: pd.DataFrame) -> pd.DataFrame:
+    """OFI at each recorded level, columns ofi_1..ofi_M (Xu, Gould & Howison 2019, Section 2).
+
+    Level m is the m-th best non-empty price level, and its OFI applies the
+    Cont et al. formula to that level's prices and sizes.
+    """
+    n_levels = 1 + sum(c.startswith("bid_px_") for c in quotes.columns)
+    out = {}
+    for m in range(1, n_levels + 1):
+        sfx = "" if m == 1 else f"_{m}"
+        cols = {f"{k}{sfx}": k for k in ("bid_px", "bid_sz", "ask_px", "ask_sz")}
+        out[f"ofi_{m}"] = order_flow_imbalance(quotes[list(cols)].rename(columns=cols))
+    return pd.DataFrame(out, index=quotes.index)
+
+
+def l1_features(quotes: pd.DataFrame) -> pd.DataFrame:
+    q = quotes.reset_index(drop=True).copy()
+    depth = q["bid_sz"] + q["ask_sz"]
+    q["mid"] = 0.5 * (q["bid_px"] + q["ask_px"])
+    q["spread"] = q["ask_px"] - q["bid_px"]
+    q["imbalance"] = q["bid_sz"] / depth                      # 1 = all depth on the bid
+    q["microprice"] = (q["bid_px"] * q["ask_sz"] + q["ask_px"] * q["bid_sz"]) / depth
+    q["ofi"] = order_flow_imbalance(q)
+    return q
+
+
+def bucket_features(features: pd.DataFrame, trades: pd.DataFrame | None = None,
+                    freq: str = "10s") -> pd.DataFrame:
+    """Aggregate per-update features into fixed time buckets.
+
+    d_mid is the change in mid from the end of the previous bucket to the end
+    of this one, so it lines up with the OFI accumulated inside the bucket.
+    A bucket with no updates is kept, with zero flow and the book state carried
+    forward, so rows form a regular time grid: the next row is the next interval.
+    """
+    f = features.set_index(pd.to_datetime(features["ts"], unit="s"))
+    g = f.resample(freq)
+    out = pd.DataFrame({
+        "ofi": g["ofi"].sum(),
+        "mid": g["mid"].last(),
+        "depth": (0.5 * (f["bid_sz"] + f["ask_sz"])).resample(freq).mean(),
+        "spread": g["spread"].mean(),
+        "imbalance": g["imbalance"].last(),
+        "micro_gap": (f["microprice"] - f["mid"]).resample(freq).last(),
+        "n_updates": g.size(),
+    })
+    for c in f.columns:
+        if c.startswith("ofi_"):                              # multi-level OFI, if computed
+            out[c] = g[c].sum()
+    state = ["mid", "depth", "spread", "imbalance", "micro_gap"]
+    out[state] = out[state].ffill()                           # empty bucket: the book did not change
+    out["d_mid"] = out["mid"].diff()
+    if trades is not None and len(trades):
+        t = trades.set_index(pd.to_datetime(trades["ts"], unit="s"))
+        out["trade_imbalance"] = (t["side"] * t["qty"]).resample(freq).sum().reindex(out.index).fillna(0.0)
+    return out.dropna()

lobkit/market_making.py

@@ -0,0 +1,168 @@
+"""Avellaneda & Stoikov (2008), "High-frequency trading in a limit order book".
+
+A market maker with CARA utility (risk aversion gamma) quotes around a
+reservation price that is skewed against inventory:
+    r = s - q * gamma * sigma^2 * (T - t)
+with total spread
+    delta_a + delta_b = gamma * sigma^2 * (T - t) + (2 / gamma) * ln(1 + gamma / k).
+Fills arrive with intensity A * exp(-k * delta), delta = distance from mid.
+
+simulate_as replicates the paper, where that fill model holds by construction.
+simulate_as_lob runs the same quotes inside the zero-intelligence order book,
+where fills depend on queue position and arrive just before adverse moves.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from lobkit.simulator import Quoter, simulate_lob
+
+
+@dataclass(frozen=True)
+class ASParams:
+    s0: float = 100.0
+    T: float = 1.0
+    sigma: float = 2.0
+    dt: float = 0.005
+    gamma: float = 0.1
+    k: float = 1.5
+    A: float = 140.0
+
+
+def reservation_price(s, q, t, p: ASParams):
+    return s - q * p.gamma * p.sigma**2 * (p.T - t)
+
+
+def optimal_spread(t, p: ASParams):
+    return p.gamma * p.sigma**2 * (p.T - t) + 2 / p.gamma * np.log(1 + p.gamma / p.k)
+
+
+@dataclass
+class ASResult:
+    pnl: np.ndarray
+    final_inventory: np.ndarray
+    inventory_paths: np.ndarray    # (n_keep, n_steps + 1)
+    mid_paths: np.ndarray
+    mean_spread: float
+
+    def summary(self) -> dict:
+        return {"mean_pnl": float(self.pnl.mean()), "std_pnl": float(self.pnl.std(ddof=1)),
+                "mean_final_q": float(self.final_inventory.mean()),
+                "std_final_q": float(self.final_inventory.std(ddof=1)),
+                "mean_spread": self.mean_spread}
+
+
+def simulate_as(p: ASParams = ASParams(), strategy: str = "inventory", n_paths: int = 1000,
+                seed: int | None = 0, keep_paths: int = 5) -> ASResult:
+    """Monte Carlo of the paper's experiment.
+
+    strategy="inventory": quotes centred on the reservation price.
+    strategy="symmetric": same spread, centred on the mid (ignores inventory).
+    """
+    _check_strategy(strategy)
+    rng = np.random.default_rng(seed)
+    n_steps = round(p.T / p.dt)
+    keep_paths = min(keep_paths, n_paths)
+    s = np.full(n_paths, p.s0)
+    q = np.zeros(n_paths)
+    cash = np.zeros(n_paths)
+    inv = np.zeros((keep_paths, n_steps + 1))
+    mids = np.zeros((keep_paths, n_steps + 1))
+    mids[:, 0] = p.s0
+    spreads = []
+
+    for i in range(n_steps):
+        t = i * p.dt
+        spread = optimal_spread(t, p)
+        spreads.append(spread)
+        centre = reservation_price(s, q, t, p) if strategy == "inventory" else s
+        bid, ask = centre - spread / 2, centre + spread / 2
+        # The mid moves while quotes rest, and fills are judged against the new mid.
+        # This builds in adverse selection: quotes the price moved through fill more often.
+        s = s + p.sigma * np.sqrt(p.dt) * np.where(rng.random(n_paths) < 0.5, 1.0, -1.0)
+        p_ask = np.clip(p.A * np.exp(-p.k * (ask - s)) * p.dt, 0, 1)
+        p_bid = np.clip(p.A * np.exp(-p.k * (s - bid)) * p.dt, 0, 1)
+        sold = rng.random(n_paths) < p_ask
+        bought = rng.random(n_paths) < p_bid
+        q += bought.astype(float) - sold
+        cash += sold * ask - bought * bid
+        inv[:, i + 1], mids[:, i + 1] = q[:keep_paths], s[:keep_paths]
+
+    return ASResult(cash + q * s, q, inv, mids, float(np.mean(spreads)))
+
+
+def _check_strategy(strategy: str) -> None:
+    if strategy not in ("inventory", "symmetric"):
+        raise ValueError("strategy must be 'inventory' or 'symmetric'")
+
+
+def as_quoter(p: ASParams, strategy: str = "inventory") -> Quoter:
+    """Avellaneda-Stoikov quotes as a simulate_lob quoter; t and p.T in seconds, prices in ticks."""
+    _check_strategy(strategy)
+
+    def quote(t: float, mid: float, q: int) -> tuple[float, float]:
+        t = min(t, p.T)
+        centre = reservation_price(mid, q, t, p) if strategy == "inventory" else mid
+        half = optimal_spread(t, p) / 2
+        return centre - half, centre + half
+
+    return quote
+
+
+def simulate_as_lob(p: ASParams, strategy: str = "inventory", n_episodes: int = 100, requote_every: float = 1.0,
+                    markouts=(1.0, 10.0), seed: int = 0, **lob_kwargs) -> pd.DataFrame:
+    """The Avellaneda-Stoikov market maker inside simulate_lob, one row per episode of p.T seconds.
+
+    p.sigma, p.k and p.T must be in the book's units (ticks, seconds); p.s0 is
+    unused. Columns:
+      pnl                cash + final inventory marked at the final mid
+      final_q, n_fills
+      spread_capture     mean over fills of side * (mid - fill price): what the quote earned on the spot
+      adverse_<m>s       mean over fills of side * (mid m seconds later - mid at fill), for m in markouts;
+                         fills less than m seconds before the episode ends are left out
+    """
+    quoter = as_quoter(p, strategy)
+    rows = []
+    for e in range(n_episodes):
+        n_max = int(100 * p.T) + 1000                     # far above the ~25 events/s of the default book
+        r = simulate_lob(n_max, seed=seed + e, quoter=quoter, requote_every=requote_every, t_end=p.T, **lob_kwargs)
+        if len(r.quotes) == n_max:
+            raise RuntimeError("episode ran out of events before p.T; the book is busier than expected")
+        f, q = r.fills, r.quotes
+        mid = 0.5 * (q["bid_px"] + q["ask_px"]).to_numpy()
+        side = f["side"].to_numpy()
+        row = {
+            "pnl": float(-(side * f["price"]).sum() + side.sum() * mid[-1]),
+            "final_q": int(side.sum()),
+            "n_fills": len(f),
+            "spread_capture": float(np.mean(side * (f["mid"] - f["price"]))) if len(f) else np.nan,
+        }
+        for m in markouts:
+            full = (f["ts"] + m <= p.T).to_numpy()
+            later = mid[np.searchsorted(q["ts"], f["ts"][full] + m) - 1]
+            row[f"adverse_{m:g}s"] = float(np.mean(side[full] * (later - f["mid"][full]))) if full.any() else np.nan
+        rows.append(row)
+    return pd.DataFrame(rows)
+
+
+def fill_intensity(deltas=(0.5, 1.0, 1.5, 2.0, 2.5, 3.0), t_end: float = 3000.0, seed: int = 7,
+                   **lob_kwargs) -> tuple[pd.DataFrame, float, float]:
+    """Calibrate the paper's fill model A * exp(-k * delta) on simulate_lob.
+
+    A quoter rests one unit delta from the mid on each side, requoting every
+    second; fills per second per side are regressed in logs on delta.
+    Returns (table, A, k).
+    """
+    rows = []
+    for d in deltas:
+        r = simulate_lob(int(100 * t_end) + 1000, seed=seed, quoter=lambda t, m, q, d=d: (m - d, m + d),
+                         t_end=t_end, **lob_kwargs)
+        rows.append({"delta": d, "fills_per_s": len(r.fills) / 2 / t_end})
+    table = pd.DataFrame(rows)
+    ok = table["fills_per_s"] > 0
+    slope, intercept = np.polyfit(table["delta"][ok], np.log(table["fills_per_s"][ok]), 1)
+    return table, float(np.exp(intercept)), float(-slope)