Struct rolling_stats::Stats

pub struct Stats<T: Float + Zero + One + AddAssign + FromPrimitive + PartialEq + Debug> {
    pub min: T,
    pub max: T,
    pub mean: T,
    pub std_dev: T,
    pub count: usize,
    /* private fields */
}

A statistics object that continuously calculates min, max, mean, and deviation for tracking time-varying statistics. Utilizes Welford’s Online algorithm. More details on the algorithm can be found at: “https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford’s_online_algorithm”

Example

use rolling_stats::Stats;
use rand_distr::{Distribution, Normal};
use rand::SeedableRng;

type T = f64;

const MEAN: T = 0.0;
const STD_DEV: T = 1.0;
const NUM_SAMPLES: usize = 10_000;
const SEED: u64 = 42;

let mut stats: Stats<T> = Stats::new();
let mut rng = rand::rngs::StdRng::seed_from_u64(SEED); // Seed the RNG for reproducibility
let normal = Normal::<T>::new(MEAN, STD_DEV).unwrap();

// Generate random data
let random_data: Vec<T> = (0..NUM_SAMPLES).map(|_x| normal.sample(&mut rng)).collect();

// Update the stats one by one
random_data.iter().for_each(|v| stats.update(*v));

// Print the stats
println!("{}", stats);
// Output: (avg: 0.00, std_dev: 1.00, min: -3.53, max: 4.11, count: 10000)

Fields

min: T

The smallest value seen so far.

max: T

The largest value seen so far.

mean: T

The calculated mean (average) of all the values seen so far.

std_dev: T

The calculated standard deviation of all the values seen so far.

count: usize

The count of the total values seen.

Implementations

impl<T> Stats<T>where T: Float + Zero + One + AddAssign + FromPrimitive + PartialEq + Debug,

pub fn new() -> Stats<T>

Creates a new stats object with all values set to their initial states.

pub fn update(&mut self, value: T)

Updates the stats object with a new value. The statistics are recalculated using the new value.

pub fn merge(&self, other: &Self) -> Self

Merges another stats object into new one. This is done by combining the statistics of the two objects in accordance with the formula provided at: https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Parallel_algorithm

This is useful for combining statistics from multiple threads or processes.

Example

use rolling_stats::Stats;
use rand_distr::{Distribution, Normal};
use rand::SeedableRng;
use rayon::prelude::*;

type T = f64;

const MEAN: T = 0.0;
const STD_DEV: T = 1.0;
const NUM_SAMPLES: usize = 500_000;
const SEED: u64 = 42;
const CHUNK_SIZE: usize = 1000;

let mut stats: Stats<T> = Stats::new();
let mut rng = rand::rngs::StdRng::seed_from_u64(SEED); // Seed the RNG for reproducibility
let normal = Normal::<T>::new(MEAN, STD_DEV).unwrap();

// Generate random data
let random_data: Vec<T> = (0..NUM_SAMPLES).map(|_x| normal.sample(&mut rng)).collect();

// Update the stats in parallel. New stats objects are created for each chunk of data.
let stats: Vec<Stats<T>> = random_data
    .par_chunks(CHUNK_SIZE) // Multi-threaded parallelization via Rayon
    .map(|chunk| {
            let mut s: Stats<T> = Stats::new();
            chunk.iter().for_each(|v| s.update(*v));
            s
     })
    .collect();

// Check if there's more than one stat object
assert!(stats.len() > 1);

// Accumulate the stats using the reduce method. The last stats object is returned.
let merged_stats = stats.into_iter().reduce(|acc, s| acc.merge(&s)).unwrap();

// Print the stats
println!("{}", merged_stats);

// Output: (avg: -0.00, std_dev: 1.00, min: -4.53, max: 4.57, count: 500000)

Trait Implementations

impl<T: Clone + Float + Zero + One + AddAssign + FromPrimitive + PartialEq + Debug> Clone for Stats<T>

fn clone(&self) -> Stats<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug + Float + Zero + One + AddAssign + FromPrimitive + PartialEq + Debug> Debug for Stats<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default + Float + Zero + One + AddAssign + FromPrimitive + PartialEq + Debug> Default for Stats<T>

fn default() -> Stats<T>

Returns the “default value” for a type.

impl<T> Display for Stats<T>where T: Display + Float + Zero + One + AddAssign + FromPrimitive + PartialEq + Debug,

Implementing the Display trait for the Stats struct to present the statistics in a readable format.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the output of the statistics.