What (One-liner)

Fama-French 3 factors + Carhart momentum OLS: given asset returns + market returns (+ optional SMB/HML/MOM), outputs α, factor βs and R². The academic benchmark for style attribution.

How to use

Drag fama_french_v1 onto the Canvas, fill asset_returns (required) + market_returns (required) + optional smb_returns / hml_returns / mom_returns / rf_returns. Output is α + β_* + R². Without SMB/HML/MOM it degrades to single-factor CAPM.

Core formulas

y_excess = asset_returns - rf_returns
mkt_excess = market_returns - rf_returns
X = [1, mkt_excess, smb?, hml?, mom?]       # optional factors added as supplied

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

Output rounding convention (pinned by golden):

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

Assumptions & applicability

Assumptions: OLS homoskedasticity + independent factor observations + rf frequency matching the returns.

Fits: monthly / daily equity and ETF style attribution; n≥20 (n≥36 recommended).

Does not fit: crypto, private companies, HFT, n<20 (auto error).

Input / Output contract

{asset_returns, market_returns, smb_returns?, hml_returns?, mom_returns?, rf_returns?} → {alpha, r_squared, n_observations, factors_used, beta_*, _method}. Details in the frontmatter.

Known limitations

1. β_* round(4) precision loss (rounding pinned by golden)
2. No Newey-West / White robust SEs
3. No t-stats / p-values / CIs
4. No VIF collinearity check
5. Momentum questioned in the post-2010 literature (caveat not surfaced)

References

Fama & French (1993) 3-factor original + Carhart (1997) momentum + Fama & French (2015) 5-factor (unimplemented; reserved upgrade path). Full citations in the frontmatter.

Golden Test

tests/golden/fixtures/tier2/fama_french/ — the Tier 2 pilot, 1e-12 tolerance (post-rounding byte-equality), 4 tests:

• matches_reference — comparison against an independent statsmodels.OLS implementation
• determinism — 5 reruns byte-identical
• rejects_short_series — n<20 → error payload without raising
• market_only_capm_fallback — market-only input degrades to CAPM (β recovers the linear relation exactly + R²=1.0)

Reference: statsmodels.api.OLS (QR-based); Pangura uses np.linalg.lstsq (SVD-based). Two numerical paths solving one OLS problem → correctness demonstrated.

Changelog

• 1.0.0 (2026-04-20) — First Active (Tier 2 pilot)