mlquantx 0.2.5__py3-none-any.whl

mlquant/features/legacy_factors.py

@@ -0,0 +1,126 @@
+"""Complete port of legacy factor zoo onto masked tensors.
+
+Ports all ~150 factors from ``legacy/features/Feature.py`` to the modern
+:mod:`mlquant.features.tensor_factors` primitives, with a uniform
+``[T, N]`` mask-aware signature.
+
+Each factor:
+  - Takes a :class:`Panel` object
+  - Returns ``(values_tensor, mask_tensor)``
+  - Uses primitives from tensor_factors.py (ts_mean, cs_rank, delta, etc.)
+
+Factor families:
+  - best_*    : close-location momentum variants (21 factors)
+  - stock_*   : per-stock derived series (22 factors)
+  - extra_*   : turnover + amount features (14 factors)
+  - add_*     : additional factor variants (30 factors)
+  - change_*  : short-window change-of-velocity (5 factors)
+  - original_*: direct close/volume statistics (28 factors)
+  - old_*     : legacy alpha signals (50 factors)
+
+All factors are auto-registered into :data:`LEGACY_REGISTRY` via
+:func:`register_legacy_factor`. Use :func:`compute_legacy_set` to
+compute all or a subset as a stacked ``[T, N, F]`` tensor.
+"""
+from __future__ import annotations
+
+from typing import Callable, Dict, Tuple
+
+import torch
+
+from ..data.panel import Panel
+from .tensor_factors import (
+    cs_rank, cs_zscore,
+    delay, delta,
+    ewma,
+    ts_corr, ts_max, ts_mean, ts_min, ts_rank, ts_std, ts_sum,
+)
+
+
+Tensor = torch.Tensor
+LegacyFn = Callable[[Panel], Tuple[Tensor, Tensor]]
+LEGACY_REGISTRY: Dict[str, LegacyFn] = {}
+
+
+def register_legacy_factor(name: str) -> Callable[[LegacyFn], LegacyFn]:
+    """Decorator to register a factor function into the global registry."""
+    def deco(fn: LegacyFn) -> LegacyFn:
+        if name in LEGACY_REGISTRY:
+            raise ValueError(f"duplicate legacy factor name: {name}")
+        LEGACY_REGISTRY[name] = fn
+        return fn
+    return deco
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _safe_div(num: Tensor, den: Tensor, eps: float = 1e-12) -> Tensor:
+    return num / den.abs().clamp_min(eps).copysign(den + eps)
+
+
+def _close_loc(panel: Panel) -> Tensor:
+    """Where in the day's range did the close land? (-1 = at low, +1 = at high)."""
+    rng = (panel.high - panel.low).clamp_min(1e-9)
+    return (2.0 * panel.close - panel.high - panel.low) / rng
+
+
+def _ts_mean_close_loc(panel: Panel, window: int) -> Tuple[Tensor, Tensor]:
+    cl = _close_loc(panel)
+    return ts_mean(cl, panel.mask, window)
+
+
+def _ret(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """1-day return."""
+    d, dm = delta(panel.close, panel.mask, 1)
+    return d / panel.close.clamp_min(1e-9), dm
+
+
+def _amount(panel: Panel) -> Tensor:
+    """Amount (turnover) — fallback to vwap * volume."""
+    return panel.amount if panel.amount is not None else panel.vwap * panel.volume
+
+
+# ---------------------------------------------------------------------------
+# Import factor groups (each group registers its factors on import)
+# ---------------------------------------------------------------------------
+from . import _factors_best      # noqa: E402, F401
+from . import _factors_stock     # noqa: E402, F401
+from . import _factors_extra     # noqa: E402, F401
+from . import _factors_add       # noqa: E402, F401
+from . import _factors_change    # noqa: E402, F401
+from . import _factors_original  # noqa: E402, F401
+from . import _factors_old       # noqa: E402, F401
+from . import _factors_better    # noqa: E402, F401
+from . import _factors_market    # noqa: E402, F401
+from . import _factors_alpha101  # noqa: E402, F401
+
+
+# ---------------------------------------------------------------------------
+# Driver
+# ---------------------------------------------------------------------------
+def compute_legacy_set(
+    panel: Panel,
+    *,
+    names: tuple[str, ...] | None = None,
+    neutralize: bool = True,
+) -> Tuple[Tensor, Tensor, list[str]]:
+    """Stack registered legacy factors into a ``[T, N, F]`` tensor."""
+    names = names or tuple(LEGACY_REGISTRY)
+    cols, joint = [], None
+    for n in names:
+        v, m = LEGACY_REGISTRY[n](panel)
+        v = torch.where(torch.isfinite(v), v, torch.zeros_like(v))
+        if neutralize:
+            v, _ = cs_zscore(v, m)
+        cols.append(v)
+        joint = m if joint is None else joint & m
+    factors = torch.stack(cols, dim=-1)
+    return factors, joint, list(names)
+
+
+__all__ = [
+    "LEGACY_REGISTRY",
+    "register_legacy_factor",
+    "compute_legacy_set",
+]

mlquant/features/market_breadth.py

@@ -0,0 +1,190 @@
+"""Market-breadth / cross-sectional return-distribution features.
+
+These are the "大盘涨跌分布信号" the legacy ``cuda_features.py`` exposes
+under names like ``CR_-10 .. CR_10``, ``OR_-10 .. OR_10`` and
+``cs_rank_{close,open,high,low,avg,amount}``. They are *cross-sectional
+broadcast* signals — every stock on date ``t`` sees the *same value*
+because the signal is a property of the whole market on that day.
+
+Two families are produced:
+
+1. **Per-stock cross-sectional ranks** of OHLCV/avg/amount within each
+   trading day, mirroring the legacy ``calc_basedata`` output.
+2. **Cross-sectional return-distribution buckets**: for each integer
+   bucket ``b ∈ [-10, 10]`` we publish the fraction of tradable stocks
+   whose rounded close-on-close return (in %) equals ``b``. These 21
+   numbers form the daily "rise/fall histogram" that the legacy
+   pipeline used as a market regime descriptor. The same is computed
+   for open-on-close (``OR_*``).
+
+Why broadcast?
+    The downstream alpha set takes ``[T, N]`` inputs, so a market-only
+    signal is replicated across the stock axis. This wastes a bit of
+    memory but keeps the data layout uniform and mask-aware.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+import torch
+
+from ..data.panel import Panel
+from .tensor_factors import cs_rank
+
+
+Tensor = torch.Tensor
+
+# Bucket grid: -10 % .. +10 % in 1 % steps -> 21 buckets.
+_BUCKETS: tuple[int, ...] = tuple(range(-10, 11))
+
+
+# ---------------------------------------------------------------------------
+# Per-stock cross-sectional ranks
+# ---------------------------------------------------------------------------
+def cs_rank_field(panel: Panel, name: str) -> Tuple[Tensor, Tensor]:
+    """Cross-sectional percentile rank of ``panel.<name>`` within each date.
+
+    The legacy code uses ``ascending=False`` (largest → rank 1.0). We
+    keep that convention for parity with the pickled feature tables.
+    """
+    field = getattr(panel, name, None)
+    if field is None:
+        raise KeyError(f"panel has no field {name!r}")
+    return cs_rank(field, panel.mask, descending=True)
+
+
+def cs_rank_avg(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Cross-sectional rank of the daily VWAP (``S_DQ_AVGPRICE``)."""
+    return cs_rank(panel.vwap, panel.mask, descending=True)
+
+
+def cs_rank_amount(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """Cross-sectional rank of the daily turnover ``amount``.
+
+    Falls back to ``vwap * volume`` when :attr:`Panel.amount` is absent.
+    """
+    if panel.amount is not None:
+        amt = panel.amount
+    else:
+        amt = panel.vwap * panel.volume
+    return cs_rank(amt, panel.mask, descending=True)
+
+
+# ---------------------------------------------------------------------------
+# Cross-sectional return-distribution buckets (CR_*, OR_*)
+# ---------------------------------------------------------------------------
+def _bucketize_pct(ret: Tensor, mask: Tensor) -> Tensor:
+    """Round ``ret`` into integer percentage buckets, clipped to ``[-10, 10]``.
+
+    Returns an ``int64`` tensor with the same shape as ``ret``; cells where
+    ``mask`` is False are set to a sentinel value ``-100`` so the caller
+    can drop them.
+    """
+    pct = (ret * 100.0).round().to(torch.int64)
+    pct = pct.clamp(min=_BUCKETS[0], max=_BUCKETS[-1])
+    return pct.masked_fill(~mask, -100)
+
+
+def _broadcast_histogram(buckets: Tensor, mask: Tensor) -> Dict[int, Tensor]:
+    """For every date, compute the fraction of tradable stocks in each bucket.
+
+    Returns a dict ``{b: tensor[T, N]}`` where each tensor is the daily
+    fraction broadcast across the stock axis.
+    """
+    T, N = buckets.shape
+    out: Dict[int, Tensor] = {}
+    n_valid = mask.sum(dim=1, keepdim=True).clamp_min(1).float()      # [T, 1]
+    for b in _BUCKETS:
+        count = ((buckets == b) & mask).sum(dim=1, keepdim=True).float()  # [T, 1]
+        frac  = count / n_valid                                            # [T, 1]
+        out[b] = frac.expand(T, N).contiguous()
+    return out
+
+
+def close_return_distribution(panel: Panel) -> Dict[int, Tensor]:
+    """``CR_-10..CR_10`` — daily fraction of stocks at each rounded close-return.
+
+    Definition (matches legacy)
+    ---------------------------
+    ``ret_t = close_t / last_close_t - 1``, clipped to ±10 %, rounded to
+    the nearest integer percent. Buckets index 21 disjoint events; the
+    sum of the 21 ``CR_*`` series at any date equals 1.
+
+    Returns
+    -------
+    dict[int, Tensor]
+        Mapping bucket → ``[T, N]`` tensor (broadcast across stocks).
+    """
+    ret = panel.returns                                # last_close-aware
+    mask = panel.mask
+    buckets = _bucketize_pct(ret, mask)
+    return _broadcast_histogram(buckets, mask)
+
+
+def open_return_distribution(panel: Panel) -> Dict[int, Tensor]:
+    """``OR_-10..OR_10`` — same idea but on ``(open_t - last_close_t) / last_close_t``."""
+    if panel.last_close is not None:
+        prev = panel.last_close.clamp_min(1e-9)
+        valid_prev = panel.last_close > 0
+    else:
+        prev = torch.roll(panel.close, shifts=1, dims=0).clamp_min(1e-9)
+        valid_prev = torch.ones_like(panel.mask)
+        valid_prev[0] = False
+    ret = panel.open / prev - 1.0
+    mask = panel.mask & valid_prev
+    buckets = _bucketize_pct(ret, mask)
+    return _broadcast_histogram(buckets, mask)
+
+
+# ---------------------------------------------------------------------------
+# Driver
+# ---------------------------------------------------------------------------
+def compute_market_breadth(panel: Panel) -> Tuple[Tensor, Tensor, List[str]]:
+    """Compute every market-breadth feature into a stacked ``[T, N, F]`` tensor.
+
+    Output columns
+    --------------
+    * ``cs_rank_close``, ``cs_rank_open``, ``cs_rank_high``,
+      ``cs_rank_low``, ``cs_rank_avg``, ``cs_rank_amount``
+    * ``CR_-10`` .. ``CR_10``  (21 buckets)
+    * ``OR_-10`` .. ``OR_10``  (21 buckets)
+
+    => 6 + 21 + 21 = 48 columns total.
+    """
+    cols: List[Tensor] = []
+    names: List[str] = []
+    joint_mask: Tensor = panel.mask.clone()
+
+    for fname in ("close", "open", "high", "low"):
+        v, m = cs_rank_field(panel, fname)
+        cols.append(v)
+        names.append(f"cs_rank_{fname}")
+        joint_mask = joint_mask & m
+
+    v, m = cs_rank_avg(panel)
+    cols.append(v); names.append("cs_rank_avg"); joint_mask = joint_mask & m
+    v, m = cs_rank_amount(panel)
+    cols.append(v); names.append("cs_rank_amount"); joint_mask = joint_mask & m
+
+    cr = close_return_distribution(panel)
+    for b in _BUCKETS:
+        cols.append(cr[b])
+        names.append(f"CR_{b}")
+
+    or_ = open_return_distribution(panel)
+    for b in _BUCKETS:
+        cols.append(or_[b])
+        names.append(f"OR_{b}")
+
+    factors = torch.stack(cols, dim=-1)       # [T, N, F]
+    return factors, joint_mask, names
+
+
+__all__ = [
+    "cs_rank_field",
+    "cs_rank_avg",
+    "cs_rank_amount",
+    "close_return_distribution",
+    "open_return_distribution",
+    "compute_market_breadth",
+]

mlquant/features/neutralize.py

@@ -0,0 +1,75 @@
+"""Cross-sectional and industry/size neutralisation.
+
+The simplest and most defensible neutralisation is a per-date
+cross-sectional z-score, which removes the market-mean drift while
+preserving the cross-sectional ordering — exactly the information a
+long-short alpha consumes downstream. We expose two variants:
+
+* :func:`neutralize_cs`        — z-score across all tradable stocks per date.
+* :func:`neutralize_industry`  — regress out a one-hot industry matrix
+  per date and return the residuals.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import torch
+
+from .tensor_factors import cs_zscore
+
+
+def neutralize_cs(x: torch.Tensor, mask: torch.Tensor) -> torch.Tensor:
+    """Per-date cross-sectional z-score, masked-aware."""
+    out, _ = cs_zscore(x, mask)
+    return out
+
+
+def neutralize_industry(
+    x: torch.Tensor,
+    mask: torch.Tensor,
+    industry_onehot: torch.Tensor,
+    *,
+    log_size: Optional[torch.Tensor] = None,
+) -> torch.Tensor:
+    """Per-date OLS-residualise ``x`` against industry dummies (+ optionally
+    log market cap).
+
+    Parameters
+    ----------
+    x : Tensor [T, N]
+    mask : Tensor [T, N] bool
+    industry_onehot : Tensor [T, N, K]   one-hot per stock-day
+    log_size : Tensor [T, N], optional   if given, added as a continuous
+        regressor.
+
+    Returns
+    -------
+    Tensor [T, N] — residuals, masked cells set to 0.
+    """
+    T, N = x.shape
+    K = industry_onehot.shape[-1]
+    out = torch.zeros_like(x)
+
+    for t in range(T):
+        m = mask[t]
+        if m.sum() < 2:
+            continue
+        y = x[t][m]
+        Xs = [industry_onehot[t][m].float()]
+        if log_size is not None:
+            Xs.append(log_size[t][m].unsqueeze(1))
+        X = torch.cat(Xs, dim=1)
+        # least-squares  Xβ = y   via lstsq for numerical stability
+        beta = torch.linalg.lstsq(X, y.unsqueeze(1)).solution.squeeze(1)
+        residual = y - X @ beta
+        # Degeneracy guard: a nearly perfect fit can leave float32 numerical
+        # noise that should not be amplified to unit variance. Compare against
+        # the signal's own scale so genuinely small signals remain valid.
+        residual = residual - residual.mean()
+        residual_scale = residual.std(unbiased=False)
+        signal_scale = (y - y.mean()).std(unbiased=False)
+        if signal_scale <= 0 or residual_scale <= signal_scale * 1e-6:
+            continue
+        out[t][m] = residual / residual_scale
+
+    return out

mlquant/features/target.py

@@ -0,0 +1,62 @@
+"""Forward-return labels (training targets).
+
+The legacy ``cuda_features.py`` ships a single label, ``target_01``,
+which the paper uses throughout::
+
+    target_01[t, i] = close[t+1, i] / close[t, i] - 1
+
+masked by ``mask[t, i] & mask[t+1, i]``. Concretely, this is the
+realised one-day forward simple return, computed only on stock-days
+where the stock was tradable both at signal time *t* and at execution
+time *t+1*. The last row is always masked because there is no ``t+1``.
+
+We expose two helpers:
+
+* :func:`target_01` — vectorised tensor implementation.
+* :func:`forward_return` — generic ``k``-day forward return.
+
+Both return ``(values, mask)`` to fit the rest of the feature engine.
+"""
+from __future__ import annotations
+
+from typing import Tuple
+
+import torch
+
+from ..data.panel import Panel
+
+
+Tensor = torch.Tensor
+
+
+def forward_return(panel: Panel, horizon: int = 1) -> Tuple[Tensor, Tensor]:
+    """``close[t+horizon] / close[t] - 1`` masked by tradability at both ends.
+
+    Parameters
+    ----------
+    panel : Panel
+    horizon : int
+        Number of periods to look ahead. Must be >= 1.
+    """
+    if horizon < 1:
+        raise ValueError(f"horizon must be >= 1, got {horizon}")
+    T, N = panel.close.shape
+    out = torch.zeros_like(panel.close)
+    out_mask = torch.zeros_like(panel.mask)
+
+    fut_close = panel.close[horizon:]
+    cur_close = panel.close[:-horizon].clamp_min(1e-9)
+    fut_mask  = panel.mask[horizon:]
+    cur_mask  = panel.mask[:-horizon]
+
+    out[:-horizon] = (fut_close / cur_close - 1.0) * (fut_mask & cur_mask).float()
+    out_mask[:-horizon] = fut_mask & cur_mask
+    return out, out_mask
+
+
+def target_01(panel: Panel) -> Tuple[Tensor, Tensor]:
+    """1-day forward simple return — the canonical training label."""
+    return forward_return(panel, horizon=1)
+
+
+__all__ = ["target_01", "forward_return"]