Skip to main content

qualia_core_db/solvers/learning/regression/
linear.rs

1//! Multiple linear regression (ISL ch 3) — ordinary least squares with full
2//! inference. Canonical implementation lives in
3//! [`crate::solvers::statistics::regression::multiple`]; this module is a thin
4//! learning-crate facade preserving `LinearModel` / `fit` names.
5
6use crate::solvers::learning::LearningError;
7use crate::solvers::statistics::regression::{multiple_ols, MultipleOls};
8
9/// A fitted OLS model with inferential output. When `fit_intercept` is true,
10/// `coefficients[0]` is the intercept and `coefficients[1..]` align with the
11/// predictor columns; the `*_per_coef` vectors are aligned the same way.
12#[derive(Debug, Clone)]
13pub struct LinearModel {
14    pub coefficients: Vec<f64>,
15    pub fit_intercept: bool,
16    pub std_errors: Vec<f64>,
17    pub t_values: Vec<f64>,
18    pub p_values: Vec<f64>,
19    pub r_squared: f64,
20    pub adj_r_squared: f64,
21    /// Overall F-statistic (all slopes = 0) and its p-value. `None` without an intercept.
22    pub f_statistic: Option<f64>,
23    pub f_p_value: Option<f64>,
24    pub residual_std_error: f64,
25    pub df_residual: usize,
26    pub n: usize,
27}
28
29impl LinearModel {
30    fn from_multiple(m: MultipleOls) -> Self {
31        Self {
32            coefficients: m.coefficients,
33            fit_intercept: m.fit_intercept,
34            std_errors: m.std_errors,
35            t_values: m.t_values,
36            p_values: m.p_values,
37            r_squared: m.r_squared,
38            adj_r_squared: m.adj_r_squared,
39            f_statistic: m.f_statistic,
40            f_p_value: m.f_p_value,
41            residual_std_error: m.residual_std_error,
42            df_residual: m.df_residual,
43            n: m.n,
44        }
45    }
46
47    /// Predict for one feature row (length `p`, predictors only — the intercept is
48    /// applied internally).
49    pub fn predict_row(&self, x_row: &[f64]) -> f64 {
50        let (b0, betas) = if self.fit_intercept {
51            (self.coefficients[0], &self.coefficients[1..])
52        } else {
53            (0.0, &self.coefficients[..])
54        };
55        b0 + betas.iter().zip(x_row).map(|(b, x)| b * x).sum::<f64>()
56    }
57
58    /// Predict for a row-major `n × p` feature matrix.
59    pub fn predict(&self, x: &[f64], n: usize, p: usize) -> Vec<f64> {
60        (0..n)
61            .map(|i| self.predict_row(&x[i * p..(i + 1) * p]))
62            .collect()
63    }
64}
65
66/// Fit OLS of `y` (length `n`) on a row-major `n × p` predictor matrix `x`.
67pub fn fit(
68    x: &[f64],
69    y: &[f64],
70    n: usize,
71    p: usize,
72    fit_intercept: bool,
73) -> Result<LinearModel, LearningError> {
74    if n == 0 || p == 0 || x.len() != n * p || y.len() != n {
75        return Err(LearningError::InvalidDimension);
76    }
77    let k = p + usize::from(fit_intercept);
78    if n <= k {
79        return Err(LearningError::InsufficientData);
80    }
81    match multiple_ols(x, y, n, p, fit_intercept) {
82        Some(m) => Ok(LinearModel::from_multiple(m)),
83        None => Err(LearningError::Singular),
84    }
85}
86
87#[cfg(test)]
88mod tests {
89    use super::*;
90
91    #[test]
92    fn recovers_exact_plane() {
93        let x = [0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0, 2.0, 1.0];
94        let y = [1.0, 3.0, 4.0, 6.0, 8.0];
95        let m = fit(&x, &y, 5, 2, true).unwrap();
96        assert!((m.coefficients[0] - 1.0).abs() < 1e-9);
97        assert!((m.coefficients[1] - 2.0).abs() < 1e-9);
98        assert!((m.coefficients[2] - 3.0).abs() < 1e-9);
99        assert!((m.r_squared - 1.0).abs() < 1e-12);
100        assert!((m.predict_row(&[3.0, 2.0]) - 13.0).abs() < 1e-9);
101    }
102
103    #[test]
104    fn matches_simple_regression_for_one_predictor() {
105        let x = [1.0, 2.0, 3.0, 4.0, 5.0];
106        let y = [2.1, 3.9, 6.1, 7.9, 10.2];
107        let m = fit(&x, &y, 5, 1, true).unwrap();
108        let simple =
109            crate::solvers::statistics::regression::simple_linear_regression(&x, &y).unwrap();
110        assert!((m.coefficients[0] - simple.intercept).abs() < 1e-9);
111        assert!((m.coefficients[1] - simple.slope).abs() < 1e-9);
112        assert!((m.p_values[1] - simple.slope_p_value).abs() < 1e-9);
113    }
114
115    #[test]
116    fn detects_collinear_predictors() {
117        let x = [1.0, 2.0, 2.0, 4.0, 3.0, 6.0, 4.0, 8.0, 5.0, 10.0];
118        let y = [1.0, 2.0, 3.0, 4.0, 5.0];
119        assert_eq!(
120            fit(&x, &y, 5, 2, true).unwrap_err(),
121            LearningError::Singular
122        );
123    }
124
125    #[test]
126    fn guards_insufficient_data() {
127        let x = [1.0, 2.0, 3.0, 4.0];
128        let y = [1.0, 2.0];
129        assert_eq!(
130            fit(&x, &y, 2, 2, true).unwrap_err(),
131            LearningError::InsufficientData
132        );
133    }
134
135    #[test]
136    fn significant_predictor_has_small_p() {
137        let x = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
138        let y = [2.0, 4.1, 5.9, 8.0, 10.1, 12.0];
139        let m = fit(&x, &y, 6, 1, true).unwrap();
140        assert!(m.p_values[1] < 1e-4);
141        assert!(m.f_p_value.unwrap() < 1e-4);
142    }
143}