Skip to main content

qualia_audio/features/loudness/
moments.rs

1//! Statistical moments of a signal: mean, variance, skewness, kurtosis.
2//!
3//! Population (biased, `/n`) moments over a mono block. Skewness and kurtosis
4//! are the standardised 3rd and 4th moments; kurtosis is **Pearson** (a normal
5//! distribution → 3.0, subtract 3 for excess kurtosis). Zero-heap (two scalar
6//! passes, no allocation).
7
8/// The four leading moments of a block.
9#[derive(Debug, Clone, Copy, PartialEq)]
10pub struct Moments {
11    /// Arithmetic mean.
12    pub mean: f32,
13    /// Population variance (`E[(x-μ)^2]`).
14    pub variance: f32,
15    /// Standardised skewness (`E[(x-μ)^3] / σ^3`); `0` for symmetric data.
16    pub skewness: f32,
17    /// Pearson kurtosis (`E[(x-μ)^4] / σ^4`); `3.0` for a normal distribution.
18    pub kurtosis: f32,
19}
20
21impl Moments {
22    /// Zero moments (used for degenerate/empty input).
23    pub const ZERO: Moments = Moments {
24        mean: 0.0,
25        variance: 0.0,
26        skewness: 0.0,
27        kurtosis: 0.0,
28    };
29}
30
31/// Compute the mean, variance, skewness and Pearson kurtosis of `samples`.
32///
33/// Returns [`Moments::ZERO`] for an empty block. For a constant block
34/// (variance `0`) skewness and kurtosis are reported as `0` (undefined ratio).
35pub fn moments(samples: &[f32]) -> Moments {
36    let n = samples.len();
37    if n == 0 {
38        return Moments::ZERO;
39    }
40    let nf = n as f64;
41
42    let mut sum = 0.0f64;
43    for &x in samples {
44        sum += x as f64;
45    }
46    let mean = sum / nf;
47
48    let (mut m2, mut m3, mut m4) = (0.0f64, 0.0f64, 0.0f64);
49    for &x in samples {
50        let d = x as f64 - mean;
51        let d2 = d * d;
52        m2 += d2;
53        m3 += d2 * d;
54        m4 += d2 * d2;
55    }
56    m2 /= nf;
57    m3 /= nf;
58    m4 /= nf;
59
60    let (skewness, kurtosis) = if m2 > 0.0 {
61        let sigma = m2.sqrt();
62        (
63            (m3 / (sigma * sigma * sigma)) as f32,
64            (m4 / (m2 * m2)) as f32,
65        )
66    } else {
67        (0.0, 0.0)
68    };
69
70    Moments {
71        mean: mean as f32,
72        variance: m2 as f32,
73        skewness,
74        kurtosis,
75    }
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81
82    #[test]
83    fn ramp_matches_closed_form() {
84        // [1,2,3,4,5]: mean 3, population var 2, skew 0 (symmetric),
85        // kurtosis = (Σ(x-3)^4/5)/var^2 = 6.8/4 = 1.7.
86        let m = moments(&[1.0, 2.0, 3.0, 4.0, 5.0]);
87        assert!((m.mean - 3.0).abs() < 1e-5, "mean {}", m.mean);
88        assert!((m.variance - 2.0).abs() < 1e-5, "var {}", m.variance);
89        assert!(m.skewness.abs() < 1e-5, "skew {}", m.skewness);
90        assert!((m.kurtosis - 1.7).abs() < 1e-5, "kurt {}", m.kurtosis);
91    }
92
93    #[test]
94    fn two_point_symmetric() {
95        // ±1: mean 0, var 1, skew 0, Pearson kurtosis 1.0 (excess −2).
96        let m = moments(&[-1.0, 1.0, -1.0, 1.0]);
97        assert!(m.mean.abs() < 1e-6);
98        assert!((m.variance - 1.0).abs() < 1e-6);
99        assert!(m.skewness.abs() < 1e-6);
100        assert!((m.kurtosis - 1.0).abs() < 1e-6, "kurt {}", m.kurtosis);
101    }
102
103    #[test]
104    fn positively_skewed_data_has_positive_skew() {
105        // Long right tail.
106        let m = moments(&[0.0, 0.0, 0.0, 0.0, 10.0]);
107        assert!(m.skewness > 1.0, "skew {}", m.skewness);
108    }
109
110    #[test]
111    fn constant_and_empty_are_well_defined() {
112        let c = moments(&[4.0; 16]);
113        assert!((c.mean - 4.0).abs() < 1e-6);
114        assert_eq!(c.variance, 0.0);
115        assert_eq!(c.skewness, 0.0);
116        assert_eq!(c.kurtosis, 0.0);
117        assert_eq!(moments(&[]), Moments::ZERO);
118    }
119}