stats.standard-deviation

export function standardDeviation(values: readonly number[], kind: DeviationKind, decimals: number): number

export type DeviationKind = "population" | "sample";

import { standardDeviation } from "#fune/stats.standard-deviation@^1";

import { type DeviationKind } from "./stats_standard_deviation_types.ts";

const POW10 = [1, 10, 100, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12];

// Half away from zero on the binary64 value. A deviation is never negative,
// so there is no sign to restore.
function roundTo(x: number, decimals: number): number {
  const scale = POW10[decimals];
  const y = x * scale;
  let r = Math.floor(y);
  if (y - r >= 0.5) r += 1;
  return r / scale + 0;
}

/**
 * Population or sample standard deviation, two-pass.
 *
 * The one-pass "mean of squares minus square of mean" shortcut cancels
 * catastrophically on large, close values; two passes do not.
 */
export function standardDeviation(values: readonly number[], kind: DeviationKind, decimals: number): number {
  if (!Array.isArray(values)) throw new TypeError("values must be a list of numbers");
  for (const v of values) {
    if (typeof v !== "number" || !Number.isFinite(v)) {
      throw new TypeError(`values must be finite numbers, received ${v}`);
    }
  }
  if (kind !== "population" && kind !== "sample") {
    throw new RangeError(`unknown standard deviation kind "${kind}"`);
  }
  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 12) {
    throw new RangeError(`decimals must be a whole number from 0 to 12, received ${decimals}`);
  }
  const n = values.length;
  if (n === 0) throw new RangeError("values must not be empty");
  if (kind === "sample" && n < 2) {
    throw new RangeError("sample standard deviation needs at least 2 values");
  }

  let sum = 0;
  for (const v of values) sum += v;
  const mean = sum / n;
  let squares = 0;
  for (const v of values) {
    const d = v - mean;
    squares += d * d;
  }
  return roundTo(Math.sqrt(squares / (kind === "sample" ? n - 1 : n)), decimals);
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add stats.standard-deviation

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./stats.standard-deviation-1.0.0-typescript.fune, or fetch it from a terminal with fune pull stats.standard-deviation@1.0.0:typescript.

The whole function, every language, is one file too: stats.standard-deviation-1.0.0.fune, 12,588 bytes, sha256 aea4bddbb12330d26f7bdff755ca24697691ed9aece2b97892c034b13986048d. It installs into a project of any language.

// fune: before stats.standard-deviation

// fune: after stats.standard-deviation

// fune: step stats.standard-deviation after <n|label>

More from the author

**Algorithm.** Two passes: the mean first, then the sum of squared deviations from it. The one-pass textbook shortcut, mean of squares minus square of the mean, cancels catastrophically when the values are large and close together (four readings near one billion come out as garbage or even a negative variance); the vectors include that case.

**Precision.** The result is rounded to `decimals` places, half away from zero, applied to the binary64 value: y = x x 10^decimals, r = floor(y), plus one if y - r >= 0.5, divided back by 10^decimals. So a deviation of exactly 0.5 rounds to 1 at zero places, where Python's `round()` gives 0.

**Why the three languages agree to the bit.** Sums run left to right, and only IEEE-754 +, -, x, /, square root and floor are used. All of these are correctly rounded by the standard (square root included, unlike sin or exp, whose last bit varies between math libraries), so TypeScript, Python and Rust hold the same double before rounding and return the same rounded value.

Sources: NIST/SEMATECH e-Handbook of Statistical Methods, section 1.3.5.6 "Measures of Scale"; B. P. Welford, "Note on a Method for Calculating Corrected Sums of Squares and Products", Technometrics 4(3), 1962, on why the one-pass formula fails.

Files