B-因子构建类 · 25 CASES · QLIB PIPELINE
QuantsPlaybook 因子案例册：25 个案例，六类因子家族
因子类是仓库里依赖最重、方法价值也最高的一类：它把「研报里的因子公式」一路做到「Qlib 因子流水线 + 分组回测」。本页按因子家族整理 25 个案例，并标出哪些代码不依赖数据权限也值得读。
- QuantsPlaybook B 类实测：25 个案例目录 / 25 个 Notebook / 31 份研报 PDF，是文件最多的目录（约 840 MB）。
- 依赖最重：
Qlib、alphalens、pyfolio_reloaded、numba、LightGBM都出现在这一类。 - 部分案例把数据通过百度网盘分发，另有案例要求自建数据库。
- 算子代码可独立读：
scr/下的因子计算逻辑不依赖数据权限。
六类因子家族分别是什么？
SIX FAMILIES
QuantsPlaybook 有哪些因子家族？代码位置与数据要求
下表按「因子怎么算出来」分组。同一族内的代码结构与方法论高度相似，读通一个就能读懂一片。
| 因子家族 | 核心逻辑 | 代表案例 | 代码结构 | 数据要求 |
|---|---|---|---|---|
| 价量类 | 从成交价与量的关系里抽信息（反转、买卖压力、振幅、高频相关） | 开源证券-市场微观结构研究系列（1）、基于量价关系度量股票的买卖压力、振幅因子的隐藏结构、高频价量相关性…、上下影线因子、聪明钱因子模型的2.0版本 | 多为单 Notebook + scr/ 算子 | 日线 + 分钟线（部分案例需要高频） |
| 动量类 | 识别动量效应与其修正（团队硬币、APM、行业内动量） | 个股动量效应的识别及球队硬币因子、高质量动量因子选股、APM因子模型、A股市场中如何构造动量因子？、行业有效量价因子与行业轮动策略 | 球队硬币案例最复杂：src/ + FactorZoo/ + 36 份 Qlib YAML | 日线；球队硬币案例需自建 MySQL 或网盘数据 |
| 波动率类 | 剥离跨期截面相关性后的「纯真」波动信息 | 剔除跨期截面相关性的纯真波动率因子（Notebook 名为「波动率选股因子_特质波动率」） | 单 Notebook + 算子 | 日线 |
| 行为金融类 | 用投资者的认知偏差解释定价（凸显性、处置效应、基金行为） | 凸显理论STR因子、处置效应因子、来自优秀基金经理的超额收益、基金重仓超配因子… | STR 案例含 5 份 PDF；处置效应案例 Notebook 名为「资本利得突出量CGO与风险偏好_重置」 | 日线 + 持仓/基金数据（部分需要） |
| 网络类 | 把股票之间的关系（或隔夜-日间关系）建成网络，用网络指标当因子 | 股票网络与网络中心度因子研究（自带 22.5 KB 中文使用指南）、基于隔夜与日间的网络关系因子 | 网络中心度：NetworkCentralityFactor 类 + SCC/TCC/CC 三因子；隔夜日间：DLE-SC 算法 + 多个类 | 网络中心度用 Qlib 字段表达式；隔夜日间需要 DolphinDB 或回退模拟数据 |
| 基本面与筹码类 | 财务质量与持仓成本结构 | 筹码因子、企业生命周期、多因子指数增强、金股增强策略、因子择时、再论动量因子 | 筹码因子：scr/cyq_ops.py、distribution_of_chips.py | 筹码因子：Qlib 数据 + 网盘数据包；企业生命周期：约 68.9 MB 因子表 |
分组依据：QuantsPlaybook 的 B 类 25 个案例目录名与 README 说明。本站未运行任何案例，「数据要求」来自案例 README 原文与它的 requirements.txt。
WHAT IS WORTH READING
QuantsPlaybook 不买数据能读什么？算子与数据契约
因子类案例的价值有一半在代码结构里，而不在运行结果里。下表列出的部分都不需要数据权限。
| 可读内容 | 在哪看 | 能学到什么 | 需要数据权限 |
|---|---|---|---|
| 因子算子实现 | scr/cyq_ops.py、turnover_coefficient_ops.py、distribution_of_chips.py（筹码因子） | 如何用 numba 重写分布类计算；作者为什么放弃 scipy.stats.triang/uniform 以换效率 | 否 |
| 网络因子类设计 | NetworkCentralityFactor 类（网络中心度案例使用指南） | SCC（空间）/ TCC（时间）/ CC（综合）三因子的构造与滑动窗口用法 | 否 |
| Qlib 工作流配置 | src/config/workflow_config_*.yaml（球队硬币案例 36 份） | Qlib 支持哪些模型（LightGBM/XGBoost/CatBoost/Linear/MLP/LSTM/GRU/ALSTM/GATs/TCN/Transformer/TabNet…）与 Alpha158 / Alpha360 特征集怎么配 | 否 |
| 因子分析流程 | factor_analyze.py、qlib_workflow.py、plotting.py | 从因子值到分组收益、IC 序列与绘图的标准流程 | 否（运行需要） |
| 偏离评估文档 | RRG 案例 README 的 5 条已知偏离、SAE 案例的「如何理解结果」 | 一份可被检验的复现说明长什么样 | 否 |
| 数据契约 | 球队硬币案例 README 的三张表结构（daily / adj_factor / daily_basic） | Tushare 口径下的字段含义与单位（手、千元、万元） | 否 |
这是本站对该项目的明确建议：先按代码与文档学方法，再决定是否为数据付费。把算子读透之后，你完全可以用自己手上的数据源重新实现同一个因子。
IC AND GROUPING
IC 与分组回测要注意什么？六个口径问题
因子类案例的产出通常是 IC 序列与分组收益。项目用了 alphalens 与 Qlib 两套体系，口径并不完全一致——这是最容易被忽略的地方。
| 指标 | 常见定义 | 项目里可能存在两套口径 | 你必须自己确认什么 |
|---|---|---|---|
| IC（信息系数） | 因子值与下期收益的截面相关系数（Pearson 或 Spearman） | alphalens 与 Qlib 在「用哪一期收益」「是否去极值」上可能不同 | 用 Pearson 还是 Rank IC；预测周期几日 |
| ICIR | IC 均值 ÷ IC 标准差（含年化与否两种做法） | 年化因子（252 或 12）不同会成倍影响数值 | 是否年化、年化时按日频还是月频 |
| 分组收益 | 按因子值排序分 N 组比较收益（多空为 top − bottom） | 分组数（5/10）、等权与否、是否行业中性化都会改变结论 | 分组数、加权方式、是否中性化 |
| 换手率 | 组合成分变动率 | 多数案例未统一披露换手口径 | 换手如何定义、是否已扣成本 |
| Sharpe / 年化 | 收益 ÷ 波动（几何或算术） | SAE 案例文档明确写过：Notebook 用几何年化、analyze.performance 用算术均值，不能混用 | 你引用的是哪一套；写报告时必须标注 |
| 样本区间与股票池 | 回测窗口与选股范围 | 多数老案例未写明成分股是否按历史时点还原 | 是否有生存偏差；是否剔除 ST、停牌、新股 |
关键提醒直接来自项目文档：同一项目里两套夏普口径并存且不能混用。如果把 Notebook 的绩效表与代码里 analyze.performance 的输出直接对照，会得到互相矛盾的数字。
QLIB PIPELINE
QuantsPlaybook 的 Qlib 流水线怎么走？四步与数据要求
多个案例共用同一套 Qlib 结构，理解这四步就能读懂一大半因子案例。
案例通常自带转换脚本，例如 python src/dump_bin.py dump_all --csv_path data\cn_data --qlib_dir data\qlib_data --date_field_name trade_date --exclude_fields code。预期输出：Qlib 可直接读取的二进制数据目录。注意 qlib_data/、cn_data/、factor_data/ 都在 .gitignore 里，克隆后默认不存在。
YAML 里定义 handler（特征集与标签表达式）与 segments（train / valid / test 区间）。预期输出：能被模型消费的数据集配置。判据：segments 是否真的把测试区间留出来。
模型类与参数写在 YAML 的 model 段。预期输出：预测分数序列。球队硬币案例的 36 份配置正好是一张「Qlib 支持哪些模型」的清单。
用 factor_analyze.py 或 alphalens 出 IC 序列、分组收益与换手。预期输出：IC 均值 / ICIR / 分组年化等指标——引用前先确认上一节那六个口径问题。
# 典型目录结构（以「个股动量效应的识别及球队硬币因子」为例）
个股动量效应的识别及球队硬币因子/
├── src/
│ ├── config/workflow_config_lightgbm_Alpha158.yaml # 36 份不同模型/特征组合
│ ├── dataservice/db_tools.py # 数据落库
│ ├── dump_bin.py # CSV → Qlib 二进制
│ ├── factor_analyze.py # 因子分析
│ ├── LGBRanker.py rolling.py plotting.py
│ └── qlib_workflow.py
├── FactorZoo/SportBetting.py # 因子本体
└── data/ qlib_data/ factor_data/ # 均被 .gitignore 忽略目录结构来自固定 commit 文件树（本站逐条核对）。data/ 一行与忽略规则相符，因此克隆后默认不存在，需按 README 的网盘说明或自建数据库补齐。
TROUBLESHOOTING
因子案例卡在哪里？从装不上到 IC 对不上
因子类的问题比择时类集中，多数落在数据与依赖两层。
| 现象 | 真实原因 | 处理办法 | 证据来源 |
|---|---|---|---|
import qlib 失败或版本报错 | 同一案例同时钉了 qlib==0.0.2.dev20 与 pyqlib==0.9.1；老版 pyqlib 只在 3.8 有 wheel | 按案例要求降到 3.8；或只装一个并确认 API 是否兼容 | 本机依赖矩阵实测 |
numba 安装失败 | numba==0.56.4 自带解释器版本上限 | 降到 Python ≤3.10，或换新版 numba 并同步调 numpy / scipy | 本机实测报错原文 |
| Qlib 找不到数据 | qlib_data/ 被 .gitignore 忽略，克隆后不存在 | 按 README 用 dump_bin.py 从 CSV 生成，或用网盘数据包 | .gitignore 原文 |
| 取数需要自建数据库 | 部分案例只给连接串模板，不提供数据 | 按 README 的三张表结构自己灌数，或改用其它数据源重写取数层 | 球队硬币案例 README |
| IC 结果与研报不同 | 股票池、极端值处理、中性化方式、预测周期、样本区间任一不同都会改变 IC | 逐项对齐：先固定区间与股票池，再对齐因子处理流程 | 公开 issue #1 |
| 跑通但结论无意义 | 无 qlib 时回退模拟数据，或用了仓库自带的过期数据切片 | 检查数据来源标记与最新日期，确认不是合成数据 | 隔夜日间案例 README |
先读算子，再配数据
把 scr/ 下的因子算法读懂，用自己熟悉的数据源实现一遍，往往比配齐 Qlib 环境更快得到可用结果。
口径写进文件名
给自己产出的因子结果命名时带上股票池与区间（如 cgo_hs300_2015_2023.csv），避免几个月后分不清哪份结果对应哪套口径。
别把 alphalens 与 Qlib 的数字混着用
两套体系的 IC、分组与年化口径不同。要么统一在一套体系里比较，要么在报告里分别标注来源。
FAQ
QuantsPlaybook 因子案例常见问题
QuantsPlaybook 的因子案例一共有多少个？
实测 B-因子构建类 下有 25 个案例目录、25 个 Notebook、31 份研报 PDF，是文件数最多的目录（约 840 MB）。官方 README 在不同位置写作「因子构建 20+」「22+」「22+个」，与实测 25 略有出入。
QuantsPlaybook 没有 JQData 权限，因子案例还能看吗？
能看，但通常跑不到有意义的输出。可行的做法是：①只读算子与配置（scr/、src/config/*.yaml、factor_analyze.py）——这一层不需要数据权限；②用自己有权限的数据源重写取数层；③优先看数据走网盘分发的案例（筹码因子、球队硬币因子、均线收敛发散）。
QuantsPlaybook IC 和 ICIR 到底怎么算？项目里写法统一吗？
不统一。项目同时使用 alphalens 与 Qlib 两套体系，在「用哪一期收益」「是否去极值」「ICIR 是否年化」上口径可能不同。本站建议：自己固定一套（例如 Rank IC + 5 日预测周期 + 月度 ICIR 年化），并在报告里写明，不要混用不同来源的数字。
QuantsPlaybook Qlib 是什么？必须用吗？
Qlib 是项目里用来做因子流水线的框架（数据转换、特征集、模型训练、因子分析）。它不是必需的：很多案例的因子算子本身不依赖 Qlib，你也可以用 pandas + alphalens 复现同一套流程。但如果要跑通球队硬币那类案例，Qlib 的 YAML 配置体系是绕不开的。
QuantsPlaybook 为什么案例里会有 mlruns 目录和 .pkl 文件？
那是 Qlib 训练过程留下的实验产物（如筹码因子目录下有 132 个 .pkl、多个 17–22 MB 的 code_diff.txt、一个 27.2 MB 的 trained_model.pkl）。.gitignore 虽然后来加了 mlruns/，但这些文件在规则加入前就被跟踪了，所以仍在仓库里，也是仓库体积达 1.36 GB 的原因之一。
QuantsPlaybook 因子类的依赖真的装不上吗？
部分案例确实装不上。本站实测 筹码因子 与 个股动量效应的识别及球队硬币因子 两套依赖在 Windows + Python 3.11.9 上均失败，原因分别是 numba==0.56.4 的版本上限与 pyqlib==0.9.3 在该环境下不可见。按案例要求降到 Python 3.8–3.10 通常能解决。详见环境与依赖页。
QuantsPlaybook 读这些因子案例的正确产出是什么？
三样：①能用自己的话讲清因子怎么算、为什么要这么算；②能用自己口径复现出 IC 与分组收益，并写明口径；③能列出与研报的偏离项。本站不提供任何投资建议，也不对因子有效性作断言——因子是否有效，取决于你的数据、区间与用途。