Skip to content

"Vibe-Trading: Your Personal Trading Agent"

19.9 KB
Raw Blame
"""Alpha Zoo base operators.

Operators all act on **wide** ``pd.DataFrame`` where ``index = trading_date``
(DatetimeIndex) and ``columns = instrument_code`` (str). The factor compute
contract returns a DataFrame of the same shape — raw scores, NaN preserved
in warmup / missing data; +/- inf is forbidden (registry rejects it).

NaN policy: every operator propagates NaN; no silent ``fillna(0)``. A constant
window for ``ts_corr`` / ``ts_cov`` returns NaN, not zero. A missing input is
never replaced by a constant — not a comparison read as False, not
``.where(cond, 0)``, not ``np.fmax`` returning the other side (#1463) — and a
full-window operator (``min_periods`` equal to its window) is NaN on every bar
whose window holds the gap. The one exception, decided on #1463 (2026-09-18):
a recursive statistic skips a missing observation and continues from its last
state — the GTJA ``SMA(A, n, m)`` written as ``.ewm(alpha=m/n, adjust=False)``,
a running product — and so does a window that declares its own partial
coverage (``min_periods`` below its length, or a coverage rule in its notes).
Those emit a value on the bars after a gap, computed from the observations
they did see. Nothing rewarms them, and nothing should: the registry already
masks the gap bar itself.

A comparison gate or ``np.fmin`` / ``np.fmax`` over operands that can be
undefined on complete data (a constant window's correlation) masks on its
inputs' reach with :func:`observed_over`, not on its operands' NaN: a gap
inside the reach is NaN, and a correlation that is undefined without any gap
keeps the verdict it always had (#1452).

Lookahead ban: ``delta(df, d)`` requires ``d >= 1``; the negative-shift
``Ref(df, -n)`` form is intentionally absent.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Protocol, runtime_checkable

import numpy as np
import pandas as pd

from src.factors._backend import HAS_BOTTLENECK, bn, sliding_window_view


class Market(str, Enum):
    """Market identifier used by ``vwap`` for market-specific formulas."""

    EQUITY_US = "equity_us"
    EQUITY_CN = "equity_cn"
    EQUITY_HK = "equity_hk"
    EQUITY_IN = "equity_in"
    EQUITY_KR = "equity_kr"
    CRYPTO = "crypto"
    FUTURES = "futures"


@dataclass(frozen=True, slots=True)
class Alpha:
    """Lightweight handle for a registered alpha (registry-owned)."""

    id: str
    zoo: str
    module_path: str
    meta: dict[str, Any] = field(default_factory=dict)


@runtime_checkable
class AlphaCompute(Protocol):
    """Structural protocol every alpha ``.py`` module satisfies."""

    def __call__(self, panel: dict[str, pd.DataFrame]) -> pd.DataFrame: ...


def _as_float(df: pd.DataFrame) -> pd.DataFrame:
    if df.dtypes.eq(np.float64).all():
        return df
    return df.astype(np.float64)


def rank(df: pd.DataFrame) -> pd.DataFrame:
    """Cross-sectional percentile rank per row (axis=1, ties=average, pct=True).

    NaN inputs stay NaN. An all-NaN row returns an all-NaN row.
    """
    return df.rank(axis=1, method="average", pct=True, na_option="keep")


def zscore(df: pd.DataFrame) -> pd.DataFrame:
    """Cross-sectional z-score per row (axis=1, sample std).

    Rows with zero or NaN standard deviation become NaN — never silent zero.
    """
    df = _as_float(df)
    mean = df.mean(axis=1, skipna=True)
    std = df.std(axis=1, ddof=1, skipna=True)
    result = df.sub(mean, axis=0).div(std.where(std > 0), axis=0)
    return result.replace([np.inf, -np.inf], np.nan)


def zscore_by_group(df: pd.DataFrame, groups: pd.DataFrame) -> pd.DataFrame:
    """Per-row within-group z-score (axis=1 groups, sample std, ddof=1).

    The z-scoring sibling of the per-row sector demean the industry-neutralized
    alpha101 alphas use: instead of one cross-sectional mean/std per date, each
    label group in the row gets its own. One difference is deliberate — there is
    NO global fallback. A cell whose group cannot produce a statistic stays NaN
    rather than silently degrading to a whole-cross-section z-score wearing an
    industry-neutral label.

    Contract:
        * ``groups`` is a wide label frame with the SAME shape as ``df``,
          positionally aligned (same precedent as the alpha101 ``sector`` tag);
          labels may be any hashable value (str, int) and are compared by
          position, never by index/column join.
        * Per row: within each label group, ``(x - group_mean) / group_std``
          with ``ddof=1`` over the group's finite observations.
        * A group with fewer than two finite observations on that row → NaN for
          that group's cells (no statistic exists); a zero-variance group → NaN
          (never inf, never silent zero).
        * NaN input cells stay NaN; cells whose label is None/NaN → NaN; ±inf
          inputs are scrubbed to NaN before grouping.
        * Output keeps ``df``'s shape, index and columns exactly.

    Args:
        df: Wide numeric frame (dates x symbols).
        groups: Wide label frame, same shape as ``df``, positionally aligned.

    Returns:
        Wide frame of within-group z-scores, NaN wherever the contract above
        refuses to produce a number.

    Raises:
        ValueError: If ``groups`` does not have the same shape as ``df``.
    """
    if df.shape != groups.shape:
        raise ValueError(
            f"zscore_by_group: groups shape {groups.shape} != df shape {df.shape}; "
            "the label frame must be positionally aligned with the value frame"
        )
    values = _as_float(df).to_numpy(dtype=np.float64, na_value=np.nan).copy()
    # ±inf is not an observation: scrub before it poisons a group mean/std.
    values[~np.isnan(values) & ~np.isfinite(values)] = np.nan
    labels = groups.to_numpy()
    # Per-row python/numpy loop, same mechanics as the alpha101 precedent —
    # correctness over cleverness; cross-sections are a few hundred cells wide.
    for i in range(values.shape[0]):
        row = values[i]
        label_row = labels[i]
        unlabeled = pd.isna(label_row)
        if unlabeled.any():
            row[unlabeled] = np.nan
        for tag in pd.unique(label_row):
            if tag is None or (isinstance(tag, float) and np.isnan(tag)) or pd.isna(tag):
                continue  # handled by the unlabeled mask above
            mask = label_row == tag
            vals = row[mask]
            finite = vals[~np.isnan(vals)]
            if finite.size < 2:
                row[mask] = np.nan
                continue
            std = finite.std(ddof=1)
            if not np.isfinite(std) or std <= 0:
                row[mask] = np.nan
                continue
            row[mask] = (vals - finite.mean()) / std
    return pd.DataFrame(values, index=df.index, columns=df.columns)


def scale(df: pd.DataFrame, a: float = 1.0) -> pd.DataFrame:
    """Per-row L1 normalize so sum of absolute values equals ``a``.

    Rows whose abs-sum is 0 (or all-NaN) become NaN — never silent zero.
    """
    df = _as_float(df)
    abs_sum = df.abs().sum(axis=1, skipna=True)
    abs_sum = abs_sum.where(abs_sum > 0)  # zero → NaN
    return df.mul(a).div(abs_sum, axis=0)


def ts_rank(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling rank (last value's rank within the n-window), per column.

    Warmup (first ``n-1`` rows per column) returns NaN. Result is a percentile
    in [0, 1] so it is compositionally compatible with cross-sectional rank.

    Uses numpy ``sliding_window_view`` for vectorized computation (~45x faster
    than pandas rolling().apply()). Note: ``bottleneck.move_rank`` computes
    Spearman rank correlation, not percentile rank, so it is not used here.
    """
    if n < 1:
        raise ValueError(f"ts_rank window must be >= 1, got {n}")

    def _last_rank(arr: np.ndarray) -> float:
        if np.isnan(arr).all():
            return np.nan
        last = arr[-1]
        if np.isnan(last):
            return np.nan
        valid = arr[~np.isnan(arr)]
        if valid.size == 0:
            return np.nan
        # average rank for ties; pct
        less = (valid < last).sum()
        eq = (valid == last).sum()
        rank_avg = less + 0.5 * (eq + 1)
        return float(rank_avg / valid.size)

    arr = df.to_numpy(dtype=np.float64)
    T, C = arr.shape
    if T < n:
        return df.rolling(window=n, min_periods=n).apply(_last_rank, raw=True)

    windows = sliding_window_view(arr, window_shape=n, axis=0)  # (T-n+1, C, n)
    last_vals = windows[:, :, -1]  # (T-n+1, C)
    nan_last = np.isnan(last_vals)
    nan_count = np.isnan(windows).sum(axis=2)
    valid_count = n - nan_count

    last_expanded = last_vals[:, :, np.newaxis]
    valid_mask = ~np.isnan(windows) & ~nan_last[:, :, np.newaxis]
    less = np.sum(np.where(valid_mask, windows < last_expanded, 0), axis=2)
    eq = np.sum(np.where(valid_mask, windows == last_expanded, 0), axis=2)
    rank_avg = less + 0.5 * (eq + 1)
    with np.errstate(divide="ignore", invalid="ignore"):
        pct = rank_avg / valid_count
    # min_periods=n: any NaN in window → NaN output
    pct[nan_last | (nan_count > 0)] = np.nan

    result = np.full((T, C), np.nan)
    result[n - 1 :] = pct
    return pd.DataFrame(result, index=df.index, columns=df.columns)


def ts_corr(x: pd.DataFrame, y: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling Pearson correlation per column, min_periods=n.

    Constant series in the window → NaN (no silent zero). Pairs are inner-joined
    on columns; columns missing from either side become NaN.
    """
    if n < 2:
        raise ValueError(f"ts_corr window must be >= 2, got {n}")
    x = _as_float(x)
    y = _as_float(y)
    cols = x.columns.union(y.columns)
    xa = x.reindex(columns=cols)
    ya = y.reindex(columns=cols)
    corr = xa.rolling(window=n, min_periods=n).corr(ya)
    # corr above can produce +/- inf when one series is constant in some
    # pandas versions; force to NaN.
    return corr.replace([np.inf, -np.inf], np.nan)


def ts_cov(x: pd.DataFrame, y: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling sample covariance per column, min_periods=n."""
    if n < 2:
        raise ValueError(f"ts_cov window must be >= 2, got {n}")
    x = _as_float(x)
    y = _as_float(y)
    cols = x.columns.union(y.columns)
    xa = x.reindex(columns=cols)
    ya = y.reindex(columns=cols)
    cov = xa.rolling(window=n, min_periods=n).cov(ya)
    return cov.replace([np.inf, -np.inf], np.nan)


def ts_mean(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling mean per column, warmup → NaN."""
    if n < 1:
        raise ValueError(f"ts_mean window must be >= 1, got {n}")
    return df.rolling(window=n, min_periods=n).mean()


def ts_std(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling sample std (ddof=1) per column, warmup → NaN."""
    if n < 2:
        raise ValueError(f"ts_std window must be >= 2, got {n}")
    return df.rolling(window=n, min_periods=n).std(ddof=1)


def ts_slope(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling OLS slope against ``0, ..., n - 1``, requiring a full window."""
    if n < 2:
        raise ValueError(f"ts_slope window must be >= 2, got {n}")
    arr = _as_float(df).to_numpy(dtype=np.float64, na_value=np.nan)
    T, C = arr.shape
    result = np.full((T, C), np.nan)
    if T < n:
        return pd.DataFrame(result, index=df.index, columns=df.columns)

    x = np.arange(n, dtype=np.float64)
    x -= x.mean()
    windows = sliding_window_view(arr, window_shape=n, axis=0)
    slopes = np.einsum("ijk,k->ij", windows, x) / np.dot(x, x)
    result[n - 1 :] = slopes
    return pd.DataFrame(result, index=df.index, columns=df.columns)


def ts_resi(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Latest observation's residual from the same trailing OLS fit."""
    slope = ts_slope(df, n)
    fitted_at_last = ts_mean(df, n) + slope * ((n - 1) / 2.0)
    return df - fitted_at_last


def ts_max(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling max per column, warmup → NaN."""
    if n < 1:
        raise ValueError(f"ts_max window must be >= 1, got {n}")
    return df.rolling(window=n, min_periods=n).max()


def ts_min(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling min per column, warmup → NaN."""
    if n < 1:
        raise ValueError(f"ts_min window must be >= 1, got {n}")
    return df.rolling(window=n, min_periods=n).min()


def _argmax_last(arr: np.ndarray) -> float:
    if np.isnan(arr).all():
        return np.nan
    arr_filled = np.where(np.isnan(arr), -np.inf, arr)
    # Ties resolve to the most recent bar, matching bottleneck's move_argmax.
    return float(len(arr) - 1 - np.argmax(arr_filled[::-1]))


def _argmin_last(arr: np.ndarray) -> float:
    if np.isnan(arr).all():
        return np.nan
    arr_filled = np.where(np.isnan(arr), np.inf, arr)
    # Ties resolve to the most recent bar, matching bottleneck's move_argmin.
    return float(len(arr) - 1 - np.argmin(arr_filled[::-1]))


def ts_argmax(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling argmax (0-based index into the window), warmup → NaN.

    Uses ``bottleneck.move_argmax`` when available (~350x faster).
    Correction: ``bn.move_argmax`` returns distance from window end,
    so we convert via ``(n - 1) - bn_result`` to get 0-based index from start.
    """
    if n < 1:
        raise ValueError(f"ts_argmax window must be >= 1, got {n}")
    if HAS_BOTTLENECK:
        arr = df.to_numpy(dtype=np.float64)
        raw = bn.move_argmax(arr, window=n, min_count=n, axis=0)
        corrected = (n - 1) - raw
        return pd.DataFrame(corrected, index=df.index, columns=df.columns)
    return df.rolling(window=n, min_periods=n).apply(_argmax_last, raw=True)


def ts_argmin(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Rolling argmin (0-based index into the window), warmup → NaN.

    Uses ``bottleneck.move_argmin`` when available (~350x faster).
    Correction: ``bn.move_argmin`` returns distance from window end,
    so we convert via ``(n - 1) - bn_result`` to get 0-based index from start.
    """
    if n < 1:
        raise ValueError(f"ts_argmin window must be >= 1, got {n}")
    if HAS_BOTTLENECK:
        arr = df.to_numpy(dtype=np.float64)
        raw = bn.move_argmin(arr, window=n, min_count=n, axis=0)
        corrected = (n - 1) - raw
        return pd.DataFrame(corrected, index=df.index, columns=df.columns)
    return df.rolling(window=n, min_periods=n).apply(_argmin_last, raw=True)


def delta(df: pd.DataFrame, d: int) -> pd.DataFrame:
    """First difference at lag ``d``: ``df - df.shift(d)``.

    Lookahead ban: ``d >= 1`` strictly. Negative lag forbidden.
    """
    if d < 1:
        raise ValueError(f"delta lag must be >= 1 (lookahead ban), got {d}")
    return df - df.shift(d)


def decay_linear(df: pd.DataFrame, n: int) -> pd.DataFrame:
    """Linear decay-weighted moving average, weights ``n, n-1, ..., 1`` normalized.

    The most recent bar gets weight ``n`` and the oldest bar in the window
    gets weight ``1`` (Kakushadze, *101 Formulaic Alphas*, Appendix A).

    Warmup (first ``n-1`` rows) → NaN.

    Uses numpy ``sliding_window_view`` + ``einsum`` for vectorized computation
    (~40x faster than pandas rolling().apply()). Causal alignment is guaranteed:
    output[i] depends only on input[i-n+1:i+1].
    """
    if n < 1:
        raise ValueError(f"decay_linear window must be >= 1, got {n}")
    # Windows run oldest -> newest, so ascending weights put n on today's bar.
    weights = np.arange(1, n + 1, dtype=np.float64)
    weights /= weights.sum()

    def _apply(arr: np.ndarray) -> float:
        if np.isnan(arr).any():
            return np.nan
        return float(np.dot(arr, weights))

    arr = df.to_numpy(dtype=np.float64)
    T, C = arr.shape
    if T < n:
        return df.rolling(window=n, min_periods=n).apply(_apply, raw=True)

    windows = sliding_window_view(arr, window_shape=n, axis=0)  # (T-n+1, C, n)
    nan_mask = np.isnan(windows).any(axis=2)  # (T-n+1, C)
    weighted = np.where(nan_mask[..., np.newaxis], 0.0, windows)
    dot = np.einsum("ijk,k->ij", weighted, weights)

    result = np.full((T, C), np.nan)
    result[n - 1 :] = np.where(nan_mask, np.nan, dot)
    return pd.DataFrame(result, index=df.index, columns=df.columns)


def signed_power(df: pd.DataFrame, p: float) -> pd.DataFrame:
    """``sign(df) * |df|**p`` — preserves sign; never produces complex output."""
    arr = df.to_numpy(dtype=np.float64, na_value=np.nan)
    out = np.sign(arr) * np.power(np.abs(arr), p)
    return pd.DataFrame(out, index=df.index, columns=df.columns)


def observed_over(*inputs: tuple[pd.DataFrame, int]) -> pd.DataFrame:
    """Mask of the cells whose every input was observed on each of its last ``n`` bars.

    A comparison or ``np.fmin`` turns an operand that is missing because its
    window holds a missing input into a verdict — a NaN comparison is False —
    so those cells must be NaN (#1463). An operand that is undefined on complete
    data, a constant window's correlation, keeps the alpha's existing verdict
    (#1452). Masking on the inputs' presence rather than on the operand's NaN is
    what separates the two. ``n`` is how far back the input reaches through the
    alpha's nested windows, so the first ``n - 1`` bars (warmup) are masked too.

    Args:
        *inputs: ``(frame, n)`` pairs, one per input the alpha reads across
            bars, each with that input's reach in bars.

    Returns:
        Boolean frame, True where every input was observed throughout its reach.
    """
    present = None
    for frame, n in inputs:
        seen = frame.notna().astype(float).rolling(n, min_periods=n).min().eq(1.0)
        present = seen if present is None else present & seen
    if present is None:
        raise ValueError("observed_over needs at least one (frame, n) pair")
    return present


def safe_div(a: pd.DataFrame, b: pd.DataFrame, eps: float = 1e-12) -> pd.DataFrame:
    """Safe division: ``a / (b + eps * sign(b))``.

    Where ``b == 0`` exactly (or NaN), result is NaN — never silently inf or 0.
    """
    a = _as_float(a)
    b = _as_float(b)
    sign = np.sign(b.to_numpy(dtype=np.float64, na_value=np.nan))
    # b == 0 → sign == 0 → denom == 0 → NaN below
    denom_arr = b.to_numpy(dtype=np.float64, na_value=np.nan) + eps * sign
    denom = pd.DataFrame(denom_arr, index=b.index, columns=b.columns)
    result = a.div(denom)
    return result.replace([np.inf, -np.inf], np.nan)


def vwap(panel: dict[str, pd.DataFrame], market: Market | str) -> pd.DataFrame:
    """Market-aware VWAP-equivalent reference price.

    - ``equity_cn``: ``(amount * 1000) / (volume * 100 + 1)`` — Tushare's
      ``daily.amount`` is in **千元 (thousand CNY)** and ``daily.vol`` is in
      **手 (100 shares)**. Probe 2026-05-17 against ``000001.SZ`` shows
      ``amount/(vol*100) ≈ 0.0093`` for a close of 9.27 — confirming the 1000x
      scale. We multiply ``amount`` by 1000 (CNY) and divide by
      ``volume * 100`` (shares); ``+1`` keeps the denominator positive on
      suspended bars.
    - ``equity_us`` / ``equity_hk`` / ``equity_in`` / ``equity_kr`` /
      ``futures``: typical price ``(H + L + C + O) / 4`` when ``panel["vwap"]``
      is absent. India (NSE/BSE) bars from Yahoo and Korea (KRX) bars from
      pykrx carry raw price/volume (no Tushare 千元/手 scaling), so the
      typical-price form applies unchanged.
    - ``crypto``: prefer ``panel["vwap"]`` if provided, else typical price.

    Any missing required column → NaN propagation; never silent zero.
    """
    if isinstance(market, str):
        market = Market(market)

    if "vwap" in panel:
        return panel["vwap"]

    if market is Market.EQUITY_CN:
        if "amount" not in panel or "volume" not in panel:
            raise KeyError("vwap(equity_cn) requires panel['amount'] and panel['volume']")
        return safe_div(panel["amount"] * 1000.0, panel["volume"] * 100.0 + 1.0)

    required = ("open", "high", "low", "close")
    missing = [k for k in required if k not in panel]
    if missing:
        raise KeyError(f"vwap({market.value}) requires panel keys {required}; missing {missing}")
    return (panel["open"] + panel["high"] + panel["low"] + panel["close"]) / 4.0