Carhart Four-Factor Model

Identify whether a persistent-return strategy carries momentum exposure after accounting for market, size and value. 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 Four-factor OLS using factor order MKT-RF, SMB, HML, MOM. MOM naming and construction are recorded; the package does not equate every UMD/WML series. 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

Momentum exposure and momentum performance answer different questions. The factor can lose money during a period while a positively exposed portfolio remains positively exposed. The loading describes sensitivity; the realized factor return supplies the sign of the contribution. By showing the contribution bars alongside residuals, the lab makes this distinction visible. A four-factor model is nested within a larger modeling workflow, and its extra explanatory power must be assessed alongside sample size, covariance and out-of-sample stability.

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

y is the asset excess return; MKT denotes MKT-RF; MOM is the explicitly supplied high-minus-low prior-return factor; beta_U is its conditional exposure.

The sources establish the method's research context; the stated variant fixes the implementation choices for this package. See Carhart (1997), On Persistence in Mutual Fund Performance, French, Detail for Monthly Momentum Factor, 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

Add momentum loading 0.5 and MOM return 0.012 to the three-factor contribution 0.0195: fitted excess return becomes 0.0255. The added 0.006 is attribution at fixed coefficients. After estimating the four-factor model anew, all coefficients may change because momentum can correlate with existing regressors.

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, 0.2]. 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 Momentum tilt reversed. Momentum attribution changes with its loading and realized return; alpha is conditional on the full model. 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

• A change in alpha after adding momentum does not by itself establish fund skill or its absence.
• Do not use the forward holding-period return to define the prior-return signal.
• Factor names do not guarantee matching construction, market, or currency.

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: Does a positive momentum loading mean the asset earned a positive momentum contribution every month?

Explain: No. Contribution is loading times that month’s supplied momentum return, which can be negative.

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

• Carhart (1997), On Persistence in Mutual Fund Performance. Four-factor performance model; no replication of the original fund sample.
• French, Detail for Monthly Momentum Factor. Prior months 2 through 12 and high-minus-low portfolios; individual scores are not this traded factor.
• 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: Fama-French Three-Factor Model. 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: Fama-French Five-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.