Skip to main content

qualia_core_db/solvers/learning/regression/
pls.rs

1//! Partial Least Squares regression (ISL ch 6.3.2) — PLS1 (univariate response) by
2//! the NIPALS algorithm. Unlike PCR (which picks directions of high predictor
3//! variance), PLS picks directions of high *covariance with the response*. The small
4//! component-space solve reuses `linear_algebra::qr` (no new solver). Kernel-class
5//! `DenseLinear`.
6
7use crate::solvers::learning::LearningError;
8use crate::solvers::linear_algebra::qr::{qr_factor, qr_solve_least_squares};
9use crate::solvers::statistics::descriptive::mean;
10
11/// A fitted PLS model collapsed to predictor-space coefficients + intercept.
12#[derive(Debug, Clone)]
13pub struct PlsModel {
14    pub coefficients: Vec<f64>,
15    pub intercept: f64,
16    pub n_components: usize,
17}
18
19impl PlsModel {
20    /// Prediction for one row.
21    pub fn predict_row(&self, x_row: &[f64]) -> f64 {
22        self.intercept
23            + self
24                .coefficients
25                .iter()
26                .zip(x_row)
27                .map(|(b, x)| b * x)
28                .sum::<f64>()
29    }
30    /// Predictions for rows.
31    pub fn predict(&self, x: &[f64], n: usize, p: usize) -> Vec<f64> {
32        (0..n)
33            .map(|i| self.predict_row(&x[i * p..(i + 1) * p]))
34            .collect()
35    }
36}
37
38/// Fit PLS1 with `n_components` (clamped to `p`). Fails closed on shape mismatch /
39/// `n < 2` / a degenerate (zero-covariance) extraction.
40pub fn fit(
41    x: &[f64],
42    y: &[f64],
43    n: usize,
44    p: usize,
45    n_components: usize,
46) -> Result<PlsModel, LearningError> {
47    if n == 0 || p == 0 || x.len() != n * p || y.len() != n {
48        return Err(LearningError::InvalidDimension);
49    }
50    if n < 2 {
51        return Err(LearningError::InsufficientData);
52    }
53    let a = n_components.clamp(1, p);
54
55    // Centre X and y.
56    let mut xbar = vec![0.0; p];
57    let mut colbuf = vec![0.0; n];
58    for j in 0..p {
59        for i in 0..n {
60            colbuf[i] = x[i * p + j];
61        }
62        xbar[j] = mean(&colbuf).ok_or(LearningError::InsufficientData)?;
63    }
64    let ybar = mean(y).ok_or(LearningError::InsufficientData)?;
65    let mut xc = vec![0.0; n * p];
66    let mut yc = vec![0.0; n];
67    for i in 0..n {
68        for j in 0..p {
69            xc[i * p + j] = x[i * p + j] - xbar[j];
70        }
71        yc[i] = y[i] - ybar;
72    }
73
74    // NIPALS: collect weight (w), loading (p_load) columns and scalar q per component.
75    let mut w_mat = vec![0.0; p * a]; // p × a, column per component
76    let mut p_mat = vec![0.0; p * a];
77    let mut q_vec = vec![0.0; a];
78
79    for comp in 0..a {
80        // w = Xcᵀ yc, normalized.
81        let mut w = vec![0.0; p];
82        for j in 0..p {
83            let mut s = 0.0;
84            for i in 0..n {
85                s += xc[i * p + j] * yc[i];
86            }
87            w[j] = s;
88        }
89        let wn = (w.iter().map(|v| v * v).sum::<f64>()).sqrt();
90        if wn < 1e-12 {
91            // No remaining covariance — stop early (use the components found so far).
92            if comp == 0 {
93                return Err(LearningError::InsufficientData);
94            }
95            return finalize(&w_mat, &p_mat, &q_vec, comp, p, &xbar, ybar);
96        }
97        for v in w.iter_mut() {
98            *v /= wn;
99        }
100        // Scores t = Xc w.
101        let mut t = vec![0.0; n];
102        for i in 0..n {
103            t[i] = (0..p).map(|j| xc[i * p + j] * w[j]).sum();
104        }
105        let tt: f64 = t.iter().map(|v| v * v).sum();
106        if tt < 1e-12 {
107            return finalize(&w_mat, &p_mat, &q_vec, comp, p, &xbar, ybar);
108        }
109        // Loadings p_load = Xcᵀ t / tt, q = ycᵀ t / tt.
110        let mut p_load = vec![0.0; p];
111        for j in 0..p {
112            let mut s = 0.0;
113            for i in 0..n {
114                s += xc[i * p + j] * t[i];
115            }
116            p_load[j] = s / tt;
117        }
118        let q = yc.iter().zip(&t).map(|(yi, ti)| yi * ti).sum::<f64>() / tt;
119        // Deflate.
120        for i in 0..n {
121            for j in 0..p {
122                xc[i * p + j] -= t[i] * p_load[j];
123            }
124            yc[i] -= t[i] * q;
125        }
126        for j in 0..p {
127            w_mat[j * a + comp] = w[j];
128            p_mat[j * a + comp] = p_load[j];
129        }
130        q_vec[comp] = q;
131    }
132
133    finalize(&w_mat, &p_mat, &q_vec, a, p, &xbar, ybar)
134}
135
136/// Collapse `a` components into predictor-space coefficients
137/// `β = W (PᵀW)⁻¹ q`, intercept `ȳ − x̄ᵀβ`.
138fn finalize(
139    w_mat: &[f64],
140    p_mat: &[f64],
141    q_vec: &[f64],
142    a: usize,
143    p: usize,
144    xbar: &[f64],
145    ybar: f64,
146) -> Result<PlsModel, LearningError> {
147    // M = PᵀW (a×a): M[r,c] = Σ_j p_mat[j,r]·w_mat[j,c].
148    let stride = w_mat.len() / p; // = number of allocated components (>= a)
149    let mut m = vec![0.0; a * a];
150    for r in 0..a {
151        for c in 0..a {
152            let mut s = 0.0;
153            for j in 0..p {
154                s += p_mat[j * stride + r] * w_mat[j * stride + c];
155            }
156            m[r * a + c] = s;
157        }
158    }
159    // Solve M α = q (square) via QR.
160    let mut tau = vec![0.0; a];
161    qr_factor(a, a, &mut m, &mut tau)?;
162    let mut b = q_vec[..a].to_vec();
163    let mut alpha = vec![0.0; a];
164    qr_solve_least_squares(a, a, &m, &tau, &mut b, &mut alpha)?;
165    // β = W α.
166    let mut coefficients = vec![0.0; p];
167    for j in 0..p {
168        let mut s = 0.0;
169        for c in 0..a {
170            s += w_mat[j * stride + c] * alpha[c];
171        }
172        coefficients[j] = s;
173    }
174    let intercept = ybar
175        - coefficients
176            .iter()
177            .zip(xbar)
178            .map(|(b, m)| b * m)
179            .sum::<f64>();
180    Ok(PlsModel {
181        coefficients,
182        intercept,
183        n_components: a,
184    })
185}
186
187#[cfg(test)]
188mod tests {
189    use super::*;
190    use crate::solvers::learning::regression::linear;
191
192    #[test]
193    fn full_components_matches_ols() {
194        // With min(n-1, p) components PLS reproduces the OLS fit.
195        let x = [1.0, 2.0, 2.0, 1.0, 3.0, 0.0, 4.0, 5.0, 5.0, 4.0, 6.0, 1.0];
196        let y = [3.0, 5.0, 4.0, 9.0, 13.0, 8.0];
197        let pls = fit(&x, &y, 6, 2, 2).unwrap();
198        let ols = linear::fit(&x, &y, 6, 2, true).unwrap();
199        let p_pred = pls.predict(&x, 6, 2);
200        let o_pred = ols.predict(&x, 6, 2);
201        for i in 0..6 {
202            assert!(
203                (p_pred[i] - o_pred[i]).abs() < 1e-6,
204                "{} vs {}",
205                p_pred[i],
206                o_pred[i]
207            );
208        }
209    }
210
211    #[test]
212    fn one_component_tracks_covariance_direction() {
213        // y driven by x0; PLS with 1 component fits well (it targets covariance).
214        let n = 20;
215        let mut x = vec![0.0; n * 2];
216        let mut y = vec![0.0; n];
217        for i in 0..n {
218            let t = i as f64;
219            x[i * 2] = t;
220            x[i * 2 + 1] = ((i % 5) as f64) - 2.0; // unrelated to y
221            y[i] = 3.0 * t + 2.0;
222        }
223        let pls = fit(&x, &y, n, 2, 1).unwrap();
224        let preds = pls.predict(&x, n, 2);
225        let r2 = crate::solvers::learning::metrics::regression::r2_score(&y, &preds).unwrap();
226        assert!(r2 > 0.99, "r2 {r2}");
227    }
228
229    #[test]
230    fn guards() {
231        assert_eq!(
232            fit(&[1.0, 2.0, 3.0], &[1.0, 2.0], 2, 2, 1).unwrap_err(),
233            LearningError::InvalidDimension
234        );
235    }
236}