CAPM Beta

Measure how much of an asset's historical excess return moves with the market and separate that slope from unexplained return. 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 OLS market-model beta with an intercept and Bartlett HAC standard errors. CAPM expected-return pricing is a separate restriction, not the fitted regression itself. 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

Think of beta as a conversion rate between two excess-return axes. A one percentage-point market movement corresponds to beta percentage points on the fitted asset line. Alpha shifts the line; it does not rotate it. Residuals are the vertical distances from observations to that line. More observations help only when the market varies and the sample remains relevant. An outlier can rotate the fitted line considerably, so the lab lets you compare a clean relation, larger residual noise and a constant-market rejection.

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

R_i and R_f are decimal same-period total and risk-free returns; x is the market excess return; alpha is a per-period intercept; beta is dimensionless; epsilon is the fitted residual.

The sources establish the method's research context; the stated variant fixes the implementation choices for this package. See Sharpe (1964), Capital Asset Prices, 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

For market excess returns -2%, -1%, 1%, 2% and asset excess returns -2.5%, -1%, 2%, 3.5%, the means are 0 and 0.5%. Centered cross-products total 0.0015 and squared market deviations total 0.001, so beta=1.5 and alpha=0.005. Residuals are zero by construction; a zero residual standard error is an exact-fit teaching boundary, not infinite economic evidence.

The machine-readable hand check is saved separately from the larger chart fixture. It asserts coefficients against [0.001, 1.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 Double market exposure. The market coefficient describes slope; noise changes residual risk and its uncertainty. 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

• Using raw asset returns with an excess market series changes the intercept and can change beta when the risk-free rate varies.
• A low beta does not imply low total risk: residual volatility may be large.
• A market return column that is constant cannot identify a slope.

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: If the asset excess returns double while market returns stay fixed, what happens to beta and alpha?

Explain: Both double in the same OLS sample. Correlation need not change. This separates slope scale from normalized association.

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

• Sharpe (1964), Capital Asset Prices. Equilibrium CAPM and systematic-risk interpretation; not proof that an empirical beta prices an asset.
• 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

• Preparation: review the linked glossary definitions, means, dispersion and the input contract before starting.
• Comparison: Fama-French Three-Factor Model. Compare its question and output units before substituting it for this method.
• Continue with: Fama-French Three-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.