pitbacktest 0.2.0__py3-none-any.whl

pitbacktest/core/costs.py

@@ -0,0 +1,144 @@
+"""Trading costs: no flat assumptions, per-security measurement as the rule.
+
+Why a flat assumption is dangerous
+    Spreads differ by security, so assuming some round-trip bp for everything understates the cost of a high-turnover
+    strategy more the higher its turnover, and can even flip the sign of the return. With high daily turnover a small
+    difference in the one-way cost accumulates a lot over a year.
+
+Estimators
+    Roll (1984)       autocovariance of trade prices. The most reliable when intraday bars exist.
+    Corwin-Schultz    high-low based. **Can return 0 for ETFs and low-volatility names, so be careful**.
+    Traded-value regression  interpolates securities with no measurement as log(bp) = a + b*log(traded value).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def roll_spread(prices: np.ndarray) -> float:
+    """Roll (1984) effective spread (in price units). NaN if the autocovariance is positive."""
+    p = np.asarray(prices, dtype=np.float64)
+    p = p[np.isfinite(p)]
+    if len(p) < 30:
+        return np.nan
+    d = np.diff(p)
+    c = np.cov(d[1:], d[:-1])[0, 1]
+    return 2 * np.sqrt(-c) if c < 0 else np.nan
+
+
+def corwin_schultz(high: pd.DataFrame, low: pd.DataFrame) -> pd.DataFrame:
+    """Corwin-Schultz (2012) high-low spread estimate (as a ratio).
+
+    Warning: for assets with a narrow high-low range (ETFs, large low-volatility stocks) the estimate goes negative and is clipped to 0.
+          If the result is all 0, do not use this estimator; move to Roll or the traded-value regression.
+    """
+    h, l = np.log(high), np.log(low)
+    beta = (h - l) ** 2 + (h.shift(1) - l.shift(1)) ** 2
+    h2 = np.maximum(high, high.shift(1))          # elementwise: pd.concat(axis=1) would double the columns
+    l2 = np.minimum(low, low.shift(1))
+    gamma = (np.log(h2) - np.log(l2)) ** 2
+    k = 3 - 2 * np.sqrt(2)
+    alpha = (np.sqrt(2 * beta) - np.sqrt(beta)) / k - np.sqrt(gamma / k)
+    return (2 * (np.exp(alpha) - 1) / (1 + np.exp(alpha))).clip(lower=0, upper=0.2)
+
+
+def fit_spread_model(dvol_m: np.ndarray, spread_bp: np.ndarray) -> tuple[float, float]:
+    """Regression log(one-way bp) = a + b*log(traded value in M). For interpolating securities with no measurement."""
+    m = np.isfinite(dvol_m) & np.isfinite(spread_bp) & (dvol_m > 0) & (spread_bp > 0)
+    if m.sum() < 20:
+        return np.nan, np.nan
+    b, a = np.polyfit(np.log(dvol_m[m]), np.log(spread_bp[m]), 1)
+    return float(a), float(b)
+
+
+def spread_panel(adv: pd.DataFrame, *, a: float, b: float,
+                 measured: dict[str, float] | None = None,
+                 lo: float = 0.05, hi: float = 50.0) -> pd.DataFrame:
+    """(date x ticker) panel of one-way spreads (bp). Measured values override it when present."""
+    dv_m = (adv / 1e6).clip(lower=0.1)
+    est = np.exp(a + b * np.log(dv_m))
+    if measured:
+        for k, v in measured.items():
+            if k in est.columns and np.isfinite(v):
+                est[k] = v
+    return est.clip(lower=lo, upper=hi)
+
+
+def apply_turnover_cost(holdings: np.ndarray, spread_bp: np.ndarray | float) -> np.ndarray:
+    """Cost proportional to turnover. Returns the daily cost (in return units).
+
+    holdings   (date x ticker) weights. Sum = 1 (long) or one per leg for long-short.
+    spread_bp  scalar (flat) or a (date x ticker) measured panel. **A panel is recommended**.
+    """
+    d = np.abs(np.diff(holdings, axis=0))
+    cost = np.zeros(holdings.shape[0])
+    if np.isscalar(spread_bp):
+        cost[1:] = d.sum(axis=1) * (spread_bp / 1e4) * 0.5
+    else:
+        s = np.nan_to_num(np.asarray(spread_bp), nan=float(np.nanmedian(spread_bp)))
+        cost[1:] = (d * s[1:] / 1e4).sum(axis=1)
+    return cost
+
+
+def rate_schedule(dates: pd.DatetimeIndex, entries, name: str = "rate") -> pd.Series:
+    """A rate that changes on known effective dates, as a value for every date: each date takes the latest entry whose
+    effective date is on or before it. `entries` is a list of (effective_date, value). A date before the first entry raises,
+    because the rate is then unknown and a made-up rate (or 0) would hide that."""
+    if not len(entries):
+        raise ValueError(f"{name}: the schedule is empty")
+    s = pd.Series({pd.Timestamp(d): float(v) for d, v in entries}).sort_index()
+    out = s.reindex(dates, method="ffill")
+    if out.isna().any():
+        raise ValueError(f"{name}: no rate is known before {s.index[0].date()}, but the panel starts on {dates[0].date()} "
+                         f"(add an earlier entry or start the panel later)")
+    return out
+
+
+def side_cost_input(value, dates: pd.DatetimeIndex, tickers: pd.Index, name: str):
+    """Validate a one-way cost for one side of a trade (bp) and bring it to a form `apply_side_cost` can use: a float, a
+    (dates x 1) array (a Series indexed by date: a rate that changes over time) or a (dates x tickers) array. Unlike `spread_bp`, a
+    missing value raises instead of being replaced by a median: a rate you do not know is not a rate of zero."""
+    if value is None:
+        return 0.0
+    if isinstance(value, pd.DataFrame):
+        a = value.reindex(index=dates, columns=tickers).to_numpy(float)
+    elif isinstance(value, pd.Series):
+        if not isinstance(value.index, pd.DatetimeIndex):
+            raise ValueError(f"{name}: a Series must be indexed by date")
+        a = value.sort_index().reindex(dates, method="ffill").to_numpy(float).reshape(-1, 1)
+    else:
+        a = np.asarray(value, dtype=float)
+        if a.ndim == 0:
+            if not np.isfinite(a) or a < 0:
+                raise ValueError(f"{name} must be a finite number, not negative, got {value!r}")
+            return float(a)
+        if a.shape != (len(dates), len(tickers)):
+            raise ValueError(f"{name}: an array must have shape (dates, tickers) = {(len(dates), len(tickers))}, got {a.shape}")
+    if np.isnan(a).any():
+        raise ValueError(f"{name}: the value is unknown for some dates or securities (NaN, or a date before the first entry); "
+                         f"a missing cost is an error, not zero")
+    if np.isinf(a).any() or (a < 0).any():
+        raise ValueError(f"{name} must be finite and not negative (a negative cost would pay you for trading)")
+    return a
+
+
+def apply_side_cost(holdings: np.ndarray, buy_bp, sell_bp) -> np.ndarray:
+    """Daily cost of trades that depends on the side: `buy_bp` per unit of weight bought and `sell_bp` per unit sold (one-way,
+    bp, on top of the spread). A weight going up is a buy and a weight going down is a sell, so opening a short is a sell and
+    covering it a buy. The first row, a build from cash, is not charged (as for the spread). `buy_bp` and `sell_bp` are floats or
+    arrays from `side_cost_input`."""
+    d = np.diff(holdings, axis=0)
+    out = np.zeros(holdings.shape[0])
+    b = buy_bp[1:] if isinstance(buy_bp, np.ndarray) else buy_bp
+    s = sell_bp[1:] if isinstance(sell_bp, np.ndarray) else sell_bp
+    out[1:] = (np.maximum(d, 0.0) * b + np.maximum(-d, 0.0) * s).sum(axis=1) / 1e4
+    return out
+
+
+def turnover(holdings: np.ndarray) -> np.ndarray:
+    """Daily one-way turnover."""
+    t = np.zeros(holdings.shape[0])
+    t[1:] = 0.5 * np.abs(np.diff(holdings, axis=0)).sum(axis=1)
+    return t

pitbacktest/core/estimators.py

@@ -0,0 +1,216 @@
+"""Estimators: Fama-MacBeth, Newey-West, deciles and the shuffled null.
+
+Overlapping returns
+    Computing an h-day holding return every day makes h-1 days overlap. The independent observations are far fewer, so without a
+    correction t is inflated several times over. Every t is computed with Newey-West.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import pandas as pd
+
+EPS = 1e-12
+
+
+def newey_west_t(series: np.ndarray, lag: int) -> tuple[float, float, float, int]:
+    """Newey-West corrected t for overlapping returns. Returns (mean, se, t, T)."""
+    x = np.asarray(series, dtype=np.float64)
+    x = x[np.isfinite(x)]
+    T = len(x)
+    if T < 30:
+        return float("nan"), float("nan"), float("nan"), T
+    mu = x.mean()
+    xd = x - mu
+    s = (xd @ xd) / T
+    for lg in range(1, min(lag, T - 1) + 1):
+        w = 1.0 - lg / (lag + 1.0)
+        s += 2.0 * w * (xd[lg:] @ xd[:-lg]) / T
+    if s <= 0:
+        return float(mu), float("nan"), float("nan"), T
+    se = np.sqrt(s / T)
+    return float(mu), float(se), float(mu / se), T
+
+
+def fama_macbeth(factor: pd.DataFrame, fwd: dict[int, pd.DataFrame],
+                 controls: dict[str, pd.DataFrame], eligible: pd.DataFrame,
+                 *, min_stocks: int | None = None) -> dict:
+    """FM coefficient series of one factor x several horizons -> NW t.
+
+    The factor is orthogonalised against the space of the controls by QR before the coefficient is taken.
+    Both the t with controls and the t without (t_raw) are produced, but the caller is made to **report only the one after controls**.
+    """
+    fv = factor.values.astype(np.float64)
+    ev = eligible.values
+    cvs = [c.values.astype(np.float64) for c in controls.values()]
+    hs = sorted(fwd)
+
+    # A fixed minimum sample throws away every date in a small universe (for example 20 names).
+    # The least a regression needs is (controls + intercept + factor), so twice that is the floor,
+    # but never more than half the median universe size.
+    if min_stocks is None:
+        need = 2 * (len(cvs) + 2)
+        med = float(np.median(ev.sum(axis=1)))
+        min_stocks = int(max(need, min(50, med * 0.5)))
+        if med < need:
+            warnings.warn(
+                f"The median universe has {med:.0f} names but there are {len(cvs)} controls, "
+                f"so the regression has too few degrees of freedom (at least {need} names needed). "
+                f"Use fewer controls or more names.", stacklevel=2)
+    rv = {h: fwd[h].values.astype(np.float64) for h in hs}
+    n = fv.shape[0]
+    betas = {h: np.full(n, np.nan) for h in hs}
+    raws = {h: np.full(n, np.nan) for h in hs}
+    n_eligible_days = 0      # days with a large enough sample
+    n_collinear = 0          # of those, days thrown away because the residual was 0 (perfectly collinear with the controls)
+
+    for i in range(n):
+        f = fv[i]
+        ok = ev[i] & np.isfinite(f)
+        for c in cvs:
+            ok &= np.isfinite(c[i])
+        if ok.sum() < min_stocks:
+            continue
+        fo = f[ok]
+        Z = np.column_stack([np.ones(ok.sum())] + [c[i][ok] for c in cvs])
+        try:
+            Q, _ = np.linalg.qr(Z)
+        except np.linalg.LinAlgError:
+            continue
+        fp = fo - Q @ (Q.T @ fo)
+        den = fp @ fp
+        foc = fo - fo.mean()
+        den_r = foc @ foc
+        n_eligible_days += 1
+        if den <= EPS or den_r <= EPS:
+            n_collinear += 1
+            continue
+        for h in hs:
+            r = rv[h][i]
+            okh = ok & np.isfinite(r)
+            if okh.sum() < min_stocks:
+                continue
+            if okh.sum() != ok.sum():
+                fo2 = f[okh]
+                Z2 = np.column_stack([np.ones(okh.sum())] + [c[i][okh] for c in cvs])
+                try:
+                    Q2, _ = np.linalg.qr(Z2)
+                except np.linalg.LinAlgError:
+                    continue
+                fp2 = fo2 - Q2 @ (Q2.T @ fo2)
+                d2 = fp2 @ fp2
+                if d2 <= EPS:
+                    continue
+                rr = r[okh]
+                betas[h][i] = (fp2 @ (rr - Q2 @ (Q2.T @ rr))) / d2
+                f2c = fo2 - fo2.mean()
+                raws[h][i] = (f2c @ (rr - rr.mean())) / (f2c @ f2c)
+            else:
+                rr = r[ok]
+                betas[h][i] = (fp @ (rr - Q @ (Q.T @ rr))) / den
+                raws[h][i] = (foc @ (rr - rr.mean())) / den_r
+
+    out = {}
+    for h in hs:
+        mu, se, t, T = newey_west_t(betas[h], lag=max(h, 21))
+        _, _, t63, _ = newey_west_t(betas[h], lag=max(h, 63))
+        mu_r, _, t_r, _ = newey_west_t(raws[h], lag=max(h, 21))
+        out[h] = {"coef_bp": mu * 1e4 if np.isfinite(mu) else np.nan, "t": t,
+                  "t_nw63": t63, "n_days": T,
+                  "coef_bp_raw": mu_r * 1e4 if np.isfinite(mu_r) else np.nan, "t_raw": t_r}
+
+    # Perfect-collinearity diagnosis: if the factor is effectively the same as the controls the residual is 0 and every date is thrown away.
+    # A silent NaN would hide the cause, so say it out loud.
+    if n_eligible_days and n_collinear / n_eligible_days > 0.5:
+        warnings.warn(
+            f"The factor is almost perfectly collinear with the controls "
+            f"(residual about 0 on {n_collinear}/{n_eligible_days} days). "
+            f"No information is left after the controls, so t is NaN. "
+            f"Change the factor definition or drop that control.",
+            stacklevel=2)
+    for h in hs:
+        out[h]["collinear_pct"] = (100.0 * n_collinear / n_eligible_days
+                                   if n_eligible_days else np.nan)
+    return out
+
+
+def decile_profile(factor: pd.DataFrame, fwd_h: pd.DataFrame, eligible: pd.DataFrame,
+                   *, lag: int = 21, n_bins: int = 10) -> dict:
+    """Decile profile. Without monotonicity only the extremes differ, which is hard to call a signal."""
+    rk = factor.where(eligible).rank(axis=1, pct=True, na_option="keep")
+    c = fwd_h.values.astype(np.float64)
+    ev = eligible.values
+    prof = []
+    for d in range(n_bins):
+        lo, hi = d / n_bins, (d + 1) / n_bins + (0.01 if d == n_bins - 1 else 0)
+        sel = ((rk >= lo) & (rk < hi) & eligible).values
+        v = []
+        for i in range(c.shape[0]):
+            s = sel[i] & np.isfinite(c[i])
+            pool = ev[i] & np.isfinite(c[i])
+            if s.sum() >= 3 and pool.sum() >= 30:
+                v.append(c[i][s].mean() - c[i][pool].mean())
+        prof.append(float(np.mean(v) * 1e4) if v else np.nan)
+    # Spearman correlation = Pearson correlation of the ranks. method="spearman" would need scipy, so it is not used
+    # (the core dependencies of this package are pandas and numpy only).
+    rho = pd.Series(prof).rank().corr(pd.Series(range(n_bins), dtype=float).rank())
+    hi_lo = [x for x in (prof[-1], prof[0]) if np.isfinite(x)]
+    return {"decile_bp": prof, "monotonicity_rho": float(rho) if pd.notna(rho) else np.nan,
+            "spread_bp": float(prof[-1] - prof[0]) if len(hi_lo) == 2 else np.nan}
+
+
+def shuffle_null(factor_builder, eligible: pd.DataFrame, fwd: dict[int, pd.DataFrame],
+                 controls: dict[str, pd.DataFrame], *, n_rep: int = 3,
+                 seed: int = 0) -> dict:
+    """Shuffled null: **measures** the multiple-testing threshold.
+
+    Only the security order is randomly permuted within each date. The date structure and the factor distribution are kept and
+    only the security-factor link is destroyed, so the |t| distribution that comes out is the 'size of chance'.
+    Theoretical corrections such as Bonferroni ignore the correlation between tests and are far too conservative.
+
+    factor_builder: (rng) -> DataFrame  -- a callback that rebuilds the factor from the shuffled source
+    """
+    rng = np.random.default_rng(seed)
+    ts = []
+    for _ in range(n_rep):
+        f = factor_builder(rng)
+        r = fama_macbeth(f, fwd, controls, eligible)
+        ts.extend(abs(v["t"]) for v in r.values() if np.isfinite(v["t"]))
+    a = np.array(ts)
+    if not len(a):
+        return {"n": 0, "p95": np.nan, "max": np.nan}
+    return {"n": int(len(a)), "median": float(np.median(a)),
+            "p95": float(np.percentile(a, 95)), "p99": float(np.percentile(a, 99)),
+            "max": float(a.max())}
+
+
+def shuffle_columns(df: pd.DataFrame, eligible: pd.DataFrame, rng) -> pd.DataFrame:
+    """Permute values only among the eligible securities of each date. The standard shuffler of shuffle_null."""
+    a = df.values.copy()
+    ev = eligible.values
+    for i in range(a.shape[0]):
+        j = np.where(ev[i])[0]
+        if len(j) > 1:
+            a[i, j] = a[i, rng.permutation(j)]
+    return pd.DataFrame(a, index=df.index, columns=df.columns)
+
+
+def paired_diff(base_mask: np.ndarray, alt_mask: np.ndarray, cum: np.ndarray,
+                *, lag: int = 21, min_n: int = 5) -> dict:
+    """Paired comparison: the pure contribution of adding a condition on the same dates.
+
+    Adding a condition almost always improves the headline number. To see whether it is a real improvement it must be compared
+    **on the same dates and the same sample**, in pairs.
+    """
+    d = []
+    for i in range(cum.shape[0]):
+        a = base_mask[i] & np.isfinite(cum[i])
+        b = alt_mask[i] & np.isfinite(cum[i])
+        if a.sum() >= min_n and b.sum() >= min_n:
+            d.append(cum[i][b].mean() - cum[i][a].mean())
+    if len(d) < 30:
+        return {"diff_bp": np.nan, "t": np.nan, "n_days": len(d)}
+    mu, _, t, n = newey_west_t(np.array(d), lag=lag)
+    return {"diff_bp": float(mu * 1e4), "t": float(t), "n_days": n}

pitbacktest/core/gates.py

@@ -0,0 +1,175 @@
+"""Gate runner: verdict gates fixed before the result is seen.
+
+The order of the gates matters: statistics -> cost -> stability -> structure.
+**Each later gate is harder to pass.** With the statistical gate alone many candidates survive, but
+after the cost, stability and structure gates far fewer remain, and that is the normal outcome.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+
+import numpy as np
+import pandas as pd
+
+from .estimators import newey_west_t
+
+
+@dataclass
+class GateConfig:
+    """Gate thresholds. Fix them before testing starts and do not change them afterwards."""
+    null_threshold: float | None = None   # None means measure it with a shuffled null
+    fallback_t: float = 3.0               # only when the null cannot be measured
+    require_net_positive: bool = True     # net profit after costs > 0
+    require_subperiod_sign: bool = True   # the sign agrees in the first and second half
+    min_monotonicity: float = 0.5         # |rho|
+    min_yearly_positive: float = 0.6      # share of years that are positive
+    max_single_name_share: float = 0.5    # firing share of the most frequent name (static basket)
+    min_turnover: float = 0.05            # lower bound of daily turnover
+
+
+def fire_structure(fire: np.ndarray, dates: pd.DatetimeIndex,
+                   tickers: pd.Index) -> dict:
+    """Firing structure: a signal or a static basket?
+
+    A factor that keeps picking the same large stocks for years is a size factor (a static basket), not a signal.
+    The top-name share and the longest run of consecutive firing days catch it.
+    """
+    n = fire.sum(axis=1)
+    act = n[n > 0]
+    cnt = pd.Series(fire.sum(axis=0), index=tickers)
+    cnt = cnt[cnt > 0].sort_values(ascending=False)
+    tot = int(fire.sum())
+    if tot == 0 or len(cnt) == 0:
+        return {"fires_per_day": 0.0, "active_days_pct": 0.0, "n_names": 0,
+                "top10_share": np.nan, "max_name_share": np.nan,
+                "max_consecutive": 0, "daily_turnover": np.nan, "top_names": {},
+                "note": "no firings"}
+    turn = []
+    for i in range(1, fire.shape[0]):
+        a, b = fire[i - 1], fire[i]
+        u = (a | b).sum()
+        if u and a.sum() and b.sum():
+            turn.append(1 - (a & b).sum() / u)
+    runs = []
+    for c in cnt.head(30).index:
+        s = fire[:, tickers.get_loc(c)].astype(int)
+        best = cur = 0
+        for x in s:
+            cur = cur + 1 if x else 0
+            best = max(best, cur)
+        runs.append(best)
+    return {
+        "fires_per_day": float(act.mean()) if len(act) else 0.0,
+        "active_days_pct": float(len(act) / max(len(dates), 1) * 100),
+        "n_names": int(len(cnt)),
+        "top10_share": float(cnt.head(10).sum() / tot) if tot else np.nan,
+        "max_name_share": float(cnt.iloc[0] / len(dates)) if len(cnt) else np.nan,
+        "max_consecutive": int(max(runs)) if runs else 0,
+        "daily_turnover": float(np.mean(turn)) if turn else np.nan,
+        "top_names": cnt.head(8).to_dict(),
+    }
+
+
+def subperiod(values: np.ndarray, dates: pd.DatetimeIndex, lag: int = 21) -> dict:
+    """First half versus second half. If the signs differ the result depends on the period."""
+    values = np.asarray(values)
+    if len(values) == 0:
+        return {"front": {"mean_bp": np.nan, "t": np.nan, "n": 0},
+                "back": {"mean_bp": np.nan, "t": np.nan, "n": 0}, "sign_match": False}
+    mid = len(values) // 2
+    out = {}
+    for lab, sl in (("front", slice(0, mid)), ("back", slice(mid, len(values)))):
+        mu, _, t, n = newey_west_t(values[sl], lag=lag)
+        out[lab] = {"mean_bp": mu * 1e4 if np.isfinite(mu) else np.nan, "t": t, "n": n}
+    f, b = out["front"]["mean_bp"], out["back"]["mean_bp"]
+    out["sign_match"] = bool(np.isfinite(f) and np.isfinite(b) and (f > 0) == (b > 0))
+    return out
+
+
+def yearly(values: np.ndarray, dates: pd.DatetimeIndex, lag: int = 21) -> dict:
+    """Consistency across years."""
+    values = np.asarray(values)
+    if len(values) == 0:
+        return {"by_year": {}, "positive": 0, "total": 0, "positive_ratio": np.nan}
+    s = pd.Series(values, index=dates[: len(values)])
+    out, pos, tot = {}, 0, 0
+    for y, g in s.groupby(s.index.year):
+        if len(g) < 40:
+            continue
+        mu, _, t, n = newey_west_t(g.values, lag=lag)
+        out[int(y)] = {"mean_bp": mu * 1e4 if np.isfinite(mu) else np.nan, "t": t}
+        tot += 1
+        pos += int(np.isfinite(mu) and mu > 0)
+    return {"by_year": out, "positive": pos, "total": tot,
+            "positive_ratio": pos / tot if tot else np.nan}
+
+
+def oos_holdout(values: np.ndarray, dates: pd.DatetimeIndex,
+                months: int = 12, lag: int = 21) -> dict:
+    """OOS holdout: set the last N months aside and test on them.
+
+    With a small sample a low t is normal. To tell 'dead' from 'cannot be measured'
+    look at n_days as well.
+    """
+    values = np.asarray(values)
+    if len(values) == 0:
+        return {"IS": {"mean_bp": np.nan, "t": np.nan, "n": 0},
+                "OOS": {"mean_bp": np.nan, "t": np.nan, "n": 0},
+                "cutoff": None, "note": "no sample: firings are too rare or the universe is too small"}
+    d = dates[: len(values)]
+    cut = d[-1] - pd.DateOffset(months=months)
+    out = {}
+    for lab, m in (("IS", d <= cut), ("OOS", d > cut)):
+        v = values[m]
+        if len(v) < 30:
+            out[lab] = {"mean_bp": np.nan, "t": np.nan, "n": len(v)}
+            continue
+        mu, _, t, n = newey_west_t(v, lag=lag)
+        out[lab] = {"mean_bp": mu * 1e4 if np.isfinite(mu) else np.nan, "t": t, "n": n}
+    out["cutoff"] = str(cut.date())
+    return out
+
+
+def run_gates(daily_excess: np.ndarray, dates: pd.DatetimeIndex, *,
+              t_stat: float, net_bp: float, rho: float,
+              fire: np.ndarray | None = None, tickers: pd.Index | None = None,
+              cfg: GateConfig | None = None, lag: int = 21) -> dict:
+    """Pass every gate in order and record where the candidate dropped out."""
+    cfg = cfg or GateConfig()
+    thr = cfg.null_threshold if cfg.null_threshold is not None else cfg.fallback_t
+    res = {"config": asdict(cfg), "threshold": thr}
+    steps: list[tuple[str, bool, str]] = []
+
+    ok1 = abs(t_stat) > thr
+    steps.append(("G1 statistical threshold", ok1, f"|t|={abs(t_stat):.2f} vs {thr:.2f}"))
+
+    ok2 = (not cfg.require_net_positive) or (np.isfinite(net_bp) and net_bp > 0)
+    steps.append(("G2 net profit after costs", ok2, f"{net_bp:+.1f}bp"))
+
+    sp = subperiod(daily_excess, dates, lag=lag)
+    ok3 = (not cfg.require_subperiod_sign) or sp["sign_match"]
+    steps.append(("G3 sub-period sign", ok3,
+                  f"first {sp['front']['mean_bp']:+.1f} / second {sp['back']['mean_bp']:+.1f}"))
+
+    ok4 = np.isfinite(rho) and abs(rho) >= cfg.min_monotonicity
+    steps.append(("G4 decile monotonicity", ok4, f"rho={rho:+.2f}"))
+
+    yr = yearly(daily_excess, dates, lag=lag)
+    ok5 = np.isfinite(yr["positive_ratio"]) and yr["positive_ratio"] >= cfg.min_yearly_positive
+    steps.append(("G5 yearly consistency", ok5, f"{yr['positive']}/{yr['total']} years"))
+
+    st = None
+    if fire is not None and tickers is not None:
+        st = fire_structure(fire, dates, tickers)
+        ok6 = (st["max_name_share"] <= cfg.max_single_name_share
+               and st["daily_turnover"] >= cfg.min_turnover)
+        steps.append(("G6 firing structure", ok6,
+                      f"top name {st['max_name_share']*100:.1f}% | turnover {st['daily_turnover']*100:.1f}%"))
+
+    res["steps"] = [{"gate": g, "pass": bool(p), "detail": d} for g, p, d in steps]
+    res["passed"] = all(p for _, p, _ in steps)
+    res["failed_at"] = next((g for g, p, _ in steps if not p), None)
+    res["subperiod"], res["yearly"], res["structure"] = sp, yr, st
+    res["oos"] = oos_holdout(daily_excess, dates, lag=lag)
+    return res