Skip to main content

qualia_core_db/solvers/statistics/regression/
verify.rs

1//! Compose OLS verification flags for Civics admission (Welc Ch.4.11).
2
3use super::diagnostics::{
4    arch_lm, box_pearce_ac, breusch_pagan, durbin_watson, jarque_bera, ramsey_reset, residual_runs,
5    residual_symmetry, vif_columns,
6};
7use super::multiple::MultipleOls;
8use super::spurious::spurious_regression_guard;
9
10/// Named verification failure / warning for a fitted model.
11#[derive(Debug, Clone, PartialEq, Eq)]
12pub struct VerificationFlag {
13    pub code: String,
14    pub message: String,
15}
16
17#[derive(Debug, Clone, PartialEq)]
18pub struct VerificationReport {
19    /// `true` iff no hard flags (warnings-only still sets ok=true unless `strict`).
20    pub ok: bool,
21    pub flags: Vec<VerificationFlag>,
22    pub alpha: f64,
23    pub f_p_value: Option<f64>,
24    pub jarque_bera_p: Option<f64>,
25    pub breusch_pagan_p: Option<f64>,
26    pub durbin_watson: Option<f64>,
27    pub max_vif: Option<f64>,
28    pub ramsey_reset_p: Option<f64>,
29    pub symmetry_p: Option<f64>,
30    pub runs_p: Option<f64>,
31    pub arch_lm_p: Option<f64>,
32    pub box_pearce_p: Option<f64>,
33    pub spurious_warn: bool,
34}
35
36/// Thresholds: α for tests; VIF soft/hard.
37pub struct VerifyOptions {
38    pub alpha: f64,
39    pub vif_soft: f64,
40    pub vif_hard: f64,
41    pub check_spurious: bool,
42    /// When true, soft warnings also set `ok = false`.
43    pub strict: bool,
44}
45
46impl Default for VerifyOptions {
47    fn default() -> Self {
48        Self {
49            alpha: 0.05,
50            vif_soft: 5.0,
51            vif_hard: 10.0,
52            check_spurious: true,
53            strict: false,
54        }
55    }
56}
57
58/// Run REG-03..07 (+ RESET, symmetry, runs, ARCH-LM, optional spurious) on a fit.
59///
60/// `x_raw` is the original `n × p` predictor matrix (no intercept); required for
61/// VIF / RESET / spurious. Pass `None` to skip those.
62pub fn verify_regression_model(
63    model: &MultipleOls,
64    x_raw: Option<(&[f64], usize)>,
65    y: Option<&[f64]>,
66    opts: &VerifyOptions,
67) -> VerificationReport {
68    let mut flags = Vec::new();
69    let mut hard = false;
70    let mut soft = false;
71
72    let f_p = model.f_p_value;
73    if let Some(p) = f_p {
74        if p > opts.alpha {
75            flags.push(VerificationFlag {
76                code: "overall_f_fail".into(),
77                message: format!("overall F p={p:.4} > α={}", opts.alpha),
78            });
79            hard = true;
80        }
81    }
82
83    let jb_p = jarque_bera(&model.residuals).map(|r| {
84        if r.p_value < opts.alpha {
85            flags.push(VerificationFlag {
86                code: "non_normal_residuals".into(),
87                message: format!("Jarque–Bera p={:.4}", r.p_value),
88            });
89            hard = true;
90        }
91        r.p_value
92    });
93
94    let bp_p = breusch_pagan(&model.residuals, &model.design, model.n, model.n_params).map(|r| {
95        if r.p_value < opts.alpha {
96            flags.push(VerificationFlag {
97                code: "heteroscedasticity".into(),
98                message: format!("Breusch–Pagan p={:.4}", r.p_value),
99            });
100            hard = true;
101        }
102        r.p_value
103    });
104
105    let dw = durbin_watson(&model.residuals).map(|r| {
106        // Classical rule of thumb: DW far from 2 indicates residual AC.
107        if r.statistic < 1.5 || r.statistic > 2.5 {
108            flags.push(VerificationFlag {
109                code: "autocorrelation".into(),
110                message: format!(
111                    "Durbin–Watson={:.3} (approx p={:.4})",
112                    r.statistic, r.approx_p_value
113                ),
114            });
115            hard = true;
116        }
117        r.statistic
118    });
119
120    let bp_ac = box_pearce_ac(&model.residuals).map(|r| {
121        if r.p_value < opts.alpha {
122            flags.push(VerificationFlag {
123                code: "residual_acf".into(),
124                message: format!("Box–Pearce lag-1 p={:.4}", r.p_value),
125            });
126            soft = true;
127        }
128        r.p_value
129    });
130
131    let arch_p = arch_lm(&model.residuals, 1).map(|r| {
132        if r.p_value < opts.alpha {
133            flags.push(VerificationFlag {
134                code: "arch_lm".into(),
135                message: format!("ARCH-LM(1) p={:.4}", r.p_value),
136            });
137            soft = true;
138        }
139        r.p_value
140    });
141
142    let mut max_vif = None;
143    let mut reset_p = None;
144    let mut spurious_warn = false;
145
146    if let Some((x, p)) = x_raw {
147        if let Some(v) = vif_columns(x, model.n, p) {
148            let mx = v.vif.iter().cloned().fold(0.0_f64, f64::max);
149            max_vif = Some(mx);
150            if mx >= opts.vif_hard {
151                flags.push(VerificationFlag {
152                    code: "high_vif".into(),
153                    message: format!("max VIF={mx:.2} ≥ {}", opts.vif_hard),
154                });
155                hard = true;
156            } else if mx >= opts.vif_soft {
157                flags.push(VerificationFlag {
158                    code: "elevated_vif".into(),
159                    message: format!("max VIF={mx:.2} ≥ {}", opts.vif_soft),
160                });
161                soft = true;
162            }
163        }
164        if let Some(y) = y {
165            if let Some(r) = ramsey_reset(x, y, model.n, p, 3) {
166                reset_p = Some(r.p_value);
167                if r.p_value < opts.alpha {
168                    flags.push(VerificationFlag {
169                        code: "reset_fail".into(),
170                        message: format!("Ramsey RESET p={:.4}", r.p_value),
171                    });
172                    hard = true;
173                }
174            }
175            if opts.check_spurious && p >= 1 {
176                // Use first predictor column as x series for bivariate guard.
177                let mut x0 = vec![0.0; model.n];
178                for i in 0..model.n {
179                    x0[i] = x[i * p];
180                }
181                if let Some(g) = spurious_regression_guard(y, Some(&x0)) {
182                    spurious_warn = g.warn_spurious;
183                    if g.warn_spurious {
184                        flags.push(VerificationFlag {
185                            code: "spurious_risk".into(),
186                            message: g.detail,
187                        });
188                        soft = true;
189                    }
190                }
191            }
192        }
193    }
194
195    let sym_p = residual_symmetry(&model.residuals).map(|r| {
196        if r.p_value < opts.alpha {
197            flags.push(VerificationFlag {
198                code: "asymmetry".into(),
199                message: format!("residual symmetry t p={:.4}", r.p_value),
200            });
201            soft = true;
202        }
203        r.p_value
204    });
205
206    let runs_p = residual_runs(&model.residuals).map(|r| {
207        if r.p_value < opts.alpha {
208            flags.push(VerificationFlag {
209                code: "non_random_runs".into(),
210                message: format!("runs test p={:.4}", r.p_value),
211            });
212            soft = true;
213        }
214        r.p_value
215    });
216
217    let ok = if opts.strict { !hard && !soft } else { !hard };
218
219    VerificationReport {
220        ok,
221        flags,
222        alpha: opts.alpha,
223        f_p_value: f_p,
224        jarque_bera_p: jb_p,
225        breusch_pagan_p: bp_p,
226        durbin_watson: dw,
227        max_vif,
228        ramsey_reset_p: reset_p,
229        symmetry_p: sym_p,
230        runs_p,
231        arch_lm_p: arch_p,
232        box_pearce_p: bp_ac,
233        spurious_warn,
234    }
235}
236
237#[cfg(test)]
238mod tests {
239    use super::*;
240    use crate::solvers::statistics::regression::multiple_ols;
241
242    #[test]
243    fn clean_fit_passes() {
244        // Cross-section-ish predictors (not a pure time index) + iid noise.
245        let x = [
246            1.2, 3.5, 2.1, 4.8, 0.5, 5.5, 3.0, 6.2, 1.8, 4.1, 2.7, 5.0, 0.9, 3.8, 4.4, 1.5,
247        ];
248        let y: Vec<f64> = x
249            .iter()
250            .enumerate()
251            .map(|(i, &xi)| 1.0 + 1.5 * xi + 0.05 * ((i % 5) as f64 - 2.0))
252            .collect();
253        let m = multiple_ols(&x, &y, 16, 1, true).unwrap();
254        let opts = VerifyOptions {
255            check_spurious: false,
256            ..Default::default()
257        };
258        let r = verify_regression_model(&m, Some((&x, 1)), Some(&y), &opts);
259        assert!(r.ok, "flags={:?}", r.flags);
260    }
261}