Module descriptive 

Descriptive statistics — zero-allocation kernels over caller-owned slices.

These are the single source of truth for descriptive statistics in the engine. Domain/specialized libraries MUST call these rather than re-implementing mean/variance/etc. inline (Modality-First Composition; see MODALITY_FIRST_CONSOLIDATION.md).

Every function operates on a slice the caller already owns — no Vec, no allocation, no copy. median_in_place sorts the caller’s buffer with the non-allocating sort_unstable_by; the caller decides whether to clone first. None is returned for an empty slice so callers can map it onto their own error type without this layer inventing one.

Functions

argmax

Index of the maximum value (the first on a tie) — the argmax selection used for greedy token decoding (choose the highest-scoring logit). None for an empty slice. Non-finite values compare by the usual > (a NaN never wins).

covariance

Covariance of two equal-length series. sample == true divides by n-1 (Bessel), else by n. None if the lengths differ or are empty.

kurtosis

Excess kurtosis (g2 = m₄ / m₂² − 3); 0 for a normal distribution. None if empty; Some(0.0) for a constant series.

max

Maximum element by total-order comparison. None if empty.

mean

Arithmetic mean. None if empty.

median_in_place

Median, sorting the caller’s buffer in place (no allocation). None if empty.

median_sorted

Median of a slice that is already sorted ascending. None if empty. For an even count, returns the mean of the two central elements.

min

Minimum element by total-order comparison. None if empty.

mode_in_place

Mode — the most frequently occurring value, with its count.

quantile_in_place

Quantile, sorting the caller’s buffer in place (no allocation). None if empty.

quantile_sorted

Linear-interpolated quantile of an already-sorted-ascending slice (the numpy “linear” / R type-7 convention). q is clamped to [0,1]. None if empty.

skewness

Sample skewness (Fisher–Pearson, g1 = m₃ / m₂^{3/2}), the standardised third moment. None if empty; Some(0.0) for a constant series (zero spread).

std_dev

Standard deviation = sqrt(variance). None if empty.

sum

Sum of all elements. Zero for an empty slice.

variance

Variance. sample == true uses Bessel’s correction (divide by n-1); otherwise the population variance (divide by n). None if empty.