btlab 0.3.0__py3-none-any.whl

btlab/__init__.py

@@ -0,0 +1,22 @@
+"""btlab: honest backtesting, with tools to detect look-ahead, survivorship and overfitting."""
+
+from btlab.data import synthetic_dollar_volume, synthetic_market
+from btlab.engine import BacktestResult, cost_sensitivity, rebalance_dates, run_backtest
+from btlab.metrics import (
+    annual_return, annual_vol, bootstrap_sharpe_ci, deflated_sharpe, expected_max_sharpe,
+    factor_attribution, max_drawdown, probabilistic_sharpe, sharpe, sortino, summary,
+)
+from btlab.strategies import CrossSectionalMomentum, Strategy, TimeSeriesMomentum
+from btlab.validation import (
+    WalkForwardResult, check_lookahead, effective_trials, probability_of_backtest_overfitting,
+    walk_forward,
+)
+
+__all__ = [
+    "BacktestResult", "CrossSectionalMomentum", "Strategy", "TimeSeriesMomentum",
+    "WalkForwardResult", "annual_return", "annual_vol", "bootstrap_sharpe_ci", "check_lookahead",
+    "cost_sensitivity", "deflated_sharpe", "effective_trials", "expected_max_sharpe",
+    "factor_attribution", "max_drawdown", "probabilistic_sharpe",
+    "probability_of_backtest_overfitting", "rebalance_dates", "run_backtest", "sharpe", "sortino",
+    "summary", "synthetic_dollar_volume", "synthetic_market", "walk_forward",
+]

btlab/data.py

@@ -0,0 +1,117 @@
+"""Synthetic markets with controllable signal, listings and delistings.
+
+Because the data-generating process is known, every claim a backtest makes
+can be checked: on a pure-noise market, no strategy should be significant.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+TRADING_DAYS = 252
+
+
+def synthetic_market(n_assets: int = 100, n_years: int = 10, momentum_strength: float = 0.0,
+                     momentum_half_life: int = 126, delist_rate: float = 0.0,
+                     delisting_return: float = -0.5, late_listing_frac: float = 0.0,
+                     seed: int | None = 0, start: str = "2014-01-01") -> pd.DataFrame:
+    """Daily prices (dates x assets) with NaN before listing and after delisting.
+
+    Returns = beta * market + mu_t + idiosyncratic noise, where mu_t is a
+    persistent AR(1) expected return with annualised cross-sectional standard
+    deviation `momentum_strength`. Past returns are informative about mu_t,
+    so momentum works exactly when momentum_strength > 0.
+
+    Firms that delist (annual hazard `delist_rate`) drift down for six months,
+    then suffer `delisting_return` on their final day.
+    """
+    rng = np.random.default_rng(seed)
+    n_days = TRADING_DAYS * n_years
+    dates = pd.bdate_range(start, periods=n_days)
+
+    vol = rng.uniform(0.20, 0.50, n_assets) / np.sqrt(TRADING_DAYS)
+    beta = rng.uniform(0.6, 1.4, n_assets)
+    market = rng.normal(0.07 / TRADING_DAYS, 0.15 / np.sqrt(TRADING_DAYS), n_days)
+
+    phi = 0.5 ** (1 / momentum_half_life)
+    mu_sd = momentum_strength / TRADING_DAYS
+    mu = np.zeros((n_days, n_assets))
+    mu[0] = rng.normal(0, mu_sd, n_assets)
+    shocks = rng.normal(0, mu_sd * np.sqrt(1 - phi**2), (n_days, n_assets))
+    for t in range(1, n_days):
+        mu[t] = phi * mu[t - 1] + shocks[t]
+
+    rets = beta * market[:, None] + mu + rng.standard_normal((n_days, n_assets)) * vol
+
+    alive = np.ones((n_days, n_assets), dtype=bool)
+    daily_hazard = 1 - (1 - delist_rate) ** (1 / TRADING_DAYS)
+    for j in range(n_assets):
+        if late_listing_frac and rng.random() < late_listing_frac:
+            alive[: rng.integers(1, int(0.6 * n_days)), j] = False
+        if delist_rate:
+            hits = np.flatnonzero(rng.random(n_days) < daily_hazard)
+            hits = hits[hits > 130]
+            if len(hits):
+                d = hits[0]
+                rets[d - 126:d, j] -= 0.4 / 126          # slow decline before failure
+                rets[d, j] = delisting_return
+                alive[d + 1:, j] = False
+
+    rets = np.clip(rets, -0.95, None)
+    rets[0] = 0.0
+    prices = 100 * np.cumprod(1 + rets, axis=0)
+    prices[~alive] = np.nan
+    return pd.DataFrame(prices, index=dates, columns=[f"A{j:03d}" for j in range(n_assets)])
+
+
+def synthetic_dollar_volume(prices: pd.DataFrame, median_adv: float = 2e7, size_dispersion: float = 1.0,
+                            seed: int | None = 0) -> pd.DataFrame:
+    """Daily traded value per asset: a lognormal firm size times lognormal daily noise.
+
+    Firm sizes span roughly two orders of magnitude around `median_adv`
+    (default $20m/day, a small/mid-cap stock), which is what makes capacity
+    depend on which names a strategy trades.
+    """
+    rng = np.random.default_rng(seed)
+    size = median_adv * np.exp(rng.normal(0, size_dispersion, prices.shape[1]))
+    noise = np.exp(rng.normal(-0.045, 0.3, prices.shape))     # mean-one daily variation
+    return pd.DataFrame(size * noise, index=prices.index, columns=prices.columns).where(prices.notna())
+
+
+FRENCH_URL = "https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/ftp/"
+
+
+def load_french_factors(start: str = "1990-01-01") -> pd.DataFrame:
+    """Daily US factors from Kenneth French's data library, as decimals.
+
+    Columns: Mkt-RF, SMB (size), HML (value), RF (T-bill), Mom (momentum).
+    """
+    import io
+    import urllib.request
+    import zipfile
+
+    frames = []
+    for name in ("F-F_Research_Data_Factors_daily_CSV.zip", "F-F_Momentum_Factor_daily_CSV.zip"):
+        with urllib.request.urlopen(FRENCH_URL + name, timeout=60) as resp:
+            zf = zipfile.ZipFile(io.BytesIO(resp.read()))
+        lines = zf.read(zf.namelist()[0]).decode("latin1").splitlines()
+        header = next(i for i, ln in enumerate(lines) if ln.startswith(","))
+        body = [ln for ln in lines[header + 1:] if ln[:8].isdigit()]
+        df = pd.read_csv(io.StringIO("\n".join(body)), header=None, index_col=0,
+                         names=["date"] + [c.strip() for c in lines[header].split(",")[1:]])
+        df.index = pd.to_datetime(df.index.astype(str), format="%Y%m%d")
+        frames.append(df)
+    out = pd.concat(frames, axis=1, join="inner").rename(columns={"MOM": "Mom"}) / 100
+    return out.loc[start:]
+
+
+def load_yfinance(tickers: list[str], start: str = "2005-01-01", end: str | None = None,
+                  field: str = "Close") -> pd.DataFrame:
+    """Adjusted prices (or field="Volume"). Today's ticker list is survivorship-biased for stocks."""
+    try:
+        import yfinance as yf
+    except ImportError as exc:
+        raise ImportError("install the data extra: pip install -e '.[data]'") from exc
+    data = yf.download(tickers, start=start, end=end, auto_adjust=True, progress=False)
+    return data[field].dropna(how="all")

btlab/engine.py

@@ -0,0 +1,154 @@
+"""Vectorised backtest engine with execution lag, drift, costs and delistings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from btlab import metrics
+
+
+def rebalance_dates(index: pd.DatetimeIndex, schedule: str | int = "M") -> pd.DatetimeIndex:
+    """'D' daily, 'W' last day of each week, 'M' last day of each month, or every n days."""
+    if isinstance(schedule, int):
+        return index[::schedule]
+    if schedule == "D":
+        return index
+    if schedule not in ("D", "W", "M"):
+        raise ValueError(f"rebalance must be 'D', 'W', 'M' or an int, got {schedule!r}")
+    if schedule == "W":
+        iso = index.isocalendar()                   # ISO year, not calendar year, at Dec/Jan
+        key = iso.week.to_numpy() + 100 * iso.year.to_numpy()
+    else:
+        key = np.asarray(index.month + 100 * index.year)
+    last = np.append(key[1:] != key[:-1], True)
+    return index[last]
+
+
+def listed_span(prices: pd.DataFrame) -> pd.DataFrame:
+    """True from an asset's first price to its last, including gaps such as trading halts."""
+    return prices.ffill().notna() & prices.bfill().notna()
+
+
+def asset_returns(prices: pd.DataFrame, delisting_return: float = 0.0) -> pd.DataFrame:
+    """Simple returns; a delisting day (price present, then NaN forever) gets `delisting_return`.
+
+    Returns across a gap (a halt) are booked on the day trading resumes.
+    """
+    rets = prices.ffill().where(listed_span(prices)).pct_change(fill_method=None)
+    listed_before = prices.shift(1).notna()
+    gone = prices.isna() & listed_before & prices[::-1].isna().cummin()[::-1]
+    rets = rets.mask(gone, delisting_return)
+    return rets.fillna(0.0)
+
+
+@dataclass
+class BacktestResult:
+    returns: pd.Series          # net daily returns
+    gross_returns: pd.Series
+    costs: pd.Series            # cost charged each day (fraction of NAV)
+    turnover: pd.Series         # one-way turnover at each rebalance
+    weights: pd.DataFrame       # executed weights at each rebalance
+
+    @property
+    def equity(self) -> pd.Series:
+        return (1 + self.returns).cumprod()
+
+    def summary(self) -> dict:
+        return metrics.summary(self.returns, self.turnover)
+
+
+def run_backtest(prices: pd.DataFrame, target_weights: pd.DataFrame, rebalance: str | int = "M",
+                 cost_bps: float = 5.0, slippage_bps: float = 0.0, execution_lag: int = 1,
+                 delisting_return: float = 0.0, dollar_volume: pd.DataFrame | None = None,
+                 capital: float = 1e8, impact_coef: float = 1.0,
+                 borrow_bps: float | pd.Series = 0.0) -> BacktestResult:
+    """Simulate trading `target_weights` (fractions of NAV, row t decided at close t).
+
+    * execution_lag=1 (default): weights decided at close t are traded at close
+      t+1. execution_lag=0 assumes you can trade at the same close the signal
+      used, which is optimistic with close-only data.
+    * Between rebalances, positions drift with their returns.
+    * Costs: (cost_bps + slippage_bps) per unit of one-way turnover.
+    * Market impact (only if `dollar_volume` is given): the square-root law,
+      impact_coef * daily_vol * sqrt(trade / ADV) per unit traded, with the
+      trade sized from `capital` and ADV the trailing 20-day mean dollar
+      volume. This is what makes a strategy's capacity finite.
+    * Borrow: short positions pay `borrow_bps` per year on their (drifting)
+      value, charged daily. Pass a Series for per-asset fees; hard-to-borrow
+      names can cost several hundred bps. Assets missing from it pay nothing.
+    * Assets that are not listed on a rebalance date cannot be bought; a
+      delisted position becomes cash. A position inside a price gap (a halt)
+      is held unchanged until prices resume.
+    """
+    target_weights = target_weights.reindex(index=prices.index, columns=prices.columns)
+    rets = asset_returns(prices, delisting_return)
+    listed = prices.notna()
+    halted = listed_span(prices).to_numpy() & ~listed.to_numpy()
+    targets = target_weights.shift(execution_lag)
+
+    dates = prices.index
+    rebal = [d for d in rebalance_dates(dates, rebalance) if targets.loc[d].notna().any()]
+    R = rets.to_numpy()
+    pos = {d: i for i, d in enumerate(dates)}
+    gross = np.zeros(len(dates))
+    costs = np.zeros(len(dates))
+    turnover, executed = {}, {}
+    w = np.zeros(prices.shape[1])
+    bps = (cost_bps + slippage_bps) / 1e4
+    borrow = pd.Series(borrow_bps, index=prices.columns, dtype=float).fillna(0.0).to_numpy() / 1e4 / 252
+    if dollar_volume is not None:
+        # ponytail: unknown vol or ADV (first days after listing) means zero impact
+        vol = rets.where(listed).rolling(63, min_periods=5).std().fillna(0.0).to_numpy()
+        # shift(1): the trade day's own volume is not known when the order is sized
+        adv = dollar_volume.reindex_like(prices).rolling(20, min_periods=1).mean().shift(1).to_numpy()
+
+    for j, d in enumerate(rebal):
+        i0 = pos[d]
+        alive = listed.iloc[i0].to_numpy()
+        w = np.where(alive | halted[i0], w, 0.0)            # delisted holdings are now cash
+        new = np.where(alive, targets.iloc[i0].fillna(0.0).to_numpy(), 0.0)
+        new = np.where(halted[i0], w, new)                  # halted holdings cannot be traded
+        trade = np.abs(new - w)
+        to = trade.sum()
+        turnover[d], executed[d] = to, new
+        costs[i0] += to * bps                               # += keeps that day's borrow fee
+        if dollar_volume is not None:
+            participation = np.divide(trade * capital, adv[i0], out=np.zeros_like(trade),
+                                      where=adv[i0] > 0)
+            costs[i0] += impact_coef * np.nansum(trade * vol[i0] * np.sqrt(participation))
+
+        i1 = pos[rebal[j + 1]] if j + 1 < len(rebal) else len(dates) - 1
+        if i1 > i0:
+            growth = np.cumprod(1 + R[i0 + 1:i1 + 1], axis=0)
+            nav = 1 + (growth - 1) @ new
+            gross[i0 + 1:i1 + 1] = nav / np.concatenate([[1.0], nav[:-1]]) - 1
+            if borrow.any():
+                start_of_day = new * np.vstack([np.ones_like(new), growth[:-1]]) \
+                    / np.concatenate([[1.0], nav[:-1]])[:, None]
+                costs[i0 + 1:i1 + 1] += np.clip(-start_of_day, 0, None) @ borrow
+            w = new * growth[-1] / nav[-1]
+        else:
+            w = new
+
+    idx = prices.index
+    return BacktestResult(
+        returns=pd.Series(gross - costs, idx, name="net"),
+        gross_returns=pd.Series(gross, idx, name="gross"),
+        costs=pd.Series(costs, idx, name="costs"),
+        turnover=pd.Series(turnover, name="turnover", dtype=float),
+        weights=pd.DataFrame(executed, index=prices.columns).T,
+    )
+
+
+def cost_sensitivity(prices: pd.DataFrame, target_weights: pd.DataFrame, bps_grid=(0, 2, 5, 10, 20, 30, 50),
+                     **kwargs) -> pd.DataFrame:
+    """Net Sharpe ratio across a grid of cost assumptions."""
+    rows = []
+    for bps in bps_grid:
+        res = run_backtest(prices, target_weights, cost_bps=bps, **kwargs)
+        rows.append({"cost_bps": bps, "sharpe": metrics.sharpe(res.returns),
+                     "annual_return": metrics.annual_return(res.returns)})
+    return pd.DataFrame(rows)

btlab/metrics.py

@@ -0,0 +1,171 @@
+"""Performance statistics, including multiple-testing-aware Sharpe ratio inference.
+
+References: Bailey & Lopez de Prado (2012) "The Sharpe Ratio Efficient
+Frontier" (PSR); Bailey & Lopez de Prado (2014) "The Deflated Sharpe Ratio".
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+PERIODS = 252
+EULER_GAMMA = 0.5772156649015329
+
+
+def _clean(r) -> np.ndarray:
+    r = np.asarray(r, dtype=float)
+    return r[np.isfinite(r)]
+
+
+def _trim_leading_zeros(r) -> np.ndarray:
+    r = _clean(r)
+    nz = np.flatnonzero(r)
+    return r[nz[0]:] if len(nz) else r[:0]
+
+
+def sharpe(r, periods: int = PERIODS) -> float:
+    r = _trim_leading_zeros(r)
+    sd = r.std(ddof=1) if len(r) > 1 else 0.0
+    # a constant series has sd 0 up to rounding error: treat that as undefined, not huge
+    return float(r.mean() / sd * np.sqrt(periods)) if sd > 0 and sd > 1e-9 * abs(r.mean()) else float("nan")
+
+
+def sortino(r, periods: int = PERIODS) -> float:
+    r = _trim_leading_zeros(r)
+    if not len(r):
+        return float("nan")
+    downside = np.sqrt(np.mean(np.minimum(r, 0.0) ** 2))
+    return float(r.mean() / downside * np.sqrt(periods)) if downside > 0 else float("nan")
+
+
+def annual_return(r, periods: int = PERIODS) -> float:
+    r = _trim_leading_zeros(r)
+    return float(np.prod(1 + r) ** (periods / len(r)) - 1) if len(r) else float("nan")
+
+
+def annual_vol(r, periods: int = PERIODS) -> float:
+    r = _trim_leading_zeros(r)
+    return float(r.std(ddof=1) * np.sqrt(periods)) if len(r) > 1 else float("nan")
+
+
+def max_drawdown(r) -> float:
+    equity = np.concatenate([[1.0], np.cumprod(1 + _clean(r))])   # the peak starts at 1, not day 1
+    return float(np.min(equity / np.maximum.accumulate(equity) - 1))
+
+
+def probabilistic_sharpe(r, sr_benchmark: float = 0.0, periods: int = PERIODS) -> float:
+    """P(true Sharpe > sr_benchmark), adjusting for sample length, skew and kurtosis.
+
+    Both Sharpe ratios are annualised at the interface and converted to
+    per-period internally, as the formula requires.
+    """
+    r = _trim_leading_zeros(r)
+    n = len(r)
+    if np.isnan(sharpe(r)):                                 # empty or constant: undefined
+        return float("nan")
+    sr = r.mean() / r.std(ddof=1)
+    sr_b = sr_benchmark / np.sqrt(periods)
+    skew, kurt = stats.skew(r), stats.kurtosis(r, fisher=False)
+    denom = np.sqrt(max(1 - skew * sr + (kurt - 1) / 4 * sr**2, 1e-12))
+    return float(stats.norm.cdf((sr - sr_b) * np.sqrt(n - 1) / denom))
+
+
+def expected_max_sharpe(n_trials: int, sharpe_std: float) -> float:
+    """Expected maximum Sharpe among n_trials skill-less strategies (annualised in, out)."""
+    if n_trials < 2:
+        return 0.0
+    return float(sharpe_std * ((1 - EULER_GAMMA) * stats.norm.ppf(1 - 1 / n_trials)
+                               + EULER_GAMMA * stats.norm.ppf(1 - 1 / (n_trials * np.e))))
+
+
+def deflated_sharpe(r, trial_sharpes, periods: int = PERIODS, n_trials: int | None = None) -> float:
+    """PSR against the Sharpe you'd expect from the best of N skill-less trials.
+
+    `trial_sharpes` are the annualised Sharpe ratios of every configuration
+    tried, including the one being evaluated. Correlated trials overstate N,
+    so by default (N = number of trials) this is conservative when
+    configurations are similar; pass `n_trials=validation.effective_trials(...)`
+    to count clusters of correlated configurations instead.
+    """
+    trial_sharpes = _clean(trial_sharpes)
+    n = len(trial_sharpes) if n_trials is None else n_trials
+    sr0 = expected_max_sharpe(n, trial_sharpes.std(ddof=1))
+    return probabilistic_sharpe(r, sr0, periods)
+
+
+def bootstrap_sharpe_ci(r, n_boot: int = 2000, mean_block: int = 20, alpha: float = 0.05,
+                        seed: int | None = 0, periods: int = PERIODS) -> tuple[float, float]:
+    """Stationary-bootstrap (Politis & Romano) confidence interval for the Sharpe ratio.
+
+    Random-length blocks preserve the autocorrelation and volatility
+    clustering that an i.i.d. bootstrap would destroy.
+    """
+    r = _trim_leading_zeros(r)
+    n = len(r)
+    if n < 2:
+        return float("nan"), float("nan")
+    rng = np.random.default_rng(seed)
+    starts = rng.integers(0, n, (n_boot, n))
+    new_block = rng.random((n_boot, n)) < 1 / mean_block
+    new_block[:, 0] = True
+    block_id = np.cumsum(new_block, axis=1) - 1
+    block_start = np.take_along_axis(starts, block_id, axis=1)
+    offset = np.arange(n)[None, :] - np.maximum.accumulate(np.where(new_block, np.arange(n), 0), axis=1)
+    sample = r[(block_start + offset) % n]
+    srs = sample.mean(axis=1) / sample.std(axis=1, ddof=1) * np.sqrt(periods)
+    return float(np.quantile(srs, alpha / 2)), float(np.quantile(srs, 1 - alpha / 2))
+
+
+def factor_attribution(r: pd.Series, factors: pd.DataFrame, periods: int = PERIODS,
+                       lags: int | None = None) -> pd.DataFrame:
+    """Regress returns on factor returns: how much is alpha, how much is beta?
+
+    OLS with Newey-West (HAC) standard errors, since daily strategy returns
+    are autocorrelated and heteroskedastic. `r` should be an excess return
+    (subtract the risk-free rate unless the strategy is self-financing, e.g.
+    long-short). Returns a table of coef and t_stat for alpha (annualised)
+    and each factor loading; R-squared and the number of observations are in
+    `.attrs["r2"]` and `.attrs["n_obs"]`.
+    """
+    r = pd.Series(r)
+    r = r.iloc[int(r.ne(0).to_numpy().argmax()):]                    # skip the warm-up
+    df = pd.concat([r.rename("_r"), factors], axis=1, join="inner").dropna()
+    y = df.pop("_r").to_numpy()
+    X = np.column_stack([np.ones(len(df)), df.to_numpy()])
+    n = len(y)
+    coef, *_ = np.linalg.lstsq(X, y, rcond=None)
+    resid = y - X @ coef
+
+    lags = int(4 * (n / 100) ** (2 / 9)) if lags is None else lags
+    xe = X * resid[:, None]
+    S = xe.T @ xe
+    for lag in range(1, lags + 1):
+        g = xe[lag:].T @ xe[:-lag]
+        S += (1 - lag / (lags + 1)) * (g + g.T)
+    bread = np.linalg.inv(X.T @ X)
+    se = np.sqrt(np.diag(bread @ S @ bread))
+
+    out = pd.DataFrame({"coef": coef, "t_stat": coef / se}, index=["alpha"] + list(df.columns))
+    out.loc["alpha", "coef"] *= periods
+    out.attrs["r2"] = float(1 - resid.var() / y.var())
+    out.attrs["n_obs"] = n
+    return out
+
+
+def summary(r, turnover: pd.Series | None = None, periods: int = PERIODS) -> dict:
+    out = {
+        "annual_return": annual_return(r, periods),
+        "annual_vol": annual_vol(r, periods),
+        "sharpe": sharpe(r, periods),
+        "sortino": sortino(r, periods),
+        "max_drawdown": max_drawdown(r),
+        "psr_vs_0": probabilistic_sharpe(r, 0.0, periods),
+        "sharpe_ci95": bootstrap_sharpe_ci(r, periods=periods),
+    }
+    traded = turnover[turnover > 0] if turnover is not None else []
+    if len(traded) and isinstance(r, pd.Series):
+        years = (r.index[-1] - traded.index[0]).days / 365.25   # from the first trade, not the warm-up
+        out["annual_turnover"] = float(traded.sum() / years) if years > 0 else float("nan")
+    return out

btlab/plotting.py

@@ -0,0 +1,108 @@
+"""Diagnostic plots (requires matplotlib)."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from btlab import metrics
+
+C = ["#4C72B0", "#DD8452", "#55A868", "#C44E52", "#8172B3"]
+
+
+def _style(ax):
+    ax.spines[["top", "right"]].set_visible(False)
+
+
+def plot_equity(series: dict[str, pd.Series], path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 6.5), sharex=True,
+                                   gridspec_kw={"height_ratios": [2.2, 1]})
+    styles = ["-", "--", ":", "-."]
+    for i, (name, r) in enumerate(series.items()):
+        eq = (1 + r).cumprod()
+        ax1.plot(eq.index, eq, styles[i % 4], color=C[i % 5], lw=1.6,
+                 label=f"{name} (Sharpe {metrics.sharpe(r):.2f})")
+        ax2.plot(eq.index, eq / eq.cummax() - 1, styles[i % 4], color=C[i % 5], lw=1.2)
+    ax1.set_ylabel("growth of 1")
+    ax1.legend(frameon=False)
+    ax2.set_ylabel("drawdown")
+    ax1.set_title(title, fontweight="bold", loc="left")
+    _style(ax1), _style(ax2)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def plot_trial_sharpes(trial_sharpes, expected_max: float, path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(9, 4.8))
+    ax.hist(trial_sharpes, bins=25, color=C[0], edgecolor="white", alpha=0.85)
+    best = float(np.nanmax(trial_sharpes))
+    ax.axvline(best, color=C[3], ls="-", lw=2, label=f"best trial: {best:.2f}")
+    ax.axvline(expected_max, color=C[1], ls="--", lw=2,
+               label=f"expected best of {len(trial_sharpes)} with zero skill: {expected_max:.2f}")
+    ax.set_xlabel("annualised Sharpe ratio (full sample)")
+    ax.set_ylabel("number of configurations")
+    ax.legend(frameon=False)
+    ax.set_title(title, fontweight="bold", loc="left")
+    _style(ax)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def plot_walk_forward(folds: pd.DataFrame, path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(10, 4.8))
+    x = np.arange(len(folds))
+    ax.bar(x - 0.2, folds["is_sharpe"], 0.4, color=C[0], label="in-sample (selected config)")
+    ax.bar(x + 0.2, folds["oos_sharpe"], 0.4, color=C[1], hatch="//", edgecolor="white",
+           label="out-of-sample (next year)")
+    ax.axhline(0, color="black", lw=0.8)
+    ax.set_xticks(x, [d.strftime("%Y") for d in folds["test_start"]])
+    ax.set_xlabel("test year")
+    ax.set_ylabel("annualised Sharpe")
+    ax.legend(frameon=False)
+    ax.set_title(title, fontweight="bold", loc="left")
+    _style(ax)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def plot_capacity(curves: dict[str, pd.DataFrame], path: str, title: str):
+    """Net Sharpe against fund size; each table has columns capital and sharpe."""
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 4.5))
+    for i, (name, t) in enumerate(curves.items()):
+        ax.plot(t["capital"], t["sharpe"], "os^D"[i % 4] + "-", color=C[i % 5], lw=2, label=name)
+    ax.set_xscale("log")
+    ax.axhline(0, color="black", lw=0.8)
+    ax.set_xlabel("capital ($, log scale)")
+    ax.set_ylabel("net annualised Sharpe")
+    ax.legend(frameon=False)
+    ax.set_title(title, fontweight="bold", loc="left")
+    _style(ax)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+
+
+def plot_cost_sensitivity(table: pd.DataFrame, path: str, title: str):
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(8, 4.5))
+    ax.plot(table["cost_bps"], table["sharpe"], "o-", color=C[0], lw=2)
+    ax.axhline(0, color="black", lw=0.8)
+    ax.set_xlabel("one-way trading cost (bps)")
+    ax.set_ylabel("net annualised Sharpe")
+    ax.set_title(title, fontweight="bold", loc="left")
+    _style(ax)
+    fig.tight_layout()
+    fig.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close(fig)

btlab/strategies.py

@@ -0,0 +1,70 @@
+"""Strategies map prices to target weights using only information up to each date.
+
+Convention: row t of `weights(prices)` is the portfolio decided at the close of
+day t. The engine is responsible for execution delay; strategies must never
+look past row t (verified by `validation.check_lookahead`).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+TRADING_DAYS = 252
+
+
+class Strategy(ABC):
+    @abstractmethod
+    def weights(self, prices: pd.DataFrame) -> pd.DataFrame: ...
+
+
+@dataclass(frozen=True)
+class CrossSectionalMomentum(Strategy):
+    """Rank assets on return from t-lookback to t-skip; long top, short bottom quantile.
+
+    The classic 12-1 momentum is lookback=252, skip=21: skipping the latest
+    month avoids the short-term reversal effect.
+    """
+
+    lookback: int = 252
+    skip: int = 21
+    quantile: float = 0.2
+    long_short: bool = True
+    min_assets: int = 10
+
+    def weights(self, prices: pd.DataFrame) -> pd.DataFrame:
+        logp = np.log(prices)
+        score = logp.shift(self.skip) - logp.shift(self.lookback)
+        score = score.where(prices.notna())
+        n_valid = score.notna().sum(axis=1)
+        rank = score.rank(axis=1, pct=True)
+        long = (rank > 1 - self.quantile).astype(float)
+        w = long.div(long.sum(axis=1).replace(0, np.nan), axis=0)
+        if self.long_short:
+            short = (rank <= self.quantile).astype(float)
+            w = 0.5 * w - 0.5 * short.div(short.sum(axis=1).replace(0, np.nan), axis=0)
+        w[n_valid < self.min_assets] = 0.0
+        return w.fillna(0.0)
+
+
+@dataclass(frozen=True)
+class TimeSeriesMomentum(Strategy):
+    """Each asset long/short by the sign of its own trailing return, scaled to a vol target."""
+
+    lookback: int = 252
+    vol_lookback: int = 63
+    target_vol: float = 0.10
+    max_weight: float = 0.25
+
+    def weights(self, prices: pd.DataFrame) -> pd.DataFrame:
+        logp = np.log(prices)
+        signal = np.sign(logp - logp.shift(self.lookback))
+        rets = prices.pct_change(fill_method=None)
+        asset_vol = rets.rolling(self.vol_lookback, min_periods=self.vol_lookback // 2).std() * np.sqrt(TRADING_DAYS)
+        n_valid = signal.notna().sum(axis=1).replace(0, np.nan)
+        w = signal * (self.target_vol / asset_vol)
+        w = w.div(n_valid, axis=0).clip(-self.max_weight, self.max_weight)
+        return w.where(prices.notna()).fillna(0.0)

btlab/validation.py

@@ -0,0 +1,160 @@
+"""Guards against the two most common backtest failures: look-ahead and overfitting."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import combinations
+
+import numpy as np
+import pandas as pd
+from scipy.cluster.hierarchy import fcluster, linkage
+from scipy.spatial.distance import squareform
+
+from btlab import metrics
+from btlab.engine import run_backtest
+from btlab.strategies import Strategy
+
+
+def check_lookahead(strategy: Strategy, prices: pd.DataFrame, n_cutoffs: int = 5,
+                    seed: int | None = 0, tol: float = 1e-10) -> tuple[bool, float]:
+    """Truncation test: weights up to date c must not change when data after c is removed.
+
+    Returns (passed, max_abs_difference). Any difference means the strategy
+    used information from the future. A weight that is NaN in one run but
+    not the other (typical of a `shift(-1)` peek) counts as infinite.
+    """
+    rng = np.random.default_rng(seed)
+    full = strategy.weights(prices)
+    worst = 0.0
+    lo = len(prices) // 4
+    for c in sorted(rng.integers(lo, len(prices) - 1, n_cutoffs)):
+        a = full.iloc[:c + 1].to_numpy(dtype=float)
+        b = strategy.weights(prices.iloc[:c + 1]).reindex_like(full.iloc[:c + 1]).to_numpy(dtype=float)
+        diff = np.where(np.isnan(a) != np.isnan(b), np.inf, np.abs(a - b))
+        worst = max(worst, float(np.nanmax(diff, initial=0.0)))
+    return worst <= tol, worst
+
+
+@dataclass
+class WalkForwardResult:
+    oos_returns: pd.Series
+    folds: pd.DataFrame
+    trial_returns: pd.DataFrame       # every configuration's full-history returns
+    params: list[dict]
+
+    @property
+    def trial_sharpes(self) -> pd.Series:
+        return self.trial_returns.apply(metrics.sharpe)
+
+    @property
+    def best_in_sample(self) -> int:
+        return int(self.trial_sharpes.idxmax())
+
+
+def walk_forward(prices: pd.DataFrame, strategy_cls: type[Strategy], param_grid: list[dict],
+                 train_days: int = 756, test_days: int = 252, expanding: bool = True,
+                 select=metrics.sharpe, **backtest_kwargs) -> WalkForwardResult:
+    """Choose parameters on each training window, then trade them on the next test window.
+
+    Every configuration is backtested once over the full history (strategies
+    are causal, so this is equivalent to re-running up to each date) to score
+    the training windows. The out-of-sample series is then one backtest of
+    the stitched weights: the config chosen at the close of each training
+    window's last day is traded from the next rebalance on, so entering the
+    first fold and switching configs later pay trading costs like any other
+    trade. It is the honest estimate of what the selection procedure would
+    have delivered.
+    """
+    trials = {}
+    for i, p in enumerate(param_grid):
+        w = strategy_cls(**p).weights(prices)
+        trials[i] = run_backtest(prices, w, **backtest_kwargs).returns
+    R = pd.DataFrame(trials)
+
+    start = R.index.get_loc(_trim_warmup(R).index[0])
+    folds, chosen_weights = [], {}
+    stitched = pd.DataFrame(0.0, index=prices.index, columns=prices.columns)
+    train_end = start + train_days
+    while train_end < len(R):
+        test_end = min(train_end + test_days, len(R))
+        train_start = start if expanding else train_end - train_days
+        scores = R.iloc[train_start:train_end].apply(select)
+        best = int(scores.idxmax())
+        if best not in chosen_weights:
+            chosen_weights[best] = strategy_cls(**param_grid[best]).weights(prices)
+        stitched.iloc[train_end - 1:] = chosen_weights[best].iloc[train_end - 1:]  # later folds overwrite
+        folds.append({
+            "train_start": R.index[train_start], "test_start": R.index[train_end],
+            "test_end": R.index[test_end - 1], "chosen": best, "params": param_grid[best],
+            "is_sharpe": scores[best],
+        })
+        train_end = test_end
+    if not folds:
+        raise ValueError(f"no test window: {len(R) - start} trading days after warm-up, "
+                         f"train_days={train_days}")
+
+    folds = pd.DataFrame(folds)
+    oos = run_backtest(prices, stitched, **backtest_kwargs).returns.loc[folds["test_start"].iloc[0]:]
+    folds["oos_sharpe"] = [metrics.sharpe(oos.loc[a:b]) for a, b in zip(folds["test_start"], folds["test_end"])]
+    return WalkForwardResult(oos, folds, R, param_grid)
+
+
+def _trim_warmup(trial_returns: pd.DataFrame) -> pd.DataFrame:
+    """Drop the leading rows before every configuration has started trading."""
+    return trial_returns.loc[trial_returns.ne(0).idxmax().max():]
+
+
+def probability_of_backtest_overfitting(trial_returns: pd.DataFrame, n_splits: int = 16
+                                        ) -> tuple[float, np.ndarray]:
+    """Combinatorially symmetric cross-validation (Bailey, Borwein, Lopez de Prado & Zhu, 2017).
+
+    The history is cut into `n_splits` blocks. For every way of choosing half
+    of them as in-sample, the best in-sample configuration is located in the
+    out-of-sample ranking. PBO is the fraction of splits in which it lands in
+    the bottom half. Pure noise gives PBO ~ 0.5; a genuine edge gives ~ 0.
+
+    Returns (pbo, logits), where logit > 0 means the in-sample winner
+    beat the out-of-sample median.
+    """
+    if n_splits % 2:
+        raise ValueError("n_splits must be even")
+    R = _trim_warmup(trial_returns).to_numpy()
+    n_trials = R.shape[1]
+    blocks = np.array_split(R, n_splits)
+    s1 = np.array([b.sum(axis=0) for b in blocks])        # per-block sums: Sharpe of any
+    s2 = np.array([(b**2).sum(axis=0) for b in blocks])   # union of blocks follows exactly
+    n = np.array([len(b) for b in blocks], dtype=float)
+
+    is_mask = np.array([np.isin(np.arange(n_splits), c)
+                        for c in combinations(range(n_splits), n_splits // 2)], dtype=float)
+
+    def _sr(mask):
+        cnt = (mask @ n)[:, None]
+        mean = (mask @ s1) / cnt
+        var = ((mask @ s2) - cnt * mean**2) / (cnt - 1)
+        return mean / np.sqrt(np.maximum(var, 1e-300))
+
+    is_sr, oos_sr = _sr(is_mask), _sr(1 - is_mask)
+    best = is_sr.argmax(axis=1)
+    oos_best = oos_sr[np.arange(len(best)), best][:, None]
+    rank = (oos_sr < oos_best).sum(axis=1) + 0.5 * ((oos_sr == oos_best).sum(axis=1) + 1)
+    omega = rank / (n_trials + 1)
+    logits = np.log(omega / (1 - omega))
+    return float(np.mean(logits <= 0)), logits
+
+
+def effective_trials(trial_returns: pd.DataFrame, min_corr: float = 0.5) -> int:
+    """Number of clusters of configurations whose returns correlate above `min_corr`.
+
+    45 momentum variants are not 45 independent experiments. Passing this as
+    `n_trials` to `deflated_sharpe` gives a less conservative, more accurate
+    multiple-testing correction. Average-linkage hierarchical clustering on
+    the distance sqrt((1 - corr) / 2).
+    """
+    if trial_returns.shape[1] < 2:
+        return trial_returns.shape[1]
+    corr = _trim_warmup(trial_returns).corr().fillna(0.0).to_numpy()
+    dist = np.sqrt(np.clip(0.5 * (1 - corr), 0, None))
+    np.fill_diagonal(dist, 0.0)
+    tree = linkage(squareform(dist, checks=False), "average")
+    return int(fcluster(tree, np.sqrt(0.5 * (1 - min_corr)), "distance").max())

btlab-0.3.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: btlab
+Version: 0.3.0
+Summary: A backtesting framework built around avoiding the common ways backtests lie
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hossainyousuf751/backtest-lab
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: data
+Requires-Dist: yfinance>=0.2; extra == "data"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Dynamic: license-file
+
+# backtest-lab
+
+![tests](https://github.com/hossainyousuf751/backtest-lab/actions/workflows/ci.yml/badge.svg)
+
+A backtesting framework built around one question: **should you believe this backtest?**
+
+Most backtests that look good are wrong for one of a handful of reasons: look-ahead bias,
+survivorship bias, ignored trading costs and capacity, returns that are really just factor
+exposure, or picking the best of many configurations and reporting it as if it were the only one. This project builds the tools to detect each of
+these, and validates them on synthetic markets where the true answer is known.
+
+```bash
+pip install -e ".[dev]"
+pytest
+cd examples && python 01_overfitting.py && python 02_survivorship.py && python 03_planted_signal.py && python 05_capacity.py
+pip install -e "..[data]" && python 04_live_sector_momentum.py   # needs internet: Yahoo Finance + Ken French
+```
+
+## Design
+
+| Module | What it does |
+|---|---|
+| `strategies.py` | Strategies return target weights; row *t* is decided at the close of day *t* |
+| `engine.py` | Execution lag, drift between rebalances, turnover-based costs, square-root market impact, delistings, point-in-time universe |
+| `validation.py` | Truncation test for look-ahead bias; walk-forward selection; Probability of Backtest Overfitting (CSCV); effective number of trials |
+| `metrics.py` | Sharpe, Sortino, drawdown, Probabilistic and Deflated Sharpe ratios, block-bootstrap CIs, factor attribution with Newey-West t-stats |
+| `data.py` | Synthetic markets with controllable signal, listings, delistings and traded volume; Yahoo Finance and Ken French factor loaders |
+
+**Timing is explicit.** With close-only data, weights decided at the close of day *t* are
+traded at the close of *t+1* by default (`execution_lag=1`). Positions then drift with
+returns until the next rebalance, so turnover and costs are measured on what the portfolio
+actually holds, not on idealised constant weights.
+
+**Look-ahead is tested, not assumed.** `check_lookahead` recomputes a strategy's weights
+on data truncated at random dates and requires them to match the full-history weights.
+The test suite includes a deliberately cheating strategy: the engine reports a Sharpe
+above 10 for it with zero execution lag, which is why the truncation test, not the engine,
+is the line of defence.
+
+**Walk-forward is a real backtest.** The out-of-sample series trades the stitched weights of
+each fold's chosen configuration, so entering the market and switching configurations pay costs.
+
+**Point-in-time universes need no special engine support.** Mask what the *strategy* sees, not
+the prices the *engine* trades on:
+
+```python
+weights = strategy.weights(prices.where(index_membership))   # rank only current members
+result = run_backtest(prices, weights)                       # exits sold at real prices
+```
+
+Masking the engine's prices instead would turn every index deletion into a fake delisting.
+
+## Study 1: overfitting and luck
+
+On 30 independent markets with **no signal**, 12-1 momentum has a mean Sharpe of +0.01
+but a standard deviation of 0.33, matching the theoretical 1/√years. Twelve years of noise
+routinely produces Sharpe ratios of ±0.6.
+
+On the luckiest of 12 noise markets (deliberately chosen, as a researcher who stops at the
+first good result would), a search over 45 momentum configurations finds:
+
+| Measure | Value | Verdict |
+|---|---|---|
+| Best full-sample Sharpe | 0.86 | looks like a discovery |
+| Probabilistic Sharpe vs 0 | 0.997 | "significant" (ignores the search) |
+| **Deflated Sharpe** | **0.92** | not significant at 95% once 45 trials are accounted for |
+| Deflated Sharpe, N = 2 effective trials | 0.99 | **fooled**: the 45 configs are really ~2 independent bets |
+| Probability of Backtest Overfitting | 0.34 | **fooled**: the in-sample winner usually stays above median |
+| Walk-forward out-of-sample Sharpe | 0.82 | **fooled**: the whole sample is lucky, not just the selection |
+| Chosen config on 20 fresh noise markets | +0.00 | the truth |
+
+![Trial Sharpes](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/overfitting_trials.png)
+
+The lesson is that every in-sample defence (DSR, PBO, walk-forward) protects against
+*selection* bias but not against a lucky *sample*. Only independent data (other markets,
+periods, or asset classes) does that.
+
+The two refinements cut in opposite directions. Counting all 45 near-duplicate configurations as
+independent trials makes the Deflated Sharpe too strict; clustering them (`effective_trials`)
+is more accurate, but it removes the margin that rejected this lucky sample. The cluster count also
+depends on the correlation threshold: here it is 1, 2, 10 and 35 at ρ > 0.3, 0.5, 0.7 and 0.9.
+The threshold-free eigenvalue participation ratio is about 3, which supports the 0.5 default.
+
+## Study 2: survivorship bias
+
+150 firms are listed over 12 years; 57 fail, after a decline, with a −50% final return.
+Testing only on the 93 survivors:
+
+| Strategy | Point-in-time universe | Survivors only |
+|---|---|---|
+| Equal-weight: annual return | 9.3% | **12.8%** |
+| Equal-weight: Sharpe | 0.67 | 0.88 |
+| Long-only momentum: annual return | 16.1% | 15.6% |
+
+The bias is large for strategies that would have held the failures, and nearly absent for
+momentum, which sells declining firms before they delist. The engine handles this correctly:
+assets cannot be bought before listing, and delisted holdings become cash.
+
+![Survivorship](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/survivorship.png)
+
+## Study 3: a genuine signal, and what costs leave of it
+
+With a planted persistent-return effect, every check agrees the signal is real: the
+look-ahead test passes, the Deflated Sharpe is 0.996 (1.000 with effective N = 2), and walk-forward
+out-of-sample Sharpe, after the costs of switching configuration, is 1.01 against 1.06 in the full sample.
+
+PBO is 0.54, no better than on noise, and that is the correct answer to a narrower question.
+PBO asks whether picking the in-sample winner *among these configurations* beats picking one at
+random. All 45 variants capture the same signal, so choosing among them adds nothing. A high PBO
+says "don't trust the tuning", not "there is no edge".
+
+Factor attribution against the market (equal-weight index) separates the edge from exposure:
+
+| | Alpha | t-stat | Market beta | R² |
+|---|---|---|---|---|
+| Long-short momentum | 6.1%/yr | 3.3 | 0.01 | 0.00 |
+| Long-only momentum | 6.8%/yr | 3.0 | 1.03 | 0.82 |
+
+The long-only version earns 16%/yr in raw terms, but most of that is beta.
+
+The remaining question is economic. At ~6.4× annual turnover, net Sharpe falls from 1.11
+gross to 0.79 at 30 bps and 0.58 at 50 bps. Borrowing the short leg costs more: a 50 bps/yr
+general-collateral fee takes Sharpe from 1.06 to 1.01, and a 300 bps/yr hard-to-borrow fee takes it to 0.80.
+
+![Cost sensitivity](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/planted_costs.png)
+
+## Study 4: real data
+
+`04_live_sector_momentum.py` runs long-short momentum across the 11 SPDR sector ETFs since
+2000. Sector ETFs are a deliberately survivorship-free universe; late launches (XLRE, XLC)
+enter only once listed. For single stocks, a point-in-time constituent list is required.
+
+Over 2000 to October 2026, the result at 3 bps is a Sharpe of 0.12 (95% CI −0.23 to 0.47), and it
+is gone by 20 bps. Regressed on the Fama-French factors plus momentum:
+
+| | Coef | Newey-West t |
+|---|---|---|
+| Alpha | −0.5%/yr | −0.4 |
+| Market | 0.02 | 2.0 |
+| Size (SMB) | −0.02 | −1.3 |
+| Value (HML) | −0.08 | −5.5 |
+| **Momentum** | **0.40** | **39.6** |
+
+R² is 0.58. Sector momentum is not a new strategy: it is a weak, diluted copy of the stock-level
+momentum factor, which you could hold directly.
+
+![Sector momentum](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/live_sector_momentum.png)
+
+## Study 5: capacity
+
+Flat basis-point costs ignore size. `run_backtest(..., dollar_volume=, capital=)` adds
+square-root market impact, charging `σ_daily × √(trade / ADV)` per unit traded. On the Study 3
+market, with a median stock trading $20m/day:
+
+| Capital | Net Sharpe, monthly | Net Sharpe, quarterly | Cost/yr, monthly |
+|---|---|---|---|
+| $1m | 0.96 | 0.94 | 0.8% |
+| $10m | 0.76 | 0.82 | 1.9% |
+| $100m | 0.13 | 0.43 | 5.3% |
+| $300m | −0.49 | 0.06 | 8.9% |
+| $1bn | −1.41 | −0.52 | 16.1% |
+
+The edge that survives 30 bps of flat costs is gone by about $150m. Rebalancing quarterly
+gives up a little at small size but roughly doubles capacity. The square-root law is
+calibrated for trades below about 10–20% of daily volume, so the far right of the curve
+(where trades exceed ADV) is indicative only.
+
+![Capacity](https://raw.githubusercontent.com/hossainyousuf751/backtest-lab/main/docs/capacity.png)
+
+## Roadmap
+
+- [x] **M1** Engine, strategies, look-ahead test, walk-forward, PSR/DSR, bootstrap CIs, four studies
+- [x] **M2** Probability of Backtest Overfitting via combinatorially symmetric cross-validation
+- [x] **M3** Effective number of trials (cluster correlated configurations) for a sharper DSR
+- [x] **M4** Realistic costs: spread plus square-root market impact as a function of trade size and volume
+- [x] **M5** Factor attribution: regress returns on market, size, value and momentum factors to separate alpha from beta
+- [x] **M6** Walk-forward pays to switch configuration; borrow fees on shorts; point-in-time universe recipe
+
+A real-data single-stock study remains out of scope: free sources such as Yahoo Finance drop
+delisted tickers, so it needs a survivorship-free database (e.g. CRSP or Norgate) plus
+historical index membership.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the project's invariants, roles, workflow and
+testing rules, and [CHANGELOG.md](CHANGELOG.md) for what changed between versions.
+
+## References
+
+- Bailey, D. & López de Prado, M. (2012). The Sharpe Ratio Efficient Frontier. *Journal of Risk* 15(2).
+- Bailey, D. & López de Prado, M. (2014). The Deflated Sharpe Ratio. *Journal of Portfolio Management* 40(5).
+- Bailey, D., Borwein, J., López de Prado, M. & Zhu, Q. (2017). The Probability of Backtest Overfitting. *Journal of Computational Finance* 20(4).
+- Politis, D. & Romano, J. (1994). The Stationary Bootstrap. *JASA* 89(428).
+- Jegadeesh, N. & Titman, S. (1993). Returns to Buying Winners and Selling Losers. *Journal of Finance* 48(1).
+- López de Prado, M. & Lewis, M. (2019). Detection of False Investment Strategies Using Unsupervised Learning Methods. *Quantitative Finance* 19(9).
+- Almgren, R., Thum, C., Hauptmann, E. & Li, H. (2005). Direct Estimation of Equity Market Impact. *Risk* 18(7).
+- Newey, W. & West, K. (1987). A Simple, Positive Semi-Definite, Heteroskedasticity and Autocorrelation Consistent Covariance Matrix. *Econometrica* 55(3).
+- Fama, E. & French, K. (1993). Common Risk Factors in the Returns on Stocks and Bonds. *Journal of Financial Economics* 33(1).
+- Carhart, M. (1997). On Persistence in Mutual Fund Performance. *Journal of Finance* 52(1).

btlab-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+btlab/__init__.py,sha256=bPBc9PxMx_dIyjSHu9j5XiTi39yMkPlwQ8Fo685mfSU,1209
+btlab/data.py,sha256=hJZAHdiPhQNz-P7fqRfISCPN7h-Z-GmEGHmby1OW5zw,5299
+btlab/engine.py,sha256=Hn85qR9hlqcSyehXaouIwF1Rk6BKZ-Y9lCvjmjaACVs,7270
+btlab/metrics.py,sha256=6OoJUko2hEfJXZdjdPsSS6mxT7RWH6hbtYDjxHdui5Y,7105
+btlab/plotting.py,sha256=A_CJ769Evt7BYJw4-nFJ4kPydqhuS9DxQCVuDgxuJsw,4021
+btlab/strategies.py,sha256=1hnPpKOVK4PPJLj9uRVYJM1tJssueRpLA2IuRVw_niM,2478
+btlab/validation.py,sha256=yUqL4ONkOuXinWoMfzvHFP4C7m6FdT4_pqdH9ovrvqU,7216
+btlab-0.3.0.dist-info/licenses/LICENSE,sha256=OAV_RTERHYKJrtHIxvr_VWUiM6k-1PKksx8ezi9wMmY,1079
+btlab-0.3.0.dist-info/METADATA,sha256=pShPqdp1XxlOIJ2Q-8CNE01XC6TyW75Kd4fs84Pq_4g,11788
+btlab-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+btlab-0.3.0.dist-info/top_level.txt,sha256=i3k1OKsUPFcLG3qVwtlEjSxAnAIIYcLHwQBHj6udjt4,6
+btlab-0.3.0.dist-info/RECORD,,

btlab-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

btlab-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousuf Hossain Shafeen
+
+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.

btlab-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+btlab