做什么（One-liner）

Fama-French 3 因子 + Carhart 动量 OLS 回归：给定资产收益 + 市场收益（+可选 SMB/HML/MOM），输出 α、β 因子暴露、R²。学术界基准风格归因模型。

怎么用

Canvas 拖 fama_french_v1，填 asset_returns（必填）+ market_returns（必填）+ 可选 smb_returns / hml_returns / mom_returns / rf_returns。输出 α + β_* + R²。不提供 SMB/HML/MOM 时退化为单因子 CAPM。

核心公式

y_excess = asset_returns - rf_returns
mkt_excess = market_returns - rf_returns
X = [1, mkt_excess, smb?, hml?, mom?]       # 可选因子按提供情况列入

β, residuals = numpy.linalg.lstsq(X, y_excess)
y_hat = X @ β
R² = 1 - Σ(y_excess - y_hat)² / Σ(y_excess - ȳ)²

输出 rounding 约定（golden 锁定）：

• α → round(6) 6 位小数
• β_* → round(4) 4 位小数
• R² → round(4) 4 位小数

假设与适用场景

假设：OLS 同方差 + 因子观察独立 + rf 频率与 returns 匹配。

适用：月 / 日频股票、ETF 的风格归因；n≥20（实操建议 n≥36）。

不适用：加密、私募、HFT、n<20（自动返回 error）。

输入 / 输出契约

{asset_returns, market_returns, smb_returns?, hml_returns?, mom_returns?, rf_returns?} → {alpha, r_squared, n_observations, factors_used, beta_*, _method}。详见 frontmatter。

已知局限

1. β_* round(4) 精度损失（golden 锁定 rounding 约定）
2. 无 Newey-West / White 稳健 SE
3. 无 t-stat / p-value / CI 输出
4. 无 VIF 多共线性检测
5. 动量因子在 post-2010 文献中被质疑（caveat 未 surfaced）

参考文献

Fama & French (1993) 3 因子原始论文 + Carhart (1997) 动量 4 因子 + Fama & French (2015) 5 因子（未实现，预留升级路径）。详见 frontmatter。

Golden Test

tests/golden/fixtures/tier2/fama_french/，Tier 2 pilot，1e-12 tolerance（post-rounding byte-equality）。4 tests：

• matches_reference —— statsmodels.OLS 独立实现对比
• determinism —— 5 次重跑 byte-identical
• rejects_short_series —— n<20 → error payload 不抛异常
• market_only_capm_fallback —— 仅提供 mkt_returns 时退化为 CAPM（β 准确 recover linear 关系 + R²=1.0）

参考实现：statsmodels.api.OLS（QR-based）；Pangura 用 np.linalg.lstsq（SVD-based）。两种 numerical path 求解同一 OLS 问题 → 证明算法正确。

Changelog

• 1.0.0 (2026-04-20) — 首次 Active（Tier 2 pilot）