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 StatsError, StreamingStats, mean as kahan_mean, std_dev as kahan_std_dev,
23 variance as kahan_variance,
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}