Skip to main content

tpt_math_stats/
lib.rs

1#![forbid(unsafe_code)]
2#![warn(missing_docs, missing_debug_implementations)]
3#![warn(clippy::all)]
4
5//! Descriptive statistics, hypothesis tests, and least-squares regression.
6//!
7//! This crate is the workspace's home for "classical" statistics. It implements
8//! its own distributions and special functions (see `crate::dist` and
9//! `crate::special`) behind a small, slice-oriented API that speaks plain
10//! `&[f64]` and returns plain tuples, so callers never have to build a
11//! distribution object just to get a p-value. No Apache-2.0 `statrs` dependency
12//! is pulled in.
13//!
14//! # What's here
15//!
16//! | Area | Functions |
17//! |------|-----------|
18//! | Descriptive | [`mean`], [`variance`], [`std_dev`], [`min`], [`max`], [`median`] |
19//! | Hypothesis tests | [`one_sample_t_test`], [`two_sample_t_test`], [`chi_squared_goodness_of_fit`] |
20//! | Regression | [`pearson_correlation`], [`linear_regression`] |
21//!
22//! # Conventions
23//!
24//! * Every function has a panicking short-named form and a checked `try_*`
25//!   twin returning [`StatsError`]; the former is exactly the latter unwrapped.
26//! * Inputs must be finite. `NaN`s and infinities are rejected rather than
27//!   silently poisoning a result.
28//! * Sample variance is Bessel-corrected (`n - 1`).
29//! * Tests return `(statistic, p_value)`. t-test p-values are two-sided;
30//!   chi-squared p-values are upper-tail. Both are evaluated through survival
31//!   functions, so tiny p-values keep their precision.
32//! * Sums use compensated (Neumaier) accumulation and variances use the
33//!   corrected two-pass formula, which keeps results accurate for long or
34//!   badly offset samples.
35//!
36//! # Examples
37//!
38//! Is this sample drawn from a population with mean 100?
39//!
40//! ```
41//! use tpt_math_stats::{mean, one_sample_t_test, std_dev};
42//!
43//! let iq = [105.0, 98.0, 110.0, 102.0, 99.0, 107.0, 101.0, 103.0];
44//! let (t, p) = one_sample_t_test(&iq, 100.0);
45//!
46//! assert!(mean(&iq) > 100.0 && std_dev(&iq) > 0.0);
47//! assert!(t > 0.0);
48//! assert!(p < 0.10, "mildly suggestive, p = {p}");
49//! ```
50//!
51//! Compare two groups, then fit a line:
52//!
53//! ```
54//! use tpt_math_stats::{linear_regression, pearson_correlation, two_sample_t_test};
55//!
56//! let control = [4.1, 3.9, 4.4, 4.0, 3.8];
57//! let treated = [5.2, 5.5, 5.1, 5.4, 5.3];
58//! let (_t, p) = two_sample_t_test(&control, &treated);
59//! assert!(p < 0.001);
60//!
61//! let dose = [0.0, 1.0, 2.0, 3.0, 4.0];
62//! let response = [1.0, 3.0, 5.0, 7.0, 9.0];
63//! assert_eq!(linear_regression(&dose, &response), (2.0, 1.0));
64//! assert_eq!(pearson_correlation(&dose, &response), 1.0);
65//! ```
66//!
67//! Goodness of fit for a categorical model:
68//!
69//! ```
70//! use tpt_math_stats::chi_squared_goodness_of_fit;
71//!
72//! // 100 draws that should have been split 25/25/25/25.
73//! let observed = [22u64, 27, 24, 27];
74//! let expected = [25.0; 4];
75//! let (x2, p) = chi_squared_goodness_of_fit(&observed, &expected);
76//! assert!(x2 < 1.0 && p > 0.5);
77//! ```
78//!
79//! # Special functions and distributions
80//!
81//! Anything outside the descriptive/hypothesis/regression surface is also
82//! available in-house (no Apache-2.0 `statrs` dependency): the special
83//! functions in `special` (error, gamma, beta and their regularized incomplete
84//! forms) and the distributions in `dist` (chi-squared, Student's t, normal).
85//!
86//! ```
87//! use tpt_math_stats::{ChiSquared, ContinuousCDF};
88//!
89//! // Upper-tail probability of chi-squared(3) at 10.0: significant at 5%.
90//! let chi = ChiSquared::new(3.0).unwrap();
91//! let p = chi.sf(10.0);
92//! assert!(p < 0.05);
93//! ```
94//!
95//! The randomness traits from `tpt-math-prob-core` are re-exported too, which
96//! makes simulation studies against these tests a two-liner:
97//!
98//! ```
99//! use tpt_math_stats::{mean, Distribution, SplitMix64, Standard};
100//!
101//! let mut rng = SplitMix64::seed_from_u64(7);
102//! let sample: Vec<f64> = (0..10_000).map(|_| Standard.sample(&mut rng)).collect();
103//! assert!((mean(&sample) - 0.5).abs() < 0.02);
104//! ```
105
106mod bootstrap;
107mod corrections;
108mod descriptive;
109mod dist;
110mod error;
111mod hypothesis;
112mod kde;
113mod multiple;
114mod nonparametric;
115mod regression;
116mod special;
117
118pub use bootstrap::{bootstrap_ci, try_bootstrap_ci};
119pub use corrections::{
120    benjamini_hochberg, bonferroni, holm, try_benjamini_hochberg, try_bonferroni, try_holm,
121};
122pub use descriptive::{
123    excess_kurtosis, max, mean, median, min, quantile, skewness, std_dev, try_excess_kurtosis,
124    try_max, try_mean, try_median, try_min, try_quantile, try_skewness, try_std_dev, try_variance,
125    variance,
126};
127pub use dist::{ChiSquared, ContinuousCDF, Normal, StudentsT};
128pub use error::StatsError;
129pub use hypothesis::{
130    chi_squared_goodness_of_fit, chi_squared_independence, one_sample_t_test, one_way_anova,
131    paired_t_test, pooled_t_test, try_chi_squared_goodness_of_fit, try_chi_squared_independence,
132    try_one_sample_t_test, try_one_way_anova, try_paired_t_test, try_pooled_t_test,
133    try_two_sample_t_test, two_sample_t_test,
134};
135pub use kde::{kernel_density, try_kernel_density, KernelDensity};
136pub use multiple::{try_logistic_regression, try_multiple_regression, LogisticFit, MultipleFit};
137pub use nonparametric::{
138    kolmogorov_smirnov_two_sample, mann_whitney_u, try_kolmogorov_smirnov_two_sample,
139    try_mann_whitney_u, try_wilcoxon_signed_rank, wilcoxon_signed_rank,
140};
141pub use regression::{
142    covariance, linear_regression, pearson_correlation, try_covariance, try_kendall_tau,
143    try_linear_regression, try_pearson_correlation, try_spearman_correlation,
144};
145pub use special::{beta, beta_reg, erf, erfc, gamma, gamma_p, gamma_q, lgamma};
146
147/// The workspace's randomness traits, re-exported for convenience.
148pub use tpt_math_prob_core as prob_core;
149
150pub use tpt_math_prob_core::{Distribution, Rng, Sampler, SplitMix64, Standard};
151
152#[cfg(test)]
153mod tests {
154    use super::*;
155
156    #[test]
157    fn distributions_and_special_functions_are_usable() {
158        use crate::dist::{ContinuousCDF, Normal};
159
160        let normal = Normal::new(0.0, 1.0).unwrap();
161        assert!((normal.cdf(0.0) - 0.5).abs() < 1e-15);
162        assert!((normal.pdf(0.0) - 1.0 / (2.0 * std::f64::consts::PI).sqrt()).abs() < 1e-15);
163        assert!((normal.mean() - 0.0).abs() < 1e-15);
164        assert!((normal.variance() - 1.0).abs() < 1e-15);
165
166        // The in-house special functions.
167        assert!((gamma(5.0) - 24.0).abs() < 1e-10);
168        assert!(erf(0.0).abs() < 1e-15);
169        assert!((beta(2.0, 3.0) - 1.0 / 12.0).abs() < 1e-12);
170    }
171
172    #[test]
173    fn prob_core_reexport_drives_a_simulation() {
174        // A deterministic uniform sample should look uniform to our helpers.
175        let mut rng = SplitMix64::seed_from_u64(1_234_567);
176        let sample: Vec<f64> = (0..20_000).map(|_| Standard.sample(&mut rng)).collect();
177
178        assert!((mean(&sample) - 0.5).abs() < 0.01);
179        assert!((variance(&sample) - 1.0 / 12.0).abs() < 0.005);
180        assert!(min(&sample) < 0.001 && max(&sample) > 0.999);
181        assert!((median(&sample) - 0.5).abs() < 0.02);
182
183        // The mean of a uniform sample is not significantly different from 0.5.
184        let (_t, p) = one_sample_t_test(&sample, 0.5);
185        assert!(p > 0.01, "p = {p}");
186    }
187
188    #[test]
189    fn t_test_false_positive_rate_is_calibrated() {
190        // Under H0 the p-value is uniform, so ~5% of runs fall below 0.05.
191        let mut rng = SplitMix64::seed_from_u64(2026);
192        let mut rejections = 0usize;
193        let trials = 400;
194
195        for _ in 0..trials {
196            // Sum of 12 uniforms - 6 is a decent standard normal.
197            let sample: Vec<f64> = (0..30)
198                .map(|_| (0..12).map(|_| rng.next_f64()).sum::<f64>() - 6.0)
199                .collect();
200            let (_t, p) = one_sample_t_test(&sample, 0.0);
201            if p < 0.05 {
202                rejections += 1;
203            }
204        }
205
206        // Binomial(400, 0.05) has sd ~4.4; allow a wide, flake-proof band.
207        assert!(rejections < 40, "rejected {rejections} of {trials}");
208    }
209}