Factor Pricing Research Project Plan

1. 研究逻辑

这个项目不从 SEC 数据工程开始。第一步应该先理解和复现旧因子，观察哪些因子有效、哪些暴露明显、哪些定义产生差异，再据此提出新因子或新研究问题。

正确顺序：理解经典因子 → 复现经典结果 → 比较因子和暴露 → 发现异常/空白 → 提出新假设 → 引入 SEC 原始数据 → 正式验证。

Notebook 的阅读顺序仍然是 00 到 13，但执行顺序不是依赖链。每一个 Notebook 都必须能够从原始数据入口独立运行，不能要求用户先运行前一个 Notebook，也不能把前一个 Notebook 生成的 Parquet 当作唯一输入。

独立运行原则：前一个 Notebook 的输出可以作为缓存、对照或审计证据，但不是后一个 Notebook 的硬依赖。Notebook 00 的审计文件尤其不能成为 Notebook 01 的启动条件。

2. 三阶段项目结构

PHASE 1 · CLASSIC FACTOR SURVEY

建立因子地图

使用 Qlib/市场数据和透明的手动公式，完成 Momentum、Value、Size、Volatility/Risk、Liquidity、Quality/Profitability、Technical/Price-Volume 七类因子。每个 Notebook 都从 Qlib 原始数据独立初始化，统一输出公式、字段、IC、分组收益和主要暴露。

PHASE 2 · RESEARCH DESIGN

从异常提出新问题

比较因子相关性、收益相关性、规模/行业/beta 暴露和边际贡献。比较 Notebook 可以重新读取原始数据并在本地构造所需因子；也可以读取已经存在的标准化缓存，但必须保留无缓存时的独立入口。新因子必须来自具体观察，有经济动机、精确公式、baseline、ablation 和预先写好的失败标准。

PHASE 3 · SEC FORMAL TEST

用原始数据验证 B/M

单独审计 SEC API、CIK/ticker、XBRL tag、公告时点、修订和覆盖率；构造 point-in-time Book Equity，连接 6 月市值，做 NYSE 五分位、行业控制、成本和 OOS。SEC Notebook 可以使用 Qlib 市场数据，但不能依赖 00-09 的执行结果。

3. Notebook 顺序与职责

00_setup_and_data_audit.ipynb       Qlib 数据入口、市场审计、标签方向验证
01_momentum_lab.ipynb               独立读取 Qlib，复现 MOM_12_1
02_value_lab.ipynb                  独立读取 Qlib，完成 Value survey
03_size_lab.ipynb                   独立读取 Qlib，完成 Size survey
04_volatility_risk_lab.ipynb       独立读取 Qlib，完成 Risk survey
05_liquidity_lab.ipynb              独立读取 Qlib，完成 Liquidity survey
06_quality_profitability_lab.ipynb  独立读取 Qlib，完成 Quality survey
07_technical_lab.ipynb              独立读取 Qlib，完成 Technical survey
08_cross_factor_comparison.ipynb    独立加载或重建因子，比较相关性与暴露
09_new_factor_hypothesis.ipynb       独立加载原始数据，验证新因子假设
10_sec_data_audit.ipynb              独立审计 SEC API、映射、coverage 和 filed date
11_sec_book_equity_construction.ipynb 独立构造 point-in-time Book Equity
12_bm_formal_test.ipynb              独立连接市场与账面数据，完成正式 B/M
13_final_robustness_and_oos.ipynb    独立加载所需原始数据，完成稳健性与 OOS

3.1 每个 Notebook 的统一启动协议

每个 Notebook 的前几个 cell 必须包含相同的入口顺序：

确定项目根目录、输出目录和本 Notebook 的参数。
检查当前 Python 环境是否安装依赖；缺失时显示可复制的安装命令。
检查本机 Qlib 数据目录；不存在时显示或执行下载命令。
调用 qlib.init(provider_uri=..., region=...)，读取原始数据。
在本 Notebook 内完成自己需要的月频化、字段映射、因子计算和审计。
把结果写入带有 Notebook 名称的输出文件，不覆盖其他 Notebook 的结果。

允许复用，不允许隐式依赖：公共函数可以放在 src/ 中由各 Notebook 显式导入；Notebook 之间不能用“先运行上一个 Notebook”来代替初始化和数据读取。每个 Notebook 单独执行“Restart Kernel and Run All”都应得到可解释的结果或明确的缺失数据错误。

3.2 Qlib 数据准备命令

第一次运行项目时，在终端执行以下命令。原始数据放在项目外，避免把大型数据包提交到仓库：

cd /home/ubuntu/projects/factor-pricing-research
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install jupyterlab pandas numpy matplotlib seaborn scipy statsmodels pyarrow pyyaml pyqlib
mkdir -p ~/.qlib/qlib_data/cn_data
wget -O /tmp/qlib_bin.tar.gz \
  https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz
tar -xzf /tmp/qlib_bin.tar.gz \
  -C ~/.qlib/qlib_data/cn_data --strip-components=1
rm -f /tmp/qlib_bin.tar.gz
jupyter lab

Notebook 中也要保留一个等价的“检查并准备数据” cell：如果 ~/.qlib/qlib_data/cn_data 已经存在且可读取，则跳过下载；如果目录为空，打印上面的命令并停止，而不是继续创建空 DataFrame。后续所有 Notebook 默认从这个 Qlib 中国日频数据目录读取全市场股票。

3.3 Notebook 00 与 01 的新逻辑

Notebook	独立输入	本地完成的工作	输出定位
00	Qlib 原始日频数据	读取 OHLCV 和 factor；转换月频；审计 schema、重复键、缺失、日期；构造并验证下一月标签。	审计表和月频缓存，供复查或加速使用，不是 01 的前置条件。
01	Qlib 原始日频数据；可选读取自己的缓存	自己初始化 Qlib，自己转换月频，自己构造 `fwd_return_1m`，再计算 `MOM_12_1`、IC 和五分位组合。	Momentum 信号、IC、组合收益和研究结论；不读取或依赖 00 的输出。

特别禁止：不要在 01 中写“如果文件不存在就回到 Notebook 00”；不要把 market_monthly_with_forward_return.parquet 作为 01 的必需输入。01 必须能在只保留 Qlib 原始数据时独立运行。

4. 固定研究规则

维度	决定
市场	阶段一使用 Qlib 中国市场全市场日频数据完成数据和因子管线学习；正式 SEC 阶段使用美国交易所上市普通股全市场，排除 ADR、ETF、REIT、封闭式基金、优先股、权证、单位和金融业。
独立性	每个 Notebook 从原始数据入口独立初始化；共享缓存只能加速，不能成为硬依赖。每个 Notebook 的输出使用独立文件名和目录。
Qlib 数据	默认目录为 `~/.qlib/qlib_data/cn_data`；记录下载日期、数据版本、调整价格口径和数据源限制。Qlib 数据不可用时必须明确报错。
SEC 样本	2010 年起，以覆盖率审计结果确定有效起点。
B/M 形成	每年 6 月底市值；形成日前已经 filed 的 Book Equity；7 月至次年 6 月持有。
Book Equity	`Common Equity + Preferred Stock - Non-controlling Interest`，字段优先级和回退必须留日志。
组合	NYSE breakpoints 五分位；市值加权主结果；等权稳健性；负权益单独分析。
证据	IC、Rank IC、收益梯度、High-Low、暴露、Newey-West、成本、容量、OOS。

研究纪律：不要因为结果不好而偷偷换窗口、股票池、权重或形成日期；主结果和稳健性结果必须分开。不要把缓存存在误认为数据来源，也不要把中国 Qlib 数据的演示结果直接解释成美国正式结论。

5. 交付与验收

Survey 交付

七类因子 notebook、经典定义、手动实现、Qlib 对照、IC、分位数组合、暴露分析、文献和风险问题。每个 Notebook 都包含独立启动、输入检查和自己的结果输出。

正式研究交付

SEC 数据快照、字段回退日志、CIK/ticker 审计、point-in-time B/M、French benchmark 和正式报告。10-13 也必须能从各自的原始输入独立重跑。

最低完成标准

执行任意一个 Notebook 的 Restart Kernel and Run All，不需要先运行其他 Notebook。
Notebook 00 能说清 Qlib 市场数据、月频转换和下一期标签，不夹带 SEC 工程。
Notebook 01 能独立读取 Qlib、手算并验证 MOM_12_1 的日期逻辑。
02-09 不把 00 或 01 的输出作为唯一输入；需要交叉比较时明确重建或显式读取缓存。
每个正式 B/M observation 可追溯到 SEC tag、filed、accn 和选择理由。
报告同时包含主结果、稳健性、成本、暴露、OOS 和失败分析。
README、配置、数据字典和脚本可以让别人重建主要表格和图；命令行和数据目录约定必须写清楚。

6. 里程碑

M0：冻结研究契约、目录、Qlib 数据入口和“每个 Notebook 独立运行”的统一协议。
M1：Notebook 00 独立跑通，市场审计和 forward label 通过；生成可选缓存。
M2：Notebook 01 在不读取 00 输出的情况下完成 MOM_12_1 baseline。
M3：完成 02-07 因子 survey 和基础因子地图，每个 Notebook 单独可运行。
M4：完成 08-09 因子比较与新假设，明确缓存与原始数据的边界。
M5：完成 10-12 SEC B/M 管线和正式检验，每个 Notebook 独立可重跑。
M6：完成 13 的成本、容量、暴露、OOS、报告和复现清理。