mlquantx 0.2.5__py3-none-any.whl

mlquant/data/synthetic.py

@@ -0,0 +1,138 @@
+"""Synthetic OCHLV panel generator.
+
+The paper's empirical results use proprietary Wind / Tushare data that
+external readers cannot redistribute. To make the repository
+*end-to-end runnable for anyone*, this module synthesises a
+realistically-shaped A-share-like universe via a multi-asset Geometric
+Brownian Motion (GBM) with cross-sectional correlation, plus a
+"limit-up / limit-down" simulator so the bias-correction code paths
+are exercised on the synthetic data too.
+
+Why bother making it realistic?
+    Random noise is useless for benchmarking factors. A synthetic panel
+    that obeys the same constraints as the real one (positive prices,
+    OCHL ordering, ~10% daily price-limit, ~5% halt probability,
+    cross-sectional correlation around 0.3) lets us:
+
+      * regression-test the factor engine with deterministic seeds,
+      * give new contributors a 30-second smoke-test path,
+      * publish CI runs that actually exercise the optimiser.
+
+The generator also fills in the *optional* A-share microstructure
+fields — ``amount`` (turnover), ``limit_up``, ``limit_down``,
+``last_close`` — so that code which prefers exchange-published values
+over derived proxies has something realistic to consume.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+import torch
+
+from .panel import Panel
+
+
+@dataclass
+class SyntheticConfig:
+    n_stocks:     int   = 200
+    n_dates:      int   = 500
+    start_date:   str   = "2020-01-02"
+    annual_drift: float = 0.05
+    annual_vol:   float = 0.30
+    market_beta:  float = 0.6
+    halt_prob:    float = 0.005           # per stock-day
+    limit_pct:    float = 0.10            # ±10 % A-share daily price limit
+    seed:         int   = 42
+    device:       str   = "cpu"
+
+
+def make_synthetic_panel(cfg: Optional[SyntheticConfig] = None) -> Panel:
+    """Generate a synthetic OCHLV panel obeying A-share style constraints.
+
+    The procedure is deliberately compact:
+      1. Sample a daily market log-return ``m_t ~ N(μ_m, σ_m)``.
+      2. Sample idiosyncratic log-returns ``e_{t,i} ~ N(0, σ_e)``.
+      3. Stock log-return ``r_{t,i} = β·m_t + e_{t,i}`` (single-factor model).
+      4. Reject moves outside ±``limit_pct``: clamp and mask.
+      5. Halts: Bernoulli ``halt_prob`` mask.
+      6. Synthesise OCHL around close with a small intraday range.
+      7. Derive ``amount = vwap*volume``, ``last_close = close[t-1]`` and
+         the official ±``limit_pct`` bands.
+
+    The resulting panel exercises the same masked code paths as a real
+    Wind feed — every test in ``tests/`` runs against this generator.
+    """
+    cfg = cfg or SyntheticConfig()
+    rng = np.random.default_rng(cfg.seed)
+
+    T, N = cfg.n_dates, cfg.n_stocks
+    daily_drift = cfg.annual_drift / 252.0
+    daily_vol   = cfg.annual_vol  / np.sqrt(252.0)
+
+    # 1. market and idiosyncratic shocks --------------------------------
+    market_shock = rng.normal(daily_drift, daily_vol, size=T)
+    idio_shock   = rng.normal(0.0, daily_vol * np.sqrt(1.0 - cfg.market_beta**2), size=(T, N))
+    log_ret      = cfg.market_beta * market_shock[:, None] + idio_shock
+
+    # 2. price-limit clamp + halt mask ---------------------------------
+    log_limit = np.log1p(cfg.limit_pct)
+    log_ret   = np.clip(log_ret, -log_limit, log_limit)
+    halts     = rng.random(size=(T, N)) < cfg.halt_prob
+
+    # 3. integrate to price -------------------------------------------
+    init_price = rng.uniform(5.0, 50.0, size=N).astype(np.float32)
+    cum_log    = np.cumsum(log_ret, axis=0)
+    close      = init_price[None, :] * np.exp(cum_log)
+
+    # 4. OCHL around close --------------------------------------------
+    intraday_sigma = daily_vol * 0.5
+    open_  = close * np.exp(rng.normal(0.0, intraday_sigma, size=close.shape))
+    high   = np.maximum(open_, close) * (1.0 + np.abs(rng.normal(0.0, intraday_sigma * 0.5, size=close.shape)))
+    low    = np.minimum(open_, close) * (1.0 - np.abs(rng.normal(0.0, intraday_sigma * 0.5, size=close.shape)))
+    vwap   = (open_ + high + low + close) / 4.0
+    volume = rng.lognormal(mean=15.0, sigma=0.5, size=close.shape).astype(np.float32)
+    volume[halts] = 0.0
+
+    # 5. mask: tradable iff not halted ---------------------------------
+    mask = ~halts
+
+    # 6. derive optional A-share fields --------------------------------
+    amount = (vwap * volume).astype(np.float32)
+    # last_close[t] = close[t-1]; day 0 falls back to the open price so
+    # the ±limit_pct bands stay well-defined.
+    last_close = np.empty_like(close, dtype=np.float32)
+    last_close[0]  = open_[0]
+    last_close[1:] = close[:-1]
+    # Round limit prices to two decimals to mimic exchange convention.
+    limit_up   = np.round(last_close * (1.0 + cfg.limit_pct), 2).astype(np.float32)
+    limit_down = np.round(last_close * (1.0 - cfg.limit_pct), 2).astype(np.float32)
+
+    # 7. assemble Panel ------------------------------------------------
+    dates = pd.bdate_range(cfg.start_date, periods=T).to_numpy()
+    stocks = np.asarray([f"SYN{idx:05d}" for idx in range(N)])
+
+    def _t(arr: np.ndarray) -> torch.Tensor:
+        return torch.from_numpy(arr.astype(np.float32)).to(cfg.device)
+
+    panel = Panel.from_tensors(
+        dates=dates,
+        stocks=stocks,
+        fields={
+            "open":       _t(open_),
+            "high":       _t(high),
+            "low":        _t(low),
+            "close":      _t(close),
+            "volume":     _t(volume),
+            "vwap":       _t(vwap),
+            "amount":     _t(amount),
+            "limit_up":   _t(limit_up),
+            "limit_down": _t(limit_down),
+            "last_close": _t(last_close),
+        },
+        mask=torch.from_numpy(mask).to(cfg.device),
+    )
+    panel.assert_consistent()
+    return panel

mlquant/data/yfinance_loader.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import torch
+from typing import Sequence, Optional, Union
+import yfinance as yf
+
+from .panel import Panel
+
+def load_yfinance_panel(
+    tickers: Sequence[str],
+    start: str,
+    end: str,
+    device: Union[str, torch.device] = "cpu",
+    proxy_vwap: bool = True
+) -> Panel:
+    """Download data from yfinance and return a Panel.
+
+    Parameters
+    ----------
+    tickers : Sequence[str]
+        List of tickers to download. For A-shares, use standard suffixes (e.g., '000001.SZ', '600000.SS').
+    start : str
+        Start date (e.g. "2020-01-01").
+    end : str
+        End date (e.g. "2023-12-31").
+    device : str or torch.device
+        Where to allocate the resulting tensors.
+    proxy_vwap : bool
+        If True, estimates VWAP as (Open + Close + High + Low) / 4.
+        yfinance doesn't provide VWAP natively.
+    """
+    if not tickers:
+        raise ValueError("Tickers list cannot be empty")
+
+    df = yf.download(list(tickers), start=start, end=end)
+    if df.empty:
+        raise ValueError(f"No data returned for tickers {tickers} from {start} to {end}")
+
+    # Standardize column naming
+    # For single ticker, yfinance returns flat columns. For multiple, it returns MultiIndex.
+    if isinstance(df.columns, pd.MultiIndex):
+        # MultiIndex columns: level 0 is Price (e.g. 'Close', 'Open'), level 1 is Ticker
+        pass
+    else:
+        # Flat index: this means a single ticker was given to yf.download
+        if len(tickers) == 1:
+            df.columns = pd.MultiIndex.from_product([df.columns, [tickers[0]]])
+        else:
+            raise ValueError("Unexpected flat columns for multiple tickers")
+
+    # Extract wide DataFrames
+    fields_wide = {}
+
+    def get_wide_df(price_col):
+        if price_col in df.columns.get_level_values(0):
+            # Extract cross-section and sort columns by ticker order
+            wide = df[price_col].copy()
+            # If some tickers missing, add them
+            for t in tickers:
+                if t not in wide.columns:
+                    wide[t] = np.nan
+            return wide[list(tickers)]
+        return None
+
+    open_df = get_wide_df("Open")
+    high_df = get_wide_df("High")
+    low_df = get_wide_df("Low")
+    close_df = get_wide_df("Close")
+    volume_df = get_wide_df("Volume")
+
+    if any(x is None for x in [open_df, high_df, low_df, close_df, volume_df]):
+        raise ValueError("Missing required OHLCV columns from yfinance data")
+
+    fields_wide["open"] = open_df
+    fields_wide["high"] = high_df
+    fields_wide["low"] = low_df
+    fields_wide["close"] = close_df
+    fields_wide["volume"] = volume_df
+
+    if proxy_vwap:
+        fields_wide["vwap"] = (open_df + close_df + high_df + low_df) / 4.0
+
+    dates = df.index.to_numpy()
+    stocks = np.array(list(tickers))
+
+    # Mask where close is not NaN
+    mask = (~open_df.isna() & ~high_df.isna() & ~low_df.isna() & ~close_df.isna() & ~volume_df.isna()).to_numpy()
+
+    tensors = {
+        name: torch.from_numpy(df_.fillna(0.0).to_numpy(dtype=np.float32).copy()).to(device)
+        for name, df_ in fields_wide.items()
+    }
+
+    return Panel.from_tensors(
+        dates=dates,
+        stocks=stocks,
+        fields=tensors,
+        mask=torch.from_numpy(mask.copy()).to(device),
+    )

mlquant/features/__init__.py

@@ -0,0 +1,42 @@
+"""Tensor-vectorised factor engine + Alpha101-style library.
+
+Design contract
+---------------
+* Every primitive in :mod:`tensor_factors` accepts and returns a
+  ``(values, mask)`` pair; values at masked-out cells are arbitrary
+  (typically 0) but must not contaminate aggregates.
+* Cross-sectional functions reduce along ``dim=1`` (stock axis).
+* Time-series functions slide along ``dim=0`` (date axis) with a
+  user-supplied look-back window.
+* All operations are torch ops — they run on CPU or GPU and are
+  autograd-friendly when needed.
+"""
+from .tensor_factors import (
+    cs_rank,
+    cs_zscore,
+    ts_corr,
+    ts_cov,
+    ts_max,
+    ts_mean,
+    ts_min,
+    ts_rank,
+    ts_std,
+    ts_sum,
+    ewma,
+    delay,
+    delta,
+)
+from .neutralize import neutralize_cs, neutralize_industry
+from .bias import limit_move_mask
+from .alpha101 import compute_alpha_set, ALPHA_REGISTRY
+from .legacy_factors import compute_legacy_set, LEGACY_REGISTRY
+
+__all__ = [
+    "cs_rank", "cs_zscore",
+    "ts_corr", "ts_cov", "ts_max", "ts_mean", "ts_min",
+    "ts_rank", "ts_std", "ts_sum", "ewma", "delay", "delta",
+    "neutralize_cs", "neutralize_industry",
+    "limit_move_mask",
+    "compute_alpha_set", "ALPHA_REGISTRY",
+    "compute_legacy_set", "LEGACY_REGISTRY",
+]

mlquant/features/_factors_add.py

@@ -0,0 +1,288 @@
+"""add_* family: additional factor variants (30 factors).
+
+Ported from legacy Feature.py add_001-add_030.
+"""
+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, _close_loc, _amount
+
+Tensor = torch.Tensor
+
+
+@register_legacy_factor("add_001")
+def add_001(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """rank(Δclose, 5) * rank(Δvolume, 5)."""
+    dc, dm1 = delta(panel.close, panel.mask, 5)
+    dv, dm2 = delta(panel.volume, panel.mask, 5)
+    m = dm1 & dm2
+    r1, _ = cs_rank(dc, m)
+    r2, _ = cs_rank(dv, m)
+    return (r1 * r2) * m.float(), m
+
+
+@register_legacy_factor("add_002")
+def add_002(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-(close - ts_mean(close, 10)) / ts_mean(close, 10) * rank(volume)."""
+    avg, am = ts_mean(panel.close, panel.mask, 10)
+    dev = -(panel.close - avg) / avg.clamp_min(1e-9)
+    vr, vm = cs_rank(panel.volume, panel.mask)
+    m = am & vm
+    return (dev * vr) * m.float(), m
+
+
+@register_legacy_factor("add_003")
+def add_003(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """sign(Δclose, 1) * (1 + |Δclose/close|) * Δvolume/volume."""
+    dc, dm = delta(panel.close, panel.mask, 1)
+    dv, dvm = delta(panel.volume, panel.mask, 1)
+    m = dm & dvm
+    sign_dc = torch.sign(dc)
+    mag = 1.0 + (dc / panel.close.clamp_min(1e-9)).abs()
+    vol_chg = dv / panel.volume.clamp_min(1.0)
+    return (sign_dc * mag * vol_chg) * m.float(), m
+
+
+@register_legacy_factor("add_004")
+def add_004(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_rank(volume, 20) * ts_rank(-close_loc, 10)."""
+    vr, vm = ts_rank(panel.volume, panel.mask, 20)
+    cl = -_close_loc(panel)
+    cr, cm = ts_rank(cl, panel.mask, 10)
+    m = vm & cm
+    return (vr * cr) * m.float(), m
+
+
+@register_legacy_factor("add_005")
+def add_005(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_sum(close > delay(close, 1), 12) - ts_sum(close < delay(close, 1), 12)."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    up = (panel.close > prev).float() * pm.float()
+    dn = (panel.close < prev).float() * pm.float()
+    s_up, um = ts_sum(up, pm, 12)
+    s_dn, dm2 = ts_sum(dn, pm, 12)
+    m = um & dm2
+    return (s_up - s_dn) * m.float(), m
+
+
+@register_legacy_factor("add_006")
+def add_006(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ewma(close/delay(close,1)-1, 1/12) - close/delay(close,12)-1."""
+    prev1, pm1 = delay(panel.close, panel.mask, 1)
+    ret1 = (panel.close / prev1.clamp_min(1e-9) - 1.0) * pm1.float()
+    ew, em = ewma(ret1, pm1, alpha=1.0 / 12.0)
+    prev12, pm12 = delay(panel.close, panel.mask, 12)
+    ret12 = (panel.close / prev12.clamp_min(1e-9) - 1.0) * pm12.float()
+    m = em & pm12
+    return (ew - ret12) * m.float(), m
+
+
+@register_legacy_factor("add_007")
+def add_007(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """corr(rank(close), rank(volume), 5)."""
+    cr, cm = cs_rank(panel.close, panel.mask)
+    vr, vm = cs_rank(panel.volume, panel.mask)
+    m = cm & vm
+    return ts_corr(cr, vr, m, 5)
+
+
+@register_legacy_factor("add_008")
+def add_008(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_std(close/delay(close,1)-1, 20)."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    ret = (panel.close / prev.clamp_min(1e-9) - 1.0) * pm.float()
+    return ts_std(ret, pm, 20)
+
+
+@register_legacy_factor("add_009")
+def add_009(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(high + low) / 2 - delay((high + low) / 2, 3)."""
+    mid = (panel.high + panel.low) * 0.5
+    prev, pm = delay(mid, panel.mask, 3)
+    return (mid - prev) * pm.float(), pm
+
+
+@register_legacy_factor("add_010")
+def add_010(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_max(high, 5) - ts_min(low, 5) scaled by close."""
+    mx, mm = ts_max(panel.high, panel.mask, 5)
+    mn, mnm = ts_min(panel.low, panel.mask, 5)
+    m = mm & mnm
+    out = (mx - mn) / panel.close.clamp_min(1e-9)
+    return out * m.float(), m
+
+
+@register_legacy_factor("add_011")
+def add_011(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_corr(vwap, volume, 10)."""
+    return ts_corr(panel.vwap, panel.volume, panel.mask, 10)
+
+
+@register_legacy_factor("add_012")
+def add_012(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """rank(open - mean(open,10)) * rank(abs(close-vwap))."""
+    avg_o, am = ts_mean(panel.open, panel.mask, 10)
+    r1, rm1 = cs_rank((panel.open - avg_o) * am.float(), am)
+    diff = (panel.close - panel.vwap).abs()
+    r2, rm2 = cs_rank(diff, panel.mask)
+    m = rm1 & rm2
+    return (r1 * r2) * m.float(), m
+
+
+@register_legacy_factor("add_013")
+def add_013(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(high * low)^0.5 - vwap."""
+    out = (panel.high * panel.low).clamp_min(0).sqrt() - panel.vwap
+    return out * panel.mask.float(), panel.mask
+
+
+@register_legacy_factor("add_014")
+def add_014(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """close - delay(close, 5) scaled by delay(close, 5)."""
+    prev, pm = delay(panel.close, panel.mask, 5)
+    out = (panel.close - prev) / prev.clamp_min(1e-9)
+    return out * pm.float(), pm
+
+
+@register_legacy_factor("add_015")
+def add_015(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """open / delay(close, 1) - 1 (intraday gap rank)."""
+    prev, pm = delay(panel.close, panel.mask, 1)
+    gap = (panel.open / prev.clamp_min(1e-9) - 1.0)
+    return cs_rank(gap * pm.float(), pm)
+
+
+@register_legacy_factor("add_016")
+def add_016(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_max(vwap, 10) - vwap."""
+    mx, mm = ts_max(panel.vwap, panel.mask, 10)
+    out = mx - panel.vwap
+    return out * mm.float(), mm
+
+
+@register_legacy_factor("add_017")
+def add_017(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """vwap - ts_min(vwap, 10)."""
+    mn, mm = ts_min(panel.vwap, panel.mask, 10)
+    out = panel.vwap - mn
+    return out * mm.float(), mm
+
+
+@register_legacy_factor("add_018")
+def add_018(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """mean(abs(close - open) / (high - low + 1e-9), 5)."""
+    ratio = (panel.close - panel.open).abs() / (panel.high - panel.low).clamp_min(1e-9)
+    return ts_mean(ratio, panel.mask, 5)
+
+
+@register_legacy_factor("add_019")
+def add_019(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """sum(close > open, 5) / 5 - bullishness ratio."""
+    bull = (panel.close > panel.open).float()
+    s, sm = ts_sum(bull, panel.mask, 5)
+    return (s / 5.0) * sm.float(), sm
+
+
+@register_legacy_factor("add_020")
+def add_020(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """std(close, 10) / mean(close, 10) - coefficient of variation."""
+    sd, sm = ts_std(panel.close, panel.mask, 10)
+    avg, am = ts_mean(panel.close, panel.mask, 10)
+    m = sm & am
+    out = sd / avg.clamp_min(1e-9)
+    return out * m.float(), m
+
+
+@register_legacy_factor("add_021")
+def add_021(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """rank(corr(close, volume, 20))."""
+    c, cm = ts_corr(panel.close, panel.volume, panel.mask, 20)
+    return cs_rank(c * cm.float(), cm)
+
+
+@register_legacy_factor("add_022")
+def add_022(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ewma(volume, 2/6) / ewma(volume, 2/24) - volume wave."""
+    ew1, m1 = ewma(panel.volume, panel.mask, alpha=2.0 / 6.0)
+    ew2, m2 = ewma(panel.volume, panel.mask, alpha=2.0 / 24.0)
+    m = m1 & m2
+    out = ew1 / ew2.clamp_min(1.0)
+    return out * m.float(), m
+
+
+@register_legacy_factor("add_023")
+def add_023(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """close - ts_mean(close, 5) (deviation from 5-day MA)."""
+    avg, am = ts_mean(panel.close, panel.mask, 5)
+    out = (panel.close - avg) / panel.close.clamp_min(1e-9)
+    return out * am.float(), am
+
+
+@register_legacy_factor("add_024")
+def add_024(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """close - ts_mean(close, 20) (deviation from 20-day MA)."""
+    avg, am = ts_mean(panel.close, panel.mask, 20)
+    out = (panel.close - avg) / panel.close.clamp_min(1e-9)
+    return out * am.float(), am
+
+
+@register_legacy_factor("add_025")
+def add_025(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """mean(close, 5) / mean(close, 20)."""
+    m5, mm5 = ts_mean(panel.close, panel.mask, 5)
+    m20, mm20 = ts_mean(panel.close, panel.mask, 20)
+    m = mm5 & mm20
+    out = m5 / m20.clamp_min(1e-9)
+    return out * m.float(), m
+
+
+@register_legacy_factor("add_026")
+def add_026(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_std(volume, 5) / ts_mean(volume, 5) (volume CV)."""
+    sd, sm = ts_std(panel.volume, panel.mask, 5)
+    avg, am = ts_mean(panel.volume, panel.mask, 5)
+    m = sm & am
+    out = sd / avg.clamp_min(1.0)
+    return out * m.float(), m
+
+
+@register_legacy_factor("add_027")
+def add_027(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """rank(-delta(close, 3) * Δvolume)."""
+    dc, dm1 = delta(panel.close, panel.mask, 3)
+    dv, dm2 = delta(panel.volume, panel.mask, 3)
+    m = dm1 & dm2
+    out = -dc * dv
+    return cs_rank(out * m.float(), m)
+
+
+@register_legacy_factor("add_028")
+def add_028(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(close - open) / (high - low + 1e-9)."""
+    out = (panel.close - panel.open) / (panel.high - panel.low).clamp_min(1e-9)
+    return out * panel.mask.float(), panel.mask
+
+
+@register_legacy_factor("add_029")
+def add_029(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """ts_mean((close - open) / (high - low + eps), 10)."""
+    ratio = (panel.close - panel.open) / (panel.high - panel.low).clamp_min(1e-9)
+    return ts_mean(ratio, panel.mask, 10)
+
+
+@register_legacy_factor("add_030")
+def add_030(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """rank(sum(ret, 5)) * rank(sum(ret, 20))."""
+    ret, rm = delta(panel.close, panel.mask, 1)
+    ret = ret / panel.close.clamp_min(1e-9)
+    s5, m5 = ts_sum(ret, rm, 5)
+    s20, m20 = ts_sum(ret, rm, 20)
+    m = m5 & m20
+    r1, _ = cs_rank(s5, m)
+    r2, _ = cs_rank(s20, m)
+    return (r1 * r2) * m.float(), m

mlquant/features/_factors_alpha101.py

@@ -0,0 +1,98 @@
+"""alpha_* family: curated WorldQuant Alpha101 signals (9 factors).
+
+These factors are adapted from the Alpha101 formulary (Kakushadze, 2016)
+and re-implemented on masked-tensor primitives. They cover momentum,
+reversal, volume--price correlation, volatility, and intraday patterns.
+"""
+from __future__ import annotations
+from typing import Tuple
+import torch
+
+from ..data.panel import Panel
+from .tensor_factors import (
+    cs_rank, cs_zscore, delta, ts_corr, ts_rank, ts_sum,
+)
+from .legacy_factors import register_legacy_factor
+
+Tensor = torch.Tensor
+
+
+@register_legacy_factor("alpha_001")
+def alpha_001(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """cs_rank(ts_rank(close, 5)) - 0.5 — momentum via rank of recent highs."""
+    z, m = ts_rank(panel.close, panel.mask, 5)
+    rank, _ = cs_rank(z, m)
+    return rank - 0.5, m
+
+
+@register_legacy_factor("alpha_002")
+def alpha_002(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-corr(rank(Δ log volume, 2), rank((C-O)/O), 6) — volume-vs-intraday reversal."""
+    log_vol = (panel.volume.clamp_min(1.0)).log()
+    d, dm = delta(log_vol, panel.mask, 2)
+    a, am = cs_rank(d, dm)
+
+    co = (panel.close - panel.open) / panel.open.clamp_min(1e-9)
+    b, bm = cs_rank(co, panel.mask)
+
+    common = am & bm
+    corr, cm = ts_corr(a, b, common, 6)
+    return -corr, cm
+
+
+@register_legacy_factor("alpha_003")
+def alpha_003(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-corr(rank(open), rank(volume), 10) — open/volume rank divergence."""
+    a, am = cs_rank(panel.open,   panel.mask)
+    b, bm = cs_rank(panel.volume, panel.mask)
+    corr, cm = ts_corr(a, b, am & bm, 10)
+    return -corr, cm
+
+
+@register_legacy_factor("alpha_004")
+def alpha_004(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-ts_rank(rank(low), 9) — low-quantile mean reversion."""
+    r, m = cs_rank(panel.low, panel.mask)
+    z, zm = ts_rank(r, m, 9)
+    return -z, zm
+
+
+@register_legacy_factor("alpha_006")
+def alpha_006(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-corr(open, volume, 10) — open/volume rolling correlation."""
+    corr, cm = ts_corr(panel.open, panel.volume, panel.mask, 10)
+    return -corr, cm
+
+
+@register_legacy_factor("alpha_007")
+def alpha_007(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Deviation from 20-day mean, cross-sectionally z-scored."""
+    summed, sm = ts_sum(panel.close, panel.mask, 20)
+    mean = summed / 20.0
+    dev = (panel.close - mean) * sm
+    z, zm = cs_zscore(dev, sm)
+    return z, zm
+
+
+@register_legacy_factor("alpha_012")
+def alpha_012(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """sign(Δvolume) × (−Δclose) — volume-change reversal."""
+    dv, dvm = delta(panel.volume, panel.mask, 1)
+    dc, dcm = delta(panel.close,  panel.mask, 1)
+    out = torch.sign(dv) * (-dc)
+    return out, dvm & dcm
+
+
+@register_legacy_factor("alpha_053")
+def alpha_053(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """-Δ(close-location, 9) — 9-day change in intraday close position."""
+    closeloc = ((panel.close - panel.low) - (panel.high - panel.close)) / (panel.close - panel.low + 1e-12)
+    d, dm = delta(closeloc, panel.mask, 9)
+    return -d, dm
+
+
+@register_legacy_factor("alpha_101")
+def alpha_101(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """(close - open) / (high - low + eps) — intraday close location within range."""
+    out = (panel.close - panel.open) / (panel.high - panel.low + 1e-3)
+    return out * panel.mask.float(), panel.mask