0.8: Normalization sliding windows

.gitignore

@@ -3,3 +3,4 @@
 /vendor
 /img
 /.direnv
+mutants.out/

Cargo.toml

@@ -2,7 +2,7 @@ cargo-features = ["edition2024"]
 
 [package]
 name = "sliding_features"
-version = "7.1.3"
+version = "8.0.0"
 authors = ["MathisWellmann <wellmannmathis@gmail.com>"]
 edition = "2024"
 license-file = "LICENSE"

benches/vsct.rs

@@ -15,7 +15,7 @@ use rand::{
 use sliding_features::{
     View,
     pure_functions::Echo,
-    sliding_windows::Vsct,
+    sliding_windows::ZScoreStandardization,
 };
 
 fn criterion_benchmark(c: &mut Criterion) {
@@ -26,7 +26,8 @@ fn criterion_benchmark(c: &mut Criterion) {
     group.bench_function("f64", |b| {
         let vals = Vec::<f64>::from_iter((0..N).map(|_| rng.random()));
         b.iter(|| {
-            let mut view = Vsct::<f64, _>::new(Echo::new(), NonZeroUsize::new(1024).unwrap());
+            let mut view =
+                ZScoreStandardization::<f64, _>::new(Echo::new(), NonZeroUsize::new(1024).unwrap());
             for v in vals.iter() {
                 view.update(*v);
                 let _ = black_box(view.last());
@@ -36,7 +37,8 @@ fn criterion_benchmark(c: &mut Criterion) {
     group.bench_function("f32", |b| {
         let vals = Vec::<f32>::from_iter((0..N).map(|_| rng.random()));
         b.iter(|| {
-            let mut view = Vsct::<f32, _>::new(Echo::new(), NonZeroUsize::new(1024).unwrap());
+            let mut view =
+                ZScoreStandardization::<f32, _>::new(Echo::new(), NonZeroUsize::new(1024).unwrap());
             for v in vals.iter() {
                 view.update(*v);
                 let _ = black_box(view.last());

examples/basic_chainable_view.rs

@@ -9,7 +9,7 @@ use sliding_features::{
     pure_functions::Echo,
     sliding_windows::{
         Alma,
-        Vsct,
+        ZScoreStandardization,
     },
 };
 
@@ -24,7 +24,7 @@ fn main() {
     let window_len = NonZeroUsize::new(20).unwrap();
     let mut chain = Alma::new(
         // first, define the last function which gets applied in the chain
-        Vsct::new(Echo::new(), window_len), // Make the first transformation in the chain a VSCT
+        ZScoreStandardization::new(Echo::new(), window_len), // Make the first transformation in the chain a VSCT
         window_len,
     );
     for v in &rands {

flake.nix

@@ -57,6 +57,7 @@
           taplo
           cargo-semver-checks
           cargo_upgrades
+          cargo-mutants
         ];
         nix_tools = with pkgs; [
           alejandra # Nix code formatter

src/sliding_windows/mod.rs

@@ -26,8 +26,8 @@ mod sma;
 mod super_smoother;
 mod trend_flex;
 mod variance_stabilizing_transformation;
-mod vsct;
 mod welford_online;
+mod z_score_standardization;
 
 pub use alma::Alma;
 pub use binary_entropy::BinaryEntropy;
@@ -54,5 +54,5 @@ pub use sma::Sma;
 pub use super_smoother::SuperSmoother;
 pub use trend_flex::TrendFlex;
 pub use variance_stabilizing_transformation::Vst;
-pub use vsct::Vsct;
 pub use welford_online::WelfordOnline;
+pub use z_score_standardization::ZScoreStandardization;

src/sliding_windows/welford_online.rs

@@ -54,10 +54,29 @@ where
 
     #[inline]
     fn update_stats_remove(&mut self, old_value: T) {
-        let delta = old_value - self.mean;
-        self.mean = self.mean - (delta / T::from(self.count).unwrap());
-        self.m2 = self.m2 - (delta * (old_value - self.mean));
+        // Derive sum and sum-of-squares from Welford state:
+        //   mean = sum / n,  m2 = sum_sq - n * mean^2
+        //   => sum = n * mean,  sum_sq = m2 + n * mean^2
+        let n = T::from(self.count).unwrap();
+        let sum = self.mean * n;
+        let sum_sq = self.m2 + sum * self.mean;
+
+        let sum_new = sum - old_value;
+        let sum_sq_new = sum_sq - old_value * old_value;
         self.count -= 1;
+
+        if self.count > 0 {
+            let n_new = T::from(self.count).unwrap();
+            self.mean = sum_new / n_new;
+            self.m2 = sum_sq_new - n_new * self.mean * self.mean;
+            // Clamp floating-point noise that could push m2 slightly negative.
+            if self.m2 < T::zero() {
+                self.m2 = T::zero();
+            }
+        } else {
+            self.mean = T::zero();
+            self.m2 = T::zero();
+        }
     }
 
     /// Return the variance of the sliding window
@@ -139,6 +158,47 @@ mod tests {
         assert_eq!(round(w_std_dev, 4), round(std_dev, 4));
     }
 
+    #[test]
+    fn welford_online_sliding_matches_direct_computation() {
+        // Feed [1, 2, 3, 4, 5, 6] through a window of length 3.
+        // After each step, verify the std dev matches the direct formula for
+        // the window contents.
+        let mut wo = WelfordOnline::new(Echo::new(), NonZeroUsize::new(3).unwrap());
+        let all: Vec<f64> = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
+
+        // Direct std-dev helper (sample sd).
+        let direct_sd = |vs: &[f64]| -> f64 {
+            let n = vs.len() as f64;
+            let m = vs.iter().sum::<f64>() / n;
+            let var = vs.iter().map(|v| (v - m).powi(2)).sum::<f64>() / (n - 1.0);
+            var.sqrt()
+        };
+
+        for i in 0..all.len() {
+            wo.update(all[i]);
+            let start = if i < 2 { 0 } else { i - 2 }; // i+1-window
+            let window = &all[start..=i];
+            let expected = direct_sd(&window);
+            if let Some(got) = wo.last() {
+                let diff = (got - expected).abs();
+                if diff > 1e-12 {
+                    panic!(
+                        "step {} window {:?}: expected sd={}, got={}, diff={}",
+                        i, window, expected, got, diff
+                    );
+                }
+            } else {
+                // window not full yet → None is correct for i < 2
+                assert!(
+                    i < 2,
+                    "step {}: got None but window is full ({:?})",
+                    i,
+                    window
+                );
+            }
+        }
+    }
+
     #[test]
     fn welford_online_plot() {
         let mut wo = WelfordOnline::new(Echo::new(), NonZeroUsize::new(16).unwrap());