Statistics¶

def summarize(series: Series, *, ddof: int = 1) -> Summary:
    """Compute descriptive statistics for ``series`` in a single pass.

    Args:
        series: The observations to summarise.
        ddof: Delta degrees of freedom for the variance. Use ``1`` for the
            unbiased sample variance (the default) or ``0`` for the population
            variance.

    Returns:
        A frozen [`Summary`][mypackage.Summary].

    Raises:
        EmptySeriesError: If ``series`` is empty.
        ValidationError: If ``ddof`` is negative or not smaller than the
            number of observations.

    Examples:
        >>> summary = summarize([2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0], ddof=0)
        >>> summary.count, summary.mean, summary.variance
        (8, 5.0, 4.0)
        >>> summary.minimum, summary.median, summary.maximum
        (2.0, 4.5, 9.0)

        A single observation has no unbiased variance, so use ``ddof=0``:

        >>> summarize([3.0], ddof=0).variance
        0.0

        The mean survives inputs whose sum would overflow:

        >>> summarize([1e308, 1e308], ddof=0).mean
        1e+308
    """
    values = require_non_empty(series)
    count = len(values)
    if ddof < 0:
        msg = f"'ddof' must be non-negative, got {ddof}"
        raise ValidationError(msg)
    if ddof >= count:
        msg = (
            f"'ddof' must be smaller than the number of observations, "
            f"got ddof={ddof} with {count} value(s)"
        )
        raise ValidationError(msg)

    mean = _mean(values)
    # `d * d` rather than `d ** 2`: float `**` raises OverflowError, whereas
    # multiplication overflows to inf, which is the honest IEEE answer when
    # the variance itself is not representable.
    variance = math.fsum(d * d for d in (value - mean for value in values)) / (
        count - ddof
    )
    return Summary(
        count=count,
        mean=mean,
        variance=variance,
        minimum=min(values),
        maximum=max(values),
        median=quantile(values, 0.5),
        ddof=ddof,
    )

def quantile(series: Series, q: float) -> float:
    """Return the ``q``-th quantile using linear interpolation.

    With sorted observations x_(1) ≤ … ≤ x_(N) and the fractional position
    h = q (N − 1), the result is

    Q(q) = x_(j+1) + (h − j) (x_(j+2) − x_(j+1)),  with j = ⌊h⌋.

    This matches NumPy's default ``method="linear"``.

    Args:
        series: The observations.
        q: Quantile level in ``[0, 1]``.

    Returns:
        The interpolated quantile.

    Raises:
        EmptySeriesError: If ``series`` is empty.
        ValidationError: If ``q`` lies outside ``[0, 1]``.

    Examples:
        >>> data = [1.0, 2.0, 3.0, 4.0]
        >>> quantile(data, 0.0), quantile(data, 0.5), quantile(data, 1.0)
        (1.0, 2.5, 4.0)
        >>> round(quantile(data, 0.25), 4)
        1.75
    """
    values = sorted(require_non_empty(series))
    if not 0.0 <= q <= 1.0:
        msg = f"'q' must lie in [0, 1], got {q!r}"
        raise ValidationError(msg)

    if len(values) == 1:
        return values[0]

    position = q * (len(values) - 1)
    lower = math.floor(position)
    upper = math.ceil(position)
    if lower == upper:
        return values[lower]
    weight = position - lower
    return values[lower] * (1.0 - weight) + values[upper] * weight

def zscores(series: Series, *, ddof: int = 1) -> list[float]:
    """Standardise ``series`` to zero mean and unit variance.

    zᵢ = (xᵢ − x̄) / s,  with x̄ the mean and s the standard deviation.

    Args:
        series: The observations to standardise.
        ddof: Delta degrees of freedom for the standard deviation.

    Returns:
        A new list of standardised values.

    Raises:
        EmptySeriesError: If ``series`` is empty.
        ValidationError: If the series is constant, so ``s == 0``.

    Examples:
        >>> [round(z, 4) for z in zscores([1.0, 2.0, 3.0])]
        [-1.0, 0.0, 1.0]
        >>> try:
        ...     zscores([2.0, 2.0, 2.0])
        ... except ValidationError as err:
        ...     print(err)
        cannot standardise a constant series (std == 0)
    """
    values = require_non_empty(series)
    summary = summarize(values, ddof=ddof)
    std = summary.std
    if std == 0.0:
        msg = "cannot standardise a constant series (std == 0)"
        raise ValidationError(msg)
    return [(value - summary.mean) / std for value in values]