alpha101-verified · 一份「可验证的 Alpha101」

本项目卖的不是 101 个公式，而是「凭什么说它们算对了」。 生态里不缺 Alpha101 的实现，缺的是正确性证据：算子口径对拍、golden 基准、 前视/不变量检验、与论文的偏差清单、以及诚实标注「哪几个我也验不了」。

为什么做这个

结论：「能不能算」已经有人免费给了；「算得对不对」是生态真空白。

本仓库因此从公开论文 clean-room 重写（不修复、不 fork 那个 GPL 仓库）， 把 vnpy（MIT）当测试期差分对拍参照，交付「可验证」三件套： ① 口径可判定 ② 证据可复现 ③ 验不了的如实标注。

许可证边界（设计文档 §5.3）： QAFactor_Alpha101（GPL-3.0）只被允许本地跑数值对比，其代码一行都不进本仓库； vnpy（MIT）仅作测试期参照并署名；运行时依赖只有 numpy / pandas / scipy。

快速开始

第一次用？看 docs/usage.md（安装 → 五分钟上手 → 字段不够怎么办 → 口径 → 自查 → 性能 → 常见问题），并可直接跑 python examples/hello_alpha101.py（合成面板，不需要数据库）。

PY=/home/yinxiuqu/anaconda3/envs/qa/bin/python     # Python 3.11 / pandas 2.3.3

$PY -m pytest -q                                   # 全量（含变异测试，约 15~20 分钟；早期算子层闸门才是 2~3 分钟）
$PY -m pytest tests/test_operators.py -q           # M1 闸门：算子层 20/20
$PY -m pytest tests/test_mutation.py -q            # 变异测试：7/7 注入必须被抓住

import pandas as pd
from alpha101v import rank, scale, decay_linear, ind_neutralize

# 面板契约：index = 交易日（升序唯一），columns = 股票代码
factor = decay_linear(rank(close), 5)          # 截面 rank 默认 pct=True（(0,1]）
daily  = scale(factor, k=1.0)                  # 每日 Σ|x| = 1（axis=1）
resid  = ind_neutralize(factor, industry)      # 逐日组内去均值 = 行业哑变量 OLS 残差

无需安装（conftest.py 会把 src/ 加进 sys.path）；如需安装：pip install -e .[test]。

验证套件：六层协议现在走到哪

判据（设计文档 §6.8）：六条门槛全满足才可标 verified；缺任一条标 partial/ambiguous。

终态：verified 82/101、partial 19/101、ambiguous 0。 19 个 partial 全部是 「vnpy 未实现 ⇒ 无第三方参照 ⇒ 门槛 3（必需）原理上不可满足」的因子 （18 个含 IndNeutralize + alpha56 需 cap），备注里逐条写明缺哪条、为什么。 设计文档 §6.8 的诚实预期是「verified 不可能是 101/101，预估 60~80」，实测 82。

一页复现（每条声明都能自己跑出来）

python -m pytest -q                                  # 697 项全绿（约 22 分钟）

python tools/conformance_report.py                   # L2：期望「等价 101（共 101 个因子）」
python tools/conformance_report.py --table           # 101 行偏差清单（docs/deviations.md §4 由此生成）

bash tools/fetch_vnpy_reference.sh                   # L3：抓 vnpy 参照（SHA256 固定，进 gitignored 的 .vnpy-ref/）
python tools/differential.py                         #      算子层 27 项：19 一致 + 8 已归因 + 0 待查
python tools/factor_differential.py                  #      因子层 82 个可比因子：64 一致 + 18 已归因 + 0 待查

python tools/golden_snapshot.py --check              # L5：与冻结基线比对（NaN 模式 + 数值）
python -m pytest tests/test_golden.py -q             #      5 项

python tools/real_panel_smoke.py --n-codes 120       # 真实 A 股端到端（需本地 MongoDB）

python -m pytest tests/test_mutation.py -q           # 8 个已知 bug 注入必须全部被抓住

⚠️ BRAIN 官方算子文档不在仓库里（登录墙内的专有文档，refs/ 已 gitignore）。 要复核 L-B 结论（ts_decay_linear 方向、ts_arg_max 基准、^ 的 power/signed_power、 rank/ts_rank 归一化、ts_std_dev 的 ddof），需要你自己的会话：登录后 GET https://api.worldquantbrain.com/operators（列表）与 GET /operators/{name}（完整正文， 即页面 Show more 的内容）。所有引文与结论都写在 docs/operators.md §3.13 —— 即使拿不到文档，也能看到「依据什么、选择了什么、漏在哪」。

证据索引（每个声明都指向一个可复现的命令）

仓库结构

alpha101-verified/
├── LICENSE                     # MIT
├── README.md
├── pyproject.toml              # 运行时依赖仅 numpy/pandas/scipy
├── conftest.py                 # 让 src 布局免安装可导入
├── docs/
│   ├── Alpha101_修复发布决策与验证协议_v0.1.md   # 设计依据（内容版本 v0.2）
│   ├── operators.md            # ★ 算子口径唯一权威（含歧义点决策 + 4 条文档勘误 + 论文核对回写）
│   ├── paper_formulas.md       # ★ 论文规范入库：101/101 条公式逐字（括号平衡校验 0 不平衡）
│   ├── usage.md              # ★ 使用指南（给第一次用的人）
│   ├── verification.md         # 六层协议与验证结果矩阵
│   ├── ambiguities.md          # 规范歧义清单（已决策 / 待决 / 无法判定）
│   └── deviations.md           # 与论文/GPL 原实现的偏差清单（101 行清单 M3 生成）
├── src/alpha101v/
│   ├── operators.py            # 17 个算子（纯函数，DataFrame→DataFrame）
│   ├── neutralize.py           # 3 个中性化算子（向量化，无矩阵求逆）
│   ├── panel.py                # 面板契约与校验（M0）
│   ├── registry.py             # 因子注册与按形参名自动装配（§7.5；表为空 = 尚无因子）
│   └── adapters/               # 数据适配（可选层，**延迟导入**驱动；不污染运行时依赖）
│       ├── mongo.py            # MongoDB(quantaxis) → §7.4 面板（vol→volume、vwap=amount/(vol*100)）
│       └── industry.py         # 申万 as-of 成员 → **PIT 行业标签面板**（逐日，非固定快照）
├── tests/
│   ├── test_operators.py       # §8 全部用例：A 组 / B 组 / 中性化组（54 个）
│   ├── test_invariants.py      # §6.5 不变量（129 个）
│   ├── test_panel.py           # 面板契约（13 个）
│   ├── test_registry.py        # 自动装配机制（10 个）
│   ├── test_provenance.py      # 许可/依赖机械守卫（5 个）
│   ├── test_mutation.py        # 变异测试（8 个：7 注入 + 1 勘误钉死）
│   ├── test_elemwise.py        # 逐元素层（abs/log/sign/signedpower）
│   ├── test_factors.py         # 5 个试点因子：封闭解 / 独立第二实现 / L2 结构 / L4 不变量
│   ├── test_differential.py    # vnpy 算子层差分包装（参照缺失自动跳过）
│   ├── test_adapters_real_data.py  # 真实 A 股数据端到端（无数据库时跳过）
│   └── golden/                 # golden 快照（5×320 冻结基线 + sha256 + 环境版本，已接 CI）
├── tools/
│   ├── conformance_report.py   # ★ 规范对照：论文公式 ↔ 实现 AST（算子/字段/字面量），生成偏差清单
│   ├── differential.py         # ★ 算子层差分对拍（本库 vs vnpy MIT），退出码即证据
│   ├── fetch_vnpy_reference.sh # 下载参照源码到 gitignored 的 .vnpy-ref/（含 SHA256 校验）
│   └── README.md               # conformance_report.py 待 M3
└── .github/workflows/ci.yml    # pandas 2.1/2.2/2.3 矩阵 + 算子闸门 + 变异步骤

与设计文档 §7.2 的结构对照（截至 v0.1.1，已全部补齐）： src/alpha101v/factors.py（101 个因子）、tests/golden/（冻结基线）、tools/*.py（规范对照、 算子层与因子层差分、golden 快照、第二参照差分、发布前安全确认等）均已就位。 §7.2 里的 test_edge_cases.py / test_conformance.py 未单独立文件，而是并入 test_operators.py（NaN/inf/停牌/新股的边界用例）、test_invariants.py（脏数据三连） 与 test_panel.py（面板契约）——覆盖等价，只是不按文件名一一对应。 §7.2 中的 test_edge_cases.py（NaN/inf/停牌/新股）目前在 test_operators.py:test_a26、 test_invariants.py（脏数据三连）与 test_panel.py 里已覆盖算子层部分。

路线图

⚠️ 设计文档 §7.7 的提醒照抄在此：不要一上来做 M3。口径（复权/单位/PIT/算子） 一旦有问题，拿 101 个因子做一次大规模错误实验会全部返工。

归属与许可

• 本仓库代码：MIT（见 LICENSE）。
• 规范来源：Zura Kakushadze, 101 Formulaic Alphas, Wilmott Magazine 2016(84):72–80， arXiv:1601.00991。该论文不是 WorldQuant 官方标准， 且 WorldQuant 未开源任何因子代码——「正确」只能定义为「与所选规范一致」。
• 差分对拍参照：vnpy（MIT）的 alpha_101.py 与 {cs,ts,ta}_function.py。仅用于测试期对拍（下载到 gitignored 的 .vnpy-ref/，不进仓库）。署名与许可声明见 docs/verification.md §1.2/§1.5 与 tools/README.md；另有第二参照 alpha101-pipeline（MIT， 独立 venv）用于 19 个 partial 因子的对拍，见 docs/verification.md §1.12。
• clean-room 声明：本仓库从公开论文与数学定义独立实现。被分析的 GPL-3.0 仓库 （QAFactor_Alpha101）代码从未被打开或拷贝；其 README 的中文注释表仅用于理解经济含义 （注释与分类不构成代码表达）。tests/test_provenance.py 用机械扫描守住这条纪律。