beatnothing 0.2.0__py3-none-any.whl

beatnothing/__init__.py

@@ -0,0 +1,18 @@
+"""
+beatnothing: can your model beat doing nothing, after costs, without knowing the future?
+
+A small, reproducible benchmark harness for daily equity signals. Every contestant is
+scored through one identical engine against one bar: an equal weight position in the
+same point in time universe, held with no skill at all. The score is the Net Edge,
+the net Sharpe of the strategy minus the net Sharpe of doing nothing, with a paired
+bootstrap confidence interval so that noise cannot masquerade as alpha.
+"""
+from .canary import hindsight_universe, off_by_one, peek, truncation_test
+from .engine import Backtest, COST_BPS, TRADING_DAYS
+from .score import bootstrap_sharpe_diff, cost_grid, net_edge, probabilistic_sharpe, sharpe
+from .universe import Membership, coverage_report, start_end_table
+
+__version__ = "0.2.0"
+__all__ = ["Backtest", "COST_BPS", "TRADING_DAYS", "net_edge", "sharpe", "bootstrap_sharpe_diff",
+           "probabilistic_sharpe", "cost_grid", "Membership", "coverage_report", "start_end_table",
+           "peek", "off_by_one", "hindsight_universe", "truncation_test", "__version__"]

beatnothing/canary.py

@@ -0,0 +1,57 @@
+"""
+Leak canaries: contestants that cheat on purpose.
+
+Run them through your evaluation pipeline. If they do not score absurdly well,
+your pipeline is not measuring what you think it is. Verify the verifier.
+
+Also here: the truncation test that proves features are trailing only. Delete
+everything after a cutoff, recompute, and the surviving rows must be identical.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def peek(actual: pd.DataFrame) -> pd.DataFrame:
+    """Uses the return of t+1 as the prediction on t. The loudest possible leak."""
+    return actual.copy()
+
+
+def off_by_one(feature: pd.DataFrame) -> pd.DataFrame:
+    """A trailing feature shifted the wrong way (the classic misaligned index):
+    the value observed on t+1 is used on t."""
+    return feature.shift(-1)
+
+
+def hindsight_universe(actual: pd.DataFrame, top_n: int = 10) -> pd.DataFrame:
+    """Always long the `top_n` names with the highest realised return over the whole
+    window. Survivorship and selection bias in one line."""
+    total = (1 + actual.fillna(0)).prod()
+    winners = total.sort_values(ascending=False).index[:top_n]
+    pred = pd.DataFrame(0.0, index=actual.index, columns=actual.columns)
+    pred[winners] = 1.0
+    return pred
+
+
+def truncation_test(build_features, prices: pd.DataFrame, cutoff, keys=("Date", "Ticker"),
+                    atol: float = 1e-9) -> dict:
+    """
+    Prove features are trailing only. `build_features(prices)` must return a long
+    frame keyed by `keys`. Rows on or before `cutoff` must be identical whether or
+    not data after `cutoff` exists. The target column is excluded from the verdict
+    because it is the one deliberate forward look (it needs t+1 to exist).
+    """
+    full = build_features(prices)
+    trunc = build_features(prices[prices["Date"] <= pd.Timestamp(cutoff)])
+    full = full[full["Date"] <= pd.Timestamp(cutoff)]
+    merged = full.merge(trunc, on=list(keys), suffixes=("_full", "_trunc"))
+    cols = [c for c in full.columns if c not in keys]
+    worst = {}
+    for c in cols:
+        a = merged[f"{c}_full"].to_numpy(float)
+        b = merged[f"{c}_trunc"].to_numpy(float)
+        mask = np.isfinite(a) & np.isfinite(b)
+        worst[c] = float(np.max(np.abs(a[mask] - b[mask]))) if mask.any() else 0.0
+    return {"rows_compared": int(len(merged)), "max_abs_diff": worst,
+            "passed": bool(all(v <= atol for c, v in worst.items() if c != "target"))}

beatnothing/cli.py

@@ -0,0 +1,137 @@
+"""
+Command line entry point.
+
+    beatnothing score my_signal.parquet --actual data/actual_returns.parquet
+    beatnothing score my_weights.parquet --actual ... --kind weights --start 2022-01-01
+    beatnothing leaderboard [--track survivor48|pit] [--root PATH] [--n-boot 2000]
+    beatnothing pbo v1.parquet v2.parquet v3.parquet --actual data/pit/actual_returns_pit.parquet
+    beatnothing validate submissions_pit/my_model
+    beatnothing members 2008-09-15
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _score(args) -> int:
+    from .leaderboard import score_signal
+    res = score_signal(args.signal, args.actual, kind=args.kind, start=args.start, end=args.end,
+                       n_boot=args.n_boot, cost_bps=args.cost_bps, bars_path=args.bars)
+    keys = ["window", "days", "net_edge", "ci_low", "ci_high", "clears_bar", "net_sharpe", "bar_sharpe",
+            "edge_vs_investable", "ci_low_vs_investable", "ci_high_vs_investable", "clears_investable",
+            "investable_sharpe", "gross_sharpe", "net_sharpe_20bps", "sharpe_se", "psr_vs_zero",
+            "max_drawdown", "annual_turnover", "avg_exposure", "dollar_pnl"]
+    print(json.dumps({k: res[k] for k in keys if k in res}, indent=2, default=str))
+    verdict = "clears the bar" if res["clears_bar"] else "does not clear the bar"
+    print(f"\nNet Edge {res['net_edge']:+.2f} [{res['ci_low']:+.2f}, {res['ci_high']:+.2f}]: {verdict}.", file=sys.stderr)
+    return 0
+
+
+def _leaderboard(args) -> int:
+    from .leaderboard import main
+    board = main(args.actual, n_boot=args.n_boot, root=args.root, track=args.track)
+    print(f"scored {len(board['entries'])} submissions on the {args.track} track; leaderboard written")
+    return 0
+
+
+def _pbo(args) -> int:
+    import numpy as np
+    import pandas as pd
+    from .stats import deflated_sharpe, pbo_cscv
+    from .engine import Backtest, TRADING_DAYS
+    from .leaderboard import load_actual, load_signal
+
+    actual = load_actual(args.actual)
+    curves, names = [], []
+    for path in args.signals:
+        wide = load_signal(path)
+        bt = Backtest(actual, predictions=wide, rule=args.rule, quantile=args.quantile)
+        curves.append(bt.daily_returns.reindex(actual.index).fillna(0.0).values)
+        p = Path(path)
+        names.append(p.parent.name if p.stem == "signal" else p.stem)   # every submission file is signal.parquet
+    R = np.column_stack(curves)
+    res = pbo_cscv(R, n_splits=args.splits)
+    srs = R.mean(0) / R.std(0) * np.sqrt(TRADING_DAYS)
+    best = int(np.argmax(srs))
+    deflated = deflated_sharpe(R[:, best], n_trials=R.shape[1], sr_variance=float(np.var(srs, ddof=1)))
+    print(json.dumps({"variants": names, "best": names[best], "best_sharpe": round(float(srs[best]), 3),
+                      "probability_of_backtest_overfitting": round(res["pbo"], 3),
+                      "median_out_of_sample_rank": res["median_rank"], "combinations": res["n_combinations"],
+                      "deflated_sharpe": round(deflated["deflated_sharpe"], 3),
+                      "sharpe_the_search_alone_would_give": round(deflated["expected_max_sharpe"], 3)}, indent=2))
+    if res["pbo"] > 0.4:
+        print("\nAt this overfitting probability the best variant is roughly what searching alone would "
+              "produce. Submit the one you chose before looking, or none.", file=sys.stderr)
+    return 0
+
+
+def _validate(args) -> int:
+    from .leaderboard import TRACKS, load_actual
+    from .validate import validate_submission
+    folder = Path(args.folder)
+    track = next((t for t, c in TRACKS.items() if c["submissions"] in folder.parts), "survivor48")
+    actual_path = Path(args.actual) if args.actual else Path(TRACKS[track]["actual"])
+    actual = load_actual(actual_path) if actual_path.exists() else None
+    rep = validate_submission(folder, actual)
+    print(rep.render())
+    return 0 if rep.ok else 1
+
+
+def _members(args) -> int:
+    from .universe import Membership
+    members = sorted(Membership().on(args.date))
+    print(f"{len(members)} members on {args.date}")
+    print(" ".join(members))
+    return 0
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="beatnothing",
+                                 description="Can your model beat doing nothing, after costs, without knowing the future?")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("score", help="score one signal file against realised returns")
+    s.add_argument("signal", help="parquet with columns Date, Ticker, value")
+    s.add_argument("--actual", required=True, help="parquet with columns Date, Ticker, target (next day return)")
+    s.add_argument("--kind", choices=["predictions", "weights"], default="predictions")
+    s.add_argument("--start", default=None)
+    s.add_argument("--end", default=None)
+    s.add_argument("--n-boot", type=int, default=2000)
+    s.add_argument("--cost-bps", type=float, default=10.0)
+    s.add_argument("--bars", default=None, help="parquet with Date and RSP columns to also score against the investable bar")
+    s.set_defaults(func=_score)
+
+    lb = sub.add_parser("leaderboard", help="score every submission under a benchmark root")
+    lb.add_argument("--root", default=None)
+    lb.add_argument("--actual", default=None)
+    lb.add_argument("--n-boot", type=int, default=2000)
+    lb.add_argument("--track", choices=["survivor48", "pit"], default="survivor48")
+    lb.set_defaults(func=_leaderboard)
+
+    p = sub.add_parser("pbo", help="how much of your best variant was the search itself "
+                                   "(meaningful from about eight variants upward)")
+    p.add_argument("signals", nargs="+", help="one signal parquet per variant you tried")
+    p.add_argument("--actual", required=True)
+    p.add_argument("--rule", choices=["long_flat", "long_top", "long_short"], default="long_flat")
+    p.add_argument("--quantile", type=float, default=0.1)
+    p.add_argument("--splits", type=int, default=10)
+    p.set_defaults(func=_pbo)
+
+    v = sub.add_parser("validate", help="check a submission folder against the rules")
+    v.add_argument("folder")
+    v.add_argument("--actual", default=None)
+    v.set_defaults(func=_validate)
+
+    m = sub.add_parser("members", help="who was in the S&P 500 on a date")
+    m.add_argument("date")
+    m.set_defaults(func=_members)
+
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

beatnothing/data/SOURCE.md

@@ -0,0 +1,14 @@
+# Point in time S&P 500 membership
+
+Both files come from the MIT licensed repository https://github.com/fja05680/sp500
+(snapshot taken 17 September 2026).
+
+* `sp500_membership_by_date.csv` lists the full constituent set on every date the index
+  changed, from 1996 to 18 August 2026.
+* `sp500_ticker_start_end.csv` lists each ticker's entry and exit dates.
+* `still_listed_leavers.json` records which of the members on 31 December 2021 that later
+  left the index still returned prices from Yahoo Finance on 17 September 2026. The
+  complement (47 names) is the residual survivorship gap reported on the leaderboard page.
+
+The maintainer cross checks Wikipedia's change log every couple of months; early years
+are less reliable than recent ones, and the index rarely holds exactly 500 names.

beatnothing/data/still_listed_leavers.json

@@ -0,0 +1,49 @@
+[
+ "AAL",
+ "AAP",
+ "ALK",
+ "BBWI",
+ "BIO",
+ "BWA",
+ "CAG",
+ "CE",
+ "CPB",
+ "CZR",
+ "DXC",
+ "EMN",
+ "ENPH",
+ "EPAM",
+ "ETSY",
+ "FB",
+ "FISV",
+ "FMC",
+ "ILMN",
+ "INFO",
+ "IPGP",
+ "KMX",
+ "LKQ",
+ "LNC",
+ "LUMN",
+ "LW",
+ "MHK",
+ "MKTX",
+ "MTCH",
+ "NWL",
+ "OGN",
+ "PAYC",
+ "PENN",
+ "POOL",
+ "PVH",
+ "QRVO",
+ "RHI",
+ "SBNY",
+ "SEDG",
+ "TFX",
+ "UA",
+ "UAA",
+ "VFC",
+ "VNO",
+ "WHR",
+ "XRAY",
+ "ZION"
+]

beatnothing/data/ticker_aliases.json

@@ -0,0 +1,125 @@
+{
+  "_about": "Index members that changed ticker without ceasing to trade. The membership tables use the old symbol; a free price source holds the full history under the new one. Verified against Yahoo Finance on 2026 09 17 (history start date shown). Names that were acquired or went bankrupt are not here; those need an archive that keeps delisted histories.",
+  "ABC": {
+    "alias": "COR",
+    "history_from": "2005-01-03",
+    "note": "AmerisourceBergen renamed Cencora, 2023"
+  },
+  "ANTM": {
+    "alias": "ELV",
+    "history_from": "2005-01-03",
+    "note": "Anthem renamed Elevance Health, 2022"
+  },
+  "BLL": {
+    "alias": "BALL",
+    "history_from": "2005-01-03",
+    "note": "Ball Corporation ticker change, 2022"
+  },
+  "RE": {
+    "alias": "EG",
+    "history_from": "2005-01-03",
+    "note": "Everest Re renamed Everest Group, 2023"
+  },
+  "PEAK": {
+    "alias": "DOC",
+    "history_from": "2005-01-03",
+    "note": "Healthpeak ticker change after the Physicians Realty merger, 2024"
+  },
+  "PKI": {
+    "alias": "RVTY",
+    "history_from": "2005-01-03",
+    "note": "PerkinElmer renamed Revvity, 2023"
+  },
+  "NLOK": {
+    "alias": "GEN",
+    "history_from": "2005-01-03",
+    "note": "NortonLifeLock renamed Gen Digital, 2022"
+  },
+  "GPS": {
+    "alias": "GAP",
+    "history_from": "2005-01-03",
+    "note": "Gap ticker change, 2024"
+  },
+  "BK": {
+    "alias": "BNY",
+    "history_from": "2005-01-03",
+    "note": "Bank of New York Mellon ticker change, 2025"
+  },
+  "MMC": {
+    "alias": "MRSH",
+    "history_from": "2005-01-03",
+    "note": "Marsh McLennan ticker change"
+  },
+  "FLT": {
+    "alias": "CPAY",
+    "history_from": "2010-12-15",
+    "note": "FleetCor renamed Corpay, 2024"
+  },
+  "FBHS": {
+    "alias": "FBIN",
+    "history_from": "2011-09-16",
+    "note": "Fortune Brands Home and Security renamed Fortune Brands Innovations, 2022"
+  },
+  "WRK": {
+    "alias": "SW",
+    "history_from": "2008-06-17",
+    "note": "WestRock merged into Smurfit Westrock, 2024; Yahoo continues the series"
+  },
+  "DISCA": {
+    "alias": "WBD",
+    "history_from": "2005-07-08",
+    "note": "Discovery merged into Warner Bros. Discovery, 2022; Yahoo continues the series"
+  },
+  "DISCK": {
+    "alias": "WBD",
+    "history_from": "2005-07-08",
+    "note": "Discovery class C, same continuation as DISCA"
+  },
+  "FRC": {
+    "alias": "FRCB",
+    "history_from": "2010-12-09",
+    "note": "First Republic Bank after its 2023 failure; served under FRCB by Yahoo and Tiingo"
+  },
+  "SIVB": {
+    "alias": "SIVBQ",
+    "history_from": "2005-01-03",
+    "note": "SVB Financial after its 2023 failure; Tiingo serves the continued series under SIVB and SIVBQ, Yahoo has neither"
+  },
+  "HFC": {
+    "alias": "DINO",
+    "history_from": "2005-01-03",
+    "note": "HollyFrontier became HF Sinclair, 2022; Yahoo continues the series"
+  },
+  "WLTW": {
+    "alias": "WTW",
+    "history_from": "2005-01-03",
+    "note": "Willis Towers Watson ticker change, 2022"
+  },
+  "VIAC": {
+    "alias": "PARA",
+    "history_from": "2021-02-12",
+    "note": "ViacomCBS renamed Paramount Global, 2022; Yahoo holds PARA from February 2021, which covers every day VIAC was a member after 2021"
+  },
+  "ADS": {
+    "alias": "BFH",
+    "history_from": "2001-06-15",
+    "note": "Alliance Data Systems renamed Bread Financial, 2022"
+  },
+  "CTL": {
+    "alias": "LUMN",
+    "history_from": "2000-01-03",
+    "note": "CenturyLink renamed Lumen Technologies, 2020"
+  },
+  "TMK": {
+    "alias": "GL",
+    "history_from": "2000-01-03",
+    "note": "Torchmark renamed Globe Life, 2019"
+  },
+  "_rejected": {
+    "NYX": "acquired by Intercontinental Exchange in 2013; ICE is a different company, not a rename",
+    "CCE": "Coca-Cola Enterprises was split in 2010 and merged into Coca-Cola European Partners in 2016",
+    "ESV": "Ensco became Valaris, whose equity was wiped out in 2021; the VAL series is a new company",
+    "CBS": "CBS merged into ViacomCBS then Paramount; the PARA series begins in 2021",
+    "_note": "these pass a naive continuity test and are still wrong. A successor is only usable when it is the same legal entity renamed."
+  }
+}

beatnothing/engine.py

@@ -0,0 +1,132 @@
+"""
+One engine for every contestant.
+
+A contestant hands in either predictions (dates x tickers, any real number) or
+weights (dates x tickers). Predictions become positions by one of three fixed rules:
+
+    long_flat   equal weight long every name with a positive prediction, cash otherwise
+                (the default, and the rule of season one)
+    long_top    equal weight long the top `quantile` of names by prediction each day
+    long_short  long the top `quantile` and short the bottom `quantile`, equal weight
+                within each side, half the capital on each side, so the book is dollar
+                neutral and its gross exposure is one
+
+Weights are used as given. Long only unless `allow_short`, gross exposure never above
+one, no leverage. Every unit of turnover pays `cost_bps`, day one included, and every
+dollar held short pays `borrow_bps_annual` a year. Net numbers only.
+
+Deliberately simple: trades at the close, no market impact beyond the cost parameter,
+no short rebate. Simple enough that nobody can hide anything in it.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+COST_BPS = 10.0
+BORROW_BPS_ANNUAL = 50.0
+TRADING_DAYS = 252
+INITIAL_CAPITAL = 1_000_000.0
+RULES = ("long_flat", "long_top", "long_short")
+
+
+def _equal_weight(mask: pd.DataFrame) -> pd.DataFrame:
+    n = mask.sum(axis=1)
+    return mask.div(n.replace(0, np.nan), axis=0).fillna(0.0)
+
+
+def weights_from_predictions(predictions: pd.DataFrame, actual: pd.DataFrame, rule: str = "long_flat",
+                             quantile: float = 0.1) -> pd.DataFrame:
+    """Turn predictions into weights under one of the fixed rules, on names with a realised return."""
+    if rule not in RULES:
+        raise ValueError(f"rule must be one of {RULES}")
+    valid = actual.notna()
+    if rule == "long_flat":
+        return _equal_weight((predictions > 0) & valid)
+    # Ties are broken deterministically so that a decile rule always holds a decile. A
+    # signal with few distinct values, which is what an early stopped tree model produces,
+    # otherwise gives most names the same average rank, no name clears the threshold and
+    # the book sits empty: the rule would silently stop trading rather than say it cannot
+    # rank. Breaking ties by column order is arbitrary, and that is the honest reading of
+    # a signal that declines to distinguish those names; `beatnothing.validate` warns when
+    # a submission has too little resolution for the rule it asked for.
+    ranks = predictions.where(valid).rank(axis=1, pct=True, method="first")
+    longs = (ranks > 1 - quantile) & valid
+    if rule == "long_top":
+        return _equal_weight(longs)
+    shorts = (ranks <= quantile) & valid
+    return 0.5 * _equal_weight(longs) - 0.5 * _equal_weight(shorts)
+
+
+class Backtest:
+    """
+    Args:
+        actual:       realised next day simple returns (dates x tickers), aligned so
+                      that row t is the return earned from the close of t to t+1.
+        predictions:  contestant predictions (dates x tickers), or None if `weights` given.
+        weights:      contestant weights (dates x tickers); gross exposure at most 1.
+        rule:         how predictions become weights (see module docstring).
+        quantile:     fraction of names on each side for long_top and long_short.
+        cost_bps:     cost per unit of turnover, in basis points.
+        borrow_bps_annual: annual cost of every dollar held short.
+        allow_short:  accept negative weights (set automatically for long_short).
+    """
+
+    def __init__(self, actual: pd.DataFrame, predictions: pd.DataFrame | None = None,
+                 weights: pd.DataFrame | None = None, rule: str = "long_flat", quantile: float = 0.1,
+                 cost_bps: float = COST_BPS, borrow_bps_annual: float = BORROW_BPS_ANNUAL,
+                 allow_short: bool = False, capital: float = INITIAL_CAPITAL):
+        if (predictions is None) == (weights is None):
+            raise ValueError("pass exactly one of predictions or weights")
+        allow_short = allow_short or rule == "long_short"
+        if weights is None:
+            predictions, actual = predictions.align(actual, join="inner")
+            weights = weights_from_predictions(predictions, actual, rule, quantile)
+        else:
+            weights, actual = weights.align(actual, join="inner")
+            # no position in a name on a day it has no realised return (not a member, not listed)
+            weights = weights.fillna(0.0).where(actual.notna(), 0.0)
+            if not allow_short and (weights < -1e-12).any().any():
+                raise ValueError("weights must be non negative unless allow_short=True")
+            if (weights.abs().sum(axis=1) > 1.0 + 1e-9).any():
+                raise ValueError("gross exposure must be at most 1 on every day (no leverage)")
+        self.actual, self.weights, self.rule = actual, weights, rule
+        self.cost = cost_bps / 10_000
+        self.borrow = borrow_bps_annual / 10_000 / TRADING_DAYS
+        self.capital = capital
+        gross = (weights * actual.fillna(0.0)).sum(axis=1)
+        turnover = weights.diff().abs().sum(axis=1)
+        turnover.iloc[0] = weights.iloc[0].abs().sum()
+        short_exposure = weights.clip(upper=0).abs().sum(axis=1)
+        self.turnover = turnover
+        self.daily_costs = turnover * self.cost + short_exposure * self.borrow
+        self.daily_borrow = short_exposure * self.borrow
+        self.daily_returns = gross - self.daily_costs
+        self.equity = capital * (1 + self.daily_returns).cumprod()
+        self.drawdown = self.equity / self.equity.cummax() - 1.0
+
+    def stats(self) -> dict:
+        from .score import sharpe, max_drawdown
+        r = self.daily_returns
+        years = len(r) / TRADING_DAYS
+        total = self.equity.iloc[-1] / self.capital - 1
+        return {
+            "days": int(len(r)),
+            "rule": self.rule,
+            "total_return": float(total),
+            "annualized_return": float((1 + total) ** (1 / years) - 1) if years > 0 else float("nan"),
+            "annualized_vol": float(r.std() * np.sqrt(TRADING_DAYS)),
+            "net_sharpe": sharpe(r),
+            "max_drawdown": max_drawdown(self.equity),
+            "avg_exposure": float(self.weights.sum(axis=1).mean()),
+            "avg_gross_exposure": float(self.weights.abs().sum(axis=1).mean()),
+            "avg_short_exposure": float(self.weights.clip(upper=0).abs().sum(axis=1).mean()),
+            "avg_positions": float((self.weights != 0).sum(axis=1).mean()),
+            "annual_turnover": float(self.turnover.sum() / years) if years > 0 else float("nan"),
+            "total_costs": float((self.daily_costs * self.equity.shift(1).fillna(self.capital)).sum()),
+            "total_borrow": float((self.daily_borrow * self.equity.shift(1).fillna(self.capital)).sum()),
+            "dollar_pnl": float(self.equity.iloc[-1] - self.capital),
+        }
+
+    def monthly_returns(self) -> pd.Series:
+        return (1 + self.daily_returns).resample("ME").prod() - 1