stats.percentile

def percentile(values: Sequence[float], p: float, method: PercentileMethod, decimals: int) -> float

PercentileMethod = Literal["nearest-rank", "linear"]

from fune.stats.percentile import percentile  # stats.percentile@^2

import math
from typing import Sequence

from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune
from .stats_percentile_types import PercentileMethod


def _finite(value: object) -> bool:
    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)


def percentile(values: Sequence[float], p: float, method: PercentileMethod, decimals: int) -> float:
    """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.
    """
    if isinstance(values, (str, bytes)) or not isinstance(values, (list, tuple)):
        raise TypeError("values must be a list of numbers")
    if len(values) == 0:
        raise ValueError("values must not be empty")
    for v in values:
        if not _finite(v):
            raise TypeError("values must be finite numbers, received %r" % (v,))
    if not _finite(p) or p < 0 or p > 100:
        raise ValueError("p must be between 0 and 100, received %r" % (p,))
    # Checked up front as well as in round_float (same wording), so a bad
    # decimals is reported before the method is looked at, as in 1.x.
    if isinstance(decimals, bool) or not isinstance(decimals, int) or decimals < 0 or decimals > 12:
        raise ValueError("decimals must be a whole number from 0 to 12, received %r" % (decimals,))

    # float() first so integer inputs follow exactly the binary64 path the
    # other languages take.
    ordered = sorted(float(v) for v in values)
    n = len(ordered)
    p = float(p)

    if method == "nearest-rank":
        # The smallest value with at least p% of the sample at or below it.
        rank = math.ceil((p * n) / 100.0)
        if rank < 1:
            rank = 1
        result = ordered[rank - 1]
    elif method == "linear":
        # Hyndman & Fan type 7: zero-based position (n - 1) * p / 100.
        h = ((n - 1) * p) / 100.0
        lo = math.floor(h)
        if lo >= n - 1:
            result = ordered[n - 1]
        else:
            result = ordered[lo] + (h - lo) * (ordered[lo + 1] - ordered[lo])
    else:
        raise ValueError('unknown percentile method "%s"' % (method,))
    # math.round-float rounds on the exact value of the double: 2.675 gives 2.67.
    return round_float(result, decimals)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./stats.percentile-2.0.0-python.fune, or fetch it from a terminal with fune pull stats.percentile@2.0.0:python.

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