Crate matten_stats 

matten-stats — small, explicit statistics over matten::Tensor.

This companion crate (RFC-078, RFC-083, RFC-090) provides seven statistics APIs RFC-040 §8 deliberately kept out of core: covariance, covariance_population, correlation, quantile, skewness, kurtosis, and histogram. It depends only on core matten (no default features) — no third-party dependency of any kind.

The matten-mlprep boundary (RFC-078 §5, amended RFC-090 §5)

matten-mlprep transforms tensors for ML pipelines: Tensor -> Tensor. matten-stats computes statistical summaries of a Tensor: a summary is returned as f64 where it is scalar, and as a small owned struct (e.g. Histogram) where it is inherently vector-valued. matten-stats never returns a Tensor. No function appears in both crates.

Estimator conventions (RFC-078 §4.1, RFC-083 §4.1)

Core matten’s var/std are population statistics (ddof = 0). Each function below matches the convention its ecosystem name is expected to carry — the estimator differs per function, deliberately, because the ecosystem’s own defaults differ per function:

covariance             sample,     ddof = 1        (NumPy/R/pandas `cov`/`corrcoef` default)
covariance_population  population, ddof = 0        (explicit in the name; no default to choose)
correlation            ddof-invariant                (the `n - 1` factors cancel; see below)
skewness               g1,  uncorrected               (SciPy `skew(bias=True)` default; NOT pandas' `.skew()`)
kurtosis               g2,  uncorrected, EXCESS        (SciPy `kurtosis(fisher=True, bias=True)` default; NOT pandas' `.kurt()`)

correlation is unaffected by the ddof choice (the n - 1 factors cancel algebraically); only covariance is a genuine policy decision. pandas’ .skew()/.kurt() bias-correct and so return a different number than skewness/kurtosis for the same input — this must not be assumed away. This is a deliberate divergence, not an oversight; a reader must not have to discover it empirically.

Quantile method (RFC-078 §4.2)

quantile uses linear interpolation between the two nearest ranks of the sorted sample (NumPy’s "linear" method). No alternative method (nearest, lower, higher, midpoint) is provided.

Status

Production-ready candidate (RFC-084), promoted once the six-function surface settled (RFC-083). The candidate label denotes a settled surface and a narrowed recommendation, not field-tested usage history — this crate has none. Under lock-step family versioning (RFC-030) the crate shares the workspace family version; maturity is the Status label, not the version number.

use matten::Tensor;
use matten_stats::{correlation, covariance, quantile};

let x = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[4]);
let y = Tensor::new(vec![2.0, 4.0, 6.0, 8.0], &[4]);

let cov = covariance(&x, &y).unwrap();
let r = correlation(&x, &y).unwrap();
let median = quantile(&x, 0.5).unwrap();
assert!((r - 1.0).abs() < 1e-9);
assert_eq!(median, 2.5);

Structs

Histogram

A histogram’s per-bin counts and the edges that define them.

Enums

MattenStatsError

Errors produced by matten-stats functions.

Functions

correlation

Pearson correlation of x and y: cov(x, y) / (std_sample(x) * std_sample(y)).

covariance

Sample covariance of x and y: Σ (xi - mean_x)(yi - mean_y) / (n - 1).

covariance_population

Population covariance of x and y: Σ (xi - mean_x)(yi - mean_y) / n (RFC-083 §4.1, §4.2).

histogram

Bins x into bins equal-width intervals spanning [min(x), max(x)].

kurtosis

Excess kurtosis of x: m4 / m2^2 - 3.0 (RFC-083 §4.1, §4.2) — the uncorrected g2 estimator (SciPy’s kurtosis(fisher=True, bias=True) default), not pandas’ .kurt() (which bias-corrects and would return a different number for the same input).

quantile

The q-quantile of x, using linear interpolation between the two nearest ranks of the sorted sample — NumPy’s "linear" method:

skewness

Skewness of x: m3 / m2^(3/2) (RFC-083 §4.1, §4.2) — the uncorrected g1 estimator (SciPy’s skew(bias=True) default), not pandas’ .skew() (which bias-corrects and would return a different number for the same input).