pub trait Normalizer {
fn normalize(&self, scores: &mut [f32]);
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct MinMax;
impl Normalizer for MinMax {
fn normalize(&self, scores: &mut [f32]) {
let Some(&first) = scores.first() else {
return;
};
let (min, max) = scores.iter().skip(1).fold((first, first), |(lo, hi), &s| {
(
if s.total_cmp(&lo).is_lt() { s } else { lo },
if s.total_cmp(&hi).is_gt() { s } else { hi },
)
});
let range = max - min;
if range == 0.0 {
scores.fill(1.0);
} else {
for s in scores {
*s = (*s - min) / range;
}
}
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct ZScore;
impl Normalizer for ZScore {
fn normalize(&self, scores: &mut [f32]) {
if scores.is_empty() {
return;
}
let n = scores.len() as f32;
let mean = scores.iter().sum::<f32>() / n;
let variance = scores.iter().map(|s| (s - mean).powi(2)).sum::<f32>() / n;
let stddev = variance.sqrt();
if stddev == 0.0 {
scores.fill(0.0);
} else {
for s in scores {
*s = (*s - mean) / stddev;
}
}
}
}
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Softmax;
impl Normalizer for Softmax {
fn normalize(&self, scores: &mut [f32]) {
let Some(&first) = scores.first() else {
return;
};
let max = scores.iter().skip(1).fold(
first,
|hi, &s| if s.total_cmp(&hi).is_gt() { s } else { hi },
);
let mut sum = 0.0f32;
for s in scores.iter_mut() {
*s = (*s - max).exp();
sum += *s;
}
for s in scores {
*s /= sum;
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn minmax_maps_to_unit_interval() {
let mut s = [2.0, 6.0, 4.0];
MinMax.normalize(&mut s);
assert_eq!(s, [0.0, 1.0, 0.5]);
}
#[test]
fn minmax_single_element_is_one() {
let mut s = [5.0];
MinMax.normalize(&mut s);
assert_eq!(s, [1.0]);
}
#[test]
fn minmax_all_equal_is_one() {
let mut s = [3.0, 3.0, 3.0];
MinMax.normalize(&mut s);
assert_eq!(s, [1.0, 1.0, 1.0]);
}
#[test]
fn minmax_handles_negative_ranges() {
let mut s = [-1.0, 1.0];
MinMax.normalize(&mut s);
assert_eq!(s, [0.0, 1.0]);
}
#[test]
fn zscore_centers_and_scales() {
let mut s = [1.0, 2.0, 3.0];
ZScore.normalize(&mut s);
let sd = (2.0f32 / 3.0).sqrt();
assert!((s[0] - (-1.0 / sd)).abs() < 1e-6);
assert!((s[1]).abs() < 1e-6);
assert!((s[2] - (1.0 / sd)).abs() < 1e-6);
}
#[test]
fn zscore_zero_variance_is_zero() {
let mut s = [3.0, 3.0, 3.0];
ZScore.normalize(&mut s);
assert_eq!(s, [0.0, 0.0, 0.0]);
}
#[test]
fn softmax_is_a_distribution_preserving_order() {
let mut s = [1.0, 3.0, 2.0];
Softmax.normalize(&mut s);
let sum: f32 = s.iter().sum();
assert!((sum - 1.0).abs() < 1e-6);
assert!(s[1] > s[2] && s[2] > s[0]);
}
#[test]
fn softmax_extreme_magnitudes_stay_finite() {
let mut s = [1e30, 1.0];
Softmax.normalize(&mut s);
assert!(s.iter().all(|v| v.is_finite()));
assert!((s[0] - 1.0).abs() < 1e-6);
assert_eq!(s[1], 0.0);
}
#[test]
fn empty_slices_are_noops() {
let mut s: [f32; 0] = [];
MinMax.normalize(&mut s);
ZScore.normalize(&mut s);
Softmax.normalize(&mut s);
}
}