Qust Docs

Alpha 命名空间 / alpha.py

alpha.alphalen_analysis

用于因子研究和 AlphaLen 分析链路，把因子值、未来收益、分位数组合、IC 诊断和 Monitor 面板串成同一套表达式。

接口示例returns: Expralpha

输入 / 输出

输入

按下表列名和类型准备输入。

输入项类型示例
datetimeDatetime2026-01-01 09:30:00
codeStringAAA
alphaFloat64-0.5
retFloat640.0

输出

项目说明
返回类型Expr
输出对象表达式/执行计划/配置对象
输出语义输出列由算子、alias 或底层实现决定；需要稳定列名时显式使用 alias。
执行方式先构造对象，再放入 DataSet、Monitor、UDF 或真实执行上下文。
核心调用col("datetime", "code", "alpha", "ret").alpha().alphalen_analysis(monitor)

打印输入 / 打印输出

下面内容来自本页示例代码真实执行后的 stdout，不是手写占位。

打印输入

print(data)
shape: (20, 4)
┌─────────────────────┬──────┬───────┬─────────┐
│ datetime            ┆ code ┆ alpha ┆ ret     │
│ ---                 ┆ ---  ┆ ---   ┆ ---     │
│ datetime[μs]        ┆ str  ┆ f64   ┆ f64     │
╞═════════════════════╪══════╪═══════╪═════════╡
│ 2026-01-01 09:30:00 ┆ AAA  ┆ -0.5  ┆ 0.0     │
│ 2026-01-01 09:31:00 ┆ BBB  ┆ 0.2   ┆ 0.02    │
│ 2026-01-01 09:32:00 ┆ CCC  ┆ -0.2  ┆ -0.0098 │
│ 2026-01-01 09:33:00 ┆ AAA  ┆ 0.5   ┆ 0.0396  │
│ 2026-01-01 09:34:00 ┆ BBB  ┆ 0.1   ┆ 0.019   │
│ …                   ┆ …    ┆ …     ┆ …       │
│ 2026-01-01 09:45:00 ┆ AAA  ┆ 0.1   ┆ 0.051   │
│ 2026-01-01 09:46:00 ┆ BBB  ┆ -0.3  ┆ -0.016  │
│ 2026-01-01 09:47:00 ┆ CCC  ┆ 0.4   ┆ 0.041   │
│ 2026-01-01 09:48:00 ┆ AAA  ┆ 0.0   ┆ 0.016   │
│ 2026-01-01 09:49:00 ┆ BBB  ┆ -0.4  ┆ 0.016   │
└─────────────────────┴──────┴───────┴─────────┘

打印输出

print(out)
shape: (4, 2)
┌────────────────┬─────────────────────────────────┐
│ 项目           ┆ 内容                            │
│ ---            ┆ ---                             │
│ str            ┆ str                             │
╞════════════════╪═════════════════════════════════╡
│ 调用           ┆ col("datetime", "code", "alpha… │
│ 返回类型       ┆ Expr                            │
│ 状态           ┆ 表达式构造完成                  │
│ 怎么得到业务表 ┆ 放进                            │
│                ┆ col(...).runtime().calc_dat…    │
└────────────────┴─────────────────────────────────┘

AlphaLen 图形诊断

alphalen_analysis 的目标不是输出单一收益数字，而是把一个因子的可交易性拆成几组可验证的问题：分位数是否单调、IC 是否稳定、收益是否集中在某个 horizon、异常收益是否由少数事件驱动。

AlphaLen factor analysis dashboard
AlphaLen 风格面板：分位数组合收益、IC 稳定性、分组收益和 horizon heatmap 同时展示，适合判断因子强度、衰减和风险集中度。

对齐收益

把 datetime、code、alpha 和未来 ret 对齐，确保因子只使用当时可见的信息。

截面分桶

每个交易时点按因子值分 quantile，保留 Q1 到 Q5 的样本，检查多空 spread 是否稳定。

统计诊断

同时计算 IC、分组收益、命中率、turnover 和 horizon 衰减，避免只看累计曲线。

Monitor 回查

图表中的异常区间可以继续回查样本明细，定位具体日期、标的、因子值和未来收益。

视图研究问题有效因子的典型信号
Quantile return高低分位是否产生稳定 spreadQ5 持续强于 Q1，且中间分位大体单调
IC series相关性是否稳定存在IC 均值为正，滚动均值不长期贴近 0
Horizon heatmap因子在什么持有周期衰减收益在目标 lead 附近集中，长短周期解释一致
Event drilldown收益是否由少数异常样本贡献剔除极端事件后结论仍然成立

调用

Python
col("datetime", "code", "alpha", "ret").alpha().alphalen_analysis(monitor)
参数类型默认值说明
monitorMonitor必填位置参数

完整代码

这个算子页使用接口示例：不伪造计算结果。需要真实上下文、多输入源、Monitor session、UDF 回调、策略状态，或当前底层实现之后再执行。
展开可复制完整代码
Python
import datetime as dt
import polars as pl
import qust as qs
from qust import col, pms

data = pl.DataFrame(
    {
        "datetime": ['2026-01-01 09:30:00', '2026-01-01 09:31:00', '2026-01-01 09:32:00', '2026-01-01 09:33:00', '2026-01-01 09:34:00', '2026-01-01 09:35:00', '2026-01-01 09:36:00', '2026-01-01 09:37:00', '2026-01-01 09:38:00', '2026-01-01 09:39:00', '2026-01-01 09:40:00', '2026-01-01 09:41:00', '2026-01-01 09:42:00', '2026-01-01 09:43:00', '2026-01-01 09:44:00', '2026-01-01 09:45:00', '2026-01-01 09:46:00', '2026-01-01 09:47:00', '2026-01-01 09:48:00', '2026-01-01 09:49:00'],
        "code": ['AAA', 'BBB', 'CCC', 'AAA', 'BBB', 'AAA', 'BBB', 'CCC', 'AAA', 'BBB', 'AAA', 'BBB', 'CCC', 'AAA', 'BBB', 'AAA', 'BBB', 'CCC', 'AAA', 'BBB'],
        "alpha": [-0.5, 0.2, -0.2, 0.5, 0.1, -0.3, 0.4, 0.0, -0.4, 0.3, -0.1, -0.5, 0.2, -0.2, 0.5, 0.1, -0.3, 0.4, 0.0, -0.4],
        "ret": [0.0, 0.02, -0.0098, 0.0396, 0.019, -0.028, 0.048, 0.018, -0.027, 0.046, 0.027, -0.017, 0.044, 0.017, -0.025, 0.051, -0.016, 0.041, 0.016, 0.016],
    }
).with_columns(pl.col("datetime").str.to_datetime())

pool = qs.DataPool("doc_pool")
monitor = qs.Monitor()
right = qs.DataSource("right")
schema = [("x", qs.dt.Float64)]
plot_expr = col("x")
df = col("x").runtime()

print("算子:")
print('alpha.alphalen_analysis')
print("场景:")
print('Alpha：截面信号分析和收益评估。')
print("模式:")
print('接口示例：只构造表达式或对象，不伪造计算结果。')
print("输入列:")
print('datetime, code, alpha, ret')
print("调用:")
print('col("datetime", "code", "alpha", "ret").alpha().alphalen_analysis(monitor)')
print("输入数据模板:")
print(data)
try:
    result = col("datetime", "code", "alpha", "ret").alpha().alphalen_analysis(monitor)
except BaseException as err:
    out = pl.DataFrame({
        "项目": ["调用", "状态", "错误类型", "错误信息"],
        "内容": ['col("datetime", "code", "alpha", "ret").alpha().alphalen_analysis(monitor)', "未执行成数据表", type(err).__name__, str(err)[:200]],
    })
    print("输出:")
    print(out)
else:
    out = pl.DataFrame({
        "项目": ["调用", "返回类型", "状态", "怎么得到业务表"],
        "内容": ['col("datetime", "code", "alpha", "ret").alpha().alphalen_analysis(monitor)', type(result).__name__, "表达式构造完成", "放进 col(...).runtime().calc_data(data)、col.with_cols(...).runtime().calc_data(data)，或对应 Monitor/DataSet 运行上下文。"],
    })
    print("输出:")
    print(out)

改成业务代码

改哪里怎么改
列名把示例 DataFrame 里的列名换成你的真实列名，列顺序保持和用法一致。
参数只改函数括号里的参数；不要随意改变 rolling/over/batch/select 的链式层级。
输出名需要稳定输出列名时，在表达式尾部加 .alias("name")。
调试先打印输入数据和调用字符串，再执行 calc_data；报 schema 错时先检查列数和 dtype。

注意事项

  • 先确认输入列名、顺序、类型和本页一致。
  • 输出列名不符合业务语义时，显式追加 .alias(...)。
  • 窗口和分组类算子要确认 rolling/expanding/over/batch 的链式层级。

来源

项目位置
源码文件alpha.py
类/对象AlphaNamespace