alpha-engine-lib 0.48.0__tar.gz → 0.49.0__tar.gz

{alpha_engine_lib-0.48.0 → alpha_engine_lib-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.48.0
+Version: 0.49.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary
@@ -20,6 +20,10 @@ Provides-Extra: quant-xs
 Requires-Dist: numpy>=1.24; extra == "quant-xs"
 Requires-Dist: pandas>=2.0; extra == "quant-xs"
 Requires-Dist: scikit-learn>=1.0; extra == "quant-xs"
+Provides-Extra: quant-stats
+Requires-Dist: numpy>=1.24; extra == "quant-stats"
+Requires-Dist: pandas>=2.0; extra == "quant-stats"
+Requires-Dist: scipy>=1.7; extra == "quant-stats"
 Provides-Extra: flow-doctor
 Requires-Dist: flow-doctor[diagnosis,s3]<0.5.0,>=0.4.0; extra == "flow-doctor"
 Provides-Extra: rag
@@ -264,6 +268,7 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`quant.riskstats`** — `volatility`, `sharpe_ratio`, `sortino_ratio`, `max_drawdown` (stdlib).
 - **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
 - **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
+- **`quant.stats`** — strategy/signal-quality evaluation metrics (lifted from the backtester's `analysis/`): `dsr` (Probabilistic + Deflated Sharpe, López de Prado), `information_coefficient` (Spearman rank IC), `expectancy` (hit-rate × win/loss decomposition), `multiple_testing` (Benjamini-Hochberg FDR), `risk_matched_benchmark` (EW-high-vol + beta-matched-SPY baselines + Information Ratio). **Needs pandas + scipy** — `pip install "alpha-engine-lib[quant-stats]"` (scipy is only the IC p-value; numpy fallback otherwise).
 
 ### `http_retry` — bounded-backoff transient-API retry chokepoint
 

{alpha_engine_lib-0.48.0 → alpha_engine_lib-0.49.0}/README.md

@@ -229,6 +229,7 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`quant.riskstats`** — `volatility`, `sharpe_ratio`, `sortino_ratio`, `max_drawdown` (stdlib).
 - **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
 - **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
+- **`quant.stats`** — strategy/signal-quality evaluation metrics (lifted from the backtester's `analysis/`): `dsr` (Probabilistic + Deflated Sharpe, López de Prado), `information_coefficient` (Spearman rank IC), `expectancy` (hit-rate × win/loss decomposition), `multiple_testing` (Benjamini-Hochberg FDR), `risk_matched_benchmark` (EW-high-vol + beta-matched-SPY baselines + Information Ratio). **Needs pandas + scipy** — `pip install "alpha-engine-lib[quant-stats]"` (scipy is only the IC p-value; numpy fallback otherwise).
 
 ### `http_retry` — bounded-backoff transient-API retry chokepoint
 

{alpha_engine_lib-0.48.0 → alpha_engine_lib-0.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.48.0"
+version = "0.49.0"
 description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops
@@ -39,6 +39,10 @@ quant = ["numpy>=1.24"]
 # separate from [quant] so the numpy-only consumers (e.g. robodashboard)
 # don't pull pandas+sklearn.
 quant-xs = ["numpy>=1.24", "pandas>=2.0", "scikit-learn>=1.0"]
+# Statistical evaluation utilities (alpha_engine_lib.quant.stats — PSR/DSR, IC,
+# expectancy, BH-FDR, risk-matched benchmarks). numpy + pandas always; scipy is
+# used by information_coefficient for the p-value (numpy fallback otherwise).
+quant-stats = ["numpy>=1.24", "pandas>=2.0", "scipy>=1.7"]
 flow_doctor = ["flow-doctor[diagnosis,s3]>=0.4.0,<0.5.0"]
 rag = [
     "psycopg2-binary>=2.9",

{alpha_engine_lib-0.48.0 → alpha_engine_lib-0.49.0}/src/alpha_engine_lib/__init__.py

@@ -1,3 +1,3 @@
 """alpha-engine-lib — shared utilities for Alpha Engine modules."""
 
-__version__ = "0.48.0"
+__version__ = "0.49.0"

alpha_engine_lib-0.49.0/src/alpha_engine_lib/quant/stats/__init__.py

@@ -0,0 +1,22 @@
+"""Statistical evaluation utilities for signal/strategy quality assessment.
+
+Pure-compute metrics consumed across the fleet (backtester, robodashboard) for
+judging signal quality, strategy skill, and selection bias — no I/O. Import the
+submodule you need (the package keeps no eager imports). Most need numpy+pandas;
+``information_coefficient`` additionally uses scipy when present (with a numpy
+fallback). Install ``alpha-engine-lib[quant-stats]``.
+
+Modules:
+  - ``dsr``                     — Probabilistic + Deflated Sharpe (López de Prado)
+  - ``information_coefficient`` — Spearman rank IC of conviction vs forward return
+  - ``expectancy``              — hit-rate × win/loss decomposition
+  - ``multiple_testing``        — Benjamini-Hochberg FDR correction
+  - ``risk_matched_benchmark``  — EW-high-vol + beta-matched-SPY baselines + IR
+
+Example::
+
+    from alpha_engine_lib.quant.stats.dsr import compute_dsr
+    from alpha_engine_lib.quant.stats.multiple_testing import benjamini_hochberg
+"""
+
+from __future__ import annotations

alpha_engine_lib-0.49.0/src/alpha_engine_lib/quant/stats/dsr.py

@@ -0,0 +1,278 @@
+"""dsr — Probabilistic Sharpe Ratio (PSR) and Deflated Sharpe Ratio (DSR).
+
+Confidence-adjusted Sharpe per López de Prado:
+  - PSR (Bailey & López de Prado 2012): probability that the *true* Sharpe
+    is above a benchmark, given the observed sample size + skew + kurtosis.
+    Answers "is this Sharpe distinguishable from the benchmark, given how
+    little data we have?"
+  - DSR (Bailey & López de Prado 2014): PSR with a multiple-testing
+    correction. The benchmark is set to the expected maximum Sharpe under
+    N independent trials, so DSR > 0.95 means "even after accounting for
+    cherry-picking from N candidates, this Sharpe is significant."
+
+The promotion gate for any multiple-testing factory (param sweeps that
+auto-promote the top-Sharpe combo): point-estimate Sharpe on a short sample
+has a wide CI; DSR is what prevents promoting noise winners.
+
+Mathematical reference:
+  Bailey & López de Prado (2012) "The Sharpe Ratio Efficient Frontier"
+  Bailey & López de Prado (2014) "The Deflated Sharpe Ratio: Correcting
+  for Selection Bias, Backtest Overfitting, and Non-Normality"
+
+Pure-compute. Operates on a daily return series + sample-size metadata;
+no I/O.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import TypedDict
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+_TRADING_DAYS_PER_YEAR = 252
+
+
+class PSRResult(TypedDict, total=False):
+    status: str
+    n: int
+    sharpe: float           # observed annualized Sharpe
+    sharpe_benchmark: float # benchmark Sharpe being tested against
+    psr: float              # probability in [0, 1] that true SR > benchmark
+    skew: float
+    kurtosis: float
+
+
+class DSRResult(TypedDict, total=False):
+    status: str
+    n: int
+    sharpe: float
+    n_trials: int           # number of candidates considered (multiple-testing N)
+    sharpe_benchmark: float # implied benchmark from N_trials under H0: SR=0
+    dsr: float              # probability that the true Sharpe survives selection bias
+    skew: float
+    kurtosis: float
+
+
+def _normal_cdf(x: float) -> float:
+    """Standard normal CDF — pure-Python, no scipy dependency."""
+    return 0.5 * (1.0 + math.erf(x / math.sqrt(2.0)))
+
+
+def _annualized_sharpe(returns: np.ndarray) -> float:
+    """Annualized Sharpe (risk-free = 0), sample-std (ddof=1)."""
+    if returns.size < 2:
+        return 0.0
+    mean = float(returns.mean())
+    std = float(returns.std(ddof=1))
+    if std == 0.0:
+        return 0.0
+    return mean / std * math.sqrt(_TRADING_DAYS_PER_YEAR)
+
+
+def _sample_skew_kurtosis(returns: np.ndarray) -> tuple[float, float]:
+    """Sample skewness and excess kurtosis. Pearson-style; scipy-equivalent.
+
+    Excess kurtosis = K - 3 (so a normal has 0 excess kurtosis).
+    Returns (0, 0) on insufficient sample.
+    """
+    n = returns.size
+    if n < 4:
+        return 0.0, 0.0
+    mean = returns.mean()
+    centered = returns - mean
+    var = float((centered * centered).mean())
+    if var == 0.0:
+        return 0.0, 0.0
+    std = math.sqrt(var)
+    skew = float((centered ** 3).mean() / (std ** 3))
+    kurt_excess = float((centered ** 4).mean() / (var * var)) - 3.0
+    return skew, kurt_excess
+
+
+def compute_psr(
+    daily_returns: pd.Series | np.ndarray,
+    sharpe_benchmark: float = 0.0,
+) -> PSRResult:
+    """Probabilistic Sharpe Ratio.
+
+    Parameters
+    ----------
+    daily_returns : array-like
+        Daily simple returns. NaN dropped.
+    sharpe_benchmark : float
+        Annualized Sharpe to test against (default 0.0, i.e. "is the
+        true SR positive?").
+
+    Returns
+    -------
+    PSRResult dict with:
+        status: "ok" | "insufficient_data"
+        n: sample size
+        sharpe: observed annualized SR
+        sharpe_benchmark: as input
+        psr: probability that true SR > benchmark
+        skew, kurtosis: moments of the return series
+
+    Formula (Bailey & López de Prado 2012):
+        PSR(SR*) = Phi(  (SR_hat - SR*) * sqrt(n - 1)
+                        / sqrt(1 - skew * SR_hat + (kurtosis - 1)/4 * SR_hat^2) )
+
+    where SR_hat is the *non-annualized* observed Sharpe and SR* is the
+    benchmark on the same scale. We compute on daily Sharpe internally
+    and convert benchmarks accordingly.
+    """
+    r = np.asarray(daily_returns, dtype=np.float64)
+    r = r[np.isfinite(r)]
+    n = r.size
+    if n < 30:  # PSR is asymptotic; small samples produce nonsense
+        return {"status": "insufficient_data", "n": n}
+
+    sr_annualized = _annualized_sharpe(r)
+    # PSR formula uses the daily SR. Convert annualized benchmark back to daily.
+    sr_daily = sr_annualized / math.sqrt(_TRADING_DAYS_PER_YEAR)
+    sr_bench_daily = sharpe_benchmark / math.sqrt(_TRADING_DAYS_PER_YEAR)
+
+    skew, kurt_excess = _sample_skew_kurtosis(r)
+    # The "kurtosis" term in López de Prado's formula is the raw 4th
+    # moment / variance^2 (so 3.0 for a normal); we have excess kurtosis.
+    kurt_raw = kurt_excess + 3.0
+
+    denom_sq = 1.0 - skew * sr_daily + (kurt_raw - 1.0) / 4.0 * sr_daily ** 2
+    if denom_sq <= 0.0:
+        # Pathological skew/kurtosis combo; PSR formula breaks down.
+        return {
+            "status": "ok",
+            "n": n,
+            "sharpe": sr_annualized,
+            "sharpe_benchmark": sharpe_benchmark,
+            "psr": 0.5,  # max-uncertainty fallback
+            "skew": skew,
+            "kurtosis": kurt_excess,
+        }
+    z = (sr_daily - sr_bench_daily) * math.sqrt(n - 1) / math.sqrt(denom_sq)
+    psr = _normal_cdf(z)
+
+    return {
+        "status": "ok",
+        "n": n,
+        "sharpe": sr_annualized,
+        "sharpe_benchmark": sharpe_benchmark,
+        "psr": float(psr),
+        "skew": skew,
+        "kurtosis": kurt_excess,
+    }
+
+
+_EULER_MASCHERONI = 0.5772156649015329
+
+
+def compute_dsr(
+    daily_returns: pd.Series | np.ndarray,
+    n_trials: int,
+) -> DSRResult:
+    """Deflated Sharpe Ratio.
+
+    Corrects PSR for the selection bias of choosing the maximum Sharpe
+    from ``n_trials`` candidates. The benchmark Sharpe is set to the
+    expected maximum SR under the null hypothesis (true SR = 0 for all
+    candidates), accounting for sample size + sample moments.
+
+    Parameters
+    ----------
+    daily_returns : array-like
+        Daily returns of the *winner* (the candidate selected as best).
+    n_trials : int
+        Number of candidates considered when selecting this winner. For
+        a 60-combo param sweep, n_trials = 60. Must be >= 1.
+
+    Returns
+    -------
+    DSRResult dict with:
+        status, n, sharpe, n_trials, sharpe_benchmark, dsr, skew, kurtosis
+
+    Formula (Bailey & López de Prado 2014, Theorem 1):
+        E[max(SR)] ≈ V * (sqrt(2 ln N) - (gamma + ln ln N) / (2 sqrt(2 ln N)))
+    where V is the standard deviation of estimated SRs across trials and
+    gamma is Euler-Mascheroni. We approximate V with the sampling std of
+    SR_hat = sqrt((1 - skew*SR + (k-1)/4 * SR^2) / (n - 1)) on the winner.
+
+    DSR = PSR(SR_hat | benchmark = E[max(SR_null)]).
+
+    Notes
+    -----
+    - n_trials = 1 reduces to PSR(0) — no selection correction needed.
+    - For very high n_trials (>1000) the asymptotic expansion above is
+      adequate; for small n (< 5) it overstates the threshold slightly,
+      which is the conservative direction (harder to clear) — fine for
+      a promotion gate.
+    """
+    if n_trials < 1:
+        raise ValueError(f"n_trials must be >= 1, got {n_trials}")
+
+    r = np.asarray(daily_returns, dtype=np.float64)
+    r = r[np.isfinite(r)]
+    n = r.size
+    if n < 30:
+        return {"status": "insufficient_data", "n": n, "n_trials": n_trials}
+
+    if n_trials == 1:
+        # No selection bias correction needed; reduce to PSR(0).
+        psr_result = compute_psr(r, sharpe_benchmark=0.0)
+        return {
+            "status": psr_result["status"],
+            "n": n,
+            "sharpe": psr_result.get("sharpe", 0.0),
+            "n_trials": 1,
+            "sharpe_benchmark": 0.0,
+            "dsr": psr_result.get("psr", 0.5),
+            "skew": psr_result.get("skew", 0.0),
+            "kurtosis": psr_result.get("kurtosis", 0.0),
+        }
+
+    sr_annualized = _annualized_sharpe(r)
+    sr_daily = sr_annualized / math.sqrt(_TRADING_DAYS_PER_YEAR)
+    skew, kurt_excess = _sample_skew_kurtosis(r)
+    kurt_raw = kurt_excess + 3.0
+
+    # Sampling std of SR_hat (per López de Prado eq. 5).
+    var_sr_sq = (1.0 - skew * sr_daily + (kurt_raw - 1.0) / 4.0 * sr_daily ** 2) / (n - 1)
+    if var_sr_sq <= 0.0:
+        return {
+            "status": "ok",
+            "n": n,
+            "sharpe": sr_annualized,
+            "n_trials": n_trials,
+            "sharpe_benchmark": 0.0,
+            "dsr": 0.5,
+            "skew": skew,
+            "kurtosis": kurt_excess,
+        }
+    v = math.sqrt(var_sr_sq)
+
+    # Expected max SR under the null, in daily SR units.
+    ln_n = math.log(n_trials)
+    sqrt_2_ln_n = math.sqrt(2.0 * ln_n)
+    if n_trials > 1:
+        ln_ln_n = math.log(ln_n) if ln_n > 0 else 0.0
+    else:
+        ln_ln_n = 0.0
+    expected_max_sr_daily = v * (sqrt_2_ln_n - (_EULER_MASCHERONI + ln_ln_n) / (2.0 * sqrt_2_ln_n))
+    expected_max_sr_annualized = expected_max_sr_daily * math.sqrt(_TRADING_DAYS_PER_YEAR)
+
+    psr_result = compute_psr(r, sharpe_benchmark=expected_max_sr_annualized)
+
+    return {
+        "status": psr_result["status"],
+        "n": n,
+        "sharpe": sr_annualized,
+        "n_trials": n_trials,
+        "sharpe_benchmark": expected_max_sr_annualized,
+        "dsr": psr_result.get("psr", 0.5),
+        "skew": skew,
+        "kurtosis": kurt_excess,
+    }

alpha_engine_lib-0.49.0/src/alpha_engine_lib/quant/stats/expectancy.py

@@ -0,0 +1,161 @@
+"""expectancy — hit rate × win/loss ratio decomposition.
+
+The single most diagnostic breakdown for distinguishing skilled vs unskilled
+risk-taking:
+
+  - **Selection skill**: high hit rate with symmetric W/L ratio (~1.0) — picks
+    winners more often than losers, magnitudes about equal.
+  - **Convexity skill**: moderate hit rate with W/L ratio > 1.5 — rides winners
+    and cuts losers; total expectancy positive even with <50% hit rate.
+  - **No skill (just YOLO into vol)**: declining hit rate with no compensating
+    W/L improvement → expectancy ≤ 0.
+
+Formula:
+    expectancy = hit_rate * avg_win - (1 - hit_rate) * avg_loss
+
+where avg_win is the mean of positive returns (or alpha) and avg_loss is the
+mean *magnitude* of negative returns. Reports both expectancy and the
+decomposition components so consumers can see WHICH dimension is failing.
+
+Pure-compute. Operates on a returns array; no I/O.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TypedDict
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+class ExpectancyResult(TypedDict, total=False):
+    status: str
+    n: int
+    hit_rate: float
+    avg_win: float
+    avg_loss: float  # magnitude (positive number)
+    win_loss_ratio: float
+    expectancy: float
+    expectancy_per_unit_loss: float  # expectancy / avg_loss; the "R-multiple" expectancy
+
+
+def compute_expectancy(
+    returns: pd.Series | np.ndarray,
+    threshold: float = 0.0,
+    min_samples: int = 10,
+) -> ExpectancyResult:
+    """Compute expectancy decomposition over a return series.
+
+    Parameters
+    ----------
+    returns : pd.Series or np.ndarray
+        Per-trade or per-pick returns (or alphas). NaN dropped.
+    threshold : float
+        Win/loss boundary. Default 0 → wins are positive returns. Set
+        non-zero to compute relative to a benchmark return (e.g.
+        threshold = SPY_return for "did we beat SPY?" expectancy).
+    min_samples : int
+        Minimum non-NaN samples required to compute. Returns
+        status=insufficient_data below this floor. Default 10.
+
+    Returns
+    -------
+    ExpectancyResult dict with:
+        status: "ok" | "insufficient_data" | "no_wins" | "no_losses"
+        n: sample size
+        hit_rate: fraction of trades where return > threshold
+        avg_win: mean of returns > threshold (None if no wins)
+        avg_loss: mean magnitude of returns <= threshold (None if no losses)
+        win_loss_ratio: avg_win / avg_loss (None if either is missing/zero)
+        expectancy: hit_rate * avg_win - (1 - hit_rate) * avg_loss
+        expectancy_per_unit_loss: expectancy / avg_loss (R-multiple form)
+
+    Notes
+    -----
+    The R-multiple form (expectancy / avg_loss) is the "expectancy per unit of
+    risk taken" — useful for comparing across regimes where absolute return
+    levels shift but the ratio of skilled-edge-to-typical-loss is the
+    invariant signal of skill.
+    """
+    arr = np.asarray(returns, dtype=np.float64)
+    arr = arr[np.isfinite(arr)]
+    n = arr.size
+    if n < min_samples:
+        return {"status": "insufficient_data", "n": n}
+
+    excess = arr - threshold
+    wins = excess[excess > 0]
+    losses = excess[excess <= 0]
+
+    hit_rate = float(wins.size) / n
+
+    if wins.size == 0:
+        return {
+            "status": "no_wins",
+            "n": n,
+            "hit_rate": 0.0,
+            "avg_win": None,  # type: ignore[typeddict-item]
+            "avg_loss": float(-losses.mean()) if losses.size else 0.0,
+            "win_loss_ratio": None,  # type: ignore[typeddict-item]
+            "expectancy": float(excess.mean()),
+            "expectancy_per_unit_loss": None,  # type: ignore[typeddict-item]
+        }
+
+    if losses.size == 0:
+        return {
+            "status": "no_losses",
+            "n": n,
+            "hit_rate": 1.0,
+            "avg_win": float(wins.mean()),
+            "avg_loss": 0.0,
+            "win_loss_ratio": None,  # type: ignore[typeddict-item]
+            "expectancy": float(excess.mean()),
+            "expectancy_per_unit_loss": None,  # type: ignore[typeddict-item]
+        }
+
+    avg_win = float(wins.mean())
+    avg_loss = float(-losses.mean())  # report as positive magnitude
+    win_loss_ratio = avg_win / avg_loss if avg_loss > 0 else None
+    expectancy = hit_rate * avg_win - (1.0 - hit_rate) * avg_loss
+    epul = expectancy / avg_loss if avg_loss > 0 else None
+
+    return {
+        "status": "ok",
+        "n": n,
+        "hit_rate": hit_rate,
+        "avg_win": avg_win,
+        "avg_loss": avg_loss,
+        "win_loss_ratio": win_loss_ratio,  # type: ignore[typeddict-item]
+        "expectancy": expectancy,
+        "expectancy_per_unit_loss": epul,  # type: ignore[typeddict-item]
+    }
+
+
+def compute_expectancy_by_group(
+    df: pd.DataFrame,
+    return_col: str,
+    group_col: str,
+    threshold: float = 0.0,
+    min_samples: int = 10,
+) -> dict[str, ExpectancyResult]:
+    """Stratify expectancy by a grouping column (team_id, conviction, sector, ...).
+
+    Returns
+    -------
+    dict[group_value, ExpectancyResult]
+        One result per group. Groups below ``min_samples`` get
+        status=insufficient_data entries.
+    """
+    if return_col not in df.columns:
+        raise KeyError(f"return_col {return_col!r} not in dataframe")
+    if group_col not in df.columns:
+        raise KeyError(f"group_col {group_col!r} not in dataframe")
+    out: dict[str, ExpectancyResult] = {}
+    for group_value, sub in df.groupby(group_col):
+        out[str(group_value)] = compute_expectancy(
+            sub[return_col], threshold=threshold, min_samples=min_samples,
+        )
+    return out

alpha_engine_lib-0.49.0/src/alpha_engine_lib/quant/stats/information_coefficient.py

@@ -0,0 +1,149 @@
+"""information_coefficient — Spearman rank correlation between a conviction/
+score and forward returns.
+
+The risk-invariant quality metric. IC of 0.05 on conservative picks vs 0.02 on
+aggressive picks tells you the signal is *worse* at the harder task even if
+absolute returns went up.
+
+Why Spearman over Pearson: rank correlation is invariant to the scale and
+distribution of the conviction scores — they only need to *order* picks
+correctly; absolute calibration is a separate concern.
+
+Pure-compute. Operates on parallel arrays of (conviction, return); no I/O.
+scipy.stats.spearmanr is used when available (for the p-value); otherwise a
+numpy rank-then-Pearson fallback gives the identical IC with no p-value.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TypedDict
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+class ICResult(TypedDict, total=False):
+    status: str
+    n: int
+    ic: float            # Spearman rank correlation
+    p_value: float       # two-sided p-value vs null hypothesis IC = 0
+    n_buckets: int       # number of distinct conviction levels
+
+
+def compute_ic(
+    conviction: pd.Series | np.ndarray,
+    forward_return: pd.Series | np.ndarray,
+    min_samples: int = 20,
+) -> ICResult:
+    """Compute Spearman rank correlation between conviction + forward return.
+
+    Parameters
+    ----------
+    conviction : array-like
+        Stated conviction or composite score per pick. Higher = more
+        confident. Numeric or ordinal (string ranks need to be encoded
+        upstream — Spearman is on the rank, but the array must sort
+        meaningfully).
+    forward_return : array-like
+        Realized forward return per pick over the prediction horizon.
+        Same length as ``conviction``. NaN in either column → that pair
+        is dropped before computing.
+    min_samples : int
+        Minimum valid pairs required. Below this floor returns
+        status=insufficient_data. Default 20 (Spearman p-values are
+        unreliable on small samples).
+
+    Returns
+    -------
+    ICResult dict with:
+        status: "ok" | "insufficient_data" | "no_variance"
+        n: number of (conviction, return) pairs after NaN filtering
+        ic: Spearman rank correlation in [-1, 1]
+        p_value: two-sided p-value
+        n_buckets: number of distinct conviction levels (low = collapsed
+                   conviction signal — the source isn't differentiating
+                   even if IC happens to look fine)
+
+    Notes
+    -----
+    - Uses scipy.stats.spearmanr if available; falls back to numpy
+      rank-then-pearson which gives identical IC but no p-value.
+    - n_buckets is reported separately so callers can flag the
+      degenerate case where conviction = constant (IC undefined;
+      correlation of constant with anything is 0).
+    """
+    c = np.asarray(conviction, dtype=np.float64)
+    r = np.asarray(forward_return, dtype=np.float64)
+    if c.size != r.size:
+        raise ValueError(
+            f"conviction (n={c.size}) and forward_return (n={r.size}) "
+            "must be same length"
+        )
+    valid = np.isfinite(c) & np.isfinite(r)
+    c = c[valid]
+    r = r[valid]
+    n = c.size
+    if n < min_samples:
+        return {"status": "insufficient_data", "n": n}
+
+    n_buckets = int(np.unique(c).size)
+    # min == max is the exact constancy test (avoids float64 std residual).
+    c_const = c.size > 0 and c.min() == c.max()
+    r_const = r.size > 0 and r.min() == r.max()
+    if n_buckets < 2 or c_const or r_const:
+        return {
+            "status": "no_variance",
+            "n": n,
+            "n_buckets": n_buckets,
+            "ic": 0.0,
+            "p_value": 1.0,
+        }
+
+    try:
+        from scipy.stats import spearmanr  # type: ignore[import-not-found]
+
+        result = spearmanr(c, r)
+        ic = float(result.statistic)
+        p_value = float(result.pvalue)
+    except Exception:
+        # Fallback: rank-then-pearson. Identical IC value; no p-value.
+        c_rank = pd.Series(c).rank().to_numpy()
+        r_rank = pd.Series(r).rank().to_numpy()
+        ic = float(np.corrcoef(c_rank, r_rank)[0, 1])
+        p_value = float("nan")
+
+    return {
+        "status": "ok",
+        "n": n,
+        "n_buckets": n_buckets,
+        "ic": ic,
+        "p_value": p_value,
+    }
+
+
+def compute_ic_by_bucket(
+    df: pd.DataFrame,
+    conviction_col: str,
+    return_col: str,
+    bucket_col: str,
+    min_samples: int = 20,
+) -> dict[str, ICResult]:
+    """IC stratified by a bucket column (sector, conviction tier, regime, ...).
+
+    The "is the signal good at the harder task" cut: split by conviction
+    decile or sector and compute IC within each. A signal whose IC drops
+    on its highest-conviction picks is failing exactly where it claims
+    to be most confident.
+    """
+    for col in (conviction_col, return_col, bucket_col):
+        if col not in df.columns:
+            raise KeyError(f"column {col!r} not in dataframe")
+    out: dict[str, ICResult] = {}
+    for bucket_value, sub in df.groupby(bucket_col):
+        out[str(bucket_value)] = compute_ic(
+            sub[conviction_col], sub[return_col], min_samples=min_samples,
+        )
+    return out