# stats.percentile

"The 95th percentile" is not one number: statistics packages disagree, and
Hyndman and Fan catalogue nine definitions. This capability makes the caller
name the one they mean.

- `nearest-rank`: the smallest value with at least p% of the sample at or
  below it. Rank = ceil(p/100 x n), and p = 0 gives the minimum. The answer is
  always a member of the list, which is what SLAs usually mean by "p95
  latency". This is Hyndman and Fan's type 1 (the inverse of the empirical
  distribution function).
- `linear`: interpolate between the two closest ranks at position
  h = (n - 1) x p/100 (zero-based), giving x[floor h] + (h - floor h) x
  (x[floor h + 1] - x[floor h]). This is Hyndman and Fan's type 7, the default
  in R (`quantile(type = 7)`) and NumPy (`method="linear"`), and Excel's
  `PERCENTILE.INC` (with p as a fraction there).

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, 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, with the sign restored. So 0.5
rounds to 1 and -0.5 to -1 (Python's `round()` would give 0), and -0 is
returned as 0.

**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 cannot split them. Position and rank are computed as
(n - 1) x p / 100 and p x n / 100, in that order.

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".