alpha101-pipeline

基于 DuckDB 的 A 股日内因子研究全流程工具链：公式引擎 → 因子存储 → 分层回测 → 可视化。 内置 WorldQuant 101 alpha 公式集，支持 IC 衰减 / 换手率诊断、组合级交易成本 + 净值回测。

安装

pip install alpha101-pipeline
# 带绘图功能：
pip install "alpha101-pipeline[plot]"
# 带测试 / 开发：
pip install "alpha101-pipeline[dev]"

命令一览

快速上手

# 1. 重排面板数据（按 datetime, code 排序，TIMESTAMP 类型，多行组）
alpha101-reorder --input raw.parquet --output panel_sorted.parquet

# 2. 计算因子存入 store
alpha101-store add \
  --source panel_sorted.parquet \
  --store data/factors \
  --formula mom_12='ts_mean(delta(close,1),12)' \
  --formula rev_12='ts_mean(delta(close,1),12) * -1'

# 3. 回测全部因子
alpha101-backtest \
  --store data/factors \
  --out-dir output/backtest \
  --forward 12 --groups 10

# 4. 绘制分层图
alpha101-plot batch \
  --returns-root output/backtest/series \
  --reports-dir output/backtest/reports \
  --out-dir output/backtest/plots

前向收益模式

日内回测支持两种前向收益计算方式：

# 默认：前向收益不跨日（避免隔夜跳空污染）
alpha101-backtest --store data/factors --out-dir output --forward 12 --groups 10

# 跨日 close-to-close 收益（适合长周期因子）
alpha101-backtest --store data/factors --out-dir output --forward 60 --groups 10 \
  --no-intraday-only

跨日模式的收益语义（等效持有期）：--no-intraday-only 下每日采样的是重叠的 N 日（--forward）前向收益。总收益、年化收益与净值曲线按每期等效收益 (1+r)^(1/N)-1 复利，年化波动按 std(r)·√(252/N) 折算——即一个每日 +1% 的市场会精确报告 1.01^252 的年化，而不会因重叠样本连乘放大 N 倍。

WorldQuant 101 alpha：计算 / 筛选 / 成本回测

# 1. 一键计算 101 alpha（自动只算面板列支持的；含 vwap/cap/industry 可算更多）
alpha101-compute --input panel_sorted.parquet --output alphas.parquet

# 只算指定 alpha；--rank-pct 用 [0,1] 分位 rank（WQ 原始量级，默认是 0..n-1 序号）
alpha101-compute --input panel_sorted.parquet --output alphas.parquet \
  --alphas 1,7,54,101 --rank-pct

# 2. 批量筛选：IC 衰减（多档 horizon）+ 换手率，按 |ICIR| 排名 -> screen.csv / screen.md
alpha101-screen --input panel_sorted.parquet --out-dir output/screen --horizons 1,5,10,20

# 3. 带交易成本的回测（cost-bps = 每单位换手率的单边成本，基点）
alpha101-backtest --store data/factors --out-dir output --forward 12 --groups 10 \
  --cost-bps 5

# A 股执行约束：停牌/涨跌停可交易过滤 + T+1 信号延迟 + 滑点
alpha101-backtest --store data/factors --out-dir output --forward 12 --groups 10 \
  --execution-policy ashare --limit-pct 0.1 --t-plus-one \
  --cost-bps 5 --slippage-bps 3

alpha101-backtest 在启用 series 时会写出 <factor>_nav.parquet（含 ls_gross / ls_net / nav_gross / nav_net），可由 alpha101-plot 绘制；报告 JSON 含 portfolio_turnover（真实多空组合换手）、rank_turnover_proxy（因子排名换手代理）、long_short（毛）与 long_short_net（扣成本）。

A 股约束参数包括 --execution-policy ashare、--t-plus-one、--volume-column、--prev-close-column、--limit-pct、--limit-reference {previous_bar,column}、--halt-on-zero-volume/--no-halt-on-zero-volume 与 --slippage-bps。如果有前一交易日收盘价列，使用 --limit-reference column --prev-close-column prev_daily_close 更贴近真实涨跌停判断。

低内存 / 受限设备优化

引擎全程 out-of-core（read_parquet + COPY 流式，DuckDB 超出 RAM 自动 spill 到临时盘），并对低内存机器提供一组可组合的开关。内存紧张时一行搞定：

alpha101-compute --input panel_sorted.parquet --output alphas.parquet --low-memory

--low-memory 是聚合预设，等价于 --dtype float32 --chunked always（engine 入口再加 --exclude-input-columns）；显式传的参数仍优先。也可按需单独开启：

注：--memory-limit 设得过低（低于 DuckDB 运行下限）反而会 OOM——给到几百 MB 以上让其有 spill 余地。临时 spill 目录在进程退出时自动清理。

Python API

from alpha101_pipeline import BacktestConfig, ExecutionPolicy, FactorStore, run_intraday_multi
from pathlib import Path

# 计算因子
store = FactorStore(Path("data/factors"))
store.add_factors(
    [("mom_12", "ts_mean(delta(close,1),12)")],
    source=Path("panel_sorted.parquet"),
)

# 回测
reports = run_intraday_multi(
    store.store_dir,
    ["mom_12"],
    source_panel=Path("panel_sorted.parquet"),
    factor_files={"mom_12": store.factor_path("mom_12")},
)

# 统一配置 + 可交易规则 + 信号延迟（单因子、多因子入口都支持）
from alpha101_pipeline.backtest_a_share import ashare_constraints_sql

policy = ExecutionPolicy(
    tradable_mask_sql=ashare_constraints_sql(
        volume_col="volume",
        price_col="close",
        id_col="code",
        date_col="datetime",
        halt_on_zero_volume=True,
    ),
    signal_lag=1,  # T+1：信号下一 bar 执行，执行 bar 也必须可交易
)
config = BacktestConfig(
    forward_period=12,
    num_groups=10,
    intraday=True,
    bars_per_day=48,
    transaction_cost=0.0005,
    execution_policy=policy,
)
reports = run_intraday_multi(
    store.store_dir,
    ["mom_12"],
    execution_policy=config.execution_policy,
    forward_period=config.forward_period,
    num_groups=config.num_groups,
    bars_per_day=config.bars_per_day,
    transaction_cost=config.transaction_cost,
    source_panel=Path("panel_sorted.parquet"),
    factor_files={"mom_12": store.factor_path("mom_12")},
)

# 跨日前向收益（默认 intraday_only=True 只计算日内收益）
reports = run_intraday_multi(
    store.store_dir,
    ["mom_12"],
    forward_period=60,          # 跨日（超过 bars_per_day=48）
    bars_per_day=48,
    intraday_only=False,        # 允许 close-to-close 跨日收益
    source_panel=Path("panel_sorted.parquet"),
    factor_files={"mom_12": store.factor_path("mom_12")},
)

旧的 tradable_mask_sql / t_plus_one 参数仍兼容，但不能和 execution_policy 同时传入。

# 计算 101 alpha + 批量筛选（IC 衰减 / 换手率 / 排名）
from alpha101_pipeline.formulas import compute_alphas
from alpha101_pipeline.screen import screen_alphas
from alpha101_pipeline.backtest import compute_ic_decay, compute_turnover

compute_alphas(Path("panel_sorted.parquet"), Path("alphas.parquet"))          # 自动选择可算的 alpha
df = screen_alphas(Path("panel_sorted.parquet"), Path("output/screen"),       # -> screen.csv
                   horizons=[1, 5, 10, 20])

# 单因子诊断：IC 衰减曲线 + 换手率
decay = compute_ic_decay(panel, None, "mom_12", "datetime", "code", None, [1,5,10], "close")
turnover = compute_turnover(panel, None, "mom_12", "datetime", "code", None)

支持的函数

时序窗口函数（PARTITION BY 股票 ORDER BY 日期）

截面函数（PARTITION BY 日期）

分组函数（PARTITION BY 日期 + 分组列）

数学函数（标量）

工具函数

不支持的函数（递归/状态型，无法用纯 SQL 表达）

ema, rsi, macd, atr, roc, obv, cci, mfi

运算符

小数窗口：时序函数的窗口 d 接受小数（Kakushadze 调优常数，如 3.43976），按四舍五入取整。 log(≤0)、sqrt(<0) 返回 NULL（不产生 inf/NaN 污染）。

回测输出指标

许可证

MIT