mlquantx 0.2.5__py3-none-any.whl

mlquant/features/_factors_original.py

@@ -0,0 +1,215 @@
+"""original_* family: direct close/volume statistics (28 factors)."""
+from __future__ import annotations
+from typing import Tuple
+import torch
+
+from ..data.panel import Panel
+from .tensor_factors import (
+    cs_rank, cs_zscore, delay, delta, ts_corr, ts_max, ts_mean, ts_min, ts_rank, ts_std,
+)
+from .legacy_factors import register_legacy_factor
+
+Tensor = torch.Tensor
+
+
+@register_legacy_factor("original_001")
+def original_001(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """20-day close volatility, cross-sectionally z-scored."""
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    sd, sm = ts_std(ret, rm, 20)
+    return cs_zscore(sd, sm)
+
+
+@register_legacy_factor("original_002")
+def original_002(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Close to 20-day high distance, ranked."""
+    hi, hm = ts_max(panel.close, panel.mask, 20)
+    dist = panel.close / hi.clamp_min(1e-9) - 1.0
+    return cs_rank(dist * hm.float(), hm)
+
+
+@register_legacy_factor("original_003")
+def original_003(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Close to 20-day low distance, ranked."""
+    lo, lm = ts_min(panel.close, panel.mask, 20)
+    dist = panel.close / lo.clamp_min(1e-9) - 1.0
+    return cs_rank(dist * lm.float(), lm)
+
+
+@register_legacy_factor("original_004")
+def original_004(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of close over 60 days."""
+    return ts_rank(panel.close, panel.mask, 60)
+
+
+@register_legacy_factor("original_005")
+def original_005(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of volume over 60 days."""
+    return ts_rank(panel.volume, panel.mask, 60)
+
+
+@register_legacy_factor("original_006")
+def original_006(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """20-day correlation of close and volume."""
+    return ts_corr(panel.close, panel.volume, panel.mask, 20)
+
+
+@register_legacy_factor("original_007")
+def original_007(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of close over 20 days."""
+    return ts_rank(panel.close, panel.mask, 20)
+
+
+@register_legacy_factor("original_008")
+def original_008(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of volume over 20 days."""
+    return ts_rank(panel.volume, panel.mask, 20)
+
+
+@register_legacy_factor("original_009")
+def original_009(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """10-day correlation of close and volume."""
+    return ts_corr(panel.close, panel.volume, panel.mask, 10)
+
+
+@register_legacy_factor("original_010")
+def original_010(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """5-day correlation of close and volume."""
+    return ts_corr(panel.close, panel.volume, panel.mask, 5)
+
+
+@register_legacy_factor("original_011")
+def original_011(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of close over 10 days."""
+    return ts_rank(panel.close, panel.mask, 10)
+
+
+@register_legacy_factor("original_012")
+def original_012(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of volume over 10 days."""
+    return ts_rank(panel.volume, panel.mask, 10)
+
+
+@register_legacy_factor("original_013")
+def original_013(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of close over 5 days."""
+    return ts_rank(panel.close, panel.mask, 5)
+
+
+@register_legacy_factor("original_014")
+def original_014(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank of volume over 5 days."""
+    return ts_rank(panel.volume, panel.mask, 5)
+
+
+@register_legacy_factor("original_015")
+def original_015(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """10-day close volatility."""
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    return ts_std(ret, rm, 10)
+
+
+@register_legacy_factor("original_016")
+def original_016(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """5-day close volatility."""
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    return ts_std(ret, rm, 5)
+
+
+@register_legacy_factor("original_017")
+def original_017(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Close to 10-day high distance."""
+    hi, hm = ts_max(panel.close, panel.mask, 10)
+    dist = panel.close / hi.clamp_min(1e-9) - 1.0
+    return dist * hm.float(), hm
+
+
+@register_legacy_factor("original_018")
+def original_018(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Close to 10-day low distance."""
+    lo, lm = ts_min(panel.close, panel.mask, 10)
+    dist = panel.close / lo.clamp_min(1e-9) - 1.0
+    return dist * lm.float(), lm
+
+
+@register_legacy_factor("original_019")
+def original_019(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Close to 5-day high distance."""
+    hi, hm = ts_max(panel.close, panel.mask, 5)
+    dist = panel.close / hi.clamp_min(1e-9) - 1.0
+    return dist * hm.float(), hm
+
+
+@register_legacy_factor("original_020")
+def original_020(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Close to 5-day low distance."""
+    lo, lm = ts_min(panel.close, panel.mask, 5)
+    dist = panel.close / lo.clamp_min(1e-9) - 1.0
+    return dist * lm.float(), lm
+
+
+@register_legacy_factor("original_021")
+def original_021(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """10-day momentum: close[t] / close[t-10] - 1."""
+    prev, pm = delay(panel.close, panel.mask, 10)
+    out = panel.close / prev.clamp_min(1e-9) - 1.0
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("original_022")
+def original_022(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """5-day momentum: close[t] / close[t-5] - 1."""
+    prev, pm = delay(panel.close, panel.mask, 5)
+    out = panel.close / prev.clamp_min(1e-9) - 1.0
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("original_023")
+def original_023(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """3-day momentum: close[t] / close[t-3] - 1."""
+    prev, pm = delay(panel.close, panel.mask, 3)
+    out = panel.close / prev.clamp_min(1e-9) - 1.0
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("original_024")
+def original_024(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """1-day momentum: close[t] / close[t-1] - 1."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    out = panel.close / prev.clamp_min(1e-9) - 1.0
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("original_025")
+def original_025(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """cs_rank of 10-day momentum."""
+    prev, pm = delay(panel.close, panel.mask, 10)
+    mom = panel.close / prev.clamp_min(1e-9) - 1.0
+    return cs_rank(mom * pm.float(), pm)
+
+
+@register_legacy_factor("original_026")
+def original_026(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """cs_rank of 5-day momentum."""
+    prev, pm = delay(panel.close, panel.mask, 5)
+    mom = panel.close / prev.clamp_min(1e-9) - 1.0
+    return cs_rank(mom * pm.float(), pm)
+
+
+@register_legacy_factor("original_027")
+def original_027(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """cs_rank of 1-day momentum."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    mom = panel.close / prev.clamp_min(1e-9) - 1.0
+    return cs_rank(mom * pm.float(), pm)
+
+
+@register_legacy_factor("original_028")
+def original_028(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """cs_rank of 20-day momentum."""
+    prev, pm = delay(panel.close, panel.mask, 20)
+    mom = panel.close / prev.clamp_min(1e-9) - 1.0
+    return cs_rank(mom * pm.float(), pm)

mlquant/features/_factors_stock.py

@@ -0,0 +1,270 @@
+"""stock_* family: per-stock derived series (22 factors).
+
+Ported from legacy Feature.py stock001-stock022.
+"""
+from __future__ import annotations
+from typing import Tuple
+import torch
+
+from ..data.panel import Panel
+from .tensor_factors import (
+    cs_rank, delay, delta, ewma, ts_corr, ts_max, ts_mean, ts_min, ts_rank, ts_std, ts_sum,
+)
+from .legacy_factors import register_legacy_factor, _amount
+
+Tensor = torch.Tensor
+
+
+@register_legacy_factor("stock_001")
+def stock_001(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Corr(Δlog(volume), (close-open)/open, 4)."""
+    log_vol = torch.log(panel.volume + 1.0)
+    d_lv, dm = delta(log_vol, panel.mask, 1)
+    intra_ret = (panel.close - panel.open) / panel.open.clamp_min(1e-9)
+    m = dm & panel.mask
+    return ts_corr(d_lv, intra_ret, m, 4)
+
+
+@register_legacy_factor("stock_002")
+def stock_002(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Corr(Δlog(volume), (close-open)/open, 6)."""
+    log_vol = torch.log(panel.volume + 1.0)
+    d_lv, dm = delta(log_vol, panel.mask, 1)
+    intra_ret = (panel.close - panel.open) / panel.open.clamp_min(1e-9)
+    m = dm & panel.mask
+    return ts_corr(d_lv, intra_ret, m, 6)
+
+
+@register_legacy_factor("stock_003")
+def stock_003(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """rank(close - ts_max(vwap, 15)) ^ delta(close, 5)."""
+    mx, mm = ts_max(panel.vwap, panel.mask, 15)
+    diff = (panel.close - mx) * mm.float()
+    r, rm = cs_rank(diff, mm)
+    dc, dcm = delta(panel.close, panel.mask, 5)
+    m = rm & dcm
+    # Use sign-preserving power: sign(r) * |r|^|dc/close|
+    dc_norm = dc / panel.close.clamp_min(1e-9)
+    out = torch.sign(r) * r.abs().clamp_min(1e-12).pow(dc_norm.abs().clamp(0, 2))
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_004")
+def stock_004(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """EWMA((close - mean(close,6))/mean(close,6) - delay(..., 3), alpha=1/12)."""
+    avg, am = ts_mean(panel.close, panel.mask, 6)
+    dev = (panel.close - avg) / avg.clamp_min(1e-9)
+    dev_d, dm = delay(dev, am, 3)
+    diff = (dev - dev_d) * (am & dm).float()
+    return ewma(diff, am & dm, alpha=1.0 / 12.0)
+
+
+@register_legacy_factor("stock_005")
+def stock_005(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(close - delay(close, 6)) / delay(close, 6) * (volume + 1)."""
+    prev, pm = delay(panel.close, panel.mask, 6)
+    out = (panel.close - prev) / prev.clamp_min(1e-9) * (panel.volume + 1.0)
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("stock_006")
+def stock_006(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(close - mean(close, 12)) / mean(close, 12)."""
+    avg, am = ts_mean(panel.close, panel.mask, 12)
+    out = (panel.close - avg) / avg.clamp_min(1e-9)
+    return out * am.float(), am
+
+
+@register_legacy_factor("stock_007")
+def stock_007(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(delay(ts_min(low,5), 5) - ts_min(low,5)) * rank((sum(ret,60)-sum(ret,20))/40) * rank(volume)."""
+    mn, mm = ts_min(panel.low, panel.mask, 5)
+    mn_d, md = delay(mn, mm, 5)
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    s60, s60m = ts_sum(ret, rm, 60)
+    s20, s20m = ts_sum(ret, rm, 20)
+    momentum = (s60 - s20) / 40.0
+    mom_r, momm = cs_rank(momentum, s60m & s20m)
+    vol_r, volm = cs_rank(panel.volume, panel.mask)
+    m = md & momm & volm
+    out = (mn_d - mn) * mom_r * vol_r
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_008")
+def stock_008(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-(sum(open,5)*sum(ret,5) - delay(sum(open,5)*sum(ret,5), 10)) ranked."""
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    so, som = ts_sum(panel.open, panel.mask, 5)
+    sr, srm = ts_sum(ret, rm, 5)
+    prod = so * sr
+    m_prod = som & srm
+    prod_d, pdm = delay(prod, m_prod, 10)
+    diff = prod - prod_d
+    m = m_prod & pdm
+    r, rm2 = cs_rank(-diff * m.float(), m)
+    return r, rm2
+
+
+@register_legacy_factor("stock_009")
+def stock_009(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(mean(close,3)+mean(close,6)+mean(close,12)+mean(close,24)) / (4*close)."""
+    m3, mm3 = ts_mean(panel.close, panel.mask, 3)
+    m6, mm6 = ts_mean(panel.close, panel.mask, 6)
+    m12, mm12 = ts_mean(panel.close, panel.mask, 12)
+    m24, mm24 = ts_mean(panel.close, panel.mask, 24)
+    m = mm3 & mm6 & mm12 & mm24
+    out = (m3 + m6 + m12 + m24) * 0.25 / panel.close.clamp_min(1e-9)
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_010")
+def stock_010(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """std(log(amount+1), 6)."""
+    amt = _amount(panel)
+    log_amt = torch.log(amt + 1.0)
+    return ts_std(log_amt, panel.mask, 6)
+
+
+@register_legacy_factor("stock_011")
+def stock_011(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """CCI-like: (typical - mean(typical,12)) / (0.015 * mean(|close - mean(typical,12)|, 12))."""
+    typical = (panel.high + panel.low + panel.close) / 3.0
+    avg_t, am = ts_mean(typical, panel.mask, 12)
+    dev = (panel.close - avg_t).abs()
+    avg_dev, adm = ts_mean(dev, am, 12)
+    m = am & adm
+    out = (typical - avg_t) / (0.015 * avg_dev.clamp_min(1e-9))
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_012")
+def stock_012(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """RSI-like: ewma(max(Δvol, 0), 1/6) / ewma(|Δvol|, 1/6) * 100."""
+    dv, dm = delta(panel.volume, panel.mask, 1)
+    pos = torch.clamp(dv, min=0.0)
+    abs_dv = dv.abs()
+    ew_pos, m1 = ewma(pos, dm, alpha=1.0 / 6.0)
+    ew_abs, m2 = ewma(abs_dv, dm, alpha=1.0 / 6.0)
+    m = m1 & m2
+    out = ew_pos * 100.0 / ew_abs.clamp_min(1e-9)
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_013")
+def stock_013(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Δ(vwap - close) / Δ(vwap + close)."""
+    diff = panel.vwap - panel.close
+    summ = panel.vwap + panel.close
+    d_diff, dm1 = delta(diff, panel.mask, 1)
+    d_sum, dm2 = delta(summ, panel.mask, 1)
+    m = dm1 & dm2
+    out = d_diff / d_sum.abs().clamp_min(1e-9)
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_014")
+def stock_014(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(close / delay(close, 12) - 1) * volume."""
+    prev, pm = delay(panel.close, panel.mask, 12)
+    out = (panel.close / prev.clamp_min(1e-9) - 1.0) * panel.volume
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("stock_015")
+def stock_015(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Conditional down-vol: sum(|ret|/log(amt+1) * (close<delay(close,1)), 20) / count(down, 20)."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    ret_abs = (panel.close / prev.clamp_min(1e-9) - 1.0).abs()
+    amt = _amount(panel)
+    log_amt = torch.log(amt + 1.0).clamp_min(1e-9)
+    down = (panel.close < prev).float() * pm.float()
+    signal = ret_abs / log_amt * down
+    s_sum, sm = ts_sum(signal, pm, 20)
+    d_count, cm = ts_sum(down, pm, 20)
+    m = sm & cm
+    out = s_sum / d_count.clamp_min(1.0)
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_016")
+def stock_016(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Williams %R multi-timeframe composite."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    true_low = torch.min(panel.low, prev)
+    true_high = torch.max(panel.high, prev)
+    # 6-day
+    sl6, slm6 = ts_sum(true_low, pm, 6)
+    sh6, shm6 = ts_sum(true_high - true_low, pm, 6)
+    p1 = (panel.close - sl6) / sh6.clamp_min(1e-9) * 12 * 24
+    # 12-day
+    sl12, slm12 = ts_sum(true_low, pm, 12)
+    sh12, shm12 = ts_sum(true_high - true_low, pm, 12)
+    p2 = (panel.close - sl12) / sh12.clamp_min(1e-9) * 6 * 24
+    # 24-day
+    sl24, slm24 = ts_sum(true_low, pm, 24)
+    sh24, shm24 = ts_sum(true_high - true_low, pm, 24)
+    p3 = (panel.close - sl24) / sh24.clamp_min(1e-9) * 6 * 12
+    m = slm6 & slm12 & slm24
+    out = (p1 + p2 + p3) * 100.0 / (6*12 + 6*24 + 12*24)
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_017")
+def stock_017(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-ret * mean(volume, 20) * vwap * (high - close)."""
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    avg_v, am = ts_mean(panel.volume, panel.mask, 20)
+    m = rm & am
+    out = -ret * avg_v * panel.vwap * (panel.high - panel.close)
+    return out * m.float(), m
+
+
+@register_legacy_factor("stock_018")
+def stock_018(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """5-day close return minus 20-day close return."""
+    c5, m5 = delay(panel.close, panel.mask, 5)
+    c20, m20 = delay(panel.close, panel.mask, 20)
+    r5 = (panel.close - c5) / c5.clamp_min(1e-9)
+    r20 = (panel.close - c20) / c20.clamp_min(1e-9)
+    m = m5 & m20
+    return (r5 - r20) * m.float(), m
+
+
+@register_legacy_factor("stock_019")
+def stock_019(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(low - close) * open^5 / ((close - high) * close^5)."""
+    num = -(panel.low - panel.close) * panel.open.pow(5)
+    den = (panel.close - panel.high) * panel.close.pow(5)
+    out = num / den.abs().clamp_min(1e-12).copysign(den + 1e-12)
+    return out * panel.mask.float(), panel.mask
+
+
+@register_legacy_factor("stock_020")
+def stock_020(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(close - delay(close,1)) / delay(close,1) * volume."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    out = (panel.close - prev) / prev.clamp_min(1e-9) * panel.volume
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("stock_021")
+def stock_021(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """((high-low) - ewma(high-low, 2/11)) / ewma(high-low, 2/11) * 100."""
+    rng = panel.high - panel.low
+    sma, sm = ewma(rng, panel.mask, alpha=2.0 / 11.0)
+    out = (rng - sma) / sma.clamp_min(1e-9) * 100.0
+    return out * sm.float(), sm
+
+
+@register_legacy_factor("stock_022")
+def stock_022(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """corr(mean(volume,20), low, 5) + (high+low)/2 - close."""
+    avg_v, am = ts_mean(panel.volume, panel.mask, 20)
+    corr, cm = ts_corr(avg_v, panel.low, am, 5)
+    m = am & cm
+    out = corr + (panel.high + panel.low) / 2.0 - panel.close
+    return out * m.float(), m

mlquant/features/alpha101.py

@@ -0,0 +1,84 @@
+"""Backward-compatible Alpha101 interface.
+
+The 9 curated Alpha101 factors are now registered in the unified
+:data:`LEGACY_REGISTRY` (via ``_factors_alpha101.py``) alongside all
+other factor families. This module provides the legacy
+``compute_alpha_set`` / ``ALPHA_REGISTRY`` API for backward
+compatibility.
+
+The canonical way to compute all 213 factors is::
+
+    from mlquant.features import compute_legacy_set
+    factors, mask, names = compute_legacy_set(panel)
+
+To compute only the Alpha101 subset::
+
+    from mlquant.features import compute_legacy_set
+    alpha_names = tuple(n for n in LEGACY_REGISTRY if n.startswith("alpha_"))
+    factors, mask, names = compute_legacy_set(panel, names=alpha_names)
+"""
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+import torch
+
+from ..data.panel import Panel
+from .tensor_factors import cs_zscore
+from .legacy_factors import LEGACY_REGISTRY
+
+Tensor = torch.Tensor
+
+# Expose the alpha_* subset as ALPHA_REGISTRY for backward compat
+ALPHA_REGISTRY: Dict[str, object] = {}
+
+
+def _populate_alpha_registry() -> None:
+    """Lazily populate ALPHA_REGISTRY from LEGACY_REGISTRY alpha_* entries."""
+    if ALPHA_REGISTRY:
+        return
+    for name, fn in LEGACY_REGISTRY.items():
+        if name.startswith("alpha_"):
+            # Map back to old naming convention (alpha_001 -> alpha001)
+            old_name = name.replace("alpha_", "alpha")
+            ALPHA_REGISTRY[old_name] = fn
+
+
+def compute_alpha_set(
+    panel: Panel,
+    *,
+    names: tuple[str, ...] | None = None,
+    neutralize: bool = True,
+) -> Tuple[Tensor, Tensor, list[str]]:
+    """Compute the Alpha101 subset → tensor of shape ``[T, N, F]``.
+
+    This is a backward-compatible wrapper. Prefer
+    :func:`~mlquant.features.legacy_factors.compute_legacy_set` for new
+    code.
+
+    Parameters
+    ----------
+    panel : Panel
+    names : tuple of str, optional
+        Subset of alpha names (old style: "alpha001", "alpha002", ...).
+        ``None`` → all 9 registered alphas.
+    neutralize : bool
+        If True, each factor is cross-sectionally z-scored.
+
+    Returns
+    -------
+    factors : Tensor [T, N, F]
+    mask    : Tensor [T, N]
+    names   : list[str]
+    """
+    _populate_alpha_registry()
+    names = names or tuple(ALPHA_REGISTRY)
+    cols, joint_mask = [], None
+    for n in names:
+        v, m = ALPHA_REGISTRY[n](panel)
+        if neutralize:
+            v, _ = cs_zscore(v, m)
+        cols.append(v)
+        joint_mask = m if joint_mask is None else joint_mask & m
+    factors = torch.stack(cols, dim=-1)
+    return factors, joint_mask, list(names)

mlquant/features/bias.py

@@ -0,0 +1,81 @@
+"""Bias-correction utilities for A-share microstructure quirks.
+
+The two most common look-ahead biases in A-share alpha research are:
+
+1. **Limit-up days** — when a stock closes at the +10 % cap, the close
+   you see *did not actually fill any unsatisfied buy orders*. Treating
+   such a day as tradable inflates returns.
+2. **Limit-down days** — symmetric problem on the downside.
+
+Both must be excluded from training labels and from the tradable
+universe at portfolio construction time.
+
+Two regimes
+-----------
+* **Real limits available** (``Panel.limit_up`` / ``Panel.limit_down`` set):
+  use the exchange-published prices — this is the regime real Wind
+  data lands in. A cell is masked if ``close >= limit_up - eps`` or
+  ``close <= limit_down + eps``.
+* **Proxy regime** (synthetic data, or any feed without explicit limits):
+  fall back to the ``|return| > limit_pct`` heuristic, which is the
+  unambiguous signature of a limit move on most A-shares.
+
+Both code paths are exercised by the test suite via the synthetic
+generator (which fills both real and derived fields) so this module
+behaves identically on synthetic and real feeds.
+"""
+from __future__ import annotations
+
+import torch
+
+from ..data.panel import Panel
+
+
+def limit_move_mask(
+    panel: Panel,
+    *,
+    limit_pct: float = 0.098,
+    eps: float = 1e-3,
+) -> torch.Tensor:
+    """Boolean mask, ``True`` where the day's price is **inside** the limit band.
+
+    When :attr:`Panel.has_real_limits` is True we use the exchange-published
+    ``limit_up`` / ``limit_down`` prices and require ``limit_down + eps <
+    close < limit_up - eps``. Otherwise we fall back to the
+    ``|return| <= limit_pct`` proxy.
+
+    Day 0 is always masked False because no previous close is available
+    to evaluate the return proxy. (Real-limit cells on day 0 are still
+    valid but we follow the legacy convention of masking the very first
+    row to keep the two regimes aligned.)
+    """
+    if panel.has_real_limits:
+        up   = panel.limit_up.clamp_min(0.0)
+        down = panel.limit_down.clamp_min(0.0)
+        # Treat zero/missing limit prices as "no limit" (fall through).
+        has_band = (up > 0) & (down > 0)
+        # Inside the band on every cell that has one, plus a tolerance
+        # so float round-off doesn't trip the comparison.
+        inside_band = (panel.close < up - eps) & (panel.close > down + eps)
+        # Where the band is missing, defer to the return-proxy rule.
+        ret_proxy = _return_inside(panel, limit_pct)
+        inside = torch.where(has_band, inside_band, ret_proxy)
+    else:
+        inside = _return_inside(panel, limit_pct)
+
+    inside[0] = False                 # day 0 has no previous close
+    return inside & panel.mask
+
+
+def _return_inside(panel: Panel, limit_pct: float) -> torch.Tensor:
+    """``|return| <= limit_pct`` proxy mask."""
+    if panel.last_close is not None:
+        prev = panel.last_close.clamp_min(1e-9)
+    else:
+        prev = torch.roll(panel.close, shifts=1, dims=0).clamp_min(1e-9)
+        prev[0] = panel.close[0]
+    move = (panel.close / prev) - 1.0
+    return move.abs() <= limit_pct
+
+
+__all__ = ["limit_move_mask"]