Struct ZScoreNormalizer 

pub struct ZScoreNormalizer { /* private fields */ }

Rolling z-score normalizer over a sliding window of Decimal observations.

Maps each new sample to its z-score: (x - mean) / std_dev. The rolling window maintains an O(1) mean and variance via incremental sum/sum-of-squares tracking, with O(W) recompute only when a value is evicted.

Returns 0.0 when the window has fewer than 2 observations (variance is 0).

Example

use fin_stream::norm::ZScoreNormalizer;
use rust_decimal_macros::dec;

let mut norm = ZScoreNormalizer::new(5).unwrap();
for v in [dec!(10), dec!(20), dec!(30), dec!(40), dec!(50)] {
    norm.update(v);
}
// 30 is the mean; normalize returns 0.0
let z = norm.normalize(dec!(30)).unwrap();
assert!((z - 0.0).abs() < 1e-9);

Implementations

impl ZScoreNormalizer

pub fn new(window_size: usize) -> Result<Self, StreamError>

Create a new z-score normalizer with the given rolling window size.

Errors

Returns StreamError::ConfigError if window_size == 0.

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

Add a new observation to the rolling window.

Evicts the oldest value when the window is full, adjusting running sums in O(1). No full recompute is needed unless eviction causes sum drift; the implementation recomputes exactly when necessary via recompute.

pub fn normalize(&self, value: Decimal) -> Result<f64, StreamError>

Normalize value to a z-score using the current window’s mean and std dev.

Returns 0.0 if:

• The window has fewer than 2 observations (std dev undefined).
• The standard deviation is effectively zero (all window values identical).

Errors

Returns StreamError::NormalizationError if the window is empty.

Complexity: O(1)

pub fn mean(&self) -> Option<Decimal>

Current rolling mean of the window, or None if the window is empty.

pub fn std_dev(&self) -> Option<f64>

Current population standard deviation of the window.

Returns None if the window is empty. Returns Some(0.0) if fewer than 2 observations are present (undefined variance, treated as zero) or if all values are identical.

pub fn reset(&mut self)

Reset the normalizer, clearing all observations and sums.

pub fn len(&self) -> usize

Number of observations currently in the window.

pub fn is_empty(&self) -> bool

Returns true if no observations have been added since construction or reset.

pub fn window_size(&self) -> usize

The configured window size.

pub fn is_full(&self) -> bool

Returns true when the window holds exactly window_size observations.

At full capacity the z-score calculation is stable; before this point the window may not be representative of the underlying distribution.

pub fn sum(&self) -> Option<Decimal>

Running sum of all values currently in the window.

Returns None if the window is empty. Useful for deriving a rolling mean without calling normalize.

pub fn variance(&self) -> Option<Decimal>

Current population variance of the window.

Computed as E[X²] − (E[X])² from running sums in O(1). Returns None if fewer than 2 observations are present (variance undefined).

pub fn std_dev_f64(&self) -> Option<f64>

Standard deviation of the current window as f64.

Returns None if the window has fewer than 2 observations.

pub fn variance_f64(&self) -> Option<f64>

Current window variance as f64 (convenience wrapper around variance).

Returns None if the window has fewer than 2 observations.

pub fn normalize_batch( &mut self, values: &[Decimal], ) -> Result<Vec<f64>, StreamError>

Feed a slice of values into the window and return z-scores for each.

Each value is first passed through update to advance the rolling window, then normalized. The output has the same length as values.

Errors

Propagates the first StreamError returned by normalize.

pub fn is_outlier(&self, value: Decimal, z_threshold: f64) -> bool

Returns true if value is an outlier: its z-score exceeds z_threshold in magnitude.

Returns false when the window has fewer than 2 observations (z-score undefined). A typical threshold is 2.0 (95th percentile) or 3.0 (99.7th percentile).

pub fn percentile_rank(&self, value: Decimal) -> Option<f64>

Percentile rank: fraction of window observations that are ≤ value.

Returns None if the window is empty. Range: [0.0, 1.0].

pub fn running_min(&self) -> Option<Decimal>

Minimum value seen in the current window.

Returns None when the window is empty.

pub fn running_max(&self) -> Option<Decimal>

Maximum value seen in the current window.

Returns None when the window is empty.

pub fn window_range(&self) -> Option<Decimal>

Range of values in the current window: running_max − running_min.

Returns None when the window is empty.

pub fn coefficient_of_variation(&self) -> Option<f64>

Coefficient of variation: std_dev / |mean|.

A dimensionless measure of relative dispersion. Returns None when the window has fewer than 2 observations or when the mean is zero.

pub fn sample_variance(&self) -> Option<f64>

Population variance of the current window as f64: std_dev².

Note: despite the name, this computes population variance (divides by n), consistent with std_dev and variance. Returns None when the window has fewer than 2 observations.

pub fn window_mean_f64(&self) -> Option<f64>

Current window mean as f64.

A convenience over calling mean() and then converting to f64. Returns None when the window is empty.

pub fn is_near_mean(&self, value: Decimal, sigma_tolerance: f64) -> bool

Returns true if value is within sigma_tolerance standard deviations of the window mean (inclusive).

Equivalent to |z_score(value)| <= sigma_tolerance. Returns false when the window has fewer than 2 observations (z-score undefined).

pub fn window_sum(&self) -> Decimal

Sum of all values currently in the window as Decimal.

Returns Decimal::ZERO on an empty window.

pub fn window_sum_f64(&self) -> f64

Sum of all values currently in the window as f64.

Returns 0.0 on an empty window.

pub fn window_max_f64(&self) -> Option<f64>

Maximum value currently in the window as f64.

Returns None when the window is empty.

pub fn window_min_f64(&self) -> Option<f64>

Minimum value currently in the window as f64.

Returns None when the window is empty.

pub fn window_span_f64(&self) -> Option<f64>

Difference between the window maximum and minimum, as f64.

Returns None if the window is empty.

pub fn kurtosis(&self) -> Option<f64>

Excess kurtosis of the window: (Σ((x-mean)⁴/n) / std_dev⁴) - 3.

Returns None if the window has fewer than 4 observations or std dev is zero. A normal distribution has excess kurtosis of 0; positive values indicate heavier tails (leptokurtic); negative values indicate lighter tails (platykurtic).

pub fn skewness(&self) -> Option<f64>

Fisher-Pearson skewness of the rolling window.

Positive values indicate a right-tailed distribution; negative values indicate a left-tailed distribution. Returns None for fewer than 3 observations or zero standard deviation.

pub fn is_extreme(&self, value: Decimal, sigma: f64) -> bool

Returns true if the z-score of value exceeds sigma in absolute terms.

Convenience wrapper around normalize for alert logic. Returns false if the normalizer window is empty or std-dev is zero.

pub fn latest(&self) -> Option<Decimal>

The most recently added value, or None if the window is empty.

pub fn median(&self) -> Option<Decimal>

Median of the current window, or None if empty.

pub fn percentile(&self, value: Decimal) -> Option<f64>

Empirical percentile of value within the current window: fraction of values ≤ value.

Alias for percentile_rank.

pub fn interquartile_range(&self) -> Option<Decimal>

Interquartile range: Q3 (75th percentile) − Q1 (25th percentile) of the window.

Returns None if the window has fewer than 4 observations. The IQR is a robust spread measure less sensitive to outliers than range or std dev.

pub fn ema_z_score( value: Decimal, alpha: f64, ema_mean: &mut f64, ema_var: &mut f64, ) -> Option<f64>

Stateless EMA z-score helper: updates running ema_mean and ema_var and returns the z-score (value - ema_mean) / sqrt(ema_var).

alpha ∈ (0, 1] controls smoothing speed (higher = faster adaptation). Initialize ema_mean = 0.0 and ema_var = 0.0 before first call. Returns None if value cannot be converted to f64 or variance is still zero.

pub fn z_score_of_latest(&self) -> Option<f64>

Z-score of the most recently added value.

Returns None if the window is empty or std-dev is zero.

pub fn ema_of_z_scores(&self, alpha: f64) -> Option<f64>

Exponential moving average of z-scores for all values in the current window.

alpha is the smoothing factor (0 < alpha ≤ 1). Higher alpha gives more weight to recent z-scores. Returns None if the window has fewer than 2 observations.

pub fn add_observation(&mut self, value: Decimal) -> &mut Self

Chainable alias for update: feeds value into the window and returns &mut Self.

pub fn deviation_from_mean(&self, value: Decimal) -> Option<f64>

Signed deviation of value from the window mean, as f64.

Returns None if the window is empty.

pub fn trim_outliers(&self, sigma: f64) -> Vec<Decimal>

Returns a Vec of window values that are within sigma standard deviations of the mean.

Useful for robust statistics after removing extreme outliers. Returns all values if std-dev is zero (no outliers possible), empty vec if window is empty.

pub fn rolling_zscore_batch(&mut self, values: &[Decimal]) -> Vec<Option<f64>>

Batch normalize: returns z-scores for each value as if they were added one-by-one.

Each z-score uses only the window state after incorporating that value. The internal state is modified; call reset() if you need to restore it. Returns None entries where normalization fails (window warming up or zero std-dev).

pub fn rolling_mean_change(&self) -> Option<f64>

Change in mean between the first half and second half of the current window.

Splits the window in two, computes the mean of each half, and returns second_half_mean - first_half_mean as f64. Returns None if the window has fewer than 2 observations.

pub fn count_positive_z_scores(&self) -> usize

Count of window values whose z-score is strictly positive (above the mean).

Returns 0 if the window is empty or all values are equal (z-scores are all 0).

pub fn is_mean_stable(&self, threshold: f64) -> bool

Returns true if the absolute change between first-half and second-half window means is below threshold. A stable mean indicates the distribution is not trending.

Returns false if the window has fewer than 2 observations.

pub fn above_threshold_count(&self, z_threshold: f64) -> usize

Count of window values whose absolute z-score exceeds z_threshold.

Returns 0 if the window has fewer than 2 observations or std-dev is zero.

pub fn mad(&self) -> Option<Decimal>

Median Absolute Deviation (MAD) of the current window.

MAD = median(|x_i - median(window)|). Returns None if the window is empty.

pub fn robust_z_score(&self, value: Decimal) -> Option<f64>

Robust z-score: (value - median) / MAD.

More resistant to outliers than the standard z-score. Returns None when the window is empty or MAD is zero.

pub fn count_above(&self, threshold: Decimal) -> usize

Count of window values strictly above threshold.

pub fn count_below(&self, threshold: Decimal) -> usize

Count of window values strictly below threshold.

pub fn percentile_value(&self, p: f64) -> Option<Decimal>

Value at the p-th percentile of the current window (0.0 ≤ p ≤ 1.0).

Uses linear interpolation between adjacent sorted values. Returns None if the window is empty.

pub fn ewma(&self, alpha: f64) -> Option<f64>

Exponentially-weighted moving average (EWMA) of the window values.

alpha is the smoothing factor in (0.0, 1.0]; higher values weight recent observations more. Processes values in insertion order (oldest first). Returns None if the window is empty.

pub fn midpoint(&self) -> Option<Decimal>

Midpoint between the running minimum and maximum in the window.

Returns None if the window is empty.

pub fn clamp_to_window(&self, value: Decimal) -> Decimal

Clamps value to the [running_min, running_max] range of the window.

Returns value unchanged if the window is empty.

pub fn fraction_above_mid(&self) -> Option<f64>

Fraction of window values strictly above the midpoint between the running minimum and maximum.

Returns None if the window is empty or min == max.

pub fn normalized_range(&self) -> Option<f64>

Ratio of the window span (max − min) to the mean.

Returns None if the window is empty, has fewer than 2 elements, or the mean is zero.

pub fn min_max(&self) -> Option<(Decimal, Decimal)>

Returns the (running_min, running_max) pair for the current window.

Returns None if the window is empty.

pub fn values(&self) -> Vec<Decimal>

All current window values as a Vec<Decimal>, in insertion order (oldest first).

pub fn above_zero_fraction(&self) -> Option<f64>

Fraction of window values that are strictly positive (> 0).

Returns None if the window is empty.

pub fn z_score_opt(&self, value: Decimal) -> Option<f64>

Z-score of value relative to the current window, returned as Option<f64>.

Returns None if the window has fewer than 2 elements or variance is zero. Unlike [normalize], this never returns an error for empty windows — it simply returns None.

pub fn is_stable(&self, z_threshold: f64) -> bool

Returns true if the absolute z-score of the latest observation is within z_threshold standard deviations of the mean.

Returns false if the window is empty or has insufficient data.

pub fn fraction_above(&self, threshold: Decimal) -> Option<f64>

Fraction of window values strictly above threshold.

Returns None if the window is empty.

pub fn fraction_below(&self, threshold: Decimal) -> Option<f64>

Fraction of window values strictly below threshold.

Returns None if the window is empty.

pub fn window_values_above(&self, threshold: Decimal) -> Vec<Decimal>

Returns all window values strictly above threshold.

pub fn window_values_below(&self, threshold: Decimal) -> Vec<Decimal>

Returns all window values strictly below threshold.

pub fn count_equal(&self, value: Decimal) -> usize

Count of window values equal to value.

pub fn rolling_range(&self) -> Option<Decimal>

Range of the current window: running_max - running_min.

Returns None if the window is empty.

pub fn autocorrelation_lag1(&self) -> Option<f64>

Lag-1 autocorrelation of the window values.

Returns None if fewer than 2 values or variance is zero.

pub fn trend_consistency(&self) -> Option<f64>

Fraction of consecutive pairs where the second value > first (trending upward).

Returns None if fewer than 2 values.

pub fn mean_absolute_deviation(&self) -> Option<f64>

Mean absolute deviation of the window values.

Returns None if window is empty.

pub fn percentile_of_latest(&self) -> Option<f64>

Percentile rank of the most recently added value within the window.

Returns None if no value has been added yet. Uses the same <= semantics as percentile.

pub fn tail_ratio(&self) -> Option<f64>

Tail ratio: max(window) / 75th-percentile(window).

A simple fat-tail indicator. Values well above 1.0 signal that the maximum observation is an outlier relative to the upper quartile. Returns None if the window is empty or the 75th percentile is zero.

pub fn z_score_of_min(&self) -> Option<f64>

Z-score of the window minimum relative to the current mean and std dev.

Returns None if the window is empty or std dev is zero.

pub fn z_score_of_max(&self) -> Option<f64>

Z-score of the window maximum relative to the current mean and std dev.

Returns None if the window is empty or std dev is zero.

pub fn window_entropy(&self) -> Option<f64>

Shannon entropy of the window values.

Each unique value is treated as a category. Returns None if the window is empty. A uniform distribution maximises entropy; identical values give Some(0.0).

pub fn normalized_std_dev(&self) -> Option<f64>

Normalised standard deviation (alias for coefficient_of_variation).

pub fn value_above_mean_count(&self) -> Option<usize>

Count of window values that are strictly above the window mean.

Returns None if the window is empty or the mean cannot be computed.

pub fn consecutive_above_mean(&self) -> Option<usize>

Length of the longest consecutive run of values above the window mean.

Returns None if the window is empty or the mean cannot be computed.

pub fn above_threshold_fraction(&self, threshold: Decimal) -> Option<f64>

Fraction of window values above threshold.

Returns None if the window is empty.

pub fn below_threshold_fraction(&self, threshold: Decimal) -> Option<f64>

Fraction of window values below threshold.

Returns None if the window is empty.

pub fn lag_k_autocorrelation(&self, k: usize) -> Option<f64>

Autocorrelation at lag k of the window values.

Returns None if k == 0, k >= window.len(), or variance is zero.

pub fn half_life_estimate(&self) -> Option<f64>

Estimated half-life of mean reversion using a simple AR(1) regression.

Half-life ≈ -ln(2) / ln(|β|) where β is the AR(1) coefficient. Returns None if the window has fewer than 3 values, the regression denominator is zero, or β ≥ 0 (no mean-reversion signal).

pub fn geometric_mean(&self) -> Option<f64>

Geometric mean of the window values.

exp(mean(ln(v_i))). Returns None if the window is empty or any value is non-positive.

pub fn harmonic_mean(&self) -> Option<f64>

Harmonic mean of the window values.

n / sum(1/v_i). Returns None if the window is empty or any value is zero.

pub fn range_normalized_value(&self, value: Decimal) -> Option<f64>

Normalise value to the window’s observed [min, max] range.

Returns None if the window is empty or the range is zero.

pub fn distance_from_median(&self, value: Decimal) -> Option<f64>

Signed distance of value from the window median.

value - median. Returns None if the window is empty.

pub fn momentum(&self) -> Option<f64>

Momentum: difference between the latest and oldest value in the window.

Positive = window trended up; negative = trended down. Returns None if fewer than 2 values are in the window.

pub fn value_rank(&self, value: Decimal) -> Option<f64>

Rank of value within the current window, normalised to [0.0, 1.0].

0.0 means value is ≤ all window values; 1.0 means it is ≥ all window values. Returns None if the window is empty.

pub fn coeff_of_variation(&self) -> Option<f64>

Coefficient of variation: std_dev / |mean|.

Returns None if the window has fewer than 2 values or the mean is zero.

pub fn quantile_range(&self) -> Option<f64>

Inter-quartile range: Q3 (75th percentile) minus Q1 (25th percentile).

Returns None if the window is empty.

pub fn upper_quartile(&self) -> Option<Decimal>

Upper quartile (Q3, 75th percentile) of the window values.

Returns None if the window is empty.

pub fn lower_quartile(&self) -> Option<Decimal>

Lower quartile (Q1, 25th percentile) of the window values.

Returns None if the window is empty.

pub fn sign_change_rate(&self) -> Option<f64>

Fraction of consecutive first-difference pairs whose sign flips.

A high value indicates a rapidly oscillating series; a low value indicates persistent trends. Returns None for fewer than 3 observations.

pub fn trimmed_mean(&self, p: f64) -> Option<f64>

Trimmed mean: arithmetic mean after discarding the bottom and top p fraction of window values.

p is clamped to [0.0, 0.499]. Returns None if the window is empty or trimming removes all observations.

pub fn linear_trend_slope(&self) -> Option<f64>

OLS linear trend slope of window values over their insertion index.

A positive slope indicates an upward trend; negative indicates downward. Returns None if the window has fewer than 2 observations.

pub fn variance_ratio(&self) -> Option<f64>

Ratio of first-half to second-half window variance.

Values above 1.0 indicate decreasing volatility; below 1.0 indicate increasing volatility. Returns None if fewer than 4 observations or second-half variance is zero.

pub fn z_score_trend_slope(&self) -> Option<f64>

Linear trend slope of the z-scores of window values.

Computes the z-score of each window value then fits an OLS line over the sequence. Positive slope means z-scores are trending upward. Returns None if fewer than 2 observations or std-dev is zero.

pub fn mean_absolute_change(&self) -> Option<f64>

Mean of |x_i − x_{i-1}| across consecutive window values; average absolute change.

pub fn monotone_increase_fraction(&self) -> Option<f64>

Fraction of consecutive pairs that are monotonically increasing.

pub fn abs_max(&self) -> Option<Decimal>

Maximum absolute value in the rolling window.

pub fn abs_min(&self) -> Option<Decimal>

Minimum absolute value in the rolling window.

pub fn max_count(&self) -> Option<usize>

Count of values equal to the window maximum.

pub fn min_count(&self) -> Option<usize>

Count of values equal to the window minimum.

pub fn mean_ratio(&self) -> Option<f64>

Ratio of current full-window mean to the mean of the first half.

pub fn exponential_weighted_mean(&self, alpha: f64) -> Option<f64>

Exponentially-weighted mean with decay factor alpha ∈ (0, 1]; most-recent value has highest weight.

pub fn peak_to_trough_ratio(&self) -> Option<f64>

Ratio of window maximum to window minimum; requires non-zero minimum.

pub fn second_moment(&self) -> Option<f64>

Mean of squared values in the window (second raw moment).

pub fn range_over_mean(&self) -> Option<f64>

Range / mean — coefficient of dispersion; None if mean is zero.

pub fn above_median_fraction(&self) -> Option<f64>

Fraction of window values strictly above the window median.

pub fn interquartile_mean(&self) -> Option<f64>

Mean of values strictly between Q1 and Q3 (the interquartile mean).

pub fn outlier_fraction(&self, threshold: f64) -> Option<f64>

Fraction of window values beyond threshold standard deviations from the mean.

pub fn sign_flip_count(&self) -> Option<usize>

Count of sign changes (transitions across zero) in the window.

pub fn rms(&self) -> Option<f64>

Root mean square of window values.

pub fn distinct_count(&self) -> usize

Number of distinct values in the window.

pub fn max_fraction(&self) -> Option<f64>

Fraction of window values that equal the window maximum.

pub fn min_fraction(&self) -> Option<f64>

Fraction of window values that equal the window minimum.

pub fn latest_minus_mean(&self) -> Option<f64>

Difference between the latest value and the window mean (signed).

pub fn latest_to_mean_ratio(&self) -> Option<f64>

Ratio of the latest value to the window mean; None if mean is zero.

pub fn below_mean_fraction(&self) -> Option<f64>

Fraction of window values strictly below the mean.

pub fn tail_variance(&self) -> Option<f64>

Variance of values lying outside the interquartile range. Returns None if fewer than 4 values or fewer than 2 tail values.

pub fn new_max_count(&self) -> usize

Number of times the window reaches a new running maximum (from index 0).

pub fn new_min_count(&self) -> usize

Number of times the window reaches a new running minimum (from index 0).

pub fn zero_fraction(&self) -> Option<f64>

Fraction of window values strictly equal to zero.

pub fn cumulative_sum(&self) -> Decimal

Cumulative sum of all window values.

pub fn max_to_min_ratio(&self) -> Option<f64>

Ratio of the window maximum to the window minimum. Returns None if the window is empty or minimum is zero.

pub fn above_midpoint_fraction(&self) -> Option<f64>

Fraction of window values strictly above the window midpoint (min + max) / 2.

Returns None for an empty window.

pub fn positive_fraction(&self) -> Option<f64>

Fraction of window values strictly greater than zero.

Returns None for an empty window.

pub fn above_mean_fraction(&self) -> Option<f64>

Fraction of window values strictly above the window mean.

Returns None for an empty window.

pub fn window_iqr(&self) -> Option<Decimal>

Interquartile range of the window: Q3 − Q1.

Returns None for an empty window.

pub fn run_length_mean(&self) -> Option<f64>

Mean run length of monotone non-decreasing segments.

Returns None for fewer than 2 values in the window.