quantred 2.4.0__py3-none-any.whl

quantred/alphas/horizon.py

@@ -0,0 +1,153 @@
+"""Information horizon - how fast an alpha decays, and what to do about it.
+
+Every alpha is perishable: its forecasting power (IC) decays over time at a rate
+that is an intrinsic property of the signal. Measuring that decay yields two free
+wins a research engine should surface:
+
+1. **The rebalance cadence is derivable** - trading much faster than the signal
+   regenerates pays cost for noise; much slower throws away breadth. The half-life
+   pins the sweet spot.
+2. **The freshest signal is rarely optimal** - blending the current signal with a
+   lagged copy systematically raises the information ratio (a second partly-
+   independent read, or a hedge that cancels noise).
+
+This module is the pure math: fit the decay from an IC-vs-lag profile (measured by
+the information-analysis layer), and compute the optimal current/lagged blend.
+"""
+
+import math
+from typing import Dict, Mapping, Tuple
+
+import numpy as np
+
+#: horizon/half-life ratio at which signal-return correlation peaks (≈ 0.638).
+PEAK_HORIZON_RATIO = 1.2566
+
+
+def fit_decay(ic_by_lag: Mapping[int, float], ci_z: float = 1.96) -> Dict[str, float]:
+    """Fit the per-period decay ``δ`` from an IC-vs-lag profile by log-linear regression.
+
+    Models ``IC(n) = IC₀ · δ^n`` ⇒ ``ln IC(n) = ln IC₀ + n·ln δ``, fit on the lags with
+    a positive IC (the reliable, same-sign region). Returns ``δ``, the half-life
+    ``HL = −ln2 / ln δ``, the fitted ``IC₀``, and the fit ``R²`` (low R² ⇒ the decay
+    isn't a clean exponential - don't over-trust the half-life).
+
+    Also fits the OLS standard error of the decay slope and reports the
+    ``ci_z``-sigma confidence band on the half-life (``half_life_lower``,
+    ``half_life_upper``) - short histories give wide CIs on the half-life, and
+    the multi-period trading policy's aim discount uses this band rather than
+    trusting the point estimate. ``half_life_upper`` (a less-negative slope, i.e. slower
+    decay) is the direction that avoids prematurely discounting a genuinely
+    persistent signal on a noisy short history; ``half_life_lower`` is the
+    faster-decay end. Both collapse to the point estimate when the slope's SE isn't
+    defined (fewer than 3 usable lags).
+    """
+    lags = sorted(n for n, ic in ic_by_lag.items() if ic > 0 and n >= 0)
+    if len(lags) < 2:
+        return {
+            "delta": float("nan"),
+            "half_life": float("nan"),
+            "ic0": float("nan"),
+            "r_squared": 0.0,
+            "half_life_lower": float("nan"),
+            "half_life_upper": float("nan"),
+            "decay_slope_se": float("nan"),
+        }
+
+    x = np.array(lags, dtype=float)
+    y = np.log(np.array([ic_by_lag[n] for n in lags], dtype=float))
+    slope, intercept = np.polyfit(x, y, 1)
+    delta = float(math.exp(slope))
+    resid = y - (slope * x + intercept)
+    ss_res = float(np.sum(resid**2))
+    ss_tot = float(np.sum((y - y.mean()) ** 2))
+    r_squared = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+
+    half_life = -math.log(2) / math.log(delta) if 0 < delta < 1 else float("inf")
+
+    n = len(lags)
+    sxx = float(np.sum((x - x.mean()) ** 2))
+    slope_se = math.sqrt(ss_res / (n - 2) / sxx) if n > 2 and sxx > 0 else float("nan")
+
+    def _half_life_at(s: float) -> float:
+        return -math.log(2) / s if s < 0 else float("inf")
+
+    if slope_se == slope_se:  # not NaN
+        half_life_upper = _half_life_at(slope + ci_z * slope_se)  # less negative -> slower decay
+        half_life_lower = _half_life_at(slope - ci_z * slope_se)  # more negative -> faster decay
+    else:
+        half_life_upper = half_life
+        half_life_lower = half_life
+
+    return {
+        "delta": delta,
+        "half_life": half_life,
+        "ic0": float(math.exp(intercept)),
+        "r_squared": r_squared,
+        "half_life_lower": half_life_lower,
+        "half_life_upper": half_life_upper,
+        "decay_slope_se": slope_se,
+    }
+
+
+def peak_return_horizon(half_life: float) -> float:
+    """The forward-return horizon a signal of this half-life predicts best (≈ 1.26·HL).
+
+    Scoring a short-horizon signal against a long-horizon return (or vice versa) is a
+    common way to understate real skill; this is the horizon to match.
+    """
+    return PEAK_HORIZON_RATIO * half_life if math.isfinite(half_life) else float("inf")
+
+
+def blend_weights(gamma: float, rho: float) -> Tuple[float, float]:
+    """IR-maximizing weights on the current vs lagged signal: ``(w_now, w_lag)``.
+
+    ``w_now = (1 − γ·ρ) / (1 + γ² − 2·γ·ρ)`` (decay ``γ``, current/lagged
+    autocorrelation ``ρ``); ``w_lag = 1 − w_now``. Three regimes:
+
+    - ``γ > ρ`` → **diversify**: ``w_lag > 0`` (the lag carries independent info).
+    - ``γ < ρ`` → **hedge**: ``w_lag < 0`` (it mostly cancels current noise).
+    - ``γ = ρ`` → the latest signal alone is sufficient (``w_lag = 0``).
+    """
+    denom = 1.0 + gamma * gamma - 2.0 * gamma * rho
+    if denom == 0:
+        return 1.0, 0.0
+    w_now = (1.0 - gamma * rho) / denom
+    return w_now, 1.0 - w_now
+
+
+def frequency_ir_curve(ic_by_lag: Mapping[int, float]) -> Dict[int, float]:
+    """The accuracy-vs-frequency curve ``IR(Δt) = IC(Δt)·√(1/Δt)`` over candidate cadences.
+
+    Faster rebalancing raises ``√BR`` but acts on less-confirmed information (lower
+    ``IC``); the optimum is interior. Returns ``{cadence: IR_proxy}`` so the cadence is
+    *chosen*, not assumed.
+    """
+    curve = {}
+    for dt, ic in ic_by_lag.items():
+        if dt >= 1:
+            curve[dt] = float(ic * math.sqrt(1.0 / dt))
+    return curve
+
+
+def recommended_cadence(ic_by_lag: Mapping[int, float]) -> int:
+    """The cadence (in periods) that maximizes the IR proxy ``IC(Δt)·√(1/Δt)``."""
+    curve = frequency_ir_curve(ic_by_lag)
+    return max(curve, key=curve.get) if curve else 1
+
+
+def effective_sample_size(n_obs: float, horizon: int, spacing: float = 1.0) -> float:
+    """Effective *independent* observations when each spans ``horizon`` periods.
+
+    An IC measured from returns over a ``horizon``-period holding, sampled every
+    ``spacing`` periods, overlaps: consecutive observations share ``horizon − spacing``
+    periods of return and so are not independent. The independent count is
+    ``n_obs / overlap`` with ``overlap = max(1, horizon/spacing)`` — daily rows with a
+    21-day horizon (``spacing=1``) are ~21× overlapped, so ``T_eff ≈ n/21``; rebalances
+    already spaced ``≥ horizon`` apart (``spacing ≥ horizon``) are independent and
+    ``T_eff = n``. This is the honest ``T`` the IC-uncertainty shrink
+    (:func:`quantred.alphas.refine.level_shrink_factor`) needs: using the raw row count
+    under-shrinks by exactly the overlap factor.
+    """
+    overlap = max(1.0, horizon / max(spacing, 1e-9))
+    return float(n_obs / overlap) if overlap > 0 else float(n_obs)

quantred/alphas/refine.py

@@ -0,0 +1,300 @@
+"""Alpha refinement primitives - the pure-math steps that turn a raw signal into a
+scaled, comparable residual-return forecast.
+
+Every function here is a pure cross-sectional transform on a pandas Series indexed
+by symbol: same names in, same names out, inputs untouched. They are deliberately
+standalone (no state, no I/O) so each step of the pipeline in
+:mod:`quantred.alphas.base` is unit-testable in isolation and composable.
+
+The pipeline order:
+
+    raw scores  ->  winsorize  ->  zscore  ->  [neutralize]  ->  scale  ->  cap
+
+All standardization here is **cross-sectional** (across names at one rebalance),
+never across time for one name - standardizing over time would reintroduce the
+look-ahead this module exists to avoid.
+"""
+
+import math
+
+import numpy as np
+import pandas as pd
+
+
+def winsorize(scores: pd.Series, lower: float = 0.025, upper: float = 0.975) -> pd.Series:
+    """Clip scores to their ``[lower, upper]`` cross-sectional quantiles.
+
+    Kills single-name outliers so one extreme score can't dominate the z-score's
+    mean/std. With too few names the quantiles are meaningless; callers skip this
+    step on thin universes (see :mod:`quantred.alphas.base`).
+    """
+    if scores.empty:
+        return scores
+    lo = scores.quantile(lower)
+    hi = scores.quantile(upper)
+    return scores.clip(lower=lo, upper=hi)
+
+
+def demean(scores: pd.Series) -> pd.Series:
+    """Subtract the cross-sectional mean (the thin-universe fallback for zscore).
+
+    Centers the scores at 0 without dividing by the cross-sectional std, which is
+    unstable on a handful of names. Preserves relative spacing; sets no scale.
+    """
+    if scores.empty:
+        return scores
+    return scores - scores.mean()
+
+
+def zscore(scores: pd.Series) -> pd.Series:
+    """Cross-sectional standardization: ``z = (s - mean) / std``.
+
+    Uses the population std (``ddof=0``) so the output has mean 0 and unit
+    dispersion exactly. If every score is identical (zero std) the result is all
+    zeros rather than NaN/inf - a degenerate universe expresses no view.
+    """
+    if scores.empty:
+        return scores
+    centered = scores - scores.mean()
+    std = scores.std(ddof=0)
+    if std == 0 or not np.isfinite(std):
+        return centered * 0.0
+    return centered / std
+
+
+def neutralize(z: pd.Series, exposures: pd.DataFrame) -> pd.Series:
+    """Regress ``z`` on ``exposures`` and return the residual (orthogonal to them).
+
+    Makes the alpha neutral to the supplied exposures: an intercept is always
+    included (so the residual is mean-zero, i.e. benchmark/equal-weight neutral),
+    and the residual is orthogonal to every exposure column by construction
+    (the defining property of an OLS residual). Pass a single beta column for
+    benchmark-beta neutralization, or a factor-exposure matrix for factor
+    neutralization.
+
+    ``exposures`` is a DataFrame indexed by symbol; it is aligned to ``z`` and any
+    name missing an exposure is dropped from the regression and returned unchanged.
+    """
+    if z.empty or exposures is None or exposures.empty:
+        return z
+
+    frame = exposures.reindex(z.index)
+    valid = frame.dropna().index
+    if len(valid) < 2:
+        return z
+
+    y = z.loc[valid].to_numpy(dtype=float)
+    # Design matrix: an intercept column plus the exposures.
+    x = np.column_stack([np.ones(len(valid)), frame.loc[valid].to_numpy(dtype=float)])
+    coeffs, *_ = np.linalg.lstsq(x, y, rcond=None)
+    residual = y - x @ coeffs
+
+    out = z.copy()
+    out.loc[valid] = residual
+    return out
+
+
+def scale_to_alpha(z: pd.Series, residual_vol: pd.Series, ic: float) -> pd.Series:
+    """Apply the refinement identity ``alpha_i = sigma_i * IC * z_i``.
+
+    Turns a standardized score into a forecast of annualized residual return. The
+    cross-sectional std of the result is ``~ IC * sigma`` (for unit-std ``z``), so
+    the alphas carry the right information ratio for a mean-variance optimizer to
+    size positions by genuine conviction rather than by an arbitrary signal scale.
+
+    ``residual_vol`` is aligned to ``z`` by symbol. This is the **Case 1** scaling
+    (see :func:`case_test`): correct when the signal's per-name time-series vol is
+    roughly constant across names, so the cross-sectional z equals the time-series z
+    the standard rule is stated in. For a **Case 2** signal pass a constant
+    :func:`case_scale_factor` as ``residual_vol`` instead of the per-name vector.
+    """
+    vol = residual_vol.reindex(z.index)
+    # Evaluated as (sigma * IC) * z to match the written identity exactly.
+    return vol * ic * z
+
+
+def case_scale_factor(
+    raw_scores: pd.Series,
+    residual_vol: pd.Series,
+    winsorize_limits: tuple = (0.025, 0.975),
+) -> float:
+    """The **Case 2** constant scale ``c_g = Std_CS{g} / Std_CS{g/ω}``.
+
+    A Case-2 signal (per-name signal vol ∝ the name's residual vol ``ω_n`` —
+    empirically most price/estimate signals) already carries the volatility inside
+    the raw score; multiplying by ``ω_n`` in :func:`scale_to_alpha` double-counts it
+    and tilts the book into high-vol names. The fix replaces the per-name ``ω_n`` with
+    one cross-sectional **constant** ``c_g`` (a vol-dimensioned, dispersion-matched
+    representative vol), so ``alpha = IC · c_g · z`` sizes by conviction without the
+    spurious vol tilt.
+
+    Computed on the **raw** signal (winsorized the same way the pipeline winsorizes),
+    because after standardization the raw dispersion that defines ``c_g`` is gone.
+    Returns NaN when the ratio can't be formed (too few names, all-zero vol) so the
+    caller can fall back.
+    """
+    g = raw_scores.dropna()
+    if len(g) < 2:
+        return float("nan")
+    g = winsorize(g, *winsorize_limits)
+    vol = residual_vol.reindex(g.index)
+    ratio = (g / vol.where(vol > 0)).replace([np.inf, -np.inf], np.nan).dropna()
+    num = g.std(ddof=0)
+    den = ratio.std(ddof=0)
+    if not np.isfinite(den) or den == 0:
+        return float("nan")
+    return float(num / den)
+
+
+def case_test(
+    signal_history: pd.DataFrame,
+    residual_vol: pd.Series,
+    *,
+    price_derived: bool = True,
+    min_obs: int = 36,
+    r2_case2: float = 0.25,
+    r2_case1: float = 0.05,
+    t_threshold: float = 2.0,
+) -> dict:
+    """Decide a signal's scaling: **Case 1** (``ω·IC·z``) vs **Case 2** (``IC·c_g·z``).
+
+    The standard refinement rule ``α = ω·IC·z`` is stated in *time-series* z-scores,
+    but the pipeline computes *cross-sectional* z. Whether the two coincide is an
+    empirical property of each signal:
+
+    - **Case 1** — per-name time-series signal vol ``Std_TS{g_n}`` is ~constant across
+      names ⇒ ``z_TS ≈ z_CS`` and the ``ω_n`` multiply is right (the classic
+      sector-momentum example).
+    - **Case 2** — ``Std_TS{g_n}`` is ~proportional to the name's residual vol ``ω_n``
+      (most price/estimate signals) ⇒ the vol is already inside the raw signal and the
+      ``ω_n`` multiply double-counts it.
+
+    The test regresses ``Std_TS{g_n} = a + b·ω_n`` across names: a strong, significant
+    positive slope ⇒ Case 2. ``signal_history`` is a time×name frame of the **raw**
+    signal; ``residual_vol`` the per-name ``ω_n``. Needs ``≥ min_obs`` time observations
+    to engage; below that (or in the ambiguous band ``r2_case1 < R² < r2_case2``) it
+    returns the empirical base rate — **Case 2 for price-derived signals, Case 1
+    otherwise** — flagged ``ambiguous`` so a wrong call is visible, not silent.
+    """
+    default_case = 2 if price_derived else 1
+
+    def _result(case, r2, t, slope, n_obs, n_names, engaged, ambiguous, reason):
+        return {
+            "case": case,
+            "r_squared": float(r2),
+            "t_stat": float(t),
+            "slope": float(slope),
+            "n_obs": int(n_obs),
+            "n_names": int(n_names),
+            "engaged": bool(engaged),
+            "ambiguous": bool(ambiguous),
+            "reason": reason,
+        }
+
+    if signal_history is None or signal_history.empty:
+        return _result(default_case, 0.0, 0.0, 0.0, 0, 0, False, True, "no signal history")
+
+    std_ts = signal_history.std(ddof=1)
+    counts = signal_history.count()
+    n_obs = int(counts.median()) if len(counts) else 0
+
+    aligned = pd.concat([std_ts.rename("y"), residual_vol.rename("x")], axis=1).dropna()
+    # A name needs enough time observations for its Std_TS to mean anything.
+    aligned = aligned[counts.reindex(aligned.index).fillna(0) >= min(min_obs, max(n_obs, 2))]
+    n_names = len(aligned)
+
+    if n_obs < min_obs or n_names < 3:
+        return _result(
+            default_case,
+            0.0,
+            0.0,
+            0.0,
+            n_obs,
+            n_names,
+            False,
+            True,
+            f"insufficient history (n_obs={n_obs} < {min_obs} or n_names={n_names} < 3); "
+            f"defaulting to Case {default_case} ({'price-derived' if price_derived else 'other'})",
+        )
+
+    x = aligned["x"].to_numpy()
+    y = aligned["y"].to_numpy()
+    xm, ym = x.mean(), y.mean()
+    sxx = float(((x - xm) ** 2).sum())
+    if sxx == 0:
+        return _result(default_case, 0.0, 0.0, 0.0, n_obs, n_names, False, True, "no ω dispersion")
+    slope = float(((x - xm) * (y - ym)).sum() / sxx)
+    resid = y - (ym + slope * (x - xm))
+    ss_res = float((resid**2).sum())
+    ss_tot = float(((y - ym) ** 2).sum())
+    r2 = 1.0 - ss_res / ss_tot if ss_tot > 0 else 0.0
+    dof = n_names - 2
+    se_b = math.sqrt((ss_res / dof) / sxx) if dof > 0 and sxx > 0 else float("inf")
+    t_stat = slope / se_b if np.isfinite(se_b) and se_b > 0 else 0.0
+
+    if r2 >= r2_case2 and t_stat >= t_threshold and slope > 0:
+        return _result(
+            2,
+            r2,
+            t_stat,
+            slope,
+            n_obs,
+            n_names,
+            True,
+            False,
+            f"Std_TS ∝ ω (R²={r2:.2f}, t={t_stat:.1f}): vol already in the signal",
+        )
+    if r2 <= r2_case1:
+        return _result(
+            1,
+            r2,
+            t_stat,
+            slope,
+            n_obs,
+            n_names,
+            True,
+            False,
+            f"Std_TS ⊥ ω (R²={r2:.2f}): per-name signal vol ~constant",
+        )
+    return _result(
+        default_case,
+        r2,
+        t_stat,
+        slope,
+        n_obs,
+        n_names,
+        True,
+        True,
+        f"ambiguous (R²={r2:.2f}, t={t_stat:.1f}); defaulting to Case {default_case} "
+        f"({'price-derived' if price_derived else 'other'})",
+    )
+
+
+def level_shrink_factor(ic: float, t_eff: float) -> float:
+    """IC-uncertainty level shrink: ``1/(1 + 1/(T_eff·IC²)) = g/(g+1)``, ``g=T_eff·IC²``.
+
+    The IC that scales alphas is itself estimated, and its sampling error dominates the
+    mapping (``Var{Δβ/β} ≈ 1/(IC²·T)``). This Bayes-with-zero-prior factor
+    shrinks the alpha **level** toward zero for that estimation error: ``→ 1`` as
+    ``T_eff·IC² → ∞`` (skill well established), ``→ 0`` as ``IC → 0`` or ``T_eff → 0``.
+    ``T_eff`` must be *effective independent* observations (overlapping horizons inflate
+    a raw row count — see :func:`quantred.alphas.horizon.effective_sample_size`). Anchors:
+    ``IC=0.05, T=60 → 0.13``; ``IC=0.10, T=120 → 0.55``.
+    """
+    g = t_eff * ic * ic
+    return float(g / (g + 1.0)) if np.isfinite(g) and g > 0 else 0.0
+
+
+def cap(alpha: pd.Series, n_std: float = 3.0) -> pd.Series:
+    """Final sanity bound: clip alphas to ``+/- n_std * std(alpha)``.
+
+    A guard against a single name carrying an implausible forecast after scaling.
+    With a degenerate (zero-std) alpha vector this is a no-op.
+    """
+    if alpha.empty:
+        return alpha
+    std = alpha.std(ddof=0)
+    if std == 0 or not np.isfinite(std):
+        return alpha
+    bound = n_std * std
+    return alpha.clip(lower=-bound, upper=bound)

quantred/alphas/scorers.py

@@ -0,0 +1,87 @@
+"""Scorers - the atomic "score one name's bars" functions that feed the panel.
+
+A scorer is just ``Callable[[pd.DataFrame], float]``: given one symbol's as-of-sliced
+bars, return a continuous conviction. The panel's score producer applies a scorer
+across the universe to fill the ``score`` column, which the refinement then turns
+into an alpha. Keeping the source of the score behind this one-line contract is
+what lets a strategy, a scanner, or (later) a combination of signals all flow
+through the same alpha pipeline.
+
+- :func:`strategy_scorer` - a strategy's own continuous conviction (its score).
+  The natural, richest source: it's the same number the trade clock's signal is
+  derived from.
+- :func:`signal_scorer` - a strategy's *discrete* direction as +1/-1/0. A lossy
+  bucketing of the score; useful when only the direction is trusted.
+- :func:`scanner_scorer` - a scanner's signed ``signal_strength``.
+"""
+
+from typing import Callable
+
+import pandas as pd
+
+from quantred.scanners.base import SCANNER_BUY, SCANNER_SELL, ScannerStrategy
+from quantred.strategies import signals
+from quantred.strategies.base import Strategy
+
+Scorer = Callable[[pd.DataFrame], float]
+
+#: Map a discrete trade signal to a directional score. Exit signals carry no
+#: cross-sectional view (they're about an existing position), so they score 0.
+_SIGNAL_SCORE = {
+    signals.BUY: 1.0,
+    signals.SELL: -1.0,
+    signals.HOLD: 0.0,
+    signals.CLOSE_BUY: 0.0,
+    signals.CLOSE_SELL: 0.0,
+}
+
+
+def strategy_scorer(strategy: Strategy) -> Scorer:
+    """Score a name by the strategy's continuous conviction on its last bar."""
+
+    def score(frame: pd.DataFrame) -> float:
+        processed = strategy.process_data(frame)
+        if processed.empty:
+            return 0.0
+        scores = strategy.calculate_scores(processed)
+        if scores.empty:
+            return 0.0
+        value = scores.iloc[-1]
+        return 0.0 if pd.isna(value) else float(value)
+
+    return score
+
+
+def signal_scorer(strategy: Strategy) -> Scorer:
+    """Score a name by the strategy's discrete direction (+1 BUY / -1 SELL / 0)."""
+
+    def score(frame: pd.DataFrame) -> float:
+        processed = strategy.process_data(frame)
+        if processed.empty:
+            return 0.0
+        signal = strategy._latest_signal(strategy.generate_signals(processed))
+        return _SIGNAL_SCORE.get(signal, 0.0)
+
+    return score
+
+
+def scanner_scorer(scanner: ScannerStrategy) -> Scorer:
+    """Score a name by the scanner's ``signal_strength``, signed by its direction."""
+
+    def score(frame: pd.DataFrame) -> float:
+        processed = scanner.process_data(frame)
+        if processed.empty:
+            return 0.0
+        signals_df = scanner.generate_signals_df(processed)
+        if signals_df.empty or "signal_strength" not in signals_df:
+            return 0.0
+        last = signals_df.iloc[-1]
+        strength = float(last.get("signal_strength", 0.0) or 0.0)
+        signal = last.get("signal")
+        if signal == SCANNER_BUY:
+            return strength
+        if signal == SCANNER_SELL:
+            return -strength
+        return 0.0
+
+    return score