Struct MinMaxNormalizer 

pub struct MinMaxNormalizer { /* private fields */ }

Rolling min-max normalizer over a sliding window of Decimal observations.

Example

use fin_stream::norm::MinMaxNormalizer;
use rust_decimal_macros::dec;

let mut norm = MinMaxNormalizer::new(4).unwrap();
norm.update(dec!(10));
norm.update(dec!(20));
norm.update(dec!(30));
norm.update(dec!(40));

// 40 is the current max; 10 is the current min
let v = norm.normalize(dec!(40)).unwrap();
assert!((v - 1.0).abs() < 1e-10);

Implementations

impl MinMaxNormalizer

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

Create a new 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.

If the window is full, the oldest value is evicted. After the call, the internal min/max cache is marked dirty and will be recomputed lazily on the next call to normalize or min_max.

Complexity: O(1) amortized

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

Return the current (min, max) of the window.

Returns None if the window is empty.

Complexity: O(1) when the cache is clean; O(W) after an eviction.

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

Normalize value into [0.0, 1.0] using the current window.

The value is clamped so that even if value falls outside the window range the result is always in [0.0, 1.0].

Errors

Returns StreamError::NormalizationError if the window is empty (no observations have been fed yet), or if the normalized Decimal cannot be converted to f64.

Complexity: O(1) when cache is clean; O(W) after an eviction.

pub fn denormalize(&mut self, normalized: f64) -> Result<Decimal, StreamError>

Inverse of normalize: map a [0, 1] value back to the original scale.

denormalized = normalized * (max - min) + min

Works outside [0, 1] for extrapolation, but returns StreamError::NormalizationError if the window is empty.

pub fn range(&mut self) -> Option<Decimal>

Scale of the current window: max - min.

Returns None if the window is empty. Returns Decimal::ZERO when all observations are identical (zero range → degenerate distribution).

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

Clamps value to the [min, max] range of the current window.

Returns value unchanged if the window is empty (no clamping possible).

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

Midpoint of the current window: (min + max) / 2.

Returns None if the window is empty.

pub fn reset(&mut self)

Reset the normalizer, clearing all observations and the cache.

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 the last 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 normalizer has seen enough data for stable min/max estimates; before this point early observations dominate the range.

pub fn min(&mut self) -> Option<Decimal>

Current window minimum, or None if the window is empty.

Equivalent to self.min_max().map(|(min, _)| min) but avoids also computing the max when only the min is needed.

pub fn max(&mut self) -> Option<Decimal>

Current window maximum, or None if the window is empty.

Equivalent to self.min_max().map(|(_, max)| max) but avoids also computing the min when only the max is needed.

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

Returns the arithmetic mean of the current window observations.

Returns None if the window is empty.

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

Population variance of the current window: Σ(x − mean)² / n.

Returns None if the window has fewer than 2 observations.

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

Population standard deviation of the current window: sqrt(variance).

Returns None if the window has fewer than 2 observations or if the variance cannot be converted to f64.

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 normalize_batch( &mut self, values: &[Decimal], ) -> Result<Vec<f64>, StreamError>

Feed a slice of values into the window and return normalized forms of each.

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

Errors

Propagates the first StreamError returned by normalize.

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

👎Deprecated since 2.2.0:

Use normalize() instead — it already clamps to [0.0, 1.0]

Normalize value and clamp the result to [0.0, 1.0].

Identical to normalize because normalize already clamps its output to [0.0, 1.0]. Deprecated in favour of calling normalize directly.

Errors

Returns StreamError::NormalizationError if the window is empty.

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

Compute the z-score of value relative to the current window.

z = (value - mean) / stddev

Returns None if the window has fewer than 2 observations, or if the standard deviation is zero (all values identical).

Useful for detecting outliers and standardising features for ML models when a bounded [0, 1] range is not required.

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

Returns the percentile rank of value within the current window.

The percentile rank is the fraction of window values that are <= value, expressed in [0.0, 1.0]. Returns None if the window is empty.

Useful for identifying whether the current value is historically high or low relative to its recent context without requiring a min/max range.

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

Count of observations in the current window that are strictly above threshold.

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

Count of observations in the current window that are strictly below threshold.

Complement to count_above.

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 fraction_above_mid(&mut self) -> Option<f64>

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

Returns None if the window is empty. Returns 0.0 if all values are equal.

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

(max - min) / max as f64 — the range as a fraction of the maximum.

Measures how wide the window’s spread is relative to its peak. Returns None if the window is empty or the maximum is zero.

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

Exponential weighted moving average of the current window values.

Applies alpha as the smoothing factor (most-recent weight), scanning oldest→newest. alpha is clamped to (0, 1]. Returns None if the window is empty.

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 skewness(&self) -> Option<f64>

Skewness of the window values: Σ((x - mean)³/n) / std_dev³.

Positive skew means the tail is longer on the right; negative on the left. Returns None if the window has fewer than 3 observations or std dev is zero.

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

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

Positive values indicate heavier-tailed distributions (leptokurtic); negative values indicate lighter tails (platykurtic). A normal distribution has excess kurtosis of 0.

Returns None if the window has fewer than 4 observations or if the standard deviation is zero (all values identical).

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

Median of the current window values, or None if the window is empty.

For an even-length window the median is the mean of the two middle values.

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

Bessel-corrected (sample) variance of the window — divides by n − 1.

Returns None for fewer than 2 observations.

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

Median absolute deviation (MAD) of the window.

Returns None if the window is empty.

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

Robust z-score of value using median and MAD instead of mean and std-dev.

robust_z = 0.6745 × (value − median) / MAD

The 0.6745 factor makes the scale consistent with the standard normal. Returns None if the window is empty or MAD is zero (all values identical).

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

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

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

Sum of all values currently in the window.

Returns None if the window is empty.

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

Returns true if the absolute z-score of value exceeds z_threshold.

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

Returns a copy of the window values that fall within sigma standard deviations of the mean. Values whose absolute z-score exceeds sigma are excluded.

Returns an empty Vec if the window has fewer than 2 elements.

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

Z-score of the most recently added value.

Returns None if the window has fewer than 2 elements or standard deviation is zero.

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

Signed deviation of value from the window mean, expressed as a floating-point number.

Returns None if the window is empty.

pub fn range_f64(&mut self) -> Option<f64>

Window range (max − min) as a f64.

Returns None if the window has fewer than 1 element.

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

Sum of all values in the window as a f64.

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 normalized_midpoint(&mut self) -> Option<f64>

Normalize the window midpoint ((min + max) / 2) and return it as a f64.

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

pub fn is_at_min(&mut self, value: Decimal) -> bool

Returns true if value equals the current window minimum.

Returns false if the window is empty.

pub fn is_at_max(&mut self, value: Decimal) -> bool

Returns true if value equals the current window maximum.

Returns false if the window is empty.

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: max - min.

Returns None if the window is empty.

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

Lag-1 autocorrelation of the window values.

Measures how much each value predicts the next. 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_rank.

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 from regressing Δy_t on y_{t-1}. 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.

Computes Δx_i = x_i − x_{i−1}, then counts pairs (Δx_i, Δx_{i+1}) where both are non-zero and have opposite signs. The result is in [0.0, 1.0]. A high value indicates a rapidly oscillating series; a low value indicates persistent trends. Returns None for fewer than 3 observations.

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

Count of trailing values (from the newest end of the window) that are strictly below the window mean.

Returns None if the window has fewer than 2 values.

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

Drift rate: (mean_of_second_half − mean_of_first_half) / |mean_of_first_half|.

Splits the window at its midpoint and compares the two halves. Returns None if the window has fewer than 2 values or the first-half mean is zero.

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

Ratio of the window maximum to the window minimum: max / min.

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

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

Normalised deviation of the latest value: (latest − mean) / range.

Returns None if the window is empty, has fewer than 2 values, the range is zero, or there is no latest value.

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

Coefficient of variation as a percentage: (std_dev / |mean|) × 100.

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

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

Rank of the latest value in the sorted window as a fraction in [0, 1]. Computed as (number of values strictly below latest) / (window_len − 1).

Returns None if the window has fewer than 2 values.

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 the first-half window variance to the second-half window variance.

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

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

Linear trend slope of z-scores over the window.

First computes the z-score of each window value relative to the full window mean and std-dev, then returns the OLS slope over the resulting z-score sequence. Positive 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.

Computed as count(x_{i+1} > x_i) / (n − 1). Returns None for windows with fewer than 2 values.

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

Maximum absolute value in the window.

Returns None if the window is empty.

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

Minimum absolute value in the window.

Returns None if the window is empty.

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

Count of values in the window that equal the window maximum.

Returns None if the window is empty.

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

Count of values in the window that equal the window minimum.

Returns None if the window is empty.

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

Ratio of the current window mean to the mean computed at window creation time (first window_size / 2 values).

Returns None if fewer than 2 observations or the early mean is zero.

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 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 no 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 (running total).

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 span_utilization(&self) -> Option<f64>

Position of the latest window value in the range: (latest − min) / (max − min).

Returns None when the window is empty or has zero range.

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

Fraction of window values strictly greater than zero.

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.