stats.percentile

export function percentile(values: readonly number[], p: number, method: PercentileMethod, decimals: number): number

export type PercentileMethod = "nearest-rank" | "linear";

import { percentile } from "#fune/stats.percentile@^2";

import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune
import { type PercentileMethod } from "./stats_percentile_types.ts";

/**
 * The p-th percentile of `values` by a named method.
 *
 * There is no single "95th percentile": the caller names the definition, so
 * a dashboard and a billing job cannot quietly disagree.
 */
export function percentile(values: readonly number[], p: number, method: PercentileMethod, decimals: number): number {
  if (!Array.isArray(values)) throw new TypeError("values must be a list of numbers");
  if (values.length === 0) throw new RangeError("values must not be empty");
  for (const v of values) {
    if (typeof v !== "number" || !Number.isFinite(v)) {
      throw new TypeError(`values must be finite numbers, received ${v}`);
    }
  }
  if (typeof p !== "number" || !Number.isFinite(p) || p < 0 || p > 100) {
    throw new RangeError(`p must be between 0 and 100, received ${p}`);
  }
  // Checked up front as well as in roundFloat (same wording), so a bad
  // decimals is reported before the method is looked at, as in 1.x.
  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 12) {
    throw new RangeError(`decimals must be a whole number from 0 to 12, received ${decimals}`);
  }

  const sorted = [...values].sort((a, b) => a - b);
  const n = sorted.length;

  let result: number;
  if (method === "nearest-rank") {
    // The smallest value with at least p% of the sample at or below it.
    let rank = Math.ceil((p * n) / 100);
    if (rank < 1) rank = 1;
    result = sorted[rank - 1];
  } else if (method === "linear") {
    // Hyndman & Fan type 7: zero-based position (n - 1) * p / 100.
    const h = ((n - 1) * p) / 100;
    const lo = Math.floor(h);
    if (lo >= n - 1) {
      result = sorted[n - 1];
    } else {
      result = sorted[lo] + (h - lo) * (sorted[lo + 1] - sorted[lo]);
    }
  } else {
    throw new RangeError(`unknown percentile method "${method}"`);
  }
  // math.round-float rounds on the exact value of the double: 2.675 gives 2.67.
  return roundFloat(result, decimals);
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 1 dependency, 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.percentile

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

The whole function, every language, is one file too: stats.percentile-2.0.0.fune, 16,571 bytes, sha256 4693d39eb07fa564946633d58010c57ca84c722206051c511be28ab988b4f316. It installs into a project of any language.

// fune: before stats.percentile

// fune: after stats.percentile

// fune: replace math.round-float in stats.percentile

// fune: step stats.percentile after <n|label>

More from the author

Both methods give the minimum at p = 0 and the maximum at p = 100. The input is sorted numerically on a copy and never mutated.

**Precision.** The result is rounded to `decimals` places (0 to 12) by `math.round-float`: half away from zero, decided on the exact value of the double. So 0.5 rounds to 1 and -0.5 to -1 (Python's `round()` would give 0), -0 is returned as 0, and 2.675, which is stored as 2.67499999999999982..., rounds to 2.67 at two places.

**Why the three languages agree to the bit.** Only IEEE-754 addition, subtraction, multiplication, division and floor are used, in the same order in every language, and each of those is correctly rounded by the standard. No library function whose last bit can differ between platforms (exp, log, sin) is involved, so the unrounded result is the same double everywhere and the rounding step, `math.round-float`, which is itself bit-identical in all three, cannot split them. Position and rank are computed as (n - 1) x p / 100 and p x n / 100, in that order.

## Changes in 2.0.0

2.0.0 rounds on the exact value of the double, so a percentile of 2.675 now gives 2.67 at two places. 1.x rounded the scaled product instead (floor of |x| x 10^decimals, compared with a half), and 2.675 x 100 is exactly 267.5 in floating point, so 1.x said 2.68. The private rounding helper is gone: this version requires `math.round-float ^1.0.0` and rounds with it, so every float capability in the registry rounds alike.

None of the 1.x vectors changed answers (each was recomputed from the exact value of its double). New vectors pin the difference: the linear 50th percentile of 2.6 and 2.75 gives 2.67 (1.x 2.68), of -2.75 and -2.6 gives -2.67 (1.x -2.68), the nearest-rank member 2.675 gives 2.67 (1.x 2.68), and 1.45 at one place gives 1.4 (1.x 1.5); 8.345, stored just above its tie, still gives 8.35.

`decimals` is still 0 to 12, and still refused up front with the same message ("decimals must be a whole number from 0 to 12"), before the method is looked at, as in 1.x.

Sources: R. J. Hyndman and Y. Fan, "Sample Quantiles in Statistical Packages", The American Statistician 50(4), 1996, pp. 361-365; Microsoft, "PERCENTILE.INC function" (support.microsoft.com); NIST/SEMATECH e-Handbook of Statistical Methods, section 7.2.6.2 "Percentiles".

Files