Skip to main content

qualia_core_db/solvers/statistics/regression/
influence.rs

1//! Leverage, Cook's distance, and studentized residuals (flag only — never drop).
2
3use crate::solvers::linear_algebra::cholesky::{cholesky_factor, cholesky_solve};
4use crate::solvers::linear_algebra::gemm::{gemm, Transpose};
5use crate::solvers::statistics::regression::MultipleOls;
6
7use serde::Serialize;
8
9/// Per-observation influence diagnostics.
10#[derive(Debug, Clone, PartialEq, Serialize)]
11pub struct InfluenceRow {
12    pub index: usize,
13    pub leverage: f64,
14    pub cook_d: f64,
15    pub studentized: f64,
16    /// True when leverage > 2k/n or Cook's D > 4/n or |studentized| > 3.
17    pub flagged: bool,
18}
19
20#[derive(Debug, Clone, PartialEq, Serialize)]
21pub struct InfluenceMeasures {
22    pub rows: Vec<InfluenceRow>,
23    pub leverage_threshold: f64,
24    pub cook_threshold: f64,
25}
26
27/// Compute influence from a fitted [`MultipleOls`] (uses its design + residuals).
28pub fn influence_measures(model: &MultipleOls) -> Option<InfluenceMeasures> {
29    let n = model.n;
30    let k = model.n_params;
31    if model.design.len() != n * k || model.residuals.len() != n {
32        return None;
33    }
34    // H = D (DᵀD)⁻¹ Dᵀ → leverage h_ii via solving (DᵀD) w = d_i then h = d_i·w.
35    let mut a = vec![0.0; k * k];
36    gemm(
37        Transpose::Yes,
38        Transpose::No,
39        k,
40        k,
41        n,
42        1.0,
43        &model.design,
44        &model.design,
45        0.0,
46        &mut a,
47    )
48    .ok()?;
49    let mut l = vec![0.0; k * k];
50    cholesky_factor(k, &a, &mut l).ok()?;
51
52    let mse = model.residual_std_error.powi(2);
53    if mse <= 0.0 {
54        return None;
55    }
56    let lev_thr = 2.0 * k as f64 / n as f64;
57    let cook_thr = 4.0 / n as f64;
58    let mut rows = Vec::with_capacity(n);
59    let mut di = vec![0.0; k];
60    let mut wi = vec![0.0; k];
61    for i in 0..n {
62        di.copy_from_slice(&model.design[i * k..(i + 1) * k]);
63        cholesky_solve(k, &l, &di, &mut wi).ok()?;
64        let h: f64 = di.iter().zip(wi.iter()).map(|(a, b)| a * b).sum();
65        let h = h.clamp(0.0, 1.0 - 1e-12);
66        let e = model.residuals[i];
67        let studentized = e / (model.residual_std_error * (1.0 - h).sqrt());
68        let cook_d = (e * e / (k as f64 * mse)) * (h / (1.0 - h).powi(2));
69        let flagged = h > lev_thr || cook_d > cook_thr || studentized.abs() > 3.0;
70        rows.push(InfluenceRow {
71            index: i,
72            leverage: h,
73            cook_d,
74            studentized,
75            flagged,
76        });
77    }
78    Some(InfluenceMeasures {
79        rows,
80        leverage_threshold: lev_thr,
81        cook_threshold: cook_thr,
82    })
83}
84
85#[cfg(test)]
86mod tests {
87    use super::*;
88    use crate::solvers::statistics::regression::multiple_ols;
89
90    #[test]
91    fn flags_high_leverage_point() {
92        // Mostly x≈1..5; one far x=50 pulls leverage.
93        let x = [1.0, 2.0, 3.0, 4.0, 5.0, 50.0];
94        let y = [2.0, 4.0, 6.0, 8.0, 10.0, 20.0];
95        let m = multiple_ols(&x, &y, 6, 1, true).unwrap();
96        let inf = influence_measures(&m).unwrap();
97        assert!(inf.rows[5].flagged, "far x should be flagged");
98        assert!(inf.rows[5].leverage > inf.leverage_threshold);
99    }
100}