Alphalens · tear sheet 报告
Alphalens tear sheet：7 个报告函数各自输出什么、先跑哪个
tear sheet 是 Alphalens 的交付物形态：把收益、信息系数、换手三段分析拼成一组图表。库里有 7 个现成入口，从一页摘要到事件研究都有。这一页把 7 个函数的分工、报告里每块图在说什么，以及官方示例现在的真实状态讲清楚。
Alphalens 的一份 tear sheet 由什么组成
Returns分位收益 · 多空价差 · 累计收益
InformationIC 时序 · 分布 · 分组 · 月热力图
Turnover分位换手 · rank 自相关
Tables统计表 · 分位统计 · alpha/beta
tears.py 与 plotting.py 的函数组成整理（非官方图）；实际每份报告包含的图以源码为准。Functions
Alphalens 的 7 个 tear sheet 函数分别管什么
7 个函数都来自 tears.py，参数不多但用途差别很大。下表按函数整理，每一行都能在源码里核对。
| 函数 | 输出什么 | 适合什么时候用 | 代价 | 注意点 |
|---|---|---|---|---|
create_summary_tear_sheet | 收益、信息、换手三段的精华版 | 快速过一遍某个因子，或自动化批量跑多个因子 | 图少、信息密度低，不适合深读 | 适合做筛选，不适合写研究报告的正文 |
create_returns_tear_sheet | 分位收益、多空价差、累计收益与分位统计 | 只想回答「分层收益有没有区分度」 | 图中等 | 可配 long_short / group_neutral，口径要写进记录 |
create_information_tear_sheet | IC 时序、分布、QQ 图、分组 IC、月度热力图与 IC 表 | 判断因子的方向性与稳定性 | 图较多 | 分组 IC 需要提供 groupby，否则没有分组维度 |
create_turnover_tear_sheet | 分位换手表、最高/最低分位换手曲线、rank 自相关 | 评估调仓成本与排序稳定性 | 图少但这条路径最容易报错 | 公开 issue #341 / #377 记录了该函数的报错；可退回手工算再画 |
create_full_tear_sheet | 上述三段全量拼合 | 完整记录一次因子评估 | 图最多、渲染最慢 | 官方 README 的示例就用它；脚本环境需显式指定绘图后端 |
create_event_returns_tear_sheet | 事件发生前后若干期的平均累计收益 | 研究事件类因子（公告、财报等） | 需要额外传 returns 与 avgretplot | 与常规因子报告的读法不同：看的是事件窗口曲线形状 |
create_event_study_tear_sheet | 事件研究专用报告（含收益率与 K 线柱数参数） | 事件冲击的形态研究 | 参数更多：rate_of_ret、n_bars | examples 里有对应 notebook，但官方 issue #355 报告教程已跑不通 |
Reading
Alphalens 报告里每一块图在说什么
同一张 tear sheet 里的图分属三类分析，读的顺序应该与研究的推理顺序一致：先看有没有区分度，再看稳不稳定，最后看成本。
| 区块 | 包含的图 / 表 | 先看什么 | 异常长什么样 | 异常时的下一步 |
|---|---|---|---|---|
| 分位统计 | plot_quantile_statistics_table | 各分位的样本数量是否均衡 | 某一分位样本明显少，或缺失 | 检查因子分布与 zero_aware 设置，必要时改用 bins |
| 收益分析 | 分位收益柱状图、小提琴图、累计收益、价差时序、alpha/beta 表 | 分位柱状是否成阶梯 | 柱状无明显方向，或中间分位反号 | 做行业中性化与持有期敏感性检查 |
| 信息分析 | IC 时序、IC 直方图、IC QQ 图、分组 IC、月度热力图、IC 表 | IC 均值的符号与滚动均值方向 | IC 均值接近 0 或正负比例各半 | 换持有期或换因子定义，别硬调参数 |
| 换手分析 | 分位换手表、最高/最低分位换手曲线、rank 自相关 | 换手曲线的量级 | 换手接近 1（每期几乎全换） | 拉长 period 或降低调仓频率 |
| alpha/beta 表 | plot_returns_table | beta 是否显著不为 0 | beta 高，说明因子只是市场暴露的代理 | 做中性化后重跑，并核对样本期 |
读图顺序建议：分位统计 → 分位收益 → IC → 换手 → alpha/beta。这个顺序对应「数据够不够 → 有没有区分度 → 稳不稳定 → 成本高不高 → 是不是别的东西的代理」五问，跳着读容易得出片面结论。
Steps
Alphalens 跑出第一份 tear sheet 怎么做：四步
每一步给出代码与预期输出。第 4 步是脚本环境的常见坑：不指定后端时图可能出不来。
拿到 factor_data
factor_data = alphalens.utils.get_clean_factor_and_forward_returns(factor, prices, quantiles=5, periods=(1, 5, 10))。预期：返回带分位与各期收益列的多重索引表（详见「因子输入」页）。先跑摘要报告
alphalens.tears.create_summary_tear_sheet(factor_data)。预期：输出收益、信息、换手三段的精简版；先看分位柱状与 IC 均值，决定要不要继续深读。再跑全量报告
alphalens.tears.create_full_tear_sheet(factor_data)。预期：输出完整的图组。如果这一步慢，是因为图多，不是卡死。脚本环境：显式指定后端
在无界面环境里加上
matplotlib.use("Agg")再运行，并逐个savefig。预期：图片文件正常生成。官方测试配置里也是用 Agg 后端，这是可参照的做法。
Measured
本机实测：Alphalens 的真实安装与运行记录
下面是在本机（Windows + Python 3.11.9）实际执行留下的原始记录，完整输出见研究报告目录的 _probe_reloaded3.txt。所有数据均为合成数据，不是任何真实行情。
| 环节 | 本机实际结果（合成数据） | 说明了什么 | 注意点 |
|---|---|---|---|
| 安装维护分支 | pip install alphalens-reloaded 成功，装出 0.4.6，并连带装上 pandas 2.3.3 与新版 numpy / scipy | 维护分支在现代 Python 上可安装 | 默认依赖组合下导入会失败，需要按依赖链调整版本 |
| 导入 | 把 statsmodels 与 scipy 调整到相互兼容的组合后，import alphalens 成功，版本读数 0.4.6 | 失败原因是依赖链错配，不是库本身不可用 | 具体组合见「报错」页记录二，换机器需重测 |
| 清洗 | 清洗后得到 factor_data，列为 1D / 5D / 10D / factor / factor_quantile，索引层为 date / asset | 期数列名是「期数 + D」的字符串，不是整数 | 用整数下标取列会直接 KeyError，本机实测踩到过这一点 |
| IC 计算 | IC 矩阵按期数给出三列，均值、标准差与 IC 为正的比例都能算出 | IC 链路可用，且 IC 是确定性计算 | 下表数值来自合成数据，不能作为任何因子的有效性结论 |
| 分位与多空 | 分位均值收益返回 5 行（分位）× 3 列（期数）；多空价差需要用 by_date=True 的分位收益 | 四个核心指标链路都跑通 | 直接传 by_date=False 的结果给价差函数会报 Index must be a MultiIndex |
| 换手与稳定性 | 分位换手与 rank 自相关均能输出 | 成本与稳定性指标可用 | 换手率随 period 变化，报告里必须写明 period |
本次运行的实际输出要点（逐条来自终端记录）：
alphalens 0.4.6 | pandas 2.3.3 | numpy 2.2.6Dropped 4.0% entries from factor data: 4.0% in forward returns computation and 0.0% in binning phase (set max_loss=0 to see potentially suppressed Exceptions).max_loss is 35.0%, not exceeded: OK!factor_data shape: (9680, 5)columns: ['1D', '5D', '10D', 'factor', 'factor_quantile']index names: ['date', 'asset']IC frame shape: (242, 3) columns: ['1D', '5D', '10D']mean IC: {'1D': 0.00369, '5D': 0.00953, '10D': 0.01735}IC IR : {'1D': 0.0221, '5D': 0.0593, '10D': 0.1039}IC>0 ratio: {'1D': 0.4959, '5D': 0.4959, '10D': 0.5331}mean_return_by_quantile shape: (5, 3) columns: ['1D', '5D', '10D']mean return by quantile (bps, 1D): {1: 1.57, 2: -6.08, 3: 0.53, 4: 1.04, 5: 2.94}mean spread (bps, 1D, by_date=True): 1.37mean turnover (5D, top quantile): 0.8128mean rank autocorr (1D): -0.0041
23ef0bf72598b9321b7a741456d8ebda8abbaa877ae2e0805cc855095e893271）：全部使用合成数据——40 个虚构标的、252 个交易日、随机生成的因子值。它只证明「安装与渲染链路可用」，不代表任何真实因子或市场表现；换随机种子数值就会变。$ python (alphalens 最小因子分析，合成数据)
alphalens 0.4.6 | pandas 2.3.3 | numpy 2.2.6
Dropped 4.0% entries from factor data: 4.0% in forward returns computation and 0.0% in binning phase (set max_loss=0 to see potentially suppressed Exceptions).
max_loss is 35.0%, not exceeded: OK!
factor_data shape: (9680, 5)
columns: ['1D', '5D', '10D', 'factor', 'factor_quantile']
index names: ['date', 'asset']
IC frame shape: (242, 3) columns: ['1D', '5D', '10D']
mean IC: {'1D': 0.00369, '5D': 0.00953, '10D': 0.01735}
IC IR : {'1D': 0.0221, '5D': 0.0593, '10D': 0.1039}
IC>0 ratio: {'1D': 0.4959, '5D': 0.4959, '10D': 0.5331}
mean_return_by_quantile shape: (5, 3) columns: ['1D', '5D', '10D']
mean return by quantile (bps, 1D): {1: 1.57, 2: -6.08, 3: 0.53, 4: 1.04, 5: 2.94}
mean spread (bps, 1D, by_date=True): 1.37
mean turnover (5D, top quantile): 0.8128
mean rank autocorr (1D): -0.0041
SAVED_IMAGE D:\eacyclaw官网网页站点\运作文件包\skills\alphalens\images\alphalens-real-run.png
MEASURED_OK这里不是官方示例：上面全部是本机执行的真实记录，用的是合成数据。官方仓库 examples 目录里的示例图（ExtractAlpha 提供的示例因子）与本次运行无关，请勿混为一谈。
证据边界：这段记录只证明「在本机这套环境下，安装与最小分析流程可以跑通并得到结构化输出」。它不证明主库可用（主库实测安装失败）、不证明因子在真实市场上有效，也不构成任何投资建议。所有数字来自合成数据。
Examples
Alphalens 官方示例目录：9 个 notebook 现在是什么状态
官方 README 让新手去跑 examples 目录里的 notebook。这个目录确实很全，但它停留在 2020 年，官方 issue 里已经有人报告教程跑不通。
| Notebook | 演示什么 | 现在能不能直接跑 | 替代做法 |
|---|---|---|---|
alphalens_tutorial_on_quantopian.ipynb | 官方推荐的入门教程 | README 里指向了 Quantopian 平台，而该平台已停止运营 | 把数据加载部分换成本地数据，其余分析代码结构仍可参考 |
tear_sheet_walk_through.ipynb | 逐块讲解 tear sheet 怎么读 | 需核对与当前版本输出是否一致 | 作为读图顺序的参考最合适 |
predictive_vs_non-predictive_factor.ipynb | 对比有效因子与无效因子的报告差异 | 需核对版本 | 想建立「什么叫有效」的直觉时最有用 |
event_study.ipynb / event_study_synthetic_data.ipynb | 事件研究方法（前者真实数据、后者合成） | 合成数据版本更适合本地跑 | 先用合成数据 notebook 跑通链路 |
intraday_factor.ipynb / intraday_factor_synthetic_data.ipynb | 日内因子分析 | 同前 | 同上 |
daily_factor_synthetic_data.ipynb | 日频因子流程（合成数据） | 依赖最少，最容易跑通 | 作为第一个要跑的 notebook |
pyfolio_integration.ipynb | 与 pyfolio 衔接方式 | 依赖 pyfolio，而它同样停更（PyPI 最新 0.9.2，2019-04-15） | 只参考 create_pyfolio_input 的用法，不强求跑通整本 |
ic_tear.png / returns_tear.png / sector_tear.png / table_tear.png | 官方示例报告截图（ExtractAlpha 提供的示例因子） | 静态图片，仅作观感参考 | 不要当成本站或你自己数据的结果 |
官方教程现状：issue #355（2019-11-02 开）标题就是「Tutorials Not working - needs updating」，说明这条路径官方自己也清楚已经过时。以官方仓库当前状态为准，不要假设 notebook 能开箱即跑。
Checklist
怎么读一份 tear sheet：8 个关键项与 4 个误读
把报告当图片看，和把报告当证据看，是两种不同的读法。下表给出一个可复用的检查顺序。
| 顺序 | 看什么 | 合格的样子 | 不合格时先查什么 | 注意点 |
|---|---|---|---|---|
| 1 | 分位样本量是否均衡 | 各分位标的数大致相同 | 因子分布是否极端偏斜、是否用错了 bins | 某一组只剩几只标的时，分位收益不可信 |
| 2 | 清洗丢弃比例 | 丢弃比例可解释（本机示例 4%–8%） | 价格与因子标的集合是否对齐、缺失情况 | 用放宽 max_loss 掩盖数据问题是常见错误 |
| 3 | 分位收益是否单调 | 从低分位到高分位呈阶梯 | 分位方向定义是否写反 | 方向搞反会把反向阶梯读成正向 |
| 4 | 多空价差与标准误 | 价差方向稳定，且相对标准误不微弱 | 是否由少数期贡献 | 价差不含成本与不可成交标的 |
| 5 | IC 时序与滚动均值 | 滚动均值长期同向 | 是否只在个别年份有效 | 不要只看 IC 均值 |
| 6 | IC 分布与正值占比 | 分布集中、正值占比明显偏离 50% | 偏度是否过大 | 均值可能被少数期拉高 |
| 7 | 换手率量级 | 与计划调仓周期匹配 | period 是否设错 | 换手接近 1 意味着每期几乎全换 |
| 8 | alpha / beta 表 | beta 不显著或已在预期内 | 因子是否只是市场或风格的代理 | 与中性化前后对比配合看 |
四个常见误读：①把图好看当成因子有效；②把 IC 均值当成稳定性；③把多空价差当成可实现收益；④把「官方示例图」当成自己数据的结果（官方 examples 里的示例图用的是官方示例因子，与你的数据无关）。
Source walkthrough
源码导读：四个模块里的数字是怎么算出来的
「应该读源码」是常见建议，但没人告诉你怎么读。下表按「输入 → 处理 → 输出字段 → 容易误读的地方」给出四个模块的导读路径，函数名与字段均取自源码。
| 模块 | 读哪个函数 | 它做了什么处理 | 产出字段 / 图形 | 容易误读的地方 |
|---|---|---|---|---|
utils.py | get_clean_factor_and_forward_returns → get_clean_factor → quantize_factor / compute_forward_returns | 对齐因子与价格、按期计算 forward returns、按期切分位、按组分箱、剔极值、校验丢弃比例 | factor、factor_quantile 与形如 1D/5D/10D 的期数列 | 期数列名是字符串不是整数；quantiles 与 bins 互斥；zero_aware 影响零值归组 |
performance.py | 先看 factor_information_coefficient，再看 mean_return_by_quantile / quantile_turnover / factor_rank_autocorrelation | 按期求秩相关（IC）；按期按分位求均值收益与标准误；统计分位成分替换比例；计算排名一阶自相关 | IC 矩阵、分位均值收益、多空价差、换手序列、自相关序列 | 各函数的 period 含义不同（持有期 vs 观察窗口）；by_date 影响能否直接喂给价差函数 |
tears.py | create_full_tear_sheet 及另外 6 个分段函数 | 把 performance 与 plotting 的结果按收益 / 信息 / 换手三组拼装 | 7 种现成报告 | 全量报告图多且慢；换手报告历史上更容易报错 |
plotting.py | 按需要挑：plot_ic_ts、plot_quantile_returns_bar、plot_cumulative_returns_by_quantile、plot_monthly_ic_heatmap | 只负责把已算好的数据画出来（22 个函数） | 各类图表对象 | plot_ic_ts 的 ax 需要一组轴（每期一个），传单个 Axes 会直接报错（本机实测踩到过） |
推荐读法：不要从头读文件。先读清洗入口的签名，理解 factor_data 长什么样；再读
factor_information_coefficient 十行左右的核心实现；最后打开 tears.py 看它怎么拼装。三处读完，整个库的计算链就清楚了。所有细节以官方源码为准。FAQ
Alphalens tear sheet 常见问题
函数清单以 tears.py / plotting.py 源码为准；示例目录状态以官方仓库当前内容与 issue 为准。
第一次跑该用哪个函数？
先用 create_summary_tear_sheet 看整体，再按需要跑分段报告或全量报告。全量报告图最多、渲染最慢，不适合作为第一次试跑的选择，也不适合批量跑因子筛选。
tear sheet 里的图能直接放进研究报告吗？
可以，但要标注三件事：数据来源与样本期、清洗参数（分位数、periods、max_loss）、以及库版本。缺了这三样，图就不可复现；另外本站提醒，累计收益相关图存在公开的口径争议（issue #374 等）。
为什么脚本里跑不出图？
无界面环境需要显式指定后端（例如 Agg），否则 matplotlib 可能找不到可用的显示后端。官方测试配置里就设了 MPLBACKEND=Agg，可以照这个思路处理。
事件类报告和普通报告差别在哪？
普通报告围绕「分位收益与 IC」组织，事件类报告围绕「事件前后若干期的平均累计收益曲线」组织，需要额外传入 returns 与窗口参数。用途上，前者评估因子，后者评估事件冲击形态。
官方示例图可以直接用吗？
不建议直接引用为本站或你的结论。那些图是官方仓库里用 ExtractAlpha 示例因子生成的历史示例图，既不是你的数据、也不是当前市场的结果。要引用就注明来源与「官方示例」，并说明非本站运行结果。
tear sheet 跑不动怎么办？
按三步排查：①先只跑摘要报告确认链路可用；②把 periods 与分位数量降到最小组合；③把绘图后端设为 Agg 并保存文件。若仍失败，转到「报错」页按报错原文对照处理。
这套报告和免部署技能有关系吗？
没有已证实集成。tear sheet 由 Alphalens 在 Python 环境里生成；客户端侧的 chart-image 技能可以画别的图，但不能生成 tear sheet，也不能替代这套分析。所有输出仅供研究，不构成投资建议。
本页的示例运行是多少真实数据？
零。本机实测使用完全合成的价格与因子序列，只为验证安装链路与 API 调用是否跑通。页面已在运行记录与图注中标明「合成数据」，请勿据此推断真实因子表现。