Skip to main content

embedded_maths/
statistics.rs

1// SPDX-License-Identifier: GPL-2.0-or-later
2//! Statistical analysis support for `f32` on `no_std`, powered by `embedded-stats-f32`.
3//!
4//! Provides batch statistics with compensated Kahan summation (`mean`, `variance`,
5//! `std_dev`) and constant-memory streaming statistics with Welford's algorithm
6//! (`StreamingStats`), with zero heap allocation, zero `libm`, and fail-fast rejection
7//! of `NaN` and `±inf` values.
8//!
9//! # Behavior & Notes
10//!
11//! | Operation / Input | Behavior |
12//! |-------------------|----------|
13//! | `mean(&[f32])` | Arithmetic mean via Kahan summation (`Result<f32, StatsError>`) |
14//! | `variance(&[f32])` | Population variance (divisor `N`) via Kahan (`Result<f32, StatsError>`) |
15//! | `std_dev(&[f32])` | Standard deviation (`sqrt(variance)`) (`Result<f32, StatsError>`) |
16//! | `StreamingStats::new()` | Initializes `O(1)` memory streaming accumulator |
17//! | `acc.update(x)` | Updates state if finite; preserves state on `Err(StatsError::NonFiniteValue)` |
18//! | Empty slice / uninitialized `StreamingStats` | Returns `Err(StatsError::EmptySlice)` |
19//! | `NaN` or `±Infinity` input/output | Returns `Err(StatsError::NonFiniteValue)` |
20
21pub use embedded_stats_f32::{
22    mean as kahan_mean, std_dev as kahan_std_dev, variance as kahan_variance, StatsError,
23    StreamingStats,
24};
25
26/// Computes the arithmetic mean of `slice` using Kahan compensated summation.
27pub fn mean(slice: &[f32]) -> Result<f32, StatsError> {
28    kahan_mean(slice)
29}
30
31/// Computes the population variance (divisor `N`) of `slice` using Kahan summation.
32pub fn variance(slice: &[f32]) -> Result<f32, StatsError> {
33    kahan_variance(slice)
34}
35
36/// Computes the population standard deviation of `slice`.
37pub fn std_dev(slice: &[f32]) -> Result<f32, StatsError> {
38    kahan_std_dev(slice)
39}
40
41#[cfg(test)]
42mod tests {
43    use super::*;
44
45    #[test]
46    fn batch_and_streaming_stats() {
47        let data = [2.0_f32, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0];
48        assert!((mean(&data).unwrap() - 5.0).abs() < 1e-6);
49        assert!((variance(&data).unwrap() - 4.0).abs() < 1e-5);
50        assert!((std_dev(&data).unwrap() - 2.0).abs() < 1e-5);
51
52        let mut acc = StreamingStats::new();
53        for &x in &data {
54            acc.update(x).unwrap();
55        }
56        assert!((acc.mean().unwrap() - 5.0).abs() < 1e-6);
57        assert!((acc.running_variance().unwrap() - 4.0).abs() < 1e-5);
58        assert!((acc.running_std_dev().unwrap() - 2.0).abs() < 1e-5);
59    }
60
61    #[test]
62    fn error_handling_preserves_state() {
63        assert_eq!(mean(&[]), Err(StatsError::EmptySlice));
64        assert_eq!(mean(&[f32::INFINITY]), Err(StatsError::NonFiniteValue));
65
66        let mut acc = StreamingStats::new();
67        acc.update(10.0).unwrap();
68        assert_eq!(acc.update(f32::NAN), Err(StatsError::NonFiniteValue));
69        assert_eq!(acc.count(), 1);
70        assert!((acc.mean().unwrap() - 10.0).abs() < 1e-6);
71    }
72}