vstat
Descriptive statistics, correlation, regression, histograms, streaming moments, and image-quality metrics.
| Quick fact | Value |
|---|---|
| Module | vstat |
| Import | use external "vstat/vstat.vy"; |
| Depends on | vmath |
| Status | Unstable — the public surface may change between releases. |
This page is generated from the library's in-repo manual (vyne/modules/external/vstat/README.md) so signatures and behaviour stay aligned with the source tree. Examples assume a desktop target unless the text says otherwise.
vstat is the descriptive-statistics and least-squares layer for Vyne. It is written in Vyne, in the same kernel/wrapper pattern as vlin: Kernels.vy holds the unboxed loops, the other leaves validate and allocate, and vstat.vy re-exports the whole surface.
Why a Series
A Series pairs a typed Array<Float64> with its length:
Passing a Series keeps the data pointer and the length together, which is what lets a wrapper call the k_* kernels with unboxed double* arguments. If you already have a typed array, use vstat.Series(data, data.size()) (no copy). If you have a boxed Array, vstat.from_array(xs) copies it once and returns a Series.
API
Construction and conversion
| Function | Result |
|---|---|
vstat.Series(data, n) | interface constructor; no copy |
vstat.from_array(xs :: Array) | copy a boxed array into a Series |
vstat.to_array(s) | copy a Series into Array<Float64> |
vstat.sorted_copy(s) | ascending copy |
vstat.rank(s) | average ranks, ties shared |
Reductions
| Function | Result |
|---|---|
sum(s) | sum |
mean(s) | arithmetic mean |
minimum(s) / maximum(s) | extrema |
range(s) | maximum - minimum |
variance(s, sample) | population or sample variance |
stddev(s, sample) | square root of variance |
median(s) | 50th percentile |
quantile(s, q) | linearly interpolated quantile, q in [0,1] |
percentile(s, p) | quantile(s, p/100) |
iqr(s) | interquartile range |
mad(s) | median absolute deviation |
mode(s) | most frequent value (first in sorted order on ties) |
weighted_mean(s, weights) | weighted arithmetic mean |
summary(s) | Summary { n, mean, variance, stddev, minimum, maximum, median } |
Derived series
zscore, standardize (alias), minmax_normalize, abs_series, cumulative_sum, difference.
Association
| Function | Result |
|---|---|
covariance(a, b, sample) | covariance |
pearson(a, b) | Pearson correlation |
spearman(a, b) | Spearman rank correlation |
autocorrelation(s, lag) | correlation of s with its lagged self |
cross_correlation(a, b, lag) | correlation of a with lagged b |
r_squared(y, y_hat) | coefficient of determination |
Regression
| Function | Result |
|---|---|
linear(x, y) | LinearFit { slope, intercept, r2 } |
predict(fit, x) | slope*x + intercept |
residuals(x, y, fit) | observed minus predicted Series |
multiple(X, y, rows, cols) | least-squares coefficients as a Series |
ridge(X, y, rows, cols, alpha) | ridge coefficients |
predict_row(beta, row) | dot product of coefficients and one design row |
X is row-major and must already include an intercept column if the model needs one. The normal equations use a local partial-pivot Gaussian solve; vdecomp will provide the full LU/QR/eigen surface.
Image and error metrics
| Function | Result |
|---|---|
mse(a, b) | mean squared error |
mae(a, b) | mean absolute error |
psnr(a, b, max_value) | peak signal-to-noise ratio in dB; identical inputs return 100 dB |
ssim(a, b, width, height, channels) | mean SSIM over HWC [0,1] buffers using an 8x8 uniform window |
psnr takes the data range explicitly (1.0 for normalised images, 255.0 for 8-bit buffers). ssim expects width * height * channels samples in HWC order, the same layout vimage.Image uses. The window is uniform rather than Gaussian; state that when reporting numbers against published SSIM values.
Histograms and density
| Function | Result |
|---|---|
histogram(s, bins) | equal-width Histogram { edges, counts } |
histogram_range(s, bins, lo, hi) | histogram over an explicit range |
bin_edges(h) / bin_counts(h) | the histogram arrays |
density(h) | count / (total · width) per bin |
cdf(h) | cumulative counts / total |
empirical_cdf(s, x) | fraction of samples <= x |
quantiles(s, ps) | one quantile per probability in ps |
kde(s, bandwidth, grid) | Gaussian kernel density estimate on grid |
Streaming (one pass)
| Function | Result |
|---|---|
welford_new() | empty Welford state |
welford_add(state, x) | state + one sample |
welford_variance(state, sample) | variance |
welford_stddev(state, sample) | standard deviation |
welford_merge(a, b) | merge two chunk states |
welford_from_series(s) | fold a whole series |
wcov_new() | empty bivariate state |
wcov_add(state, x, y) | state + one pair |
wcov_covariance(state, sample) | covariance |
wcov_variance_x/y(state, sample) | per-variable variance |
wcov_pearson(state) | Pearson correlation |
wcov_from_series(x, y) | fold two series |
Semantics and limits
- Empty inputs throw for reductions that have no defined value (
mean,median,minimum, …).sumof an emptySeriesis0. variance,stddev,covariance, and the Welford variants take asampleflag.falseis population,trueis sample (n−1). Sample variants need at least two values.median,quantile,iqr, andmodecopy and sort the input; the input is never mutated.spearmanuses O(n²) average ranking. It is correct for ties and fine for the usual few-thousand-sample analysis; usevstat.rank+pearsondirectly if you need a different rank strategy.kdeuses an isotropic Gaussian kernel with the caller's bandwidth.