alpha101v 0.1.2__py3-none-any.whl

alpha101v/__init__.py

@@ -0,0 +1,128 @@
+"""alpha101v — 一份「可验证的 Alpha101」实现（M0/M1：算子层）。
+
+设计依据：``docs/Alpha101_修复发布决策与验证协议_v0.1.md``（内容版本 v0.2）。
+口径唯一权威：``docs/operators.md``。
+
+公开算子面恰好 20 个（16 个时序/截面算子 + ``rolling_rank`` 构件 + 3 个中性化算子），
+见 :data:`OPERATORS`；另有**不属于算子面**的逐元素函数层见 :data:`ELEMWISE`
+（论文把它们列为 Functions，见 ``docs/operators.md`` §3.9）。
+
+因子层（M3）交付 **全部 101 个因子**（:data:`ALL_FACTOR_NAMES`），导入本包即自动登记进
+``registry.REGISTRY``；状态只有 ``partial``（结构对照等价）与 ``ambiguous``
+（规范未定，见 ``factors.AMBIGUOUS_FACTORS``）——``verified`` 需六条门槛，见设计文档 §6.8。因子层（``factors.py``）已含全部 101 个因子（论文逐字转写）。
+本包**不含任何来自 GPL 实现的代码**（clean-room，见 ``docs/paper_formulas.md`` 与
+``tests/test_provenance.py``）。
+"""
+
+from __future__ import annotations
+
+from . import elemwise, factors, neutralize, operators, panel, registry
+from .elemwise import ELEMWISE, abs_, log, maximum, minimum, sign, signedpower
+from .factors import ALL_FACTOR_NAMES, PILOT_NAMES, alpha4, alpha41, alpha5, alpha56, alpha101
+from .neutralize import ind_neutralize, neu_industry, neutral
+from .operators import (
+    correlation,
+    covariance,
+    decay_linear,
+    delta,
+    delay,
+    product,
+    rank,
+    rolling_rank,
+    scale,
+    sma,
+    stddev,
+    ts_argmax,
+    ts_argmin,
+    ts_max,
+    ts_min,
+    ts_rank,
+    ts_sum,
+)
+
+def _resolve_version() -> str:
+    """版本号**单一来源**：优先读安装元数据（`pyproject.toml` 里的 version），
+    源码树直接 import（未安装）时回退。硬编码版本号曾与 pyproject 漂移过
+    （`__init__` 写 0.1.0、dist 是 0.1.1），因此有 tests/test_version.py 专门守这条。
+    """
+    try:
+        from importlib.metadata import version as _v
+
+        return _v("alpha101v")
+    except Exception:  # noqa: BLE001 - 未安装/元数据缺失时回退
+        return "0.1.2"
+
+
+__version__ = _resolve_version()
+
+#: 20 个算子的名字（设计文档 §7.3 的 17 个 API + §8.1 的 rolling_rank + §8.3 的两个中性化变体）。
+#: ``tests/test_operators.py::test_api_surface_is_exactly_twenty`` 会守住这个清单。
+OPERATORS: tuple[str, ...] = (
+    # A 组 / 时序与截面（§7.3）
+    "ts_sum",
+    "sma",
+    "stddev",
+    "correlation",
+    "covariance",
+    "ts_rank",
+    "product",
+    "ts_min",
+    "ts_max",
+    "delta",
+    "delay",
+    "rank",
+    "scale",
+    "ts_argmax",
+    "ts_argmin",
+    "decay_linear",
+    # §8.1 明确要求对拍的构件
+    "rolling_rank",
+    # §8.3 中性化组
+    "ind_neutralize",
+    "neu_industry",
+    "neutral",
+)
+
+__all__ = [
+    "ALL_FACTOR_NAMES",
+    "ELEMWISE",
+    "OPERATORS",
+    "PILOT_NAMES",
+    "__version__",
+    "alpha4",
+    "alpha41",
+    "alpha56",
+    "alpha101",
+    "factors",
+    "panel",
+    "registry",
+    "abs_",
+    "elemwise",
+    "log",
+    "maximum",
+    "minimum",
+    "sign",
+    "signedpower",
+    "correlation",
+    "covariance",
+    "decay_linear",
+    "delta",
+    "delay",
+    "ind_neutralize",
+    "neu_industry",
+    "neutral",
+    "neutralize",
+    "operators",
+    "product",
+    "rank",
+    "rolling_rank",
+    "scale",
+    "sma",
+    "stddev",
+    "ts_argmax",
+    "ts_argmin",
+    "ts_max",
+    "ts_min",
+    "ts_rank",
+    "ts_sum",
+]

alpha101v/adapters/__init__.py

@@ -0,0 +1,18 @@
+"""alpha101v.adapters — 数据适配层（可选，**不属于运行时依赖**）。
+
+设计文档 §7.1 硬约束：本包**运行时**只依赖 ``numpy / pandas / scipy``。
+适配器因此遵循两条纪律：
+
+1. **延迟导入**：第三方驱动（如 ``pymongo``）只在函数体内 import，且本模块**不被
+   ``alpha101v/__init__.py`` 导入** ⇒ ``import alpha101v`` 永远不会拉进它们
+   （由 ``tests/test_provenance.py::test_runtime_import_is_minimal`` 机械守门）；
+2. **不做隐式插值**：缺数据就是 NaN，需要前向填充必须由调用方显式开关并写清理由。
+
+子模块
+------
+* :mod:`alpha101v.adapters.mongo` —— 本地 MongoDB（``quantaxis``）→ §7.4 面板契约；
+* :mod:`alpha101v.adapters.industry` —— 申万 as-of 成员 → **PIT 行业标签面板**
+  （DataFrame 形态，正是 :func:`alpha101v.neutralize.ind_neutralize` 支持的逐日口径）。
+"""
+
+__all__: list[str] = []

alpha101v/adapters/adjust.py

@@ -0,0 +1,224 @@
+"""价格复权（除权除息）——**PIT 安全**版本。
+
+为什么必须有这一层
+------------------
+``stock_day`` 是**原始价**：除权除息当天价格会「跳空」（送转股/派现），
+这不是亏损却会被算成收益率暴跌。实测样例（000153，2024-06-07，每 10 股送 4 股 + 派 1.5 元）::
+
+    前收 7.74 → 当日收 5.61   ⇒ 原始收益率 −27.5%（假信号）
+
+本模块按「除权除息参考价」口径复权，把该跳空抹平（同一例复权收益率 +3.5%）。
+
+口径（实证确定，2026-10-09）
+--------------------------
+``stock_xdxr`` 的 ``fenhong`` / ``songzhuangu`` / ``peigu`` 是 **每 10 股**口径
+（用 6 个真实案例反推参考价，与当日实际收盘的相对误差 0.6%~3.9%；按「每股」解释则偏 44%~85%）::
+
+    R = (C_prev − fenhong/10 + (peigu/10)·peigujia) / (1 + songzhuangu/10 + peigu/10)
+
+累计因子 ``F_t = Π_{e ≤ t} (C_prev,e / R_e)``（≥1，随时间增长）。
+
+**两种模式与它们的关键差别**
+
+* ``hfq``（**本库默认**）：把 ``F`` 归一化到面板**第一行 = 1**（早期价不动、后期价上调）。
+  因子只依赖**过去**的除权事件 ⇒ **因果/PIT 安全**，能通过时间截断一致性检验；
+* ``qfq``：把 ``F`` 归一化到**最后一行 = 1**（最新价与原始价一致，便于人工核对）。
+  它让**全部历史价格**都依赖**未来**的除权事件 ⇒ 全样本 qfq 存在前视
+  （``docs/verification.md`` §1.3 的已知限制之一），**仅供展示/回测取价，不用于因子计算**。
+
+两者只差每只股票一个**常数**缩放，因此对 `rank` 型因子无影响，但对跨股**水平型**比较
+（如 `alpha41 = sqrt(high·low) − vwap`）会有差异——这正是必须显式选一种口径的原因。
+
+不做什么
+--------
+* 不改 ``volume`` / ``amount``（成交量额是交易数量，不是价格）；
+* 不改 ``cap``（市值口径由调用方声明，见歧义 A19）；
+* 不做隐式填充（缺前收的事件跳过并计数，由调用方决定）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+import pandas as pd
+
+__all__ = [
+    "ADJUST_MODES",
+    "PRICE_FIELDS",
+    "adjust_price_panels",
+    "cumulative_factors",
+    "load_xdxr_events",
+    "reference_price",
+]
+
+#: 允许的复权模式：``none`` 不复权；``hfq`` 后复权（因果，默认）；``qfq`` 前复权（非因果，仅供展示）。
+ADJUST_MODES: tuple[str, ...] = ("none", "hfq", "qfq")
+
+#: 需要按同一因子缩放的价格类字段（``vwap`` 是价格，必须一起缩放，否则 `close − vwap` 失去意义）。
+PRICE_FIELDS: tuple[str, ...] = ("close", "Open", "high", "low", "vwap")
+
+#: 影响价格连续性的 xdxr 类别（1 = 除权除息）；其余类别（股本变化/送配股上市…）不影响价格。
+XDXR_PRICE_CATEGORY = 1
+
+_XDXR_FIELDS = ("fenhong", "songzhuangu", "peigu", "peigujia")
+
+
+def reference_price(
+    prev_close: float, fenhong: float, songzhuangu: float, peigu: float, peigujia: float
+) -> float:
+    """除权除息参考价 ``R``（字段按**每 10 股**解释）。
+
+    ``R = (C_prev − fenhong/10 + (peigu/10)·peigujia) / (1 + songzhuangu/10 + peigu/10)``
+
+    返回 ``nan`` 表示该事件无法定价（前收非正、R 非正），调用方应跳过。
+    """
+    if not np.isfinite(prev_close) or prev_close <= 0:
+        return float("nan")
+    dividend = (0.0 if fenhong is None else float(fenhong)) / 10.0
+    bonus = (0.0 if songzhuangu is None else float(songzhuangu)) / 10.0
+    rights = (0.0 if peigu is None else float(peigu)) / 10.0
+    rights_price = 0.0 if peigujia is None else float(peigujia)
+    denominator = 1.0 + bonus + rights
+    if denominator <= 0:
+        return float("nan")
+    ref = (prev_close - dividend + rights * rights_price) / denominator
+    return float(ref) if ref > 0 else float("nan")
+
+
+def load_xdxr_events(
+    codes: Iterable[str],
+    start: str,
+    end: str,
+    *,
+    uri: str = "mongodb://127.0.0.1:27017",
+    database: str = "quantaxis",
+    collection: str = "stock_xdxr",
+    category: int = XDXR_PRICE_CATEGORY,
+    chunk_size: int = 200,
+) -> pd.DataFrame:
+    """读取区间内的除权除息事件（只读；``pymongo`` 延迟导入）。
+
+    返回列：``code, date, fenhong, songzhuangu, peigu, peigujia``（缺失字段按 0 处理）。
+    """
+    try:
+        import pymongo  # 延迟导入：不进运行时依赖
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError("读取 xdxr 需要 pymongo：pip install 'alpha101v[mongo]'") from exc
+
+    codes = sorted({str(code) for code in codes})
+    if not codes:
+        raise ValueError("codes 不能为空")
+
+    client = pymongo.MongoClient(uri, serverSelectionTimeoutMS=5000)
+    try:
+        coll = client[database][collection]
+        frames: list[pd.DataFrame] = []
+        for offset in range(0, len(codes), chunk_size):
+            batch = codes[offset : offset + chunk_size]
+            cursor = coll.find(
+                {"code": {"$in": batch}, "category": category, "date": {"$gte": start, "$lte": end}},
+                {"_id": 0, "code": 1, "date": 1, **{f: 1 for f in _XDXR_FIELDS}},
+            )
+            frames.append(pd.DataFrame(list(cursor)))
+    finally:
+        client.close()
+
+    if not frames or all(frame.empty for frame in frames):
+        return pd.DataFrame(columns=["code", "date", *_XDXR_FIELDS])
+
+    events = pd.concat(frames, ignore_index=True)
+    events["date"] = pd.to_datetime(events["date"])
+    for field in _XDXR_FIELDS:
+        if field not in events.columns:
+            events[field] = np.nan
+        events[field] = pd.to_numeric(events[field], errors="coerce")
+    return events.sort_values(["date", "code"], ignore_index=True)
+
+
+def cumulative_factors(
+    close: pd.DataFrame,
+    events: pd.DataFrame,
+    *,
+    mode: str = "hfq",
+    anchor_date=None,
+) -> pd.DataFrame:
+    """累计复权因子面板（与 ``close`` 同形，逐股票取值）。
+
+    * 事件日若不是交易日，映射到**该日或之后第一个交易日**（用 ``searchsorted``）；
+    * **前收取「该事件日之前最后一个非 NaN 的收盘」**（跳过停牌）——修 bug A：
+      原实现用 ``series.iloc[position-1]``，若中间有停牌（NaN）会把除权事件**静默当成 1.0**，
+      导致「同一股票单独请求 vs 与别人一起请求」结果不同；
+    * ``anchor_date`` 给定时，**该日期的因子被归一为 1**，且结果**与请求窗口/批次无关**（修 bug B）；
+      调用方应传入固定的 ``ref_date``（锚从哪来是调用方的事：库只保证「给定锚，算得对」）；
+    * 未给 ``anchor_date`` 时保留历史语义：``hfq`` 归一化到面板**首行** = 1（因果，但**依赖窗口**）、
+      ``qfq`` 归一化到**末行** = 1（非因果，仅供展示）。跨窗口复现请显式传 ``anchor_date``。
+    """
+    if mode not in ADJUST_MODES:
+        raise ValueError(f"mode 只接受 {ADJUST_MODES}，收到 {mode!r}")
+    if mode == "none":
+        return pd.DataFrame(1.0, index=close.index, columns=close.columns)
+
+    factors = pd.DataFrame(1.0, index=close.index, columns=close.columns)
+    if events is None or events.empty:
+        return factors
+
+    for code, group in events.groupby("code", sort=False):
+        if code not in close.columns:
+            continue
+        series = close[code]
+        if series.notna().sum() == 0:
+            continue
+        multipliers: list[tuple[int, float]] = []
+        for row in group.itertuples(index=False):
+            position = int(series.index.searchsorted(row.date))
+            if position <= 0 or position >= len(series):
+                continue  # 面板首行或窗口之外：无前收，跳过
+            # 修 bug A：向前找「事件日之前最后一个非 NaN 的收盘」（跳过停牌/缺数据）
+            prior = series.iloc[:position].dropna()
+            if prior.empty:
+                continue
+            prev_close = prior.iloc[-1]
+            ref = reference_price(
+                prev_close, row.fenhong, row.songzhuangu, row.peigu, row.peigujia
+            )
+            if not np.isfinite(ref):
+                continue
+            multipliers.append((position, float(prev_close) / ref))
+
+        if not multipliers:
+            continue
+        column = np.ones(len(series), dtype=float)
+        for position, ratio in multipliers:
+            column[position:] *= ratio
+        factors[code] = column
+
+    if anchor_date is not None:
+        # 显式锚：该日期因子归一为 1 ⇒ 结果与窗口/批次无关（修 bug B）
+        anchor = pd.Timestamp(anchor_date)
+        if anchor not in factors.index:
+            position = int(factors.index.searchsorted(anchor))
+            position = min(max(position, 0), len(factors.index) - 1)
+            anchor = factors.index[position]
+        row = factors.loc[anchor].replace(0.0, np.nan)
+        factors = factors.div(row, axis=1).fillna(1.0)
+    elif mode == "qfq":
+        tail = factors.iloc[-1].replace(0.0, np.nan)
+        factors = factors.div(tail, axis=1).fillna(1.0)
+    return factors
+
+
+def adjust_price_panels(
+    panels: dict[str, pd.DataFrame],
+    factors: pd.DataFrame,
+    *,
+    price_fields: Sequence[str] = PRICE_FIELDS,
+) -> dict[str, pd.DataFrame]:
+    """按累计因子缩放价格类字段，返回**新字典**（不修改入参）。"""
+    adjusted = dict(panels)
+    for field in price_fields:
+        if field in adjusted:
+            adjusted[field] = adjusted[field].reindex(
+                index=factors.index, columns=factors.columns
+            ) * factors
+    return adjusted

alpha101v/adapters/industry.py

@@ -0,0 +1,130 @@
+"""申万行业 as-of 成员 → **PIT 行业标签面板**（可选适配层）。
+
+数据源（设计文档 §10.2 指定）
+----------------------------
+``/home/yinxiuqu/quantming/data/sw_industry/members.parquet``（覆盖约 98.4%）::
+
+    index_code  level  src     con_code  in_date     out_date  is_new  iface
+    801010.SI   L1     SW2021  000019    2021-12-13  NaT       Y       index_member
+
+``out_date`` 为 ``NaT`` 表示**仍在成分内**。另有 ``classify.parquet`` 提供
+``index_code → industry_name``（中文名），本模块可选地用它把标签换成人可读的名称。
+
+**为什么必须是 as-of**：原始 GPL 仓库用的是「固定 2017-01 快照」（设计文档 §3.3 缺陷 5），
+那等于把未来信息灌进历史因子。本模块按 ``(交易日, 股票)`` 取 **``in_date <= t`` 且
+(``out_date`` 为空或 ``> t``)** 的最近一次成分记录，构造 ``ind`` 面板——这正是
+:func:`alpha101v.neutralize.ind_neutralize` 支持的逐日 DataFrame 形态。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+__all__ = ["coverage_of", "load_sw_industry", "load_sw_industry_names"]
+
+DEFAULT_MEMBERS = "/home/yinxiuqu/quantming/data/sw_industry/members.parquet"
+DEFAULT_CLASSIFY = "/home/yinxiuqu/quantming/data/sw_industry/classify.parquet"
+
+
+def load_sw_industry_names(classify_path: str | Path = DEFAULT_CLASSIFY) -> dict[str, str]:
+    """``index_code → industry_name``（中文名，便于人工核对与文档展示）。"""
+    classify = pd.read_parquet(classify_path)
+    required = {"index_code", "industry_name"}
+    missing = required - set(classify.columns)
+    if missing:
+        raise KeyError(f"classify.parquet 缺少列 {sorted(missing)}；实际 {sorted(classify.columns)}")
+    return dict(zip(classify["index_code"], classify["industry_name"], strict=False))
+
+
+def load_sw_industry(
+    dates: Iterable[pd.Timestamp],
+    codes: Iterable[str],
+    *,
+    members_path: str | Path = DEFAULT_MEMBERS,
+    classify_path: str | Path | None = DEFAULT_CLASSIFY,
+    level: str = "L1",
+    src: str = "SW2021",
+    use_names: bool = True,
+) -> pd.DataFrame:
+    """构造 PIT 行业标签面板（``index``=交易日, ``columns``=股票代码）。
+
+    规则（显式，全部可测）：
+
+    1. 只取 ``level`` / ``src`` 匹配的成分记录；
+    2. 对每个 (交易日, 股票)，取 **``in_date <= 交易日``** 的最近一条（``merge_asof`` backward）；
+    3. 若该条的 ``out_date`` 非空且 ``<= 交易日`` ⇒ 已调出，标签置 ``NaN``；
+    4. 同一 (交易日, 股票) 命中多条（数据里同一 ``in_date`` 多行业）时，按
+       ``index_code`` 升序取第一条 —— **确定性的显式策略**，不随机；
+    5. 没有任何成分记录的格子为 ``NaN``（覆盖率缺口，不下沉填充——行业标签无法插值）。
+    """
+    dates = pd.DatetimeIndex(sorted(pd.DatetimeIndex(dates).unique()))
+    codes = [str(code) for code in codes]
+    if len(dates) == 0 or not codes:
+        raise ValueError("dates 与 codes 都不能为空")
+
+    members = pd.read_parquet(members_path)
+    required = {"index_code", "level", "src", "con_code", "in_date", "out_date"}
+    missing = required - set(members.columns)
+    if missing:
+        raise KeyError(f"members.parquet 缺少列 {sorted(missing)}；实际 {sorted(members.columns)}")
+
+    members = members[(members["level"] == level) & (members["src"] == src)].copy()
+    members = members[members["con_code"].astype(str).isin(codes)]
+    members["con_code"] = members["con_code"].astype(str)
+    members["in_date"] = pd.to_datetime(members["in_date"])
+    members["out_date"] = pd.to_datetime(members["out_date"])
+
+    label_column = "index_code"
+    if use_names and classify_path is not None and Path(classify_path).exists():
+        names = load_sw_industry_names(classify_path)
+        members["label"] = members["index_code"].map(names).fillna(members["index_code"])
+        label_column = "label"
+    else:
+        members["label"] = members["index_code"]
+
+    # merge_asof 要求**按 on-key 全局有序**（by 分组内自然随之有序）：
+    # 左表按 (date, code) 排、右表按 (in_date, con_code) 排。
+    members = members.sort_values(["in_date", "con_code", "index_code"], ignore_index=True)
+
+    grid = pd.MultiIndex.from_product([dates, codes], names=["date", "code"]).to_frame(index=False)
+    grid = grid.sort_values(["date", "code"], ignore_index=True)
+
+    merged = pd.merge_asof(
+        grid,
+        members[["con_code", "in_date", "out_date", label_column]].rename(
+            columns={"con_code": "code"}
+        ),
+        left_on="date",
+        right_on="in_date",
+        by="code",
+        direction="backward",
+    )
+
+    active = merged["out_date"].isna() | (merged["out_date"] > merged["date"])
+    merged = merged[active]
+    merged = merged.drop_duplicates(["date", "code"], keep="first")
+
+    labels = merged.pivot(index="date", columns="code", values=label_column)
+    labels = labels.reindex(index=dates, columns=codes)
+    labels.index.name = None
+    labels.columns.name = None
+    coverage = float(labels.notna().to_numpy().mean())
+    if coverage == 0.0:
+        raise ValueError(
+            f"行业覆盖率 0：level={level} src={src} 下没有任何 (date, code) 命中；"
+            "请检查成分表与股票代码格式（如 000001 vs 000001.SZ）"
+        )
+    labels.attrs["coverage"] = coverage
+    labels.attrs["level"] = level
+    labels.attrs["src"] = src
+    return labels
+
+
+def coverage_of(labels: pd.DataFrame) -> float:
+    """辅助：行业标签覆盖率（``0~1``）。"""
+    values = labels.to_numpy()
+    return float(np.mean(~pd.isna(values)))