#[derive(Debug, Clone)]
pub struct WelfordState {
count: u64,
mean: f64,
m2: f64,
}
impl WelfordState {
#[must_use]
pub const fn new() -> Self {
Self {
count: 0,
mean: 0.0,
m2: 0.0,
}
}
pub fn update(&mut self, x: f64) {
self.count += 1;
let delta = x - self.mean;
self.mean += delta / self.count as f64;
let delta2 = x - self.mean;
self.m2 = delta.mul_add(delta2, self.m2);
}
#[must_use]
pub const fn count(&self) -> u64 {
self.count
}
#[must_use]
pub const fn mean(&self) -> f64 {
self.mean
}
#[must_use]
pub fn population_variance(&self) -> f64 {
if self.count < 1 {
return 0.0;
}
self.m2 / self.count as f64
}
#[must_use]
pub fn sample_variance(&self) -> f64 {
if self.count < 2 {
return 0.0;
}
self.m2 / (self.count - 1) as f64
}
#[must_use]
pub fn std_dev(&self) -> f64 {
self.sample_variance().sqrt()
}
pub fn merge(&mut self, other: &Self) {
if other.count == 0 {
return;
}
if self.count == 0 {
*self = other.clone();
return;
}
let combined_count = self.count + other.count;
let delta = other.mean - self.mean;
let combined_mean = delta.mul_add(other.count as f64 / combined_count as f64, self.mean);
let combined_m2 = (delta * delta).mul_add(
self.count as f64 * other.count as f64 / combined_count as f64,
self.m2 + other.m2,
);
self.count = combined_count;
self.mean = combined_mean;
self.m2 = combined_m2;
}
#[must_use]
pub fn from_slice(data: &[f64]) -> Self {
let mut state = Self::new();
for &x in data {
state.update(x);
}
state
}
}
impl Default for WelfordState {
fn default() -> Self {
Self::new()
}
}
#[derive(Debug, Clone)]
pub struct WelfordCovState {
count: u64,
mean_x: f64,
mean_y: f64,
m2_x: f64,
m2_y: f64,
co_moment: f64,
}
impl WelfordCovState {
#[must_use]
pub const fn new() -> Self {
Self {
count: 0,
mean_x: 0.0,
mean_y: 0.0,
m2_x: 0.0,
m2_y: 0.0,
co_moment: 0.0,
}
}
pub fn update(&mut self, x: f64, y: f64) {
self.count += 1;
let n = self.count as f64;
let dx = x - self.mean_x;
self.mean_x += dx / n;
let dy = y - self.mean_y;
self.mean_y += dy / n;
self.co_moment = dx.mul_add(y - self.mean_y, self.co_moment);
self.m2_x = dx.mul_add(x - self.mean_x, self.m2_x);
self.m2_y = dy.mul_add(y - self.mean_y, self.m2_y);
}
#[must_use]
pub const fn count(&self) -> u64 {
self.count
}
#[must_use]
pub const fn mean_x(&self) -> f64 {
self.mean_x
}
#[must_use]
pub const fn mean_y(&self) -> f64 {
self.mean_y
}
#[must_use]
pub fn population_covariance(&self) -> f64 {
if self.count < 1 {
return 0.0;
}
self.co_moment / self.count as f64
}
#[must_use]
pub fn sample_covariance(&self) -> f64 {
if self.count < 2 {
return 0.0;
}
self.co_moment / (self.count - 1) as f64
}
#[must_use]
pub fn correlation(&self) -> f64 {
let denom = (self.m2_x * self.m2_y).sqrt();
if denom == 0.0 {
return f64::NAN;
}
self.co_moment / denom
}
#[must_use]
pub fn variance_x(&self) -> f64 {
if self.count < 2 {
return 0.0;
}
self.m2_x / (self.count - 1) as f64
}
#[must_use]
pub fn variance_y(&self) -> f64 {
if self.count < 2 {
return 0.0;
}
self.m2_y / (self.count - 1) as f64
}
pub fn merge(&mut self, other: &Self) {
if other.count == 0 {
return;
}
if self.count == 0 {
*self = other.clone();
return;
}
let combined = self.count + other.count;
let dx = other.mean_x - self.mean_x;
let dy = other.mean_y - self.mean_y;
let factor = self.count as f64 * other.count as f64 / combined as f64;
self.co_moment += (dx * dy).mul_add(factor, other.co_moment);
self.m2_x += (dx * dx).mul_add(factor, other.m2_x);
self.m2_y += (dy * dy).mul_add(factor, other.m2_y);
self.mean_x = dx.mul_add(other.count as f64 / combined as f64, self.mean_x);
self.mean_y = dy.mul_add(other.count as f64 / combined as f64, self.mean_y);
self.count = combined;
}
#[must_use]
pub fn from_slices(x: &[f64], y: &[f64]) -> Self {
let mut state = Self::new();
for (&xi, &yi) in x.iter().zip(y.iter()) {
state.update(xi, yi);
}
state
}
}
impl Default for WelfordCovState {
fn default() -> Self {
Self::new()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn welford_mean() {
let data = [2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0];
let state = WelfordState::from_slice(&data);
assert!((state.mean() - 5.0).abs() < 1e-10);
}
#[test]
fn welford_population_variance() {
let data = [2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0];
let state = WelfordState::from_slice(&data);
assert!((state.population_variance() - 4.0).abs() < 1e-10);
}
#[test]
fn welford_sample_variance() {
let data = [1.0, 2.0, 3.0, 4.0, 5.0];
let state = WelfordState::from_slice(&data);
assert!((state.sample_variance() - 2.5).abs() < 1e-10);
}
#[test]
fn welford_empty() {
let state = WelfordState::new();
assert_eq!(state.count(), 0);
assert_eq!(state.population_variance(), 0.0);
assert_eq!(state.sample_variance(), 0.0);
}
#[test]
fn welford_single_point() {
let mut state = WelfordState::new();
state.update(42.0);
assert!((state.mean() - 42.0).abs() < 1e-15);
assert_eq!(state.population_variance(), 0.0);
assert_eq!(state.sample_variance(), 0.0);
}
#[test]
fn welford_merge() {
let data = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
let full = WelfordState::from_slice(&data);
let mut a = WelfordState::from_slice(&data[..4]);
let b = WelfordState::from_slice(&data[4..]);
a.merge(&b);
assert!((a.mean() - full.mean()).abs() < 1e-10);
assert!((a.sample_variance() - full.sample_variance()).abs() < 1e-10);
}
#[test]
fn welford_cov_perfect_positive() {
let xs = [1.0, 2.0, 3.0, 4.0, 5.0];
let ys = [2.0, 4.0, 6.0, 8.0, 10.0];
let state = WelfordCovState::from_slices(&xs, &ys);
assert!((state.sample_covariance() - 5.0).abs() < 1e-10);
assert!((state.correlation() - 1.0).abs() < 1e-10);
}
#[test]
fn welford_cov_perfect_negative() {
let xs = [1.0, 2.0, 3.0, 4.0, 5.0];
let ys = [10.0, 8.0, 6.0, 4.0, 2.0];
let state = WelfordCovState::from_slices(&xs, &ys);
assert!((state.sample_covariance() + 5.0).abs() < 1e-10);
assert!((state.correlation() + 1.0).abs() < 1e-10);
}
#[test]
fn welford_cov_self_is_variance() {
let xs = [1.0, 2.0, 3.0, 4.0, 5.0];
let state = WelfordCovState::from_slices(&xs, &xs);
assert!((state.sample_covariance() - 2.5).abs() < 1e-10);
assert!((state.variance_x() - 2.5).abs() < 1e-10);
}
#[test]
fn welford_cov_merge() {
let xs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
let ys = [2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0];
let full = WelfordCovState::from_slices(&xs, &ys);
let mut a = WelfordCovState::from_slices(&xs[..4], &ys[..4]);
let b = WelfordCovState::from_slices(&xs[4..], &ys[4..]);
a.merge(&b);
assert!((a.sample_covariance() - full.sample_covariance()).abs() < 1e-10);
assert!((a.correlation() - full.correlation()).abs() < 1e-10);
}
#[test]
fn welford_numerical_stability_large_mean() {
let data: Vec<f64> = (0..1000).map(|i| 1e9 + i as f64).collect();
let state = WelfordState::from_slice(&data);
let expected_mean = 1e9 + 499.5;
assert!((state.mean() - expected_mean).abs() < 1e-6);
let expected_var = 83_333.25;
assert!(
(state.population_variance() - expected_var).abs() < 0.01,
"got {}",
state.population_variance()
);
}
#[test]
fn welford_std_dev() {
let data = [2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0];
let state = WelfordState::from_slice(&data);
let expected = state.sample_variance().sqrt();
assert!((state.std_dev() - expected).abs() < 1e-15);
}
#[test]
fn welford_std_dev_single() {
let mut state = WelfordState::new();
state.update(5.0);
assert_eq!(state.std_dev(), 0.0);
}
#[test]
fn welford_default() {
let state = WelfordState::default();
assert_eq!(state.count(), 0);
assert_eq!(state.mean(), 0.0);
}
#[test]
fn welford_merge_into_empty() {
let b = WelfordState::from_slice(&[1.0, 2.0, 3.0]);
let mut a = WelfordState::new();
a.merge(&b);
assert_eq!(a.count(), 3);
assert!((a.mean() - 2.0).abs() < 1e-15);
}
#[test]
fn welford_merge_empty_into_nonempty() {
let mut a = WelfordState::from_slice(&[1.0, 2.0, 3.0]);
let b = WelfordState::new();
let mean_before = a.mean();
a.merge(&b);
assert_eq!(a.count(), 3);
assert!((a.mean() - mean_before).abs() < 1e-15);
}
#[test]
fn welford_cov_empty() {
let state = WelfordCovState::new();
assert_eq!(state.count(), 0);
assert_eq!(state.mean_x(), 0.0);
assert_eq!(state.mean_y(), 0.0);
assert_eq!(state.population_covariance(), 0.0);
assert_eq!(state.sample_covariance(), 0.0);
assert_eq!(state.variance_x(), 0.0);
assert_eq!(state.variance_y(), 0.0);
}
#[test]
fn welford_cov_single_point() {
let mut state = WelfordCovState::new();
state.update(3.0, 7.0);
assert_eq!(state.count(), 1);
assert!((state.mean_x() - 3.0).abs() < 1e-15);
assert!((state.mean_y() - 7.0).abs() < 1e-15);
assert_eq!(state.population_covariance(), 0.0);
assert_eq!(state.sample_covariance(), 0.0);
}
#[test]
fn welford_cov_correlation_constant_returns_nan() {
let mut state = WelfordCovState::new();
state.update(5.0, 5.0);
state.update(5.0, 5.0);
assert!(state.correlation().is_nan());
}
#[test]
fn welford_cov_default() {
let state = WelfordCovState::default();
assert_eq!(state.count(), 0);
}
#[test]
fn welford_cov_population_covariance() {
let xs = [1.0, 2.0, 3.0, 4.0, 5.0];
let ys = [2.0, 4.0, 6.0, 8.0, 10.0];
let state = WelfordCovState::from_slices(&xs, &ys);
assert!((state.population_covariance() - 4.0).abs() < 1e-10);
}
#[test]
fn welford_cov_merge_into_empty() {
let b = WelfordCovState::from_slices(&[1.0, 2.0], &[3.0, 4.0]);
let mut a = WelfordCovState::new();
a.merge(&b);
assert_eq!(a.count(), 2);
assert!((a.mean_x() - 1.5).abs() < 1e-15);
assert!((a.mean_y() - 3.5).abs() < 1e-15);
}
#[test]
fn welford_cov_merge_empty_into_nonempty() {
let mut a = WelfordCovState::from_slices(&[1.0, 2.0, 3.0], &[2.0, 4.0, 6.0]);
let b = WelfordCovState::new();
let count_before = a.count();
a.merge(&b);
assert_eq!(a.count(), count_before);
}
#[test]
fn welford_cov_from_slices_unequal_length() {
let state = WelfordCovState::from_slices(&[1.0, 2.0, 3.0], &[4.0, 5.0]);
assert_eq!(state.count(), 2);
}
#[test]
fn welford_cov_variance_xy() {
let xs = [1.0, 2.0, 3.0, 4.0, 5.0];
let ys = [10.0, 20.0, 30.0, 40.0, 50.0];
let state = WelfordCovState::from_slices(&xs, &ys);
assert!((state.variance_x() - 2.5).abs() < 1e-10);
assert!((state.variance_y() - 250.0).abs() < 1e-10);
}
}