Fama-French Three-Factor Model

Separate market, size and value exposure before describing a return intercept as unexplained performance. The useful result is not just a scalar. You should be able to trace it back to eligible observations, explain which convention produced it and recognize when the calculation should stop.

This tutorial builds Time-series OLS of asset excess returns on supplied MKT-RF, SMB and HML with an intercept; this estimates exposures and does not reconstruct the French portfolios. You will calculate a small example, run matching Python and TypeScript implementations, inspect a controlled synthetic case and change one assumption in a guided lab. No historical market performance is claimed.

The chart shows the canonical fixture. Read the axis units before comparing values: a return, a score, a weight and a statistical diagnostic are different objects. Its numerical source is the same fixture used by the executable examples. Open the full-size chart when you need to inspect small labels.

Start with the question, then the mechanism

A multivariate loading measures the part of one factor that the other included factors cannot explain. This is why three separate univariate regressions do not reproduce the three-factor fit. A portfolio can appear to have high market beta simply because its size and value tilts co-move with the market in this sample. The joint fit estimates all slopes together and preserves the residual. Interpret a negative HML loading as exposure toward the opposite side of the supplied value spread, not as a finding that value investing fails.

Fit an intercept and all declared factor columns jointly; reject a rank-deficient design instead of deleting a factor.

From fitted exposure to a pricing claim

There are three different questions in asset pricing. A time-series fit asks how an asset moved with supplied factors. A pricing restriction asks what its expected return should be. A trading decision asks whether a feasible position offers an attractive return after costs and uncertainty. The same coefficient cannot answer all three questions. Keep the expected-return assumption outside the realized-return regression until you have evidence that connects them.

For regression topics, arrange observations in chronological rows, include an intercept, and express every return in decimal units at the same frequency. Subtract the same-period risk-free return once from the asset. Do not subtract it again from a self-financing spread. The factor order is part of the API: a correct vector multiplied by mislabeled columns is a wrong model. Estimate all included columns jointly; one regression per factor does not estimate partial exposures.

The implementation uses reorthogonalized, column-scaled QR to solve least squares. This avoids explicitly forming the normal equations for the coefficient estimate. A column that becomes numerically dependent on earlier columns causes a rejection. Bartlett HAC covariance describes sampling uncertainty under appropriate weak-dependence conditions; it does not repair endogeneity, structural breaks, a mismatched benchmark, or an unrepresentative sample. The intercept remains a per-period return, not an automatically annualized alpha.

Before presenting results, inspect the residual series and fitted-versus-observed plot. Compare an economically motivated competing specification using the same dates. A smaller in-sample residual is expected when adding regressors; it is not by itself a reason to select the larger model. Out-of-sample evidence, model stability and the intended use determine whether the extra exposure estimates are helpful. The APT calculator is deliberately different: it accepts premia as assumptions rather than estimating them from this regression machinery.

Freeze the definition

SMB is a small-minus-big return spread; HML is a high-minus-low book-to-market return spread. All regressors are decimal period returns; coefficients are dimensionless.

The sources establish the method's research context; the stated variant fixes the implementation choices for this package. See French, Description of Fama/French Factors, statsmodels, cov_hac documentation. Where a teaching convention differs from a published portfolio or test, it is labeled explicitly rather than borrowing the published method's empirical conclusions.

Work a small example before running the code

With alpha=0.001, loadings (1.2, 0.4, -0.3), and one factor row (0.02, -0.01, 0.005), fitted excess return is 0.001+1.2×0.02+0.4×(-0.01)-0.3×0.005=0.0195. An observed excess return of 0.021 leaves residual 0.0015. A single row explains attribution; the multi-period fixture is required to estimate the coefficients.

The machine-readable hand check is saved separately from the larger chart fixture. It asserts coefficients against [0.001, 1.2, 0.4, -0.3]. Some hand checks use a different small input from the prose example to test the same invariant from another direction. For a model with several regressors, a one-row attribution example cannot estimate the loadings; the multi-period executable fixture supplies the necessary observations.

To audit the arithmetic, carry full precision through intermediate values and round only for display. Ask whether the result's unit is consistent with the formula. Then consider a limiting case: does the method return an explicit rejection or undefined result when its denominator or identifying variation disappears?

Prepare data without borrowing from the future

All calls also require formation_at, inputs_available_at and as_of as real ISO calendar dates. Inputs must be available by formation; formation cannot exceed the evaluation cutoff. Evaluation topics additionally require outcome start, end and availability dates. These envelope checks reject impossible chronology but cannot certify the provenance of individual rows. Your adapter must verify IDs, timestamps, frequency, currency, total-return adjustments, release dates and source vintages before building the arrays.

Missing, nonfinite, boolean or string-valued numbers are not silently repaired. The complete-case contract is intentional: changing eligibility changes the quantity being measured. Preserve the rejected records and the reason in a data-quality report, then choose a documented repair or a different model. Do not turn an undefined quantity into zero to make a chart look complete.

Follow the execution path

1. Align returns and clocks. Fit an intercept and all declared factor columns jointly; reject a rank-deficient design instead of deleting a factor.
2. Subtract the risk-free leg. Retain the inputs and the intermediate quantities; alignment is part of correctness.
3. Fit exposures jointly. Calculate at full precision using the declared variant, not a convenient substitute.
4. Inspect residuals and uncertainty. Check the method’s invariant and preserve undefined outcomes separately from numeric zero.
5. Compare a competing specification. A loading estimates realized co-movement conditional on the included regressors. It is neither a forecast premium nor proof of a causal exposure.

Run the reference implementation

From the downloaded topic directory:

python examples/run.py
python -m unittest discover -s tests -p "test_*.py"
npx tsc -p implementations/typescript/tsconfig.json
node tests/test-typescript.mjs

The Python calculation has no third-party runtime dependency. TypeScript needs a compiler and an ES2022-capable JavaScript runtime. The public call accepts one JSON-shaped input and returns a discriminated success or error object. A minimal Python integration is:

from pathlib import Path
import importlib.util, json

root = Path.cwd()  # Run from this topic directory.
spec = importlib.util.spec_from_file_location("topic", root / "implementations/python/algorithm.py")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
data = json.loads((root / "datasets/canonical-input.json").read_text())
result = module.compute(data)
if result["status"] != "ok":
    raise ValueError(result["code"])
print(result["primary"])

After compilation, the equivalent TypeScript module can be used from JavaScript:

import { readFileSync } from 'node:fs';
import { compute } from './implementations/typescript/dist/algorithm.js';
const input = JSON.parse(readFileSync('./datasets/canonical-input.json', 'utf8'));
const result = compute(input);
if (result.status !== 'ok') throw new Error(result.code);
console.log(result.primary);

The canonical primary display is 1.2. More informative output fields include:

Inspect the complete returned object rather than reducing every use case to primary. That field is a playground convenience; the named intermediate and result fields preserve the method's meaning. Both languages use the same defaults and reason codes and do not mutate the input. Package tests compare the whole output tree, while independent mathematical checks avoid treating one implementation as the sole authority for the other.

Use the playground as an experiment

Open the topic's Playground tab or the self-contained guided lab. It starts from a meaningful canonical preview. Choose a scenario, predict the result, use Step to follow the calculation, and explain the evidence before pressing Play. Back and Reset let you revisit exactly the same state. Reduced-motion mode advances one deliberate step instead of running a timed sequence.

The main control is Residual noise multiplier, ranging from 0 to 3 with default 1. The comparison scenario is Value tilt reversed. Joint factor loadings isolate exposures conditional on all included return columns. Every change recomputes the result through the validated TypeScript kernel; it does not select a prerecorded result.

The deliberate failure scenario, Constant market: exposure cannot be identified, should return SINGULAR_DESIGN. First explain which assumption failed. Then return to the canonical case and identify the information that makes the calculation possible. This rejection is part of the lesson: it prevents an invalid model from producing a plausible-looking number.

This second chart uses the comparison scenario at the default parameter. The caption and diagnostics in the lab explain what changes and what remains invariant. Identical output can be the correct outcome of an invariance experiment; do not mistake it for a broken control.

Avoid these interpretation failures

• Never subtract risk-free returns from SMB or HML again: they are already self-financing spreads.
• Changing the factor vintage or geographic universe changes the model being estimated.
• Correlated columns can make individual slopes unstable even when fitted returns remain stable.

A loading estimates realized co-movement conditional on the included regressors. It is neither a forecast premium nor proof of a causal exposure.

Check your understanding

Predict: Would three separate one-factor regressions recover the joint model loadings?

Explain: Only under special orthogonality conditions. The joint coefficients control for the other columns; separate fits generally absorb their correlated effects.

Investigate: Run the canonical case, the comparison and the deliberate rejection. Save the input, output and one sentence explaining each difference. Identify a field whose unit could be confused with another field, and describe the consequence of that confusion.

Transfer: Before substituting real data, write the upstream eligibility and alignment rules. Name the source vintage, decision time and missing-value policy. Then identify one out-of-sample or data-quality check needed for your intended use. A successful synthetic calculation is a correctness demonstration, not evidence that the market rewards the signal.

What this package does and does not establish

The implementation makes the declared formula reproducible, exposes intermediates and rejects known invalid inputs. The sources motivate the method. The synthetic fixture lets you control one mechanism at a time. A named historical case remains deferred until its source observations and decision-time provenance can be archived; no invented returns are presented as real history.

Production use needs dataset-specific validation, monitored numerical limits, error logging, independent review and an execution or inference design appropriate to the application. See the source-package data contract and reference ledger for the full boundary. Educational material is not a recommendation to buy, sell or allocate capital.

Sources and further reading

• French, Description of Fama/French Factors. MKT-RF, SMB and HML definitions; fitted examples here use original synthetic returns.
• statsmodels, cov_hac documentation. Bartlett-weight Newey-West covariance for equally spaced observations; our finite-sample convention is stated explicitly.

Choosing the method and continuing the lesson

This lesson is for analysts and developers who can work with aligned numerical arrays, means and return units. Regression and statistical-test topics also assume familiarity with residuals and sampling uncertainty; review the linked prerequisite before interpreting an inferential result.

Use the declared approach when its input and interpretation match your research question. If you choose the alternative, freeze a new convention and rerun the examples; changing a label is not enough to change the calculation.

Related concepts

Excess return, Total return. For any use with observed market data, keep the point-in-time dataset boundary explicit.

Learning connections

• Prerequisite: CAPM Beta. Establish the inputs or mathematical distinction used here.
• Comparison: CAPM Beta. Compare its question and output units before substituting it for this method.
• Continue with: Carhart Four-Factor Model. Carry the same formation clock and declared units into the next calculation.

Inspect the return attribution

In playground steps 3 and 4, the stage changes from fitted-versus-observed returns to an attribution for one selected date. Add alpha, each named factor contribution and the residual to reconstruct that date’s observed excess return. The diagnostic cards expose every loading, so a reversed size, value, momentum or profitability tilt remains visible even when market beta barely changes. Return to step 5 to compare the complete sample.