1use ndarray::{Array1, Array2, ArrayView1, ArrayView2, Axis};
40use solow_core::{numeric::compensated_mean_and_var, Error, Result};
41
42#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
63#[derive(Clone, Debug, PartialEq)]
64pub struct StandardScaler {
65 pub mean: Array1<f64>,
67 pub scale: Array1<f64>,
70 biased: bool,
72 with_mean: bool,
74 with_std: bool,
76}
77
78impl StandardScaler {
79 pub fn fit(x: ArrayView2<'_, f64>) -> Result<Self> {
81 Self::fit_with(x, true, true, false)
82 }
83
84 pub fn fit_with(
91 x: ArrayView2<'_, f64>,
92 with_mean: bool,
93 with_std: bool,
94 biased: bool,
95 ) -> Result<Self> {
96 if x.nrows() == 0 || x.ncols() == 0 {
97 return Err(Error::Value(
98 "StandardScaler::fit: x must have at least one row and one column".into(),
99 ));
100 }
101 let d = x.ncols();
102 let n = x.nrows();
103 let mut mean = Array1::<f64>::zeros(d);
104 let mut scale = Array1::<f64>::ones(d);
105 for j in 0..d {
106 let (m, v) = compensated_mean_and_var(x.column(j).iter().copied());
107 mean[j] = m;
108 let var = if biased && n > 1 {
110 v * (n as f64 - 1.0) / n as f64
111 } else {
112 v
113 };
114 let s = var.sqrt();
115 scale[j] = if s > 0.0 && s.is_finite() { s } else { 1.0 };
116 }
117 Ok(Self {
118 mean,
119 scale,
120 biased,
121 with_mean,
122 with_std,
123 })
124 }
125
126 pub fn population(mut self) -> Self {
128 self.biased = true;
129 self
130 }
131
132 pub fn fit_transform(x: ArrayView2<'_, f64>) -> Result<(Self, Array2<f64>)> {
134 let s = Self::fit(x)?;
135 let t = s.transform(x)?;
136 Ok((s, t))
137 }
138
139 pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
141 if x.ncols() != self.mean.len() {
142 return Err(Error::Shape(format!(
143 "StandardScaler::transform: expected {} columns, got {}",
144 self.mean.len(),
145 x.ncols()
146 )));
147 }
148 let mut out = x.to_owned();
149 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
150 for v in col.iter_mut() {
151 if self.with_mean {
152 *v -= self.mean[j];
153 }
154 if self.with_std {
155 *v /= self.scale[j];
156 }
157 }
158 }
159 Ok(out)
160 }
161
162 pub fn inverse_transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
164 if x.ncols() != self.mean.len() {
165 return Err(Error::Shape(format!(
166 "StandardScaler::inverse_transform: expected {} columns, got {}",
167 self.mean.len(),
168 x.ncols()
169 )));
170 }
171 let mut out = x.to_owned();
172 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
173 for v in col.iter_mut() {
174 if self.with_std {
175 *v *= self.scale[j];
176 }
177 if self.with_mean {
178 *v += self.mean[j];
179 }
180 }
181 }
182 Ok(out)
183 }
184}
185
186#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
195#[derive(Clone, Debug, PartialEq)]
196pub struct MinMaxScaler {
197 pub data_min: Array1<f64>,
199 pub data_max: Array1<f64>,
201 pub scale: Array1<f64>,
204 pub min: Array1<f64>,
206 pub low: f64,
208 pub high: f64,
210}
211
212impl MinMaxScaler {
213 pub fn fit(x: ArrayView2<'_, f64>) -> Result<Self> {
215 Self::fit_range(x, 0.0, 1.0)
216 }
217
218 pub fn fit_range(x: ArrayView2<'_, f64>, low: f64, high: f64) -> Result<Self> {
220 if x.nrows() == 0 || x.ncols() == 0 {
221 return Err(Error::Value(
222 "MinMaxScaler::fit_range: x must have at least one row and one column".into(),
223 ));
224 }
225 if !(low.is_finite() && high.is_finite() && low < high) {
226 return Err(Error::Value(format!(
227 "MinMaxScaler::fit_range: require low < high (got low={low}, high={high})"
228 )));
229 }
230 let d = x.ncols();
231 let mut data_min = Array1::<f64>::zeros(d);
232 let mut data_max = Array1::<f64>::zeros(d);
233 let mut scale = Array1::<f64>::ones(d);
234 let mut min = Array1::<f64>::zeros(d);
235 for j in 0..d {
236 let mut mn = f64::INFINITY;
237 let mut mx = f64::NEG_INFINITY;
238 for &v in x.column(j).iter() {
239 if !v.is_finite() {
240 return Err(Error::Value(format!(
241 "MinMaxScaler::fit_range: column {j} contains non-finite values"
242 )));
243 }
244 if v < mn {
245 mn = v;
246 }
247 if v > mx {
248 mx = v;
249 }
250 }
251 data_min[j] = mn;
252 data_max[j] = mx;
253 let range = mx - mn;
254 if range > 0.0 {
255 scale[j] = (high - low) / range;
256 min[j] = low - mn * scale[j];
257 } else {
258 scale[j] = 0.0;
260 min[j] = 0.5 * (low + high);
261 }
262 }
263 Ok(Self {
264 data_min,
265 data_max,
266 scale,
267 min,
268 low,
269 high,
270 })
271 }
272
273 pub fn fit_transform(x: ArrayView2<'_, f64>) -> Result<(Self, Array2<f64>)> {
275 let s = Self::fit(x)?;
276 let t = s.transform(x)?;
277 Ok((s, t))
278 }
279
280 pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
282 if x.ncols() != self.scale.len() {
283 return Err(Error::Shape(format!(
284 "MinMaxScaler::transform: expected {} columns, got {}",
285 self.scale.len(),
286 x.ncols()
287 )));
288 }
289 let mut out = x.to_owned();
290 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
291 for v in col.iter_mut() {
292 *v = *v * self.scale[j] + self.min[j];
293 }
294 }
295 Ok(out)
296 }
297
298 pub fn inverse_transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
300 if x.ncols() != self.scale.len() {
301 return Err(Error::Shape(format!(
302 "MinMaxScaler::inverse_transform: expected {} columns, got {}",
303 self.scale.len(),
304 x.ncols()
305 )));
306 }
307 let mut out = x.to_owned();
308 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
309 if self.scale[j] > 0.0 {
310 for v in col.iter_mut() {
311 *v = (*v - self.min[j]) / self.scale[j];
312 }
313 } else {
314 for v in col.iter_mut() {
316 *v = self.data_min[j];
317 }
318 }
319 }
320 Ok(out)
321 }
322}
323
324#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
336#[derive(Clone, Debug, PartialEq)]
337pub struct RobustScaler {
338 pub center: Array1<f64>,
340 pub scale: Array1<f64>,
342 pub q_low: f64,
344 pub q_high: f64,
346 with_center: bool,
348 with_scale: bool,
350}
351
352impl RobustScaler {
353 pub fn fit(x: ArrayView2<'_, f64>) -> Result<Self> {
355 Self::fit_range(x, 0.25, 0.75, true, true)
356 }
357
358 pub fn fit_range(
360 x: ArrayView2<'_, f64>,
361 q_low: f64,
362 q_high: f64,
363 with_center: bool,
364 with_scale: bool,
365 ) -> Result<Self> {
366 if !(0.0 <= q_low && q_low < q_high && q_high <= 1.0) {
367 return Err(Error::Value(format!(
368 "RobustScaler::fit_range: require 0 ≤ q_low < q_high ≤ 1 (got {q_low}, {q_high})"
369 )));
370 }
371 if x.nrows() == 0 || x.ncols() == 0 {
372 return Err(Error::Value(
373 "RobustScaler::fit_range: x must have at least one row and one column".into(),
374 ));
375 }
376 let d = x.ncols();
377 let mut center = Array1::<f64>::zeros(d);
378 let mut scale = Array1::<f64>::ones(d);
379 for j in 0..d {
380 let mut col: Vec<f64> = x.column(j).iter().copied().collect();
381 col.sort_by(|a, b| a.partial_cmp(b).unwrap());
382 center[j] = quantile_sorted(&col, 0.5);
383 let iqr = quantile_sorted(&col, q_high) - quantile_sorted(&col, q_low);
384 scale[j] = if iqr > 0.0 && iqr.is_finite() {
385 iqr
386 } else {
387 1.0
388 };
389 }
390 Ok(Self {
391 center,
392 scale,
393 q_low,
394 q_high,
395 with_center,
396 with_scale,
397 })
398 }
399
400 pub fn quantile_range(mut self, q_low: f64, q_high: f64) -> Self {
402 self.q_low = q_low;
403 self.q_high = q_high;
404 self
405 }
406
407 pub fn fit_transform(x: ArrayView2<'_, f64>) -> Result<(Self, Array2<f64>)> {
409 let s = Self::fit(x)?;
410 let t = s.transform(x)?;
411 Ok((s, t))
412 }
413
414 pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
416 if x.ncols() != self.center.len() {
417 return Err(Error::Shape(format!(
418 "RobustScaler::transform: expected {} columns, got {}",
419 self.center.len(),
420 x.ncols()
421 )));
422 }
423 let mut out = x.to_owned();
424 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
425 for v in col.iter_mut() {
426 if self.with_center {
427 *v -= self.center[j];
428 }
429 if self.with_scale {
430 *v /= self.scale[j];
431 }
432 }
433 }
434 Ok(out)
435 }
436
437 pub fn inverse_transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
439 if x.ncols() != self.center.len() {
440 return Err(Error::Shape(format!(
441 "RobustScaler::inverse_transform: expected {} columns, got {}",
442 self.center.len(),
443 x.ncols()
444 )));
445 }
446 let mut out = x.to_owned();
447 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
448 for v in col.iter_mut() {
449 if self.with_scale {
450 *v *= self.scale[j];
451 }
452 if self.with_center {
453 *v += self.center[j];
454 }
455 }
456 }
457 Ok(out)
458 }
459}
460
461#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
470#[derive(Clone, Debug, PartialEq)]
471pub struct MaxAbsScaler {
472 pub max_abs: Array1<f64>,
474 pub scale: Array1<f64>,
476}
477
478impl MaxAbsScaler {
479 pub fn fit(x: ArrayView2<'_, f64>) -> Result<Self> {
481 if x.nrows() == 0 || x.ncols() == 0 {
482 return Err(Error::Value(
483 "MaxAbsScaler::fit: x must have at least one row and one column".into(),
484 ));
485 }
486 let d = x.ncols();
487 let mut max_abs = Array1::<f64>::zeros(d);
488 let mut scale = Array1::<f64>::ones(d);
489 for j in 0..d {
490 let m = x
491 .column(j)
492 .iter()
493 .copied()
494 .map(f64::abs)
495 .fold(0.0, f64::max);
496 max_abs[j] = m;
497 scale[j] = if m > 0.0 { m } else { 1.0 };
498 }
499 Ok(Self { max_abs, scale })
500 }
501
502 pub fn fit_transform(x: ArrayView2<'_, f64>) -> Result<(Self, Array2<f64>)> {
504 let s = Self::fit(x)?;
505 let t = s.transform(x)?;
506 Ok((s, t))
507 }
508
509 pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
511 if x.ncols() != self.scale.len() {
512 return Err(Error::Shape(format!(
513 "MaxAbsScaler::transform: expected {} columns, got {}",
514 self.scale.len(),
515 x.ncols()
516 )));
517 }
518 let mut out = x.to_owned();
519 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
520 for v in col.iter_mut() {
521 *v /= self.scale[j];
522 }
523 }
524 Ok(out)
525 }
526
527 pub fn inverse_transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
529 if x.ncols() != self.scale.len() {
530 return Err(Error::Shape(format!(
531 "MaxAbsScaler::inverse_transform: expected {} columns, got {}",
532 self.scale.len(),
533 x.ncols()
534 )));
535 }
536 let mut out = x.to_owned();
537 for (j, mut col) in out.axis_iter_mut(Axis(1)).enumerate() {
538 for v in col.iter_mut() {
539 *v *= self.scale[j];
540 }
541 }
542 Ok(out)
543 }
544}
545
546#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
552#[derive(Copy, Clone, Debug, PartialEq, Eq)]
553pub enum NormKind {
554 L1,
556 L2,
558 Max,
560}
561
562#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
572#[derive(Copy, Clone, Debug, PartialEq)]
573pub struct Normalizer {
574 pub kind: NormKind,
576}
577
578impl Normalizer {
579 pub fn new(kind: NormKind) -> Self {
581 Self { kind }
582 }
583
584 pub fn default() -> Self {
586 Self { kind: NormKind::L2 }
587 }
588
589 pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
591 let mut out = x.to_owned();
592 for mut row in out.axis_iter_mut(Axis(0)) {
593 let n = match self.kind {
594 NormKind::L1 => row.iter().map(|v| v.abs()).sum::<f64>(),
595 NormKind::L2 => row.iter().map(|v| v * v).sum::<f64>().sqrt(),
596 NormKind::Max => row.iter().map(|v| v.abs()).fold(0.0, f64::max),
597 };
598 if n > 0.0 {
599 for v in row.iter_mut() {
600 *v /= n;
601 }
602 }
603 }
604 Ok(out)
605 }
606
607 pub fn fit_transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
609 self.transform(x)
610 }
611}
612
613fn quantile_sorted(sorted: &[f64], q: f64) -> f64 {
618 let n = sorted.len();
619 if n == 0 {
620 return f64::NAN;
621 }
622 let h = (n as f64 - 1.0) * q;
623 let lo = h.floor() as usize;
624 let hi = (lo + 1).min(n - 1);
625 let frac = h - lo as f64;
626 (1.0 - frac) * sorted[lo] + frac * sorted[hi]
627}
628
629#[allow(dead_code)]
631fn _unused(_v: ArrayView1<'_, f64>) {}
632
633#[cfg(test)]
634mod tests {
635 use super::*;
636 use approx::assert_abs_diff_eq;
637 use ndarray::array;
638
639 #[test]
640 fn standard_scaler_zeroes_mean_and_units_variance() {
641 let x = array![[1.0, 10.0], [2.0, 20.0], [3.0, 30.0], [4.0, 40.0]];
642 let scaler = StandardScaler::fit(x.view()).unwrap();
643 assert_abs_diff_eq!(scaler.mean[0], 2.5, epsilon = 1e-12);
644 assert_abs_diff_eq!(scaler.mean[1], 25.0, epsilon = 1e-12);
645 let t = scaler.transform(x.view()).unwrap();
646 for j in 0..2 {
648 let m: f64 = t.column(j).iter().sum::<f64>() / t.nrows() as f64;
649 assert_abs_diff_eq!(m, 0.0, epsilon = 1e-12);
650 }
651 let back = scaler.inverse_transform(t.view()).unwrap();
653 for (a, b) in back.iter().zip(x.iter()) {
654 assert_abs_diff_eq!(a, b, epsilon = 1e-12);
655 }
656 }
657
658 #[test]
659 fn minmax_scaler_maps_to_target_range() {
660 let x = array![[-1.0, 100.0], [0.0, 0.0], [1.0, -100.0]];
661 let scaler = MinMaxScaler::fit_range(x.view(), 0.0, 1.0).unwrap();
662 let t = scaler.transform(x.view()).unwrap();
663 for j in 0..2 {
664 let mn = t.column(j).iter().cloned().fold(f64::INFINITY, f64::min);
665 let mx = t
666 .column(j)
667 .iter()
668 .cloned()
669 .fold(f64::NEG_INFINITY, f64::max);
670 assert_abs_diff_eq!(mn, 0.0, epsilon = 1e-12);
671 assert_abs_diff_eq!(mx, 1.0, epsilon = 1e-12);
672 }
673 let back = scaler.inverse_transform(t.view()).unwrap();
675 for (a, b) in back.iter().zip(x.iter()) {
676 assert_abs_diff_eq!(a, b, epsilon = 1e-12);
677 }
678 }
679
680 #[test]
681 fn robust_scaler_is_immune_to_a_lone_outlier() {
682 let x = array![[1e6, 1.0], [1.0, 2.0], [2.0, 3.0], [3.0, 4.0], [4.0, 5.0]];
687 let robust = RobustScaler::fit(x.view()).unwrap();
688 assert_abs_diff_eq!(robust.center[0], 3.0, epsilon = 1e-12);
689 assert_abs_diff_eq!(robust.scale[0], 2.0, epsilon = 1e-12);
690 }
691
692 #[test]
693 fn maxabs_scaler_preserves_sign() {
694 let x = array![[2.0, -4.0], [-1.0, 2.0], [0.0, 0.0]];
695 let scaler = MaxAbsScaler::fit(x.view()).unwrap();
696 let t = scaler.transform(x.view()).unwrap();
697 assert_abs_diff_eq!(t[[0, 0]], 1.0, epsilon = 1e-12);
698 assert_abs_diff_eq!(t[[1, 0]], -0.5, epsilon = 1e-12);
699 assert_abs_diff_eq!(t[[0, 1]], -1.0, epsilon = 1e-12);
700 }
701
702 #[test]
703 fn normalizer_l2_gives_unit_norm_rows() {
704 let x = array![[3.0, 4.0], [1.0, 0.0], [0.0, 0.0]];
705 let n = Normalizer::default();
706 let t = n.transform(x.view()).unwrap();
707 assert_abs_diff_eq!(
708 (t.row(0).iter().map(|v| v * v).sum::<f64>()).sqrt(),
709 1.0,
710 epsilon = 1e-12
711 );
712 assert_abs_diff_eq!(t[[2, 0]], 0.0, epsilon = 1e-12); }
714
715 #[test]
716 fn standard_scaler_handles_constant_columns() {
717 let x = array![[1.0, 5.0], [1.0, 6.0], [1.0, 7.0]];
718 let scaler = StandardScaler::fit(x.view()).unwrap();
719 assert_eq!(scaler.scale[0], 1.0); let t = scaler.transform(x.view()).unwrap();
721 assert_abs_diff_eq!(t[[0, 0]], 0.0, epsilon = 1e-12);
722 }
723}