Skip to main content

qualia_core_db/solvers/statistics/regression/
design.rs

1//! Dummy / seasonal design matrices and series transforms.
2
3use serde::Serialize;
4
5#[derive(Debug, Clone, PartialEq, Serialize)]
6pub struct DummyDesign {
7    /// Row-major `n × (n_levels − 1)` (reference = first level dropped).
8    pub matrix: Vec<f64>,
9    pub n: usize,
10    pub n_columns: usize,
11    pub level_labels: Vec<String>,
12}
13
14/// One-hot dummies with first category as reference (dropped).
15pub fn design_dummies(categories: &[u32]) -> Option<DummyDesign> {
16    let n = categories.len();
17    if n == 0 {
18        return None;
19    }
20    let mut levels: Vec<u32> = categories.to_vec();
21    levels.sort_unstable();
22    levels.dedup();
23    if levels.len() < 2 {
24        return None;
25    }
26    let n_columns = levels.len() - 1;
27    let mut matrix = vec![0.0; n * n_columns];
28    for (i, &c) in categories.iter().enumerate() {
29        if let Some(pos) = levels.iter().position(|&l| l == c) {
30            if pos > 0 {
31                matrix[i * n_columns + (pos - 1)] = 1.0;
32            }
33        }
34    }
35    let level_labels: Vec<String> = levels.iter().map(|l| format!("L{l}")).collect();
36    Some(DummyDesign {
37        matrix,
38        n,
39        n_columns,
40        level_labels,
41    })
42}
43
44/// Additive seasonal dummies for period `period` (e.g. 4 or 12); drops season 0.
45pub fn seasonal_dummies(n: usize, period: usize) -> Option<DummyDesign> {
46    if n == 0 || period < 2 {
47        return None;
48    }
49    let cats: Vec<u32> = (0..n).map(|i| (i % period) as u32).collect();
50    design_dummies(&cats)
51}
52
53#[derive(Debug, Clone, Copy, PartialEq, Eq)]
54pub enum TransformKind {
55    Log,
56    Log1p,
57    Sqrt,
58    Square,
59    Reciprocal,
60    Exp,
61}
62
63/// Element-wise transform; `None` if any domain violation (e.g. log of ≤0).
64pub fn transform_series(values: &[f64], kind: TransformKind) -> Option<Vec<f64>> {
65    let mut out = Vec::with_capacity(values.len());
66    for &v in values {
67        let t = match kind {
68            TransformKind::Log => {
69                if v <= 0.0 {
70                    return None;
71                }
72                v.ln()
73            }
74            TransformKind::Log1p => {
75                if v <= -1.0 {
76                    return None;
77                }
78                (1.0 + v).ln()
79            }
80            TransformKind::Sqrt => {
81                if v < 0.0 {
82                    return None;
83                }
84                v.sqrt()
85            }
86            TransformKind::Square => v * v,
87            TransformKind::Reciprocal => {
88                if v.abs() < 1e-15 {
89                    return None;
90                }
91                1.0 / v
92            }
93            TransformKind::Exp => v.exp(),
94        };
95        if !t.is_finite() {
96            return None;
97        }
98        out.push(t);
99    }
100    Some(out)
101}
102
103#[cfg(test)]
104mod tests {
105    use super::*;
106
107    #[test]
108    fn dummies_drop_reference() {
109        let cats = [0u32, 1, 0, 2, 1];
110        let d = design_dummies(&cats).unwrap();
111        assert_eq!(d.n_columns, 2);
112        assert_eq!(d.matrix[0], 0.0); // L0
113        assert_eq!(d.matrix[2], 1.0); // row1 → L1 → col0
114    }
115
116    #[test]
117    fn log_rejects_nonpositive() {
118        assert!(transform_series(&[1.0, 0.0], TransformKind::Log).is_none());
119        let t = transform_series(&[1.0, std::f64::consts::E], TransformKind::Log).unwrap();
120        assert!((t[1] - 1.0).abs() < 1e-12);
121    }
122}