Stable Online Variance and Welford's Algorithm

Beginner level · synthetic teaching data · Python and TypeScript verification

The useful question

What does Stable Online Variance and Welford's Algorithm help us see, and what can it never prove by itself?

Welford's algorithm updates count, mean, and squared-deviation state without subtracting two large nearly equal totals. This sounds compact because a statistic or model is compression: it keeps information relevant to one question and drops other detail. The first skill is therefore not memorizing notation. It is matching a human question to the information the method preserves.

For this package the frozen convention is n←n+1; δ=x−mean; mean←mean+δ/n; M2←M2+δ(x−mean). On the canonical synthetic fixture, the independently stored result is count = 5; mean = 3.0.

Begin with the picture

The visual keeps inputs, transformation, and output in separate layers. That separation is important in financial engineering. Raw observations have units, timestamps, identifiers, and availability rules. A derived number inherits those choices even when its final display looks simple.

Ask three questions while reading the picture:

1. Which observations are allowed to influence the result?
2. Which feature—magnitude, order, probability, time, path, or numerical precision—is preserved?
3. Which different datasets could produce the same output?

The third question reveals the method's blind spot. A summary can be correct and still be insufficient for a decision.

Translate the rule into plain language

n←n+1; δ=x−mean; mean←mean+δ/n; M2←M2+δ(x−mean)

Read each symbol as a data instruction, not decoration. A sum declares which observations enter. A denominator declares the reference population or sample. A lag declares which information is earlier. A probability declares a model and support. A square, absolute value, rank, or quantile declares which differences matter. A tolerance declares when two floating-point outputs count as equivalent.

The package stores these decisions in DATA-CONTRACT.md so a future implementation cannot quietly adopt a library default that changes the answer.

Work the synthetic example

The fixture at ../examples/worked-example.json contains the exact input and expected fields. The verified output is count = 5; mean = 3.0. It is intentionally small enough to audit but not presented as a real market observation.

Use this five-step verification habit:

1. Confirm field names, units, array lengths, and timestamps.
2. Recalculate the first intermediate quantity by hand.
3. Apply the stated convention without early rounding.
4. Compare only after aligning output names and numerical tolerance.
5. Write one sentence that states both the result and its limitation.

The Python and TypeScript facades read the same fixture. Cross-language agreement is useful evidence that both implement the frozen rule, but it does not prove that the rule is suitable for every dataset.

What changes the answer?

The guided lab includes 48 observations in five synthetic scenarios: canonical, one-shock, structured or symmetric, flat or tied, and boundary/failure. Each scenario changes one teaching feature while keeping the rest understandable.

Stream values spanning large offsets with small variation. Predict first. Then reveal observations with Step or Play and compare the diagnostic panel. Prediction makes the lab an experiment rather than a moving illustration.

The parameter control is family-specific. It changes spread for robust statistics, probability for event models, scale for distributions, visible sample size for inference, influence for regression, window length for time series, confidence for risk, or numerical tolerance for reproducibility.

The boundary is part of the answer

Sample variance needs at least two accepted observations and mergeable variants need an explicit combination rule.

This is not a disclaimer added after the lesson. It is part of the mathematical contract. Undefined denominators, impossible probabilities, zero variance, invalid windows, future leakage, misaligned benchmarks, and unsupported numerical states should stop the calculation or route it to a different method.

A clean number does not establish causation or future performance. Passing an implementation fixture answers “Did we calculate the selected definition?” It does not answer “Will this signal remain useful after costs, bias controls, and new data?”

Nearby methods and selection logic

Choose the simplest method that preserves the feature your decision needs. Pair magnitude summaries with distribution views, probability models with assumption checks, estimates with uncertainty, correlations with scatterplots and subgroup analysis, time-series statistics with causal splits, risk ratios with paths and tail views, and numerical outputs with metadata and tolerance policies.

If two tools produce different answers, do not average them automatically. First ask whether they use different centers, denominators, tails, ranks, time windows, probability models, frequencies, or invalid-state rules.

Implementation walkthrough

The reference flow is deliberately readable:

validate required fields and alignment
freeze convention, time order, and parameter boundaries
derive intermediate state at full precision
calculate the named output
attach audit fields and reason codes
reject unsupported states

The narrow topic facade keeps the public function discoverable. Shared arithmetic prevents eighty foundational topics from drifting into eighty incompatible definitions. Optimization can come later; explicit state and testability come first.

Testing beyond the happy path

A responsible test set includes canonical arithmetic, equality boundaries, zero and constant states, malformed values, misalignment, numerical tolerance, and causal ordering where relevant. For models, it separates implementation correctness from model fit. For risk metrics, it freezes sign, confidence, horizon, and annualization. For reproducibility, it verifies reset, seed, version, and metadata behavior.

The browser playground adds another layer: controls must recompute immediately, Reset must be deterministic, Step and Play must share one transition, reduced-motion behavior must remain useful, and mobile layouts must not hide diagnostics.

A safe financial interpretation

Imagine the fixture represents validated returns, prices, durations, or model outputs. Before applying the formula, add currency, unit, calendar, corporate-action basis, observation time, availability time, source ownership, and missing-value policy. Without those fields, a mathematically correct result may describe the wrong economic object.

No result in this topic is investment advice. It is a reproducible educational calculation designed to make a later analytical decision easier to audit.

Checklist

• Is the question precise enough to choose this method?
• Are all inputs finite, aligned, correctly timed, and correctly scaled?
• Is the convention written beside the result?
• Does the worked output match count = 5; mean = 3.0?
• Did I inspect the scenario where the method is least informative?
• Did I avoid turning association into causation or description into prediction?
• Can another language reproduce the same fixture and failure behavior?
• Are source roles, synthetic labels, and historical-example decisions visible?

Takeaway

Welford's algorithm updates count, mean, and squared-deviation state without subtracting two large nearly equal totals. The formula is n←n+1; δ=x−mean; mean←mean+δ/n; M2←M2+δ(x−mean), and the canonical fixture produces count = 5; mean = 3.0. The answer becomes trustworthy only when its input contract, convention, and boundary travel with it.

Previous lesson: Stable Summation and Mean Calculation. Next lesson: Batch, Rolling, and Streaming Statistic Equivalence.