Skip to main content

solow_preprocessing/
encoders.rs

1//! Categorical encoders.
2//!
3//! * [`LabelEncoder`] — 1-D categorical values (any hashable) ↔ dense
4//!   `usize` indices, with a stable-sorted vocabulary so a given input
5//!   distribution always produces the same encoding across runs.
6//! * [`OrdinalEncoder`] — the multi-column generalisation for a full
7//!   feature matrix; each column has its own [`LabelEncoder`].
8//! * [`OneHotEncoder`] — expands each categorical column into a dense
9//!   `k`-column binary indicator block. Supports `drop_first` for
10//!   dummy-variable regression parity with `pandas.get_dummies(..., drop_first=True)`,
11//!   and reports the fitted per-column categories so unseen categories
12//!   at transform time raise a clean [`Error::Value`] instead of a panic.
13
14use ndarray::{Array1, Array2, ArrayView1, ArrayView2, Axis};
15use solow_core::{Error, Result};
16use std::collections::BTreeMap;
17
18// ---------------------------------------------------------------------------
19// LabelEncoder
20// ---------------------------------------------------------------------------
21
22/// 1-D label ↔ `usize` encoder with a lexicographically-sorted vocabulary.
23///
24/// # Complexity
25///
26/// * `fit`: `O(n · log n)` time (sort + dedup), `O(k)` space where `k`
27///   is the number of distinct classes.
28/// * `transform`: `O(n · log k)` time via binary search.
29#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
30#[derive(Clone, Debug, PartialEq)]
31pub struct LabelEncoder {
32    /// Sorted, deduplicated class values as strings.
33    /// Storing labels as owned `String`s keeps the encoder generic and
34    /// `Serialize`-friendly without pulling in a hashable-trait bound.
35    pub classes: Vec<String>,
36}
37
38impl LabelEncoder {
39    /// Fit onto an iterable of labels (each rendered with `to_string`).
40    pub fn fit<I, T>(labels: I) -> Self
41    where
42        I: IntoIterator<Item = T>,
43        T: ToString,
44    {
45        let mut set: BTreeMap<String, ()> = BTreeMap::new();
46        for l in labels {
47            set.insert(l.to_string(), ());
48        }
49        Self {
50            classes: set.into_keys().collect(),
51        }
52    }
53
54    /// Number of distinct classes.
55    pub fn n_classes(&self) -> usize {
56        self.classes.len()
57    }
58
59    /// Transform each label to its class index. Errors on an unseen label.
60    pub fn transform<I, T>(&self, labels: I) -> Result<Array1<usize>>
61    where
62        I: IntoIterator<Item = T>,
63        T: ToString,
64    {
65        let ll: Vec<String> = labels.into_iter().map(|l| l.to_string()).collect();
66        let mut out = Array1::<usize>::zeros(ll.len());
67        for (i, l) in ll.iter().enumerate() {
68            let idx = self
69                .classes
70                .binary_search(l)
71                .map_err(|_| Error::Value(format!("LabelEncoder: unseen label {l:?}")))?;
72            out[i] = idx;
73        }
74        Ok(out)
75    }
76
77    /// Inverse-map class indices back to labels.
78    pub fn inverse_transform(&self, encoded: ArrayView1<'_, usize>) -> Result<Vec<String>> {
79        let mut out = Vec::with_capacity(encoded.len());
80        for &c in encoded.iter() {
81            if c >= self.classes.len() {
82                return Err(Error::Value(format!(
83                    "LabelEncoder::inverse_transform: class {c} is out of range for {}",
84                    self.classes.len()
85                )));
86            }
87            out.push(self.classes[c].clone());
88        }
89        Ok(out)
90    }
91
92    /// One-call fit + transform.
93    pub fn fit_transform<I, T>(labels: I) -> (Self, Array1<usize>)
94    where
95        I: IntoIterator<Item = T>,
96        T: ToString,
97        T: Clone,
98    {
99        // Materialize once to avoid consuming the iterator twice.
100        let materialized: Vec<T> = labels.into_iter().collect();
101        let enc = Self::fit(materialized.iter().cloned());
102        let arr = enc
103            .transform(materialized.into_iter())
104            .expect("fit vocabulary must cover every input label");
105        (enc, arr)
106    }
107}
108
109// ---------------------------------------------------------------------------
110// OrdinalEncoder
111// ---------------------------------------------------------------------------
112
113/// Multi-column [`LabelEncoder`] — one per feature column.
114///
115/// Takes a `n × d` matrix of numeric categorical codes and returns a
116/// `n × d` matrix of `usize` class indices per column. This is the
117/// natural preprocessor for a tree-based estimator that expects
118/// integer categorical inputs.
119#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
120#[derive(Clone, Debug, PartialEq)]
121pub struct OrdinalEncoder {
122    /// One encoder per column, in column order.
123    pub encoders: Vec<LabelEncoder>,
124}
125
126impl OrdinalEncoder {
127    /// Fit onto a numeric-categorical matrix.
128    pub fn fit(x: ArrayView2<'_, f64>) -> Result<Self> {
129        if x.nrows() == 0 || x.ncols() == 0 {
130            return Err(Error::Value(
131                "OrdinalEncoder::fit: x must have at least one row and one column".into(),
132            ));
133        }
134        let mut encoders = Vec::with_capacity(x.ncols());
135        for j in 0..x.ncols() {
136            let col: Vec<String> = x.column(j).iter().map(|v| v.to_string()).collect();
137            encoders.push(LabelEncoder::fit(col.into_iter()));
138        }
139        Ok(Self { encoders })
140    }
141
142    /// Transform a matrix column-by-column.
143    pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<usize>> {
144        if x.ncols() != self.encoders.len() {
145            return Err(Error::Shape(format!(
146                "OrdinalEncoder::transform: expected {} columns, got {}",
147                self.encoders.len(),
148                x.ncols()
149            )));
150        }
151        let mut out = Array2::<usize>::zeros((x.nrows(), x.ncols()));
152        for j in 0..x.ncols() {
153            let col: Vec<String> = x.column(j).iter().map(|v| v.to_string()).collect();
154            let enc = self.encoders[j].transform(col.into_iter())?;
155            for i in 0..x.nrows() {
156                out[[i, j]] = enc[i];
157            }
158        }
159        Ok(out)
160    }
161
162    /// One-call fit + transform.
163    pub fn fit_transform(x: ArrayView2<'_, f64>) -> Result<(Self, Array2<usize>)> {
164        let e = Self::fit(x)?;
165        let t = e.transform(x)?;
166        Ok((e, t))
167    }
168}
169
170// ---------------------------------------------------------------------------
171// OneHotEncoder
172// ---------------------------------------------------------------------------
173
174/// One-hot / dummy-variable encoder for categorical numeric input.
175///
176/// For a `n × d` matrix, produces a `n × Σⱼ kⱼ` (or `n × Σⱼ (kⱼ - 1)`
177/// with `drop_first`) dense indicator matrix. Column ordering is
178/// deterministic — for column `j` with sorted categories
179/// `[c0, c1, …, ck-1]`, the encoded block appears in that order.
180#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
181#[derive(Clone, Debug, PartialEq)]
182pub struct OneHotEncoder {
183    /// One `LabelEncoder` per input column, in column order.
184    pub encoders: Vec<LabelEncoder>,
185    /// Whether to drop the first category of every column (dummy-variable
186    /// convention, avoids the classical `X'X` rank-deficiency of a full
187    /// dummy set in a design matrix with an intercept).
188    pub drop_first: bool,
189}
190
191impl OneHotEncoder {
192    /// Fit — no drop by default.
193    pub fn fit(x: ArrayView2<'_, f64>) -> Result<Self> {
194        Self::fit_with(x, false)
195    }
196
197    /// Fit with explicit `drop_first` flag.
198    pub fn fit_with(x: ArrayView2<'_, f64>, drop_first: bool) -> Result<Self> {
199        if x.nrows() == 0 || x.ncols() == 0 {
200            return Err(Error::Value(
201                "OneHotEncoder::fit: x must have at least one row and one column".into(),
202            ));
203        }
204        let ord = OrdinalEncoder::fit(x)?;
205        Ok(Self {
206            encoders: ord.encoders,
207            drop_first,
208        })
209    }
210
211    /// Compute the total number of output columns.
212    pub fn n_output_columns(&self) -> usize {
213        self.encoders
214            .iter()
215            .map(|e| {
216                let k = e.n_classes();
217                if self.drop_first {
218                    k.saturating_sub(1)
219                } else {
220                    k
221                }
222            })
223            .sum()
224    }
225
226    /// Transform.
227    pub fn transform(&self, x: ArrayView2<'_, f64>) -> Result<Array2<f64>> {
228        if x.ncols() != self.encoders.len() {
229            return Err(Error::Shape(format!(
230                "OneHotEncoder::transform: expected {} columns, got {}",
231                self.encoders.len(),
232                x.ncols()
233            )));
234        }
235        let cols_out = self.n_output_columns();
236        let mut out = Array2::<f64>::zeros((x.nrows(), cols_out));
237        // For each row and each input column, set the appropriate output col to 1.
238        let mut base_col = 0usize;
239        for (j, enc) in self.encoders.iter().enumerate() {
240            let k = enc.n_classes();
241            let drop = if self.drop_first { 1 } else { 0 };
242            let block_width = k - drop;
243            let col: Vec<String> = x.column(j).iter().map(|v| v.to_string()).collect();
244            let codes = enc.transform(col.into_iter())?;
245            for i in 0..x.nrows() {
246                let c = codes[i];
247                if c < drop {
248                    // Dropped baseline — everything in this block is zero.
249                    continue;
250                }
251                out[[i, base_col + (c - drop)]] = 1.0;
252            }
253            base_col += block_width;
254        }
255        Ok(out)
256    }
257
258    /// One-call fit + transform.
259    pub fn fit_transform(x: ArrayView2<'_, f64>) -> Result<(Self, Array2<f64>)> {
260        let e = Self::fit(x)?;
261        let t = e.transform(x)?;
262        Ok((e, t))
263    }
264}
265
266// Silence "unused import" when the module compiles without exercising it.
267#[allow(dead_code)]
268fn _touch(_: Axis) {}
269
270#[cfg(test)]
271mod tests {
272    use super::*;
273    use ndarray::array;
274
275    #[test]
276    fn label_encoder_round_trip() {
277        let (enc, codes) = LabelEncoder::fit_transform(["b", "a", "c", "a", "b"]);
278        assert_eq!(
279            enc.classes,
280            vec!["a".to_string(), "b".to_string(), "c".to_string()]
281        );
282        assert_eq!(codes.to_vec(), vec![1, 0, 2, 0, 1]);
283        let back = enc.inverse_transform(codes.view()).unwrap();
284        assert_eq!(back, vec!["b", "a", "c", "a", "b"]);
285    }
286
287    #[test]
288    fn label_encoder_rejects_unseen() {
289        let enc = LabelEncoder::fit(["a", "b", "c"]);
290        assert!(enc.transform(["a", "d"].into_iter()).is_err());
291    }
292
293    #[test]
294    fn one_hot_no_drop_produces_full_block() {
295        let x = array![[0.0], [1.0], [2.0], [0.0]];
296        let (enc, oh) = OneHotEncoder::fit_transform(x.view()).unwrap();
297        assert_eq!(enc.n_output_columns(), 3);
298        assert_eq!(oh.dim(), (4, 3));
299        // Row 0 encodes category "0" → the first column of the block.
300        assert_eq!(oh.row(0).to_vec(), vec![1.0, 0.0, 0.0]);
301        assert_eq!(oh.row(1).to_vec(), vec![0.0, 1.0, 0.0]);
302        assert_eq!(oh.row(2).to_vec(), vec![0.0, 0.0, 1.0]);
303    }
304
305    #[test]
306    fn one_hot_drop_first_drops_baseline() {
307        let x = array![[0.0], [1.0], [2.0]];
308        let enc = OneHotEncoder::fit_with(x.view(), true).unwrap();
309        let oh = enc.transform(x.view()).unwrap();
310        assert_eq!(oh.dim(), (3, 2));
311        assert_eq!(oh.row(0).to_vec(), vec![0.0, 0.0]); // baseline
312        assert_eq!(oh.row(1).to_vec(), vec![1.0, 0.0]);
313        assert_eq!(oh.row(2).to_vec(), vec![0.0, 1.0]);
314    }
315}