Skip to main content

solow_preprocessing/
target_encoder.rs

1//! TargetEncoder — mean-target encoding with a smoothing prior.
2//!
3//! For each categorical column `j`, replaces every value `v` with
4//!
5//! ```text
6//!     ĉ(v) = (nⱼ,ᵥ · μⱼ,ᵥ + m · μ_global) / (nⱼ,ᵥ + m)
7//! ```
8//!
9//! `μⱼ,ᵥ` = mean of `y` when `xⱼ = v`, and `m` is a Bayesian
10//! smoothing hyperparameter (`smooth` in the reference ≥ 1.3).
11
12use ndarray::{Array2, ArrayView2};
13use solow_core::{Error, Result};
14
15/// TargetEncoder.
16#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
17#[derive(Clone, Debug, PartialEq)]
18pub struct TargetEncoder {
19    /// Per-column category → smoothed mean.
20    pub encodings: Vec<std::collections::BTreeMap<i64, f64>>,
21    /// Global fallback mean.
22    pub target_mean: f64,
23    /// Smoothing weight `m`.
24    pub smooth: f64,
25    /// Column count at fit time.
26    pub n_features_in: usize,
27}
28
29impl TargetEncoder {
30    /// Fit with `smooth = 10.0`.
31    pub fn fit(x: ArrayView2<'_, f64>, y: &[f64]) -> Result<Self> {
32        Self::fit_with(x, y, 10.0)
33    }
34
35    /// Full-configuration fit. Column values are read as `i64` (i.e.,
36    /// the caller has already integer-encoded the categorical column).
37    pub fn fit_with(x: ArrayView2<'_, f64>, y: &[f64], smooth: f64) -> Result<Self> {
38        let n = x.nrows();
39        if y.len() != n {
40            return Err(Error::Shape("TargetEncoder: y/x length mismatch".into()));
41        }
42        if smooth < 0.0 {
43            return Err(Error::Value("TargetEncoder: smooth must be ≥ 0".into()));
44        }
45        let d = x.ncols();
46        let mut target_mean = 0.0_f64;
47        for &v in y {
48            target_mean += v;
49        }
50        target_mean /= n as f64;
51        let mut encodings: Vec<std::collections::BTreeMap<i64, f64>> = Vec::with_capacity(d);
52        for j in 0..d {
53            let mut sums: std::collections::BTreeMap<i64, (f64, usize)> = Default::default();
54            for i in 0..n {
55                let cat = x[[i, j]].round() as i64;
56                let e = sums.entry(cat).or_insert((0.0, 0));
57                e.0 += y[i];
58                e.1 += 1;
59            }
60            let mut map: std::collections::BTreeMap<i64, f64> = Default::default();
61            for (k, (s, c)) in sums {
62                let mean = s / c as f64;
63                let smoothed = (c as f64 * mean + smooth * target_mean) / (c as f64 + smooth);
64                map.insert(k, smoothed);
65            }
66            encodings.push(map);
67        }
68        Ok(Self {
69            encodings,
70            target_mean,
71            smooth,
72            n_features_in: d,
73        })
74    }
75
76    /// Transform: replace each value with its smoothed target mean.
77    pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
78        if x.ncols() != self.n_features_in {
79            return Err(Error::Shape("TargetEncoder::transform: column count mismatch".into()));
80        }
81        let n = x.nrows();
82        let d = x.ncols();
83        let mut out = Array2::<f64>::zeros((n, d));
84        for i in 0..n {
85            for j in 0..d {
86                let cat = x[[i, j]].round() as i64;
87                out[[i, j]] = *self.encodings[j].get(&cat).unwrap_or(&self.target_mean);
88            }
89        }
90        Ok(out)
91    }
92}
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97    use ndarray::array;
98
99    #[test]
100    fn target_encoder_replaces_categories_with_smoothed_means() {
101        // 3 categories, y = category * 10 → smoothed toward global mean = 10.
102        let x = array![[0.0_f64], [0.0], [1.0], [1.0], [2.0], [2.0]];
103        let y = vec![0.0_f64, 0.0, 10.0, 10.0, 20.0, 20.0];
104        let te = TargetEncoder::fit_with(x.view(), &y, 1.0).unwrap();
105        let z = te.transform(x.view()).unwrap();
106        assert!((z[[0, 0]] - z[[1, 0]]).abs() < 1e-12);
107        assert!(z[[0, 0]] < z[[2, 0]]);
108        assert!(z[[2, 0]] < z[[4, 0]]);
109    }
110}