Skip to content

stats #

Descriptive sample statistics

stats.summarize computes count, mean, variance, standard deviation, minimum, and maximum in one pass using Welford's online moment update.

ddof: 0 returns population variance; ddof: 1 returns sample variance. The input must be non-empty and ddof must be valid for the observations used. The existing API rejects non-finite samples. summarize_with_policy accepts NonFinitePolicy.reject, .omit, or .propagate: omission updates the count and degrees of freedom using finite values only; propagation returns NaN for numeric summary statistics when any sample is non-finite, while count reports the input length. Variance and standard deviation are returned as f64.

stats.quantile(values, q) and stats.percentile(values, p) sort a copy and use linear interpolation (Type 7, the NumPy/SciPy default). The quantile_with_method and percentile_with_method variants also support all thirteen estimators exposed by NumPy through QuantileMethod, including the Hyndman-Fan estimators and lower, higher, midpoint, and nearest. The available methods are inverted_cdf, averaged_inverted_cdf, closest_observation, interpolated_inverted_cdf, hazen, weibull, linear, median_unbiased, normal_unbiased, lower, higher, midpoint, and nearest. Probabilities must be finite and lie in [0, 1] or [0, 100]. Existing quantile APIs reject non-finite samples and do not modify the input slice. quantile_with_policy, percentile_with_policy, and their method variants accept the same policies: .omit filters non-finite samples, while .propagate returns NaN if any sample is non-finite.

stats.quantile_weighted(values, weights, q) and stats.percentile_weighted(values, weights, p) implement NumPy's weighted inverted-CDF method. Weights must be non-negative, match the sample length, and have positive finite total mass. The existing APIs reject non-finite values and weights. Policy variants omit any pair with a non-finite value or weight; propagation returns NaN for non-finite positive-mass values and rejects non-finite weights because their contribution is undefined. Finite negative weights remain invalid under every policy.

vsl.dist.WeightedHistogram.count(values, weights, clear) accumulates non-negative bin weights and returns the total input weight, including samples outside the configured range. density(total_weight) uses that total for normalization, so the integrated density is the in-range weight fraction. The histogram count_with_policy and automatic-bin *_with_policy variants can omit non-finite observations. Since integer counts and bin-edge selection cannot meaningfully propagate NaN, their .propagate policy returns an error when a non-finite sample is present. Existing histogram calls retain their previous behavior. vsl.dist.histogram_bin_edges(values, rule) selects edges with NumPy's auto, fd, doane, scott, stone, rice, sturges, or sqrt rule. Use histogram_bin_edges_in_range to select edges over an explicit interval.

import math
import vsl.stats

summary := stats.summarize([2.0, 4.0, 6.0], 1)!
println('mean=${summary.mean}, sample stddev=${summary.stddev}')

sample := [1.0, math.nan(), 3.0]
finite_summary := stats.summarize_with_policy(sample, 0, .omit)!
propagated_median := stats.quantile_with_policy(sample, 0.5, .propagate)!
println('finite count=${finite_summary.count}, propagated median=${propagated_median}')

See the runnable descriptive statistics example for summaries, quantiles, and automatic histogram bins. Inferential tests and confidence intervals are tracked separately in VSL issue #572.

fn percentile #

fn percentile(values []f64, p f64) !f64

percentile returns the requested percentile using linear interpolation. p is expressed on the inclusive range [0, 100].

fn percentile_weighted #

fn percentile_weighted(values []f64, weights []f64, p f64) !f64

percentile_weighted is the 0..100-scale form of quantile_weighted.

fn percentile_weighted_with_policy #

fn percentile_weighted_with_policy(values []f64, weights []f64, p f64, policy NonFinitePolicy) !f64

percentile_weighted_with_policy is the 0..100-scale weighted quantile.

fn percentile_with_method #

fn percentile_with_method(values []f64, p f64, method QuantileMethod) !f64

percentile_with_method is the 0..100-scale form of quantile_with_method.

fn percentile_with_method_and_policy #

fn percentile_with_method_and_policy(values []f64, p f64, method QuantileMethod, policy NonFinitePolicy) !f64

percentile_with_method_and_policy is the 0..100-scale policy variant.

fn percentile_with_policy #

fn percentile_with_policy(values []f64, p f64, policy NonFinitePolicy) !f64

percentile_with_policy is the 0..100-scale form of quantile_with_policy.

fn quantile #

fn quantile(values []f64, q f64) !f64

quantile returns the requested quantile using linear interpolation between adjacent sorted values (the default Type 7 definition used by NumPy/SciPy).

fn quantile_weighted #

fn quantile_weighted(values []f64, weights []f64, q f64) !f64

quantile_weighted returns NumPy's inverted-CDF weighted quantile. Weights represent non-negative sample mass, and values/weights must have equal lengths. Non-finite samples or weights are rejected.

fn quantile_weighted_with_policy #

fn quantile_weighted_with_policy(values []f64, weights []f64, q f64, policy NonFinitePolicy) !f64

quantile_weighted_with_policy uses NumPy's inverted-CDF weighted quantile. Under omit, any pair with a non-finite value or weight is excluded. Propagate returns NaN when a positive-mass pair contains a non-finite value; invalid weights remain errors because their contribution is undefined.

fn quantile_with_method #

fn quantile_with_method(values []f64, q f64, method QuantileMethod) !f64

quantile_with_method returns a quantile using the selected estimator. It sorts a copy and rejects empty or non-finite samples.

fn quantile_with_method_and_policy #

fn quantile_with_method_and_policy(values []f64, q f64, method QuantileMethod, policy NonFinitePolicy) !f64

quantile_with_method_and_policy applies a quantile estimator and an explicit policy for non-finite samples.

fn quantile_with_policy #

fn quantile_with_policy(values []f64, q f64, policy NonFinitePolicy) !f64

quantile_with_policy returns a linear quantile using the selected non-finite sample policy.

fn summarize #

fn summarize(values []f64, ddof int) !Summary

summarize computes stable online moments and extrema for a non-empty sample. ddof is the delta degrees of freedom: 0 gives population variance, 1 gives sample variance. Non-finite values are rejected rather than silently skipped.

fn summarize_with_policy #

fn summarize_with_policy(values []f64, ddof int, policy NonFinitePolicy) !Summary

summarize_with_policy computes stable moments using the selected policy. Omitted samples do not contribute to count or degrees of freedom. Propagate returns NaN for numeric statistics when any sample is non-finite; count remains the number of input observations.

fn NonFinitePolicy.from #

fn NonFinitePolicy.from[W](input W) !NonFinitePolicy

from returns the NonFinitePolicy value of an integer or of a field name, or an error if there is none.

fn QuantileMethod.from #

fn QuantileMethod.from[W](input W) !QuantileMethod

from returns the QuantileMethod value of an integer or of a field name, or an error if there is none.

enum NonFinitePolicy #

enum NonFinitePolicy {
	reject
	omit
	propagate
}

NonFinitePolicy controls how descriptive statistics handle NaN and infinity.

enum QuantileMethod #

enum QuantileMethod {
	inverted_cdf
	averaged_inverted_cdf
	closest_observation
	interpolated_inverted_cdf
	hazen
	weibull
	linear
	median_unbiased
	normal_unbiased
	lower
	higher
	midpoint
	nearest
}

QuantileMethod selects one of NumPy's thirteen sample-quantile estimators.

struct Summary #

struct Summary {
pub:
	count    int
	mean     f64
	variance f64
	stddev   f64
	min      f64
	max      f64
}

Summary contains single-pass descriptive statistics for finite f64 samples.