quantred 2.4.0__py3-none-any.whl

quantred/analytics/information.py

@@ -0,0 +1,197 @@
+"""Information analysis - measure skill (IC), scope (breadth), and reconcile the IR.
+
+The rest of the stack *assumes* an information coefficient and *predicts* an information
+ratio. This module **measures** them and confronts the prediction with reality - the
+most honest diagnostic in the whole system. Classical information analysis is
+cross-sectional and decompositional: how much skill (IC), across how many
+*independent* bets (BR), and does the realized IR match ``IC·√BR``?
+
+Everything here is pure math on already-computed forecasts and realized returns; the
+data wiring (sampling rebalances, aligning forward returns) lives in the service
+layer. Research-clock only.
+"""
+
+import math
+from typing import Dict, List, Sequence
+
+import numpy as np
+import pandas as pd
+
+#: Below this many rebalances the IC volatility - and so the t-stat - is meaningless.
+MIN_PERIODS = 12
+
+
+def pearson_ic(forecast: pd.Series, realized: pd.Series) -> float:
+    """Cross-sectional Pearson correlation between a forecast and the realized return."""
+    aligned = pd.concat([forecast, realized], axis=1).dropna()
+    if len(aligned) < 2 or aligned.iloc[:, 0].std() == 0 or aligned.iloc[:, 1].std() == 0:
+        return float("nan")
+    return float(aligned.iloc[:, 0].corr(aligned.iloc[:, 1]))
+
+
+def rank_ic(forecast: pd.Series, realized: pd.Series) -> float:
+    """Spearman (rank) IC - robust to alpha scale and outliers."""
+    aligned = pd.concat([forecast, realized], axis=1).dropna()
+    if len(aligned) < 2:
+        return float("nan")
+    ranked = aligned.rank()
+    if ranked.iloc[:, 0].std() == 0 or ranked.iloc[:, 1].std() == 0:
+        return float("nan")
+    return float(ranked.iloc[:, 0].corr(ranked.iloc[:, 1]))
+
+
+def ic_stats(ics: Sequence[float]) -> Dict[str, float]:
+    """Summarize an IC time series: mean, volatility, and the skill t-stat.
+
+    ``IC_tstat = mean_IC / (IC_vol / √P)`` is the honesty gate on skill - a fine mean
+    IC with a t-stat below ~2 is a few lucky periods, not evidence of skill.
+    """
+    arr = np.array([x for x in ics if x == x], dtype=float)  # drop NaNs
+    p = len(arr)
+    mean = float(arr.mean()) if p else 0.0
+    vol = float(arr.std(ddof=1)) if p > 1 else 0.0
+    tstat = float(mean / (vol / math.sqrt(p))) if vol > 0 and p > 1 else 0.0
+    return {"mean_ic": mean, "ic_vol": vol, "ic_tstat": tstat, "periods": p}
+
+
+def effective_breadth(n_names: int, rebalances_per_year: float, rho_bar: float) -> Dict[str, float]:
+    """Effective vs naive breadth - the most common self-deception in quant.
+
+    ``BR_naive = (rebalances/yr)·N`` counts every name as an independent bet.
+    ``BR_eff = (rebalances/yr)·N / (1 + (N−1)·ρ̄)`` deflates it by the average pairwise
+    correlation ρ̄: perfectly correlated bets (ρ̄→1) collapse to ``rebalances/yr``
+    (effectively one bet), independent bets (ρ̄=0) keep the full count.
+    """
+    br_naive = rebalances_per_year * n_names
+    denom = 1.0 + (n_names - 1) * rho_bar
+    br_eff = br_naive / denom if denom > 0 else br_naive
+    return {"br_eff": float(br_eff), "br_naive": float(br_naive), "rho_bar": float(rho_bar)}
+
+
+def predicted_ir(mean_ic: float, br_eff: float) -> float:
+    """The Fundamental Law: ``predicted_IR = mean_IC · √BR_eff``."""
+    return float(mean_ic * math.sqrt(max(br_eff, 0.0)))
+
+
+def ir_standard_error(ir: float, years: float) -> float:
+    """Standard error of a realized IR over ``years``: ``√((1 + IR²/2) / T)``.
+
+    A 3-year backtest has ``SE(IR) ≈ 0.58`` - so an IR of 0.5 is statistically
+    indistinguishable from 0. Report IR with this band, not as a point estimate.
+    """
+    if years <= 0:
+        return float("inf")
+    return float(math.sqrt((1.0 + ir * ir / 2.0) / years))
+
+
+def multiple_testing_inflation(n_trials: int) -> float:
+    """``P(any |t| > 2 in m trials) = 1 − 0.95^m`` - why one lucky backtest means little.
+
+    With 20 informationless strategies this is ~0.64, not 0.05.
+    """
+    return float(1.0 - 0.95 ** max(n_trials, 0))
+
+
+def risk_bucket_diagnostic(
+    active_weights: pd.Series,
+    sigma: np.ndarray,
+    symbols: Sequence[str],
+    residual_vol: pd.Series,
+    *,
+    min_per_bucket: int = 8,
+) -> Dict:
+    """Equal-risk-contribution check by residual-vol bucket.
+
+    Under **correct** alpha scaling every name contributes ~equally to active variance
+    (``E{z²}=1``), so a residual-vol bucket's share of ``w_aᵀΣw_a`` should track its
+    share of *names*, not its vol. A monotone gradient across vol buckets is the
+    fingerprint of mis-scaled alphas — most often a Case mis-choice (see
+    :func:`quantred.alphas.refine.case_test`): scaling a Case-2 signal as Case 1 multiplies
+    in ``ω_n`` a second time and tilts variance into the high-vol bucket.
+
+    Buckets names by residual-vol quantile and reports each bucket's share of active
+    variance and of ``Σ|w_a|``, the expected (name-fraction) share, and the per-bucket
+    sampling error ``√(2/n)`` of mean ``z²``. Degrades quintiles → terciles → suppressed
+    as the universe thins (tiny buckets are noise, not signal). ``active_weights`` are
+    the book's active weights ``w_a = w − w_B``; ``sigma`` the annualized Σ over
+    ``symbols`` in that order.
+    """
+    aligned = (
+        pd.concat([active_weights.rename("w"), residual_vol.rename("vol")], axis=1)
+        .reindex(list(symbols))
+        .dropna()
+    )
+    n = len(aligned)
+
+    # Bucket count: a bucket mean of z² has sampling error ≈ √(2/n_bucket); below
+    # ~min_per_bucket names per bucket the gradient is noise, so widen or suppress.
+    if n >= 5 * min_per_bucket:
+        n_buckets = 5
+    elif n >= 3 * max(min_per_bucket - 3, 4):
+        n_buckets = 3
+    else:
+        return {
+            "engaged": False,
+            "n_names": int(n),
+            "reason": f"universe too thin for reliable buckets (n={n}); "
+            f"need ≥ {3 * max(min_per_bucket - 3, 4)} names for terciles",
+        }
+
+    idx = list(aligned.index)
+    w = aligned["w"].to_numpy()
+    vols = aligned["vol"].to_numpy()
+    pos = {s: i for i, s in enumerate(symbols)}
+    order = [pos[s] for s in idx]
+    sub = np.asarray(sigma, dtype=float)[np.ix_(order, order)]
+
+    # Per-name contribution to active variance: w_i·(Σw)_i sums to w_aᵀΣw_a exactly.
+    contrib = w * (sub @ w)
+    total_var = float(contrib.sum())
+    total_abs_w = float(np.abs(w).sum())
+
+    order_by_vol = np.argsort(vols, kind="stable")
+    buckets = np.array_split(order_by_vol, n_buckets)
+    rows: List[Dict] = []
+    var_shares: List[float] = []
+    for b, members in enumerate(buckets):
+        nb = len(members)
+        var_share = float(contrib[members].sum() / total_var) if total_var != 0 else 0.0
+        rows.append(
+            {
+                "bucket": b + 1,  # 1 = lowest residual vol
+                "n_names": int(nb),
+                "vol_low": float(vols[members].min()),
+                "vol_high": float(vols[members].max()),
+                "variance_share": var_share,
+                "name_fraction": float(nb / n),
+                "abs_weight_share": float(np.abs(w[members]).sum() / total_abs_w) if total_abs_w > 0 else 0.0,
+                "sampling_error": float(math.sqrt(2.0 / nb)) if nb > 0 else float("inf"),
+            }
+        )
+        var_shares.append(var_share)
+
+    # Monotone gradient beyond the sampling band ⇒ a vol tilt (mis-scaling).
+    diffs = np.diff(var_shares)
+    monotone = bool(np.all(diffs > 0) or np.all(diffs < 0))
+    gradient = float(var_shares[-1] - var_shares[0])
+    band = float(math.sqrt(2.0 / (n / n_buckets)) / n_buckets)
+    tilt = bool(monotone and abs(gradient) > band)
+    direction = "high-vol" if gradient > 0 else "low-vol"
+
+    return {
+        "engaged": True,
+        "n_names": int(n),
+        "n_buckets": n_buckets,
+        "buckets": rows,
+        "expected_share": float(1.0 / n_buckets),
+        "variance_share_gradient": gradient,
+        "monotone": monotone,
+        "sampling_band": band,
+        "tilt_detected": tilt,
+        "verdict": (
+            f"vol-bucket tilt toward {direction} names (gradient {gradient:+.2f} vs band "
+            f"±{band:.2f}) — likely a Case mis-choice; check the per-signal case_test"
+            if tilt
+            else "no material vol-bucket tilt (contributions ~equal across buckets)"
+        ),
+    }

quantred/analytics/metrics.py

@@ -0,0 +1,502 @@
+"""Pure performance-metric primitives - the numbers that tell you, honestly,
+whether you have an edge or just a flattering backtest.
+
+One definition each for the ratios and risk measures used in the project, shared
+by the backtest analytics (:mod:`quantred.analytics.performance`) and the scanner base
+class - so "Sharpe" or "max drawdown" mean the same thing everywhere (a Sharpe
+that changes depending on who's asking is how people end up trading their savings).
+
+Every function is pure and defensive: empty/degenerate inputs yield 0.0 (or inf
+for ratios with a zero denominator) rather than raising - a backtest with zero
+trades shouldn't crash; it should just quietly tell you it found nothing.
+
+A note on annualization: the headline ratios take a
+``periods_per_year`` so they annualize to the *sampling frequency of the series
+passed in*. The backtest equity curve is resampled to daily P&L
+(:func:`quantred.analytics.performance.build_equity_curve`), so its returns are daily
+and ``TRADING_DAYS_PER_YEAR`` is the correct factor; intraday or weekly series
+pass their own factor via :meth:`quantred.marketdata.timeframe.Timeframe.periods_per_year`.
+"""
+
+import math
+from typing import Sequence, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+#: US trading days per year, used to annualize daily-return ratios.
+TRADING_DAYS_PER_YEAR = 252
+
+#: Euler-Mascheroni constant, used by the Deflated Sharpe expected-maximum.
+_EULER_MASCHERONI = 0.5772156649015329
+
+Numbers = Union[Sequence[float], pd.Series, np.ndarray]
+
+
+def _as_series(values: Numbers) -> pd.Series:
+    return values if isinstance(values, pd.Series) else pd.Series(list(values), dtype="float64")
+
+
+# --------------------------------------------------------------------------- #
+# Gaussian helpers (hand-rolled so the base install needs no scipy)
+# --------------------------------------------------------------------------- #
+def norm_cdf(x: float) -> float:
+    """Standard-normal CDF via the error function (exact, stdlib only)."""
+    return 0.5 * (1.0 + math.erf(x / math.sqrt(2.0)))
+
+
+def norm_ppf(p: float) -> float:
+    """Standard-normal inverse CDF (quantile) via Acklam's rational approximation.
+
+    Accurate to ~1e-9 over the open interval (0, 1); clamps the endpoints.
+    """
+    if p <= 0.0:
+        return float("-inf")
+    if p >= 1.0:
+        return float("inf")
+
+    # Coefficients for Acklam's algorithm.
+    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, phigh = 0.02425, 1.0 - 0.02425
+    if p < plow:
+        q = math.sqrt(-2.0 * math.log(p))
+        return (((((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
+        )
+    if p > phigh:
+        q = math.sqrt(-2.0 * math.log(1.0 - p))
+        return -(((((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
+        )
+    q = p - 0.5
+    r = q * q
+    return (
+        (((((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)
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Returns / growth
+# --------------------------------------------------------------------------- #
+def returns_from_equity(equity_curve: Numbers) -> pd.Series:
+    """Period-over-period returns from an equity curve."""
+    return _as_series(equity_curve).pct_change().dropna()
+
+
+def cagr(equity_curve: Numbers, years: float) -> float:
+    """Compound annual growth rate from first->last equity over ``years`` elapsed.
+
+    Returns a fraction (0.20 == 20%/yr). ``0.0`` for non-positive elapsed time or
+    a degenerate curve.
+    """
+    equity = _as_series(equity_curve)
+    if len(equity) < 2 or years <= 0:
+        return 0.0
+    start, end = float(equity.iloc[0]), float(equity.iloc[-1])
+    if start <= 0 or end <= 0:
+        return 0.0
+    return float((end / start) ** (1.0 / years) - 1.0)
+
+
+def annualized_volatility(returns: Numbers, periods_per_year: int = TRADING_DAYS_PER_YEAR) -> float:
+    """Standard deviation of returns scaled to a year."""
+    r = _as_series(returns)
+    if len(r) < 2:
+        return 0.0
+    return float(r.std() * np.sqrt(periods_per_year))
+
+
+def downside_deviation(returns: Numbers, periods_per_year: int = TRADING_DAYS_PER_YEAR) -> float:
+    """Annualized deviation of negative returns only (the Sortino denominator)."""
+    r = _as_series(returns)
+    downside = r[r < 0]
+    if len(downside) < 2:
+        return 0.0
+    return float(downside.std() * np.sqrt(periods_per_year))
+
+
+# --------------------------------------------------------------------------- #
+# Risk-adjusted ratios
+# --------------------------------------------------------------------------- #
+def sharpe_ratio(returns: Numbers, periods_per_year: int = TRADING_DAYS_PER_YEAR) -> float:
+    """Annualized Sharpe ratio (risk-free rate assumed 0)."""
+    r = _as_series(returns)
+    if len(r) < 2 or r.std() == 0:
+        return 0.0
+    return float(np.sqrt(periods_per_year) * r.mean() / r.std())
+
+
+def sortino_ratio(returns: Numbers, periods_per_year: int = TRADING_DAYS_PER_YEAR) -> float:
+    """Annualized Sortino ratio (downside-deviation denominator)."""
+    r = _as_series(returns)
+    if len(r) < 2:
+        return 0.0
+    downside = r[r < 0]
+    if downside.empty or downside.std() == 0:
+        return 0.0
+    return float(np.sqrt(periods_per_year) * r.mean() / downside.std())
+
+
+def calmar_ratio(cagr_value: float, max_drawdown_value: float) -> float:
+    """CAGR / max drawdown.
+
+    Both arguments are fractions. ``inf`` when drawdown is zero. The drawdown's sign
+    convention varies by caller, so only its magnitude is used; the CAGR keeps its sign.
+    Taking the magnitude of the whole ratio reported a losing run's Calmar as positive.
+    """
+    if max_drawdown_value == 0:
+        return float("inf")
+    return float(cagr_value / abs(max_drawdown_value))
+
+
+#: Below this, a book has no market exposure worth dividing by and Treynor stops
+#: meaning anything: the ratio's error grows as 1/beta², and a beta this small is not
+#: resolvable from zero by the regression that produced it. Guarding only the exact
+#: ``beta == 0`` let a beta of -0.0001 through and produced a Treynor of -262 beside a
+#: beta the report rendered as "-0.00" - an unbounded number whose cause was invisible
+#: on the same screen. :class:`~quantred.execution.sizing.BetaSizer` already clamps
+#: for this when it *sizes* on beta; the same blow-up applies when reporting on it, and
+#: `--beta-sizing` puts books in exactly this regime by design, so it is not exotic.
+MIN_ABS_BETA_FOR_TREYNOR = 0.05
+
+
+def treynor_ratio(returns: Numbers, beta: float, periods_per_year: int = TRADING_DAYS_PER_YEAR) -> float:
+    """Annualized excess return per unit of market beta.
+
+    ``0.0`` when ``|beta|`` is below :data:`MIN_ABS_BETA_FOR_TREYNOR` - the established
+    "unavailable" value for the benchmark-relative metrics, flagged alongside them so a
+    suppressed ratio is distinguishable from a genuine zero.
+    """
+    r = _as_series(returns)
+    if len(r) < 2 or abs(beta) < MIN_ABS_BETA_FOR_TREYNOR:
+        return 0.0
+    return float(r.mean() * periods_per_year / beta)
+
+
+# --------------------------------------------------------------------------- #
+# Drawdown shape
+# --------------------------------------------------------------------------- #
+def drawdown_series(equity_curve: Numbers) -> pd.Series:
+    """Per-point drawdown as a (negative) fraction of the running peak."""
+    equity = _as_series(equity_curve)
+    if equity.empty:
+        return pd.Series(dtype="float64")
+    running_max = equity.expanding().max()
+    return (equity - running_max) / running_max
+
+
+def max_drawdown(equity_curve: Numbers) -> float:
+    """Maximum peak-to-trough decline of an equity curve, as a positive fraction."""
+    dd = drawdown_series(equity_curve)
+    return float(abs(dd.min())) if not dd.empty else 0.0
+
+
+def max_drawdown_duration(equity_curve: Numbers) -> int:
+    """Longest run of consecutive periods spent below a prior peak (underwater)."""
+    equity = _as_series(equity_curve)
+    if len(equity) < 2:
+        return 0
+    underwater = equity < equity.cummax()
+    longest = current = 0
+    for uw in underwater.to_numpy():
+        current = current + 1 if uw else 0
+        longest = max(longest, current)
+    return int(longest)
+
+
+def ulcer_index(equity_curve: Numbers) -> float:
+    """Root-mean-square drawdown depth (%), penalizing deep *and* long drawdowns."""
+    dd = drawdown_series(equity_curve)
+    if dd.empty:
+        return 0.0
+    return float(np.sqrt(np.mean((dd.to_numpy() * 100.0) ** 2)))
+
+
+def recovery_factor(net_profit: float, max_drawdown_value: float) -> float:
+    """Net profit / max drawdown (absolute-dollar cousin of Calmar)."""
+    if max_drawdown_value == 0:
+        return float("inf")
+    return float(net_profit / max_drawdown_value)
+
+
+def martin_ratio(cagr_value: float, ulcer_index_value: float) -> float:
+    """Ulcer Performance Index: CAGR / ulcer index. ``0.0`` if ulcer is zero."""
+    if ulcer_index_value == 0:
+        return 0.0
+    return float(cagr_value * 100.0 / ulcer_index_value)
+
+
+def sterling_ratio(cagr_value: float, average_drawdown: float) -> float:
+    """CAGR / average drawdown. ``inf`` when average drawdown is zero; negative for a
+    losing run, as :func:`calmar_ratio` is."""
+    if average_drawdown == 0:
+        return float("inf")
+    return float(cagr_value / abs(average_drawdown))
+
+
+# --------------------------------------------------------------------------- #
+# Tail / distribution risk
+# --------------------------------------------------------------------------- #
+def value_at_risk(returns: Numbers, level: float = 0.95) -> float:
+    """Historical Value-at-Risk: the loss not exceeded with ``level`` confidence.
+
+    Returned as a positive fraction (0.03 == a 3% loss), and 0.0 when even that tail is
+    a gain: taking the magnitude of the percentile reported a 0.2% *gain* at the 5th
+    percentile as a 0.2% loss.
+    """
+    r = _as_series(returns)
+    if r.empty:
+        return 0.0
+    return float(max(0.0, -np.percentile(r.to_numpy(), (1.0 - level) * 100.0)))
+
+
+def conditional_var(returns: Numbers, level: float = 0.95) -> float:
+    """Expected shortfall: mean loss in the worst ``1 - level`` tail (positive), 0.0 when
+    that tail is on average a gain - the same sign rule as :func:`value_at_risk`."""
+    r = _as_series(returns)
+    if r.empty:
+        return 0.0
+    cutoff = np.percentile(r.to_numpy(), (1.0 - level) * 100.0)
+    tail = r[r <= cutoff]
+    if tail.empty:
+        return float(max(0.0, -cutoff))
+    return float(max(0.0, -tail.mean()))
+
+
+def skewness(returns: Numbers) -> float:
+    """Sample skewness of returns (0.0 for < 3 points)."""
+    r = _as_series(returns)
+    if len(r) < 3:
+        return 0.0
+    return float(r.skew())
+
+
+def kurtosis(returns: Numbers) -> float:
+    """Excess kurtosis of returns (Fisher; 0.0 for a normal distribution)."""
+    r = _as_series(returns)
+    if len(r) < 4:
+        return 0.0
+    return float(r.kurtosis())
+
+
+def tail_ratio(returns: Numbers) -> float:
+    """Ratio of the right tail (95th pct) to the left tail (5th pct), in magnitude."""
+    r = _as_series(returns)
+    if r.empty:
+        return 0.0
+    left = abs(np.percentile(r.to_numpy(), 5))
+    if left == 0:
+        return float("inf")
+    return float(abs(np.percentile(r.to_numpy(), 95)) / left)
+
+
+def omega_ratio(returns: Numbers, threshold: float = 0.0) -> float:
+    """Probability-weighted gains over losses relative to ``threshold``."""
+    r = _as_series(returns)
+    if r.empty:
+        return 0.0
+    excess = r - threshold
+    gains = excess[excess > 0].sum()
+    losses = -excess[excess < 0].sum()
+    if losses == 0:
+        return float("inf")
+    return float(gains / losses)
+
+
+# --------------------------------------------------------------------------- #
+# Statistical robustness (Bailey & Lopez de Prado) - the honest-evaluation core
+# --------------------------------------------------------------------------- #
+def probabilistic_sharpe_ratio(returns: Numbers, benchmark_sr: float = 0.0) -> float:
+    """P(true Sharpe > ``benchmark_sr``) given the observed per-period Sharpe.
+
+    Corrects the Sharpe estimate for sample length, skew and (excess) kurtosis.
+    ``benchmark_sr`` is a *per-period* (non-annualized) Sharpe, matching the
+    series passed in. Returns a probability in [0, 1].
+    """
+    r = _as_series(returns)
+    n = len(r)
+    if n < 3 or r.std() == 0:
+        return 0.0
+    sr = float(r.mean() / r.std())  # per-period Sharpe estimate
+    skew = skewness(r)
+    kurt = kurtosis(r) + 3.0  # Pearson kurtosis (normal == 3)
+    denom = 1.0 - skew * sr + (kurt - 1.0) / 4.0 * sr**2
+    if denom <= 0:
+        return 0.0
+    z = (sr - benchmark_sr) * math.sqrt(n - 1) / math.sqrt(denom)
+    return float(norm_cdf(z))
+
+
+def expected_max_sharpe(var_of_trial_sr: float, n_trials: int) -> float:
+    """Expected maximum per-period Sharpe across ``n_trials`` independent trials.
+
+    The multiple-testing benchmark used by the Deflated Sharpe Ratio.
+    """
+    if n_trials <= 1 or var_of_trial_sr <= 0:
+        return 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(var_of_trial_sr) * ((1.0 - _EULER_MASCHERONI) * z1 + _EULER_MASCHERONI * z2))
+
+
+def deflated_sharpe_ratio(returns: Numbers, n_trials: int, var_of_trial_sr: float = None) -> float:
+    """PSR against the expected best of ``n_trials`` configs (anti-overfitting).
+
+    ``var_of_trial_sr`` is the variance of the *per-period* Sharpe estimates
+    across the configs that were tried. When unknown (a standalone backtest),
+    it falls back to the null-hypothesis estimator variance ``1/(n-1)`` so the
+    deflation is still conservative. Returns a probability in [0, 1].
+    """
+    r = _as_series(returns)
+    n = len(r)
+    if n < 3 or r.std() == 0 or n_trials < 1:
+        return 0.0
+    if var_of_trial_sr is None:
+        var_of_trial_sr = 1.0 / (n - 1)
+    sr_star = expected_max_sharpe(var_of_trial_sr, n_trials)
+    return probabilistic_sharpe_ratio(r, benchmark_sr=sr_star)
+
+
+# --------------------------------------------------------------------------- #
+# Trade-level statistics
+# --------------------------------------------------------------------------- #
+def win_rate(pnl: Numbers) -> float:
+    """Fraction of trades with positive P&L."""
+    p = _as_series(pnl)
+    return float((p > 0).sum() / len(p)) if len(p) else 0.0
+
+
+def profit_factor(pnl: Numbers) -> float:
+    """Gross profit / gross loss. ``inf`` when there are no losses."""
+    p = _as_series(pnl)
+    gross_loss = abs(p[p < 0].sum())
+    if gross_loss == 0:
+        return float("inf")
+    return float(p[p > 0].sum() / gross_loss)
+
+
+def expectancy(pnl: Numbers) -> float:
+    """Mean P&L per trade (in account currency)."""
+    p = _as_series(pnl)
+    return float(p.mean()) if len(p) else 0.0
+
+
+def payoff_ratio(pnl: Numbers) -> float:
+    """Average win / average loss (magnitudes). ``inf`` with no losing trades."""
+    p = _as_series(pnl)
+    wins, losses = p[p > 0], p[p < 0]
+    if losses.empty or losses.mean() == 0:
+        return float("inf") if not wins.empty else 0.0
+    if wins.empty:
+        return 0.0
+    return float(wins.mean() / abs(losses.mean()))
+
+
+def gain_to_pain_ratio(pnl: Numbers) -> float:
+    """Sum of P&L over the sum of absolute losses. ``inf`` with no losses."""
+    p = _as_series(pnl)
+    pain = abs(p[p < 0].sum())
+    if pain == 0:
+        return float("inf")
+    return float(p.sum() / pain)
+
+
+def kelly_criterion(pnl: Numbers) -> float:
+    """Kelly fraction from the win rate and payoff ratio: ``W - (1 - W)/R``.
+
+    The theoretical optimal capital fraction; values are typically scaled down
+    in practice. ``0.0`` for degenerate input.
+    """
+    p = _as_series(pnl)
+    if p.empty:
+        return 0.0
+    w = win_rate(p)
+    r = payoff_ratio(p)
+    if r == 0 or math.isinf(r):
+        return 0.0
+    return float(w - (1.0 - w) / r)
+
+
+def system_quality_number(pnl: Numbers) -> float:
+    """Van Tharp's SQN: ``sqrt(n) * mean(pnl) / std(pnl)`` (expectancy quality)."""
+    p = _as_series(pnl)
+    if len(p) < 2 or p.std() == 0:
+        return 0.0
+    return float(np.sqrt(len(p)) * p.mean() / p.std())
+
+
+def consecutive(pnl: Numbers, *, winning: bool) -> int:
+    """Longest run of consecutive winning (or losing) trades, in trade order."""
+    p = _as_series(pnl)
+    longest = current = 0
+    for value in p.to_numpy():
+        hit = value > 0 if winning else value < 0
+        current = current + 1 if hit else 0
+        longest = max(longest, current)
+    return int(longest)
+
+
+# --------------------------------------------------------------------------- #
+# Benchmark-relative
+# --------------------------------------------------------------------------- #
+def _align(returns: Numbers, benchmark_returns: Numbers) -> pd.DataFrame:
+    paired = pd.concat([_as_series(returns), _as_series(benchmark_returns)], axis=1, keys=["r", "b"]).dropna()
+    return paired
+
+
+def alpha_beta(returns: Numbers, benchmark_returns: Numbers) -> Tuple[float, float, float]:
+    """OLS of strategy returns on benchmark returns -> ``(alpha, beta, r_squared)``.
+
+    ``alpha`` is the per-period intercept; ``beta`` the slope; ``r_squared`` the
+    fraction of variance explained. ``(0.0, 0.0, 0.0)`` for degenerate input.
+    """
+    paired = _align(returns, benchmark_returns)
+    if len(paired) < 3:
+        return 0.0, 0.0, 0.0
+    benchmark_var = paired["b"].var()
+    if benchmark_var == 0:
+        return 0.0, 0.0, 0.0
+    beta = float(paired["r"].cov(paired["b"]) / benchmark_var)
+    alpha = float(paired["r"].mean() - beta * paired["b"].mean())
+    corr = paired["r"].corr(paired["b"])
+    r_squared = float(corr**2) if pd.notna(corr) else 0.0
+    return alpha, beta, r_squared
+
+
+def information_ratio(
+    returns: Numbers, benchmark_returns: Numbers, periods_per_year: int = TRADING_DAYS_PER_YEAR
+) -> float:
+    """Annualized mean active return over its tracking error vs a benchmark."""
+    paired = _align(returns, benchmark_returns)
+    if len(paired) < 2:
+        return 0.0
+    active = paired["r"] - paired["b"]
+    if active.std() == 0:
+        return 0.0
+    return float(np.sqrt(periods_per_year) * active.mean() / active.std())