factor-qc 0.1.0__py3-none-any.whl

factor_qc/__init__.py

@@ -0,0 +1,34 @@
+"""factor-qc: fail-closed quality gate for backtests.
+
+One numpy-only engine for the standard backtest-overfit statistics —
+Deflated Sharpe Ratio, Probability of Backtest Overfitting (CSCV),
+Harvey-Liu multiple-testing haircut, Minimum Track Record Length — wrapped
+in a gate that refuses to judge a backtest that does not declare how many
+configurations were tried.
+"""
+
+from .gate import run_gate
+from .stats import (
+    build_check_artifact,
+    build_overfit_report,
+    deflated_sharpe_ratio,
+    haircut_sharpe,
+    minimum_track_record_length,
+    probability_of_backtest_overfitting,
+    sharpe_ratio,
+    skew_kurt,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "build_check_artifact",
+    "build_overfit_report",
+    "deflated_sharpe_ratio",
+    "haircut_sharpe",
+    "minimum_track_record_length",
+    "probability_of_backtest_overfitting",
+    "run_gate",
+    "sharpe_ratio",
+    "skew_kurt",
+]

factor_qc/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

factor_qc/cli.py

@@ -0,0 +1,114 @@
+"""Command-line interface for factor-qc.
+
+Subcommands:
+
+- ``check``   run the fail-closed gate on a returns series
+- ``version`` print version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from . import __version__
+from .gate import run_gate
+
+
+def _load_returns(path: str) -> np.ndarray:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, list) or not all(isinstance(x, (int, float)) for x in value):
+        raise ValueError(f"returns must be a JSON list of numbers: {path}")
+    return np.asarray(value, dtype=float)
+
+
+def _load_trials(path: str) -> np.ndarray:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, list) or not value:
+        raise ValueError(f"trials must be a non-empty JSON list of lists: {path}")
+    rows = []
+    for row in value:
+        if not isinstance(row, list):
+            raise ValueError(f"trials rows must be lists: {path}")
+        rows.append([float(x) for x in row])
+    matrix = np.asarray(rows, dtype=float)
+    if matrix.ndim != 2:
+        raise ValueError(f"trials must be 2D (T x N): {path}")
+    return matrix
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="qc",
+        description="Fail-closed quality gate for backtests.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="run the fail-closed gate")
+    check.add_argument("--returns", required=True, help="JSON list of per-period returns")
+    check.add_argument("--trials", default=None, help="JSON 2D matrix (T x N) of trial returns")
+    check.add_argument(
+        "--n-trials",
+        type=int,
+        default=None,
+        help="honest number of configurations tried (required, fail-closed)",
+    )
+    check.add_argument("--periods-per-year", type=int, default=252)
+    check.add_argument(
+        "--n-blocks",
+        type=int,
+        default=16,
+        help="CSCV blocks for PBO (default 16 = 12,870 splits; use 8 or 10 for speed)",
+    )
+    check.add_argument("--json", action="store_true", help="machine-readable output")
+
+    sub.add_parser("version", help="print version")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "version":
+        print(__version__)
+        return 0
+
+    if args.command == "check":
+        returns = _load_returns(args.returns)
+        trials = _load_trials(args.trials) if args.trials else None
+        if args.n_trials is not None and args.n_trials < 1:
+            parser.error("--n-trials must be >= 1")
+        body: dict[str, Any] = run_gate(
+            returns,
+            args.n_trials,
+            trials_matrix=trials,
+            periods_per_year=args.periods_per_year,
+            n_blocks=args.n_blocks,
+        )
+        if args.json:
+            print(json.dumps(body, ensure_ascii=False, indent=2))
+        else:
+            print(body["verdict"])
+            if body["report"] is not None:
+                print(body["report_text"])
+            for check in body["checks"]:
+                marker = "PASS" if check["passed"] else "FAIL"
+                print(
+                    f" [{marker}] {check['severity']} {check['check_id']}: "
+                    f"{check['title']} (value={check['value']}, "
+                    f"threshold={check['threshold']})"
+                )
+        return 0 if body["passed"] else 1
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

factor_qc/gate.py

@@ -0,0 +1,230 @@
+"""The fail-closed quality gate.
+
+``factor_qc.stats`` computes; this module decides — and its default answer
+is *no*.  A backtest that refuses to declare how many configurations were
+tried is refused outright: without an honest ``n_trials`` there is no
+deflation benchmark, no haircut and no track-record floor, and any verdict
+would be theatre.
+
+Checks are graded by severity:
+
+- **P0 (fatal)** — the candidate must not pass:
+  - Deflated Sharpe Ratio below threshold (selection-bias corrected),
+  - Probability of Backtest Overfitting above threshold (when a trials
+    matrix is provided),
+  - multiple-testing haircut annual Sharpe below the floor,
+  - Minimum Track Record Length longer than the available sample.
+- **P1 (warning)** — proceed with eyes open:
+  - PSR vs zero below 0.95 (weak evidence even before deflation),
+  - sample shorter than one year (252 obs),
+  - trials count aggressive relative to sample (n_trials > n_obs / 5).
+- **P2 (info)** — recorded, no action:
+  - non-normal return moments (skew / kurtosis),
+  - very few trials (n_trials < 5).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .stats import (
+    DSR_THRESHOLD,
+    PBO_THRESHOLD,
+    build_overfit_report,
+    minimum_track_record_length,
+    probabilistic_sharpe_ratio,
+    render_report_text,
+    sharpe_ratio,
+    skew_kurt,
+)
+
+SAFETY = {
+    "production_effect": False,
+    "changes_probability": False,
+    "allow_real_trade": False,
+}
+MIN_YEAR_OBS = 252
+ADJUSTED_SHARPE_FLOOR = 0.5
+PSR_ZERO_THRESHOLD = 0.95
+TRIAL_AGGRESSION_DENOM = 5.0
+MIN_TRIALS_INFO = 5
+
+
+def run_gate(
+    returns: np.ndarray,
+    n_trials: int | None,
+    *,
+    trials_matrix: np.ndarray | None = None,
+    periods_per_year: int = 252,
+    dsr_threshold: float = DSR_THRESHOLD,
+    pbo_threshold: float = PBO_THRESHOLD,
+    adjusted_sharpe_floor: float = ADJUSTED_SHARPE_FLOOR,
+    require_declared_trials: bool = True,
+    n_blocks: int = 16,
+) -> dict[str, Any]:
+    """Run the fail-closed gate. Returns a dict with ``passed``, ``checks``
+    and the underlying statistics report.
+
+    When ``require_declared_trials`` is true (default) and ``n_trials`` is
+    None, the gate refuses: ``passed=False`` with a single P0 blocker
+    ``n_trials_declaration_required``.
+
+    ``n_blocks`` controls the CSCV granularity of the PBO check; note that
+    CSCV enumerates C(n_blocks, n_blocks/2) splits (12,870 for the default
+    16), so smaller values (e.g. 8 or 10) run much faster on large trial
+    matrices.
+    """
+    r = np.asarray(returns, dtype=float)
+    r = r[~np.isnan(r)]
+    checks: list[dict[str, Any]] = []
+
+    def add(check_id: str, severity: str, title: str, value: Any, threshold: Any, passed: bool) -> None:
+        checks.append(
+            {
+                "check_id": check_id,
+                "severity": severity,
+                "title": title,
+                "value": value,
+                "threshold": threshold,
+                "passed": passed,
+            }
+        )
+
+    if n_trials is None:
+        if require_declared_trials:
+            add(
+                "n_trials_declaration_required",
+                "P0",
+                "honest n_trials declaration",
+                None,
+                "declared integer >= 1",
+                False,
+            )
+            return {
+                "passed": False,
+                "verdict": "FAIL - n_trials must be declared before a backtest "
+                           "can be judged (fail-closed)",
+                "checks": checks,
+                "report": None,
+                "safety": SAFETY,
+            }
+        n_trials = 1
+
+    n_obs = int(r.size)
+    report = build_overfit_report(
+        r,
+        n_trials,
+        trials_matrix=trials_matrix,
+        periods_per_year=periods_per_year,
+        dsr_threshold=dsr_threshold,
+        pbo_threshold=pbo_threshold,
+        n_blocks=n_blocks,
+    )
+    dsr = report["deflated_sharpe_ratio"]
+    pbo = report["pbo"]
+    ann = np.sqrt(periods_per_year)
+    sr_pp = sharpe_ratio(r)
+    skew, kurt = skew_kurt(r)
+    mintrl = minimum_track_record_length(sr_pp, 0.0, skew, kurt)
+    psr_zero = probabilistic_sharpe_ratio(sr_pp, 0.0, n_obs, skew, kurt)
+    adjusted_annual = report["haircut"]["adjusted_sharpe_annual"]
+
+    # P0: fatal
+    add(
+        "dsr",
+        "P0",
+        "deflated sharpe ratio >= threshold",
+        round(dsr, 4),
+        dsr_threshold,
+        bool(dsr >= dsr_threshold),
+    )
+    if pbo is not None:
+        add(
+            "pbo",
+            "P0",
+            "probability of backtest overfitting <= threshold",
+            round(pbo["pbo"], 4),
+            pbo_threshold,
+            bool(pbo["pbo"] <= pbo_threshold),
+        )
+    add(
+        "haircut_sharpe",
+        "P0",
+        "multiple-testing haircut annual sharpe >= floor",
+        round(adjusted_annual, 4),
+        adjusted_sharpe_floor,
+        bool(adjusted_annual >= adjusted_sharpe_floor),
+    )
+    add(
+        "mintrl",
+        "P0",
+        "minimum track record length <= sample",
+        round(mintrl, 1) if np.isfinite(mintrl) else None,
+        f"<= {n_obs}",
+        bool(np.isfinite(mintrl) and mintrl <= n_obs),
+    )
+
+    # P1: warnings
+    add(
+        "psr_vs_zero",
+        "P1",
+        "probabilistic sharpe vs zero >= threshold",
+        round(psr_zero, 4) if np.isfinite(psr_zero) else None,
+        PSR_ZERO_THRESHOLD,
+        bool(np.isfinite(psr_zero) and psr_zero >= PSR_ZERO_THRESHOLD),
+    )
+    add(
+        "sample_length",
+        "P1",
+        "sample >= one year of observations",
+        n_obs,
+        MIN_YEAR_OBS,
+        bool(n_obs >= MIN_YEAR_OBS),
+    )
+    add(
+        "trial_aggression",
+        "P1",
+        "trials not aggressive relative to sample",
+        n_trials,
+        f"<= {n_obs / TRIAL_AGGRESSION_DENOM:.0f}",
+        bool(n_trials <= n_obs / TRIAL_AGGRESSION_DENOM),
+    )
+
+    # P2: info
+    add(
+        "return_moments",
+        "P2",
+        "return moments near-normal",
+        {"skew": round(skew, 4), "kurtosis": round(kurt, 4)},
+        "skew ~ 0, kurtosis ~ 3",
+        bool(abs(skew) < 0.5 and abs(kurt - 3.0) < 1.0),
+    )
+    add(
+        "trial_count",
+        "P2",
+        "trials count >= minimal",
+        n_trials,
+        MIN_TRIALS_INFO,
+        bool(n_trials >= MIN_TRIALS_INFO),
+    )
+
+    p0_failed = [check for check in checks if check["severity"] == "P0" and not check["passed"]]
+    passed = not p0_failed
+    if passed:
+        verdict = "PASS - survives multiple-testing correction (no P0 failures)"
+    else:
+        detail = "; ".join(
+            f"{check['check_id']}: {check['value']} vs {check['threshold']}"
+            for check in p0_failed
+        )
+        verdict = f"FAIL - P0 blocker(s): {detail}"
+    return {
+        "passed": passed,
+        "verdict": verdict,
+        "checks": checks,
+        "report": report,
+        "report_text": render_report_text(report),
+        "safety": SAFETY,
+    }

factor_qc/stats.py

@@ -0,0 +1,493 @@
+"""Independent backtest-overfit statistics (DSR / PBO / haircut / MinTRL).
+
+Implementation of the published methods:
+
+- Deflated / Probabilistic Sharpe Ratio and Minimum Track Record Length:
+  Bailey & Lopez de Prado (2012, 2014).
+- Probability of Backtest Overfitting (PBO) via Combinatorially-Symmetric
+  Cross-Validation: Bailey, Borwein, Lopez de Prado & Zhu (2017).
+- Multiple-testing haircut of the Sharpe Ratio: Harvey & Liu (2015).
+
+Implementation notes
+--------------------
+Only numpy + the standard library are required (no scipy).  The
+standard-normal inverse CDF uses Acklam's rational approximation with one
+Newton refinement.  All Sharpe ratios are per-observation (not annualised);
+the report builder annualises only for display.
+
+This module computes; it never decides.  The fail-closed gate lives in
+``factor_qc.gate``.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime
+from itertools import combinations
+from typing import Any, Sequence
+
+import numpy as np
+
+EULER_MASCHERONI = 0.5772156649015328606
+DSR_THRESHOLD = 0.95
+PBO_THRESHOLD = 0.50
+
+
+# --------------------------------------------------------------------------- #
+# Standard normal helpers (no scipy)
+# --------------------------------------------------------------------------- #
+def _norm_cdf(z: float) -> float:
+    return 0.5 * (1.0 + math.erf(z / math.sqrt(2.0)))
+
+
+def _norm_sf(z: float) -> float:
+    return 0.5 * math.erfc(z / math.sqrt(2.0))
+
+
+def _norm_ppf(p: float) -> float:
+    """Inverse standard-normal CDF (Acklam's rational approximation + Newton step)."""
+    p = min(max(p, 1e-16), 1.0 - 1e-16)
+    a = [
+        -3.969683028665376e01,
+        2.209460984245205e02,
+        -2.759285104469687e02,
+        1.383577518672690e02,
+        -3.066479806614716e01,
+        2.506628277459239e00,
+    ]
+    b = [
+        -5.447609879822406e01,
+        1.615858368580409e02,
+        -1.556989798598866e02,
+        6.680131188771972e01,
+        -1.328068155288572e01,
+    ]
+    c = [
+        -7.784894002430293e-03,
+        -3.223964580411365e-01,
+        -2.400758277161838e00,
+        -2.549732539343734e00,
+        4.374664141464968e00,
+        2.938163982698783e00,
+    ]
+    d = [
+        7.784695709041462e-03,
+        3.224671290700398e-01,
+        2.445134137142996e00,
+        3.754408661907416e00,
+    ]
+    plow = 0.02425
+    if p < plow:
+        q = math.sqrt(-2.0 * math.log(p))
+        x = (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / (
+            (((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1.0
+        )
+    elif p <= 1.0 - plow:
+        q = p - 0.5
+        r = q * q
+        x = (
+            (((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q
+        ) / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1.0)
+    else:
+        q = math.sqrt(-2.0 * math.log(1.0 - p))
+        x = -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / (
+            (((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1.0
+        )
+    error = _norm_cdf(x) - p
+    u = error * math.sqrt(2.0 * math.pi) * math.exp(x * x / 2.0)
+    return x - u / (1.0 + x * u / 2.0)
+
+
+def _norm_isf(p: float) -> float:
+    return _norm_ppf(1.0 - p)
+
+
+# --------------------------------------------------------------------------- #
+# Sharpe ratio and moments
+# --------------------------------------------------------------------------- #
+def sharpe_ratio(returns: np.ndarray, benchmark: float = 0.0) -> float:
+    """Per-period Sharpe ratio (ddof=1); NaN when fewer than 2 observations."""
+    r = np.asarray(returns, dtype=float)
+    r = r[~np.isnan(r)]
+    if r.size < 2:
+        return float("nan")
+    sd = r.std(ddof=1)
+    if sd == 0:
+        return float("nan")
+    return float((r.mean() - benchmark) / sd)
+
+
+def skew_kurt(returns: np.ndarray) -> tuple[float, float]:
+    """Sample skewness (g1) and non-excess kurtosis (g2, normal == 3)."""
+    r = np.asarray(returns, dtype=float)
+    r = r[~np.isnan(r)]
+    if r.size < 4:
+        return 0.0, 3.0
+    mean = r.mean()
+    sd = r.std(ddof=0)
+    if sd == 0:
+        return 0.0, 3.0
+    centered = (r - mean) / sd
+    return float(np.mean(centered ** 3)), float(np.mean(centered ** 4))
+
+
+# --------------------------------------------------------------------------- #
+# Deflated Sharpe Ratio / PSR / MinTRL
+# --------------------------------------------------------------------------- #
+def probabilistic_sharpe_ratio(
+    observed_sr: float,
+    benchmark_sr: float,
+    n_obs: int,
+    skew: float,
+    kurtosis: float,
+) -> float:
+    """P(SR > SR*) under the non-normal Sharpe estimator standard error."""
+    if n_obs < 2 or math.isnan(observed_sr):
+        return float("nan")
+    denom = 1.0 - skew * observed_sr + ((kurtosis - 1.0) / 4.0) * observed_sr ** 2
+    denom = max(denom, 1e-12)
+    se = math.sqrt(denom / (n_obs - 1))
+    return _norm_cdf((observed_sr - benchmark_sr) / se)
+
+
+def expected_max_sharpe(sr_variance_across_trials: float, n_trials: int) -> float:
+    """E[max SR] across N independent zero-true-SR trials (deflation benchmark)."""
+    if n_trials < 2:
+        return 0.0
+    variance = max(sr_variance_across_trials, 0.0)
+    z1 = _norm_ppf(1.0 - 1.0 / n_trials)
+    z2 = _norm_ppf(1.0 - 1.0 / (n_trials * math.e))
+    return float(
+        math.sqrt(variance)
+        * ((1.0 - EULER_MASCHERONI) * z1 + EULER_MASCHERONI * z2)
+    )
+
+
+def deflated_sharpe_ratio(
+    strategy_returns: np.ndarray,
+    n_trials: int,
+    *,
+    sr_variance_across_trials: float | None = None,
+    all_trial_sharpes: Sequence[float] | None = None,
+    threshold: float = DSR_THRESHOLD,
+) -> dict[str, Any]:
+    r = np.asarray(strategy_returns, dtype=float)
+    r = r[~np.isnan(r)]
+    n = r.size
+    sr = sharpe_ratio(r)
+    skew, kurt = skew_kurt(r)
+    if sr_variance_across_trials is None:
+        if all_trial_sharpes is not None and len(all_trial_sharpes) > 1:
+            sr_variance_across_trials = float(
+                np.var(np.asarray(all_trial_sharpes, dtype=float), ddof=1)
+            )
+        else:
+            denom = 1.0 - skew * sr + ((kurt - 1.0) / 4.0) * sr ** 2
+            sr_variance_across_trials = max(denom, 1e-12) / max(n - 1, 1)
+    sr0 = expected_max_sharpe(sr_variance_across_trials, n_trials)
+    return {
+        "observed_sharpe": sr,
+        "deflated_benchmark_sr0": sr0,
+        "psr_vs_zero": probabilistic_sharpe_ratio(sr, 0.0, n, skew, kurt),
+        "deflated_sharpe_ratio": probabilistic_sharpe_ratio(sr, sr0, n, skew, kurt),
+        "n_obs": n,
+        "n_trials": n_trials,
+        "skew": skew,
+        "kurtosis": kurt,
+        "passed": bool(
+            probabilistic_sharpe_ratio(sr, sr0, n, skew, kurt) >= threshold
+        ),
+    }
+
+
+def minimum_track_record_length(
+    observed_sr: float,
+    benchmark_sr: float,
+    skew: float,
+    kurtosis: float,
+    confidence: float = 0.95,
+) -> float:
+    if observed_sr <= benchmark_sr:
+        return float("inf")
+    z = _norm_ppf(confidence)
+    num = max(
+        1.0 - skew * observed_sr + ((kurtosis - 1.0) / 4.0) * observed_sr ** 2,
+        1e-12,
+    )
+    return float(1.0 + num * (z / (observed_sr - benchmark_sr)) ** 2)
+
+
+# --------------------------------------------------------------------------- #
+# Multiple-testing haircut (Harvey & Liu 2015)
+# --------------------------------------------------------------------------- #
+def _p_from_t(tstat: float) -> float:
+    return 2.0 * _norm_sf(abs(tstat))
+
+
+def _adjusted_p(p: float, n_tests: int, method: str, rank: int = 1) -> float:
+    method = method.lower()
+    if method == "bonferroni":
+        return min(1.0, p * n_tests)
+    if method == "holm":
+        return min(1.0, p * (n_tests - rank + 1))
+    if method == "bhy":
+        harmonic = sum(1.0 / i for i in range(1, n_tests + 1))
+        return min(1.0, p * n_tests * harmonic / rank)
+    raise ValueError(f"unknown method: {method}")
+
+
+def haircut_sharpe(
+    observed_sharpe_per_period: float,
+    n_obs: int,
+    n_tests: int,
+    method: str = "bonferroni",
+    rank: int = 1,
+) -> dict[str, Any]:
+    t_obs = observed_sharpe_per_period * math.sqrt(n_obs)
+    p_obs = _p_from_t(t_obs)
+    p_adj = _adjusted_p(p_obs, n_tests, method, rank)
+    # The inverse-CDF approximation is only meaningful down to ~1e-15; clip
+    # extreme significance so the adjusted Sharpe stays finite.
+    p_adj = min(1.0, max(p_adj, 1e-15))
+    t_adj = math.copysign(_norm_isf(p_adj / 2.0), observed_sharpe_per_period)
+    sr_adj = t_adj / math.sqrt(n_obs)
+    haircut = (
+        1.0 - sr_adj / observed_sharpe_per_period
+        if observed_sharpe_per_period
+        else float("nan")
+    )
+    return {
+        "method": method,
+        "observed_sharpe": observed_sharpe_per_period,
+        "adjusted_sharpe": sr_adj,
+        "haircut": haircut,
+        "observed_pvalue": p_obs,
+        "adjusted_pvalue": p_adj,
+        "n_tests": n_tests,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Probability of Backtest Overfitting (CSCV, Bailey et al. 2017)
+# --------------------------------------------------------------------------- #
+def _sharpe_cols(block: np.ndarray) -> np.ndarray:
+    mean = np.nanmean(block, axis=0)
+    sd = np.nanstd(block, axis=0, ddof=1)
+    sd = np.where(sd == 0, np.nan, sd)
+    return mean / sd
+
+
+def probability_of_backtest_overfitting(
+    perf_matrix: np.ndarray,
+    n_blocks: int = 16,
+) -> dict[str, Any]:
+    matrix = np.asarray(perf_matrix, dtype=float)
+    if matrix.ndim != 2:
+        raise ValueError("perf_matrix must be 2D (T x N)")
+    t_rows, n_strategies = matrix.shape
+    if n_strategies < 2:
+        raise ValueError("need at least 2 strategy configurations for PBO")
+    if n_blocks % 2 != 0:
+        raise ValueError("n_blocks must be even")
+    if n_blocks > t_rows:
+        raise ValueError("n_blocks cannot exceed observations")
+
+    block_idx = np.array_split(np.arange(t_rows), n_blocks)
+    blocks = list(range(n_blocks))
+    logits: list[float] = []
+    oos_ranks: list[float] = []
+
+    for is_blocks in combinations(blocks, n_blocks // 2):
+        is_set = set(is_blocks)
+        is_rows = np.concatenate([block_idx[b] for b in blocks if b in is_set])
+        oos_rows = np.concatenate([block_idx[b] for b in blocks if b not in is_set])
+        is_perf = _sharpe_cols(matrix[is_rows])
+        oos_perf = _sharpe_cols(matrix[oos_rows])
+        if np.all(np.isnan(is_perf)):
+            continue
+        n_star = int(np.nanargmax(is_perf))
+        valid = ~np.isnan(oos_perf)
+        rank = float(np.sum(oos_perf[valid] <= oos_perf[n_star]))
+        w = rank / (float(np.sum(valid)) + 1.0)
+        w = min(max(w, 1e-6), 1.0 - 1e-6)
+        logits.append(float(np.log(w / (1.0 - w))))
+        oos_ranks.append(w)
+
+    pbo = (
+        float(np.mean([1.0 if lam <= 0 else 0.0 for lam in logits]))
+        if logits
+        else float("nan")
+    )
+    return {
+        "pbo": pbo,
+        "n_splits": len(logits),
+        "n_strategies": n_strategies,
+        "n_blocks": n_blocks,
+        "median_logit": float(np.median(logits)) if logits else float("nan"),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# Report builder
+# --------------------------------------------------------------------------- #
+def build_overfit_report(
+    selected_returns: np.ndarray,
+    n_trials: int,
+    *,
+    trials_matrix: np.ndarray | None = None,
+    periods_per_year: int = 252,
+    dsr_threshold: float = DSR_THRESHOLD,
+    pbo_threshold: float = PBO_THRESHOLD,
+    n_blocks: int = 16,
+    haircut_method: str = "bonferroni",
+) -> dict[str, Any]:
+    r = np.asarray(selected_returns, dtype=float)
+    r = r[~np.isnan(r)]
+    ann = math.sqrt(periods_per_year)
+    sr_pp = sharpe_ratio(r)
+    skew, kurt = skew_kurt(r)
+
+    all_trial_sharpes = None
+    if trials_matrix is not None:
+        tm = np.asarray(trials_matrix, dtype=float)
+        all_trial_sharpes = [
+            sharpe_ratio(tm[:, column]) for column in range(tm.shape[1])
+        ]
+        all_trial_sharpes = [value for value in all_trial_sharpes if not math.isnan(value)]
+        n_trials = max(n_trials, len(all_trial_sharpes))
+
+    dsr = deflated_sharpe_ratio(
+        r,
+        n_trials,
+        all_trial_sharpes=all_trial_sharpes,
+        threshold=dsr_threshold,
+    )
+    hc = haircut_sharpe(sr_pp, r.size, n_trials, method=haircut_method)
+    mintrl = minimum_track_record_length(sr_pp, 0.0, skew, kurt)
+
+    pbo_block = None
+    if trials_matrix is not None and np.asarray(trials_matrix).shape[1] >= 2:
+        pbo_block = probability_of_backtest_overfitting(
+            np.asarray(trials_matrix, dtype=float),
+            n_blocks=n_blocks,
+        )
+
+    flags: list[str] = []
+    if dsr["deflated_sharpe_ratio"] < dsr_threshold:
+        flags.append(f"DSR {dsr['deflated_sharpe_ratio']:.2f} < {dsr_threshold}")
+    if pbo_block is not None and pbo_block["pbo"] > pbo_threshold:
+        flags.append(f"PBO {pbo_block['pbo']:.2f} > {pbo_threshold}")
+    if hc["adjusted_sharpe"] * ann < 0.5:
+        flags.append(f"haircut Sharpe {hc['adjusted_sharpe'] * ann:.2f} < 0.5")
+    if mintrl > r.size:
+        flags.append(f"MinTRL {mintrl:.0f} > sample {r.size}")
+
+    passed = len(flags) == 0
+    verdict = (
+        "PASS - survives multiple-testing correction"
+        if passed
+        else "FAIL - likely overfit / selection-biased: " + "; ".join(flags)
+    )
+    return {
+        "verdict": verdict,
+        "passed": passed,
+        "observed_sharpe_annual": round(sr_pp * ann, 4),
+        "skew": round(skew, 4),
+        "kurtosis": round(kurt, 4),
+        "n_obs": int(r.size),
+        "n_trials": int(n_trials),
+        "deflated_sharpe_ratio": round(dsr["deflated_sharpe_ratio"], 4),
+        "deflation_benchmark_sr0_annual": round(dsr["deflated_benchmark_sr0"] * ann, 4),
+        "psr_vs_zero": round(dsr["psr_vs_zero"], 4),
+        "haircut": {
+            "method": hc["method"],
+            "adjusted_sharpe_annual": round(hc["adjusted_sharpe"] * ann, 4),
+            "haircut_pct": round(hc["haircut"], 4),
+            "observed_pvalue": hc["observed_pvalue"],
+            "adjusted_pvalue": hc["adjusted_pvalue"],
+        },
+        "minimum_track_record_length": round(mintrl, 1),
+        "pbo": pbo_block,
+    }
+
+
+def render_report_text(report: dict[str, Any]) -> str:
+    lines = [
+        "=" * 64,
+        " BACKTEST OVERFITTING REPORT",
+        "=" * 64,
+        f" Verdict : {report['verdict']}",
+        "-" * 64,
+        f" Observed Sharpe (annual) : {report['observed_sharpe_annual']}",
+        f" Trials (multiple tests)  : {report['n_trials']}",
+        f" Observations             : {report['n_obs']}",
+        f" Skew / Kurtosis          : {report['skew']} / {report['kurtosis']}",
+        "-" * 64,
+        f" Deflated Sharpe Ratio    : {report['deflated_sharpe_ratio']} "
+        f"(benchmark SR0 {report['deflation_benchmark_sr0_annual']} ann.)",
+        f" PSR vs 0                 : {report['psr_vs_zero']}",
+        f" Haircut Sharpe ({report['haircut']['method']}): "
+        f"{report['haircut']['adjusted_sharpe_annual']} "
+        f"(-{report['haircut']['haircut_pct']:.0%})",
+        f" Min Track Record Length  : {report['minimum_track_record_length']} obs",
+    ]
+    if report["pbo"] is not None:
+        lines.append(
+            f" PBO                      : {report['pbo']['pbo']} "
+            f"({report['pbo']['n_splits']} CSCV splits)"
+        )
+    lines.append("=" * 64)
+    return "\n".join(lines)
+
+
+def build_check_artifact(
+    *,
+    name: str,
+    source: str,
+    selected_returns: np.ndarray,
+    n_trials: int,
+    trials_matrix: np.ndarray | None = None,
+    periods_per_year: int = 252,
+    n_blocks: int = 16,
+    returns_meta: dict[str, Any] | None = None,
+    trials_meta: dict[str, Any] | None = None,
+    generated_at: str | None = None,
+) -> dict[str, Any]:
+    """Provenance-wrapped check artifact (schema ``factor_qc.check.v1``)."""
+    report = build_overfit_report(
+        selected_returns,
+        n_trials,
+        trials_matrix=trials_matrix,
+        periods_per_year=periods_per_year,
+        n_blocks=n_blocks,
+    )
+    artifact: dict[str, Any] = {
+        "schema_version": "factor_qc.check.v1",
+        "generated_at": generated_at
+        or datetime.now().astimezone().isoformat(timespec="seconds"),
+        "tool": "factor_qc.stats (independent engine, numpy only)",
+        "name": name,
+        "declared": {
+            "n_trials": n_trials,
+            "periods_per_year": periods_per_year,
+            "haircut_method": report["haircut"]["method"],
+        },
+        "inputs": {
+            "returns": returns_meta or {},
+            "trials": trials_meta,
+        },
+        "source": source,
+        "boundaries": {
+            "production_effect": False,
+            "changes_probability": False,
+            "allow_real_trade": False,
+        },
+        "report": report,
+    }
+    if trials_matrix is None and report.get("pbo") is None:
+        artifact["limitations"] = [
+            "trials matrix not provided; PBO not computed (report pbo=null) and "
+            "the DSR cross-trial variance degrades to a conservative "
+            "single-trial estimate."
+        ]
+    return artifact

factor_qc-0.1.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: factor-qc
+Version: 0.1.0
+Summary: Fail-closed quality gate for backtests: DSR, PBO, Harvey-Liu haircut and MinTRL in one numpy-only engine, with P0/P1/P2 severity grading.
+License-Expression: MIT
+Keywords: backtest,overfitting,deflated-sharpe,pbo,mintrl,factor,qc,quant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# factor-qc
+
+A **fail-closed quality gate** for backtests: one numpy-only engine covering
+Deflated Sharpe Ratio, Probability of Backtest Overfitting (CSCV), the
+Harvey-Liu multiple-testing haircut and Minimum Track Record Length —
+graded P0/P1/P2, and **it refuses to judge a backtest that will not declare
+how many configurations were tried**. Python 3.11+, one dependency
+(`numpy`), Windows / Linux / macOS.
+
+**Status:** v0.1 — alpha. The statistics are battle-tested inside a
+production research pipeline and validated against published reference
+values, but this standalone package is new: expect the CLI to shift before
+v1.0.
+
+## Why this exists
+
+The standard story: you try 200 factor configurations, the best one shows a
+Sharpe of 1.65, you feel great. The honest story: with 200 trials of pure
+noise, *someone* is going to show a Sharpe of 1.65 — the expected maximum of
+200 zero-true-SR trials — and it will not be your skill, it will be your
+selection bias.
+
+Most backtest tooling computes statistics and prints reports. `factor-qc`
+is a **gate**: it decides, with graded severity, whether a candidate may
+pass — and its default answer is *no*:
+
+- **P0 (fatal)** — DSR below threshold, PBO above threshold, haircut Sharpe
+  below floor, MinTRL longer than the sample → the candidate must not pass.
+- **P1 (warning)** — weak PSR vs zero, short sample, aggressive trial count
+  → proceed with eyes open.
+- **P2 (info)** — non-normal moments, tiny trial count → recorded, no action.
+
+## Philosophy
+
+**Honesty is the default; the gate is fail-closed.**
+
+The one non-negotiable input is `n_trials`: the honest count of
+configurations you tried. Without it there is no deflation benchmark
+([Bailey & López de Prado 2014](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2460551)),
+no haircut ([Harvey, Liu & Zhu 2016, RFS](https://doi.org/10.1093/rfs/hhv059)),
+no track-record floor
+([Bailey & López de Prado 2018, JPM](https://ideas.repec.org/a/rsk/journl/0journalpm-v44n5.html))
+and no overfitting probability
+([Bailey, Borwein, López de Prado & Zhu 2017, JCF](https://escholarship.org/uc/item/4w1110bb)).
+Refuse to declare, and the gate refuses to judge — that asymmetry is the
+point. `qc check` exits non-zero on any P0 failure, so it drops into CI,
+pre-commit hooks and research gates as a hard blocker, not a suggestion.
+
+Two design commitments that keep it honest:
+
+1. **numpy only, no scipy** — the standard-normal inverse CDF is Acklam's
+   rational approximation with one Newton refinement; every number in the
+   report is reproducible from the code in this repo, no hidden black box.
+2. **PBO is optional but explicit** — without a trials matrix the gate says
+   PBO *was not computed*, and the DSR cross-trial variance degrades to a
+   conservative single-trial estimate. Absence of evidence is reported as
+   absence, never as evidence.
+
+## Quick start
+
+```bash
+# install from PyPI (once published)
+pip install factor-qc
+
+# or run without installing anything:
+#   PYTHONPATH=src python -m factor_qc --help
+
+python examples/demo.py   # try it on reproducible synthetic cases
+```
+
+Your own backtest:
+
+```bash
+# returns.json = JSON list of per-period returns of the selected candidate
+# trials.json   = JSON 2D matrix (T x N) of every configuration you tried
+
+qc check --returns returns.json --trials trials.json --n-trials 200
+# -> FAIL - P0 blocker(s): dsr: 0.63 vs 0.95; mintrl: 250.8 vs <= 1000; ...
+
+qc check --returns returns.json --n-trials 5 --json   # machine-readable
+```
+
+Exit codes: `0` = no P0 failures (P1/P2 may still be failing), `1` = at
+least one P0 failure (or missing `n_trials`), `2` = usage error. Wire it
+into CI as a hard gate.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `check` | Run the gate: DSR, PBO (when `--trials` given), haircut Sharpe, MinTRL as P0; PSR-vs-zero, sample length, trial aggression as P1; moments and trial count as P2. Human-readable or `--json` output |
+| `version` | Print version |
+
+Flags: `--returns` (required), `--trials` (optional), `--n-trials`
+(required unless `require_declared_trials` is disabled in code),
+`--periods-per-year` (default 252), `--n-blocks` (CSCV granularity, default
+16).
+
+## The checks
+
+| Check | Severity | Method | Reference |
+| --- | --- | --- | --- |
+| `dsr` | P0 | Deflated Sharpe Ratio: P(SR > E[max SR of N trials]) under non-normal moments | [Bailey & López de Prado (2014), JPM 40(5)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2460551) |
+| `pbo` | P0 | Probability of Backtest Overfitting via Combinatorially-Symmetric Cross-Validation (12,870 splits at n_blocks=16) | [Bailey, Borwein, López de Prado & Zhu (2017), JCF](https://escholarship.org/uc/item/4w1110bb) |
+| `haircut_sharpe` | P0 | Multiple-testing haircut of the Sharpe ratio (Bonferroni/Holm/BHY) | [Harvey & Liu (2015)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2528780) |
+| `mintrl` | P0 | Minimum Track Record Length: observations needed before SR is significant | [Bailey & López de Prado (2018), JPM 44(5)](https://ideas.repec.org/a/rsk/journl/0journalpm-v44n5.html) |
+| `psr_vs_zero` | P1 | Probabilistic Sharpe vs zero | [Bailey & López de Prado (2012)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2168747) |
+| `sample_length` | P1 | ≥ 252 observations | — |
+| `trial_aggression` | P1 | n_trials ≤ n_obs / 5 | — |
+| `return_moments` | P2 | skew ≈ 0, kurtosis ≈ 3 | — |
+| `trial_count` | P2 | n_trials ≥ 5 | — |
+
+The P0 set mirrors the spirit of [Harvey, Liu & Zhu (2016),
+"…and the Cross-Section of Expected Returns"](https://doi.org/10.1093/rfs/hhv059):
+a factor must survive multiple-testing correction to earn the right to be
+called a factor. The gate is the machine version of that editorial stance.
+
+## Performance note
+
+CSCV enumerates C(n_blocks, n_blocks/2) splits — 12,870 at the default 16.
+On large trial matrices (T=1000, N=200) that takes minutes; use
+`--n-blocks 8` (70 splits) or `10` (252 splits) for interactive speed at
+slightly coarser granularity.
+
+## Development
+
+```bash
+python -m pip install -e . pytest
+python -m pytest
+```
+
+CI runs the full test suite on Ubuntu, Windows and macOS with Python 3.11
+and 3.12. Issues are handled on weekends; pull requests are welcome.
+
+## Related work
+
+- [Bailey & López de Prado (2014), The Deflated Sharpe Ratio](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2460551)
+- [Bailey, Borwein, López de Prado & Zhu (2017), The Probability of Backtest Overfitting](https://escholarship.org/uc/item/4w1110bb)
+- [Harvey, Liu & Zhu (2016), …and the Cross-Section of Expected Returns (RFS)](https://doi.org/10.1093/rfs/hhv059)
+- [Harvey & Liu (2021), Lucky Factors (JFE)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2528780)
+- [Mobarekeh & López de Prado (2024), Backtest Overfitting in the Machine Learning Era (SSRN 4778909)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4778909) — why OOS methods still need honest trial accounting
+
+## License
+
+MIT

factor_qc-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+factor_qc/__init__.py,sha256=DYAYqtljdvNsFaW7eLSKYmNqv0ZM5_fduNdIxuIQJaM,908
+factor_qc/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+factor_qc/cli.py,sha256=FR59UdOvGSLySdqsZwmz07C_D5CgGLB8T6E35QwrHPA,3704
+factor_qc/gate.py,sha256=IMWflYb8ieQ5Els3hf0kyvRV-vtNmGso5Kp9B4S_8nI,6966
+factor_qc/stats.py,sha256=qxNhUpGJvEiAOyUOCrGFEBzyTg-ZhtYEtW2_-LLqDes,17250
+factor_qc-0.1.0.dist-info/licenses/LICENSE,sha256=rk_db6ozKbaQzFNI1YAoOBuzKn5b7YsYH53CRpYHXAU,1079
+factor_qc-0.1.0.dist-info/METADATA,sha256=p6LtsfDqqxWdEpBIlDN8PUkPY7C7GUILOl3Vf4JWxnA,8144
+factor_qc-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+factor_qc-0.1.0.dist-info/entry_points.txt,sha256=P3KEI5brT2meq1qKSWLEPeL7lZOHqhwzWab4hAkWSiM,73
+factor_qc-0.1.0.dist-info/top_level.txt,sha256=YdSiclAtCi5Oth-kuaO0AMi4YZVjzISbQD55j0OpvL4,10
+factor_qc-0.1.0.dist-info/RECORD,,

factor_qc-0.1.0.dist-info/WHEEL

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

factor_qc-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+factor-qc = factor_qc.cli:main
+qc = factor_qc.cli:main

factor_qc-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Factor QC contributors
+
+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.

factor_qc-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+factor_qc