Skip to main content

Crate tpt_math_stats

Crate tpt_math_stats 

Source
Expand description

Descriptive statistics, hypothesis tests, and least-squares regression.

This crate is the workspace’s home for “classical” statistics. It implements its own distributions and special functions (see crate::dist and crate::special) behind a small, slice-oriented API that speaks plain &[f64] and returns plain tuples, so callers never have to build a distribution object just to get a p-value. No Apache-2.0 statrs dependency is pulled in.

§What’s here

§Conventions

  • Every function has a panicking short-named form and a checked try_* twin returning StatsError; the former is exactly the latter unwrapped.
  • Inputs must be finite. NaNs and infinities are rejected rather than silently poisoning a result.
  • Sample variance is Bessel-corrected (n - 1).
  • Tests return (statistic, p_value). t-test p-values are two-sided; chi-squared p-values are upper-tail. Both are evaluated through survival functions, so tiny p-values keep their precision.
  • Sums use compensated (Neumaier) accumulation and variances use the corrected two-pass formula, which keeps results accurate for long or badly offset samples.

§Examples

Is this sample drawn from a population with mean 100?

use tpt_math_stats::{mean, one_sample_t_test, std_dev};

let iq = [105.0, 98.0, 110.0, 102.0, 99.0, 107.0, 101.0, 103.0];
let (t, p) = one_sample_t_test(&iq, 100.0);

assert!(mean(&iq) > 100.0 && std_dev(&iq) > 0.0);
assert!(t > 0.0);
assert!(p < 0.10, "mildly suggestive, p = {p}");

Compare two groups, then fit a line:

use tpt_math_stats::{linear_regression, pearson_correlation, two_sample_t_test};

let control = [4.1, 3.9, 4.4, 4.0, 3.8];
let treated = [5.2, 5.5, 5.1, 5.4, 5.3];
let (_t, p) = two_sample_t_test(&control, &treated);
assert!(p < 0.001);

let dose = [0.0, 1.0, 2.0, 3.0, 4.0];
let response = [1.0, 3.0, 5.0, 7.0, 9.0];
assert_eq!(linear_regression(&dose, &response), (2.0, 1.0));
assert_eq!(pearson_correlation(&dose, &response), 1.0);

Goodness of fit for a categorical model:

use tpt_math_stats::chi_squared_goodness_of_fit;

// 100 draws that should have been split 25/25/25/25.
let observed = [22u64, 27, 24, 27];
let expected = [25.0; 4];
let (x2, p) = chi_squared_goodness_of_fit(&observed, &expected);
assert!(x2 < 1.0 && p > 0.5);

§Special functions and distributions

Anything outside the descriptive/hypothesis/regression surface is also available in-house (no Apache-2.0 statrs dependency): the special functions in special (error, gamma, beta and their regularized incomplete forms) and the distributions in dist (chi-squared, Student’s t, normal).

use tpt_math_stats::{ChiSquared, ContinuousCDF};

// Upper-tail probability of chi-squared(3) at 10.0: significant at 5%.
let chi = ChiSquared::new(3.0).unwrap();
let p = chi.sf(10.0);
assert!(p < 0.05);

The randomness traits from tpt-math-prob-core are re-exported too, which makes simulation studies against these tests a two-liner:

use tpt_math_stats::{mean, Distribution, SplitMix64, Standard};

let mut rng = SplitMix64::seed_from_u64(7);
let sample: Vec<f64> = (0..10_000).map(|_| Standard.sample(&mut rng)).collect();
assert!((mean(&sample) - 0.5).abs() < 0.02);

Re-exports§

pub use tpt_math_prob_core as prob_core;

Structs§

ChiSquared
A chi-squared distribution with k degrees of freedom.
KernelDensity
A fitted Gaussian kernel density estimate.
LogisticFit
The result of a logistic regression fit.
MultipleFit
The result of an ordinary least-squares fit with an intercept.
Normal
A normal (Gaussian) distribution with mean mu and standard deviation sigma.
SplitMix64
SplitMix64: a tiny, fast, deterministic 64-bit PRNG.
Standard
The standard uniform distribution over the type’s natural range.
StudentsT
Student’s t-distribution with location loc, scale scale, and df degrees of freedom.

Enums§

StatsError
Errors reported by the checked (try_*) entry points of this crate.

Traits§

ContinuousCDF
Cumulative and survival probabilities of a continuous distribution.
Distribution
A distribution that can produce samples of type T.
Rng
A source of pseudo-random bits.
Sampler
Bulk sampling for any Distribution.

Functions§

benjamini_hochberg
Benjamini–Hochberg correction. See try_benjamini_hochberg.
beta
The beta function B(a, b) = Γ(a)Γ(b) / Γ(a + b).
beta_reg
Regularized incomplete beta I_x(a, b): the CDF of Beta(a, b) at x.
bonferroni
Bonferroni correction. See try_bonferroni.
bootstrap_ci
Percentile bootstrap confidence interval. See try_bootstrap_ci.
chi_squared_goodness_of_fit
Pearson’s chi-squared goodness-of-fit test.
chi_squared_independence
Pearson’s chi-squared test of independence. See try_chi_squared_independence.
covariance
Sample covariance; see try_covariance.
erf
The error function erf(x) = 2/√π ∫₀ˣ e^{-t²} dt.
erfc
The complementary error function erfc(x) = 1 - erf(x).
excess_kurtosis
Population excess kurtosis; see try_excess_kurtosis.
gamma
The gamma function Γ(x), including its sign for negative non-integers.
gamma_p
Regularized lower incomplete gamma P(a, x) = γ(a, x) / Γ(a).
gamma_q
Regularized upper incomplete gamma Q(a, x) = Γ(a, x) / Γ(a) = 1 - P(a, x).
holm
Holm correction. See try_holm.
kernel_density
Panicking form of try_kernel_density.
kolmogorov_smirnov_two_sample
Two-sample Kolmogorov–Smirnov test. See try_kolmogorov_smirnov_two_sample.
lgamma
Natural logarithm of the absolute value of the gamma function, ln|Γ(x)|.
linear_regression
Ordinary least-squares fit of y = slope · x + intercept.
mann_whitney_u
Mann–Whitney U test. See try_mann_whitney_u.
max
Largest observation in samples.
mean
Arithmetic mean of samples.
median
Median of samples.
min
Smallest observation in samples.
one_sample_t_test
Student’s one-sample t-test of H₀: μ = mu0 against H₁: μ ≠ mu0.
one_way_anova
One-way ANOVA. See try_one_way_anova.
paired_t_test
Paired t-test of H₀: mean(a - b) = 0.
pearson_correlation
Pearson product-moment correlation coefficient of x and y.
pooled_t_test
Student’s pooled-variance two-sample t-test of H₀: μ_a = μ_b.
quantile
Sample p-quantile; see try_quantile.
skewness
Population skewness; see try_skewness.
std_dev
Sample standard deviation: the square root of variance.
try_benjamini_hochberg
Benjamini–Hochberg step-up correction, which controls the false discovery rate.
try_bonferroni
Bonferroni correction: p_adj = min(1, m · p) for m tests.
try_bootstrap_ci
Percentile bootstrap confidence interval for statistic(samples).
try_chi_squared_goodness_of_fit
Pearson’s chi-squared goodness-of-fit test.
try_chi_squared_independence
Pearson’s chi-squared test of independence on an r × c contingency table.
try_covariance
Sample covariance Σ(xᵢ − x̄)(yᵢ − ȳ) / (n − 1) of two paired samples.
try_excess_kurtosis
Population excess kurtosis m₄ / m₂² − 3 (zero for a normal distribution). Returns NaN for a constant sample.
try_holm
Holm step-down correction, which controls the family-wise error rate and is uniformly more powerful than Bonferroni.
try_kendall_tau
Kendall’s τ-b rank correlation, which corrects for ties in either sample.
try_kernel_density
Fit a Gaussian kernel density estimate.
try_kolmogorov_smirnov_two_sample
Two-sample Kolmogorov–Smirnov test.
try_linear_regression
Ordinary least-squares fit of y = slope · x + intercept.
try_logistic_regression
Fit P(y = 1) = σ(β₀ + β·x) by maximum likelihood, using Newton’s method (iteratively reweighted least squares).
try_mann_whitney_u
Mann–Whitney U test of two independent samples.
try_max
Largest observation in samples.
try_mean
Arithmetic mean of samples.
try_median
Median of samples: the middle observation, or the mean of the two middle observations when the sample size is even.
try_min
Smallest observation in samples.
try_multiple_regression
Fit y ≈ β₀ + β₁ x₁ + … + β_p x_p by least squares.
try_one_sample_t_test
Student’s one-sample t-test of H₀: μ = mu0 against H₁: μ ≠ mu0.
try_one_way_anova
One-way analysis of variance: do k groups share a common mean?
try_paired_t_test
Paired t-test of H₀: mean(a - b) = 0.
try_pearson_correlation
Pearson product-moment correlation coefficient of x and y.
try_pooled_t_test
Student’s pooled-variance two-sample t-test of H₀: μ_a = μ_b.
try_quantile
Sample p-quantile by linear interpolation between order statistics (type 7, the default of R and NumPy): h = (n − 1) p.
try_skewness
Population skewness m₃ / m₂^{3/2} (with mₖ the k-th central moment). Returns NaN for a constant sample.
try_spearman_correlation
Spearman rank correlation: the Pearson correlation of the average ranks.
try_std_dev
Sample standard deviation: the square root of try_variance.
try_two_sample_t_test
Welch’s unequal-variances two-sample t-test of H₀: μ_a = μ_b.
try_variance
Unbiased sample variance of samples (Bessel-corrected, n - 1 divisor).
try_wilcoxon_signed_rank
Wilcoxon signed-rank test for paired samples.
two_sample_t_test
Welch’s unequal-variances two-sample t-test of H₀: μ_a = μ_b.
variance
Unbiased sample variance of samples (Bessel-corrected, n - 1 divisor).
wilcoxon_signed_rank
Wilcoxon signed-rank test. See try_wilcoxon_signed_rank.