Skip to main content

qualia_core_db/solvers/statistics/regression/
diagnostics.rs

1//! Classical residual / specification tests for single-equation OLS (Welc Ch.4).
2
3use crate::solvers::statistics::descriptive::{kurtosis, mean, skewness, variance};
4use crate::solvers::statistics::distributions::{chi_squared, fisher_f, students_t};
5use crate::solvers::statistics::regression::multiple_ols;
6
7use serde::Serialize;
8
9/// Jarque–Bera normality of residuals.
10#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
11pub struct JarqueBeraResult {
12    pub statistic: f64,
13    pub p_value: f64,
14    pub skewness: f64,
15    pub excess_kurtosis: f64,
16}
17
18/// JB = n/6 · (S² + K²/4); asymptotic χ²(2). `None` if n < 4 or zero variance.
19pub fn jarque_bera(residuals: &[f64]) -> Option<JarqueBeraResult> {
20    let n = residuals.len();
21    if n < 4 {
22        return None;
23    }
24    let s = skewness(residuals)?;
25    let k = kurtosis(residuals)?; // Fisher excess
26    let jb = (n as f64) / 6.0 * (s * s + k * k / 4.0);
27    Some(JarqueBeraResult {
28        statistic: jb,
29        p_value: chi_squared::upper_p(jb, 2.0),
30        skewness: s,
31        excess_kurtosis: k,
32    })
33}
34
35/// Breusch–Pagan heteroscedasticity: regress e² on the same design (no intercept
36/// double-count — uses predictors only when design includes intercept column).
37#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
38pub struct BreuschPaganResult {
39    pub lm_statistic: f64,
40    pub p_value: f64,
41    pub df: f64,
42}
43
44/// `design` is row-major `n × k` (same as MultipleOls.design). Uses all columns
45/// of `design` as regressors for e² (including intercept). LM = n·R² ~ χ²(k−1).
46pub fn breusch_pagan(
47    residuals: &[f64],
48    design: &[f64],
49    n: usize,
50    k: usize,
51) -> Option<BreuschPaganResult> {
52    if residuals.len() != n || design.len() != n * k || k < 2 || n <= k {
53        return None;
54    }
55    let e2: Vec<f64> = residuals.iter().map(|e| e * e).collect();
56    // Predictors = design columns 1..k-1 (drop intercept) for classical BP;
57    // if k==1 only intercept, nothing to test.
58    let p = k - 1;
59    let mut x = vec![0.0; n * p];
60    for i in 0..n {
61        x[i * p..(i + 1) * p].copy_from_slice(&design[i * k + 1..i * k + k]);
62    }
63    let m = multiple_ols(&x, &e2, n, p, true)?;
64    let lm = n as f64 * m.r_squared;
65    let df = p as f64;
66    Some(BreuschPaganResult {
67        lm_statistic: lm,
68        p_value: chi_squared::upper_p(lm, df),
69        df,
70    })
71}
72
73/// ARCH-LM: regress e_t² on lag-1..q of e².
74#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
75pub struct ArchLmResult {
76    pub lm_statistic: f64,
77    pub p_value: f64,
78    pub df: f64,
79    pub q: usize,
80}
81
82/// ARCH Lagrange-multiplier test on `residuals` at lag `q`.
83pub fn arch_lm(residuals: &[f64], q: usize) -> Option<ArchLmResult> {
84    let n = residuals.len();
85    if q == 0 || n <= q + 2 {
86        return None;
87    }
88    let e2: Vec<f64> = residuals.iter().map(|e| e * e).collect();
89    let m = n - q;
90    let mut x = vec![0.0; m * q];
91    let mut y = vec![0.0; m];
92    for t in 0..m {
93        y[t] = e2[t + q];
94        for j in 0..q {
95            x[t * q + j] = e2[t + q - 1 - j];
96        }
97    }
98    let fit = multiple_ols(&x, &y, m, q, true)?;
99    let lm = m as f64 * fit.r_squared;
100    Some(ArchLmResult {
101        lm_statistic: lm,
102        p_value: chi_squared::upper_p(lm, q as f64),
103        df: q as f64,
104        q,
105    })
106}
107
108/// Durbin–Watson statistic on ordered residuals.
109#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
110pub struct DurbinWatsonResult {
111    pub statistic: f64,
112    /// Rough two-sided p via normal approx of DW around 2 (informational).
113    pub approx_p_value: f64,
114}
115
116/// `?::durbin_watson`.
117pub fn durbin_watson(residuals: &[f64]) -> Option<DurbinWatsonResult> {
118    let n = residuals.len();
119    if n < 3 {
120        return None;
121    }
122    let mut num = 0.0;
123    let mut den = 0.0;
124    for i in 0..n {
125        den += residuals[i] * residuals[i];
126        if i > 0 {
127            let d = residuals[i] - residuals[i - 1];
128            num += d * d;
129        }
130    }
131    if den <= 0.0 {
132        return None;
133    }
134    let dw = num / den;
135    // Under H0, E[DW]≈2, Var≈4/n → Z = (DW−2)/√(4/n).
136    let se = (4.0 / n as f64).sqrt();
137    let z = (dw - 2.0) / se;
138    let approx_p = crate::solvers::statistics::distributions::normal::two_sided_p(z);
139    Some(DurbinWatsonResult {
140        statistic: dw,
141        approx_p_value: approx_p,
142    })
143}
144
145/// Box–Pearce / residual AC F-style: first-lag autocorrelation squared × (n−1).
146#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
147pub struct BoxPearceResult {
148    pub lag1_acf: f64,
149    pub statistic: f64,
150    pub p_value: f64,
151}
152
153/// Box-Pierce autocorrelation test on `residuals`.
154pub fn box_pearce_ac(residuals: &[f64]) -> Option<BoxPearceResult> {
155    let n = residuals.len();
156    if n < 4 {
157        return None;
158    }
159    let ac = crate::solvers::statistics::timeseries::autocorrelation(residuals, 1)?;
160    let stat = (n as f64 - 1.0) * ac * ac;
161    Some(BoxPearceResult {
162        lag1_acf: ac,
163        statistic: stat,
164        p_value: chi_squared::upper_p(stat, 1.0),
165    })
166}
167
168/// Per-predictor VIF from the design columns excluding intercept.
169#[derive(Debug, Clone, PartialEq, Serialize)]
170pub struct VifResult {
171    pub vif: Vec<f64>,
172}
173
174/// `x` is row-major `n × p` predictors (no intercept column). VIF_j = 1/(1−R²_j).
175pub fn vif_columns(x: &[f64], n: usize, p: usize) -> Option<VifResult> {
176    if p < 2 || x.len() != n * p || n <= p {
177        return None;
178    }
179    let mut vif = vec![0.0; p];
180    for j in 0..p {
181        let mut y = vec![0.0; n];
182        let mut xo = vec![0.0; n * (p - 1)];
183        for i in 0..n {
184            y[i] = x[i * p + j];
185            let mut c = 0;
186            for k in 0..p {
187                if k == j {
188                    continue;
189                }
190                xo[i * (p - 1) + c] = x[i * p + k];
191                c += 1;
192            }
193        }
194        let m = multiple_ols(&xo, &y, n, p - 1, true)?;
195        let r2 = m.r_squared.clamp(0.0, 1.0 - 1e-15);
196        vif[j] = 1.0 / (1.0 - r2);
197    }
198    Some(VifResult { vif })
199}
200
201/// Ramsey RESET: augment with powers of fitted ŷ.
202#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
203pub struct RamseyResetResult {
204    pub f_statistic: f64,
205    pub p_value: f64,
206    pub df_num: f64,
207    pub df_den: f64,
208}
209
210/// Powers 2..=power_max of fitted values added to original predictors.
211pub fn ramsey_reset(
212    x: &[f64],
213    y: &[f64],
214    n: usize,
215    p: usize,
216    power_max: usize,
217) -> Option<RamseyResetResult> {
218    if power_max < 2 || n < p + power_max + 2 {
219        return None;
220    }
221    let restricted = multiple_ols(x, y, n, p, true)?;
222    let extra = power_max - 1; // ŷ² .. ŷ^power_max
223    let p2 = p + extra;
224    let mut x2 = vec![0.0; n * p2];
225    for i in 0..n {
226        x2[i * p2..i * p2 + p].copy_from_slice(&x[i * p..(i + 1) * p]);
227        let yh = restricted.fitted[i];
228        for (t, pow) in (2..=power_max).enumerate() {
229            x2[i * p2 + p + t] = yh.powi(pow as i32);
230        }
231    }
232    let unrestricted = multiple_ols(&x2, y, n, p2, true)?;
233    let sse_r = restricted.residuals.iter().map(|e| e * e).sum::<f64>();
234    let sse_u = unrestricted.residuals.iter().map(|e| e * e).sum::<f64>();
235    let df_num = extra as f64;
236    let df_den = unrestricted.df_residual as f64;
237    if df_den <= 0.0 || sse_u <= 0.0 {
238        return None;
239    }
240    let f = ((sse_r - sse_u) / df_num) / (sse_u / df_den);
241    Some(RamseyResetResult {
242        f_statistic: f,
243        p_value: fisher_f::upper_p(f, df_num, df_den),
244        df_num,
245        df_den,
246    })
247}
248
249/// Chow structural-break test at `break_index` (second subsample starts here).
250#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
251pub struct ChowResult {
252    pub f_statistic: f64,
253    pub p_value: f64,
254    pub df_num: f64,
255    pub df_den: f64,
256}
257
258/// Chow structural-break test between two subsamples.
259pub fn chow_test(
260    x: &[f64],
261    y: &[f64],
262    n: usize,
263    p: usize,
264    break_index: usize,
265) -> Option<ChowResult> {
266    let k = p + 1; // with intercept
267    if break_index < k + 1 || n - break_index < k + 1 || x.len() != n * p {
268        return None;
269    }
270    let pooled = multiple_ols(x, y, n, p, true)?;
271    let sse_p: f64 = pooled.residuals.iter().map(|e| e * e).sum();
272
273    let n1 = break_index;
274    let n2 = n - break_index;
275    let x1 = &x[..n1 * p];
276    let y1 = &y[..n1];
277    let x2 = &x[n1 * p..];
278    let y2 = &y[n1..];
279    let m1 = multiple_ols(x1, y1, n1, p, true)?;
280    let m2 = multiple_ols(x2, y2, n2, p, true)?;
281    let sse_1: f64 = m1.residuals.iter().map(|e| e * e).sum();
282    let sse_2: f64 = m2.residuals.iter().map(|e| e * e).sum();
283    let sse_u = sse_1 + sse_2;
284    let df_num = k as f64;
285    let df_den = (n - 2 * k) as f64;
286    if df_den <= 0.0 || sse_u <= 0.0 {
287        return None;
288    }
289    let f = ((sse_p - sse_u) / df_num) / (sse_u / df_den);
290    Some(ChowResult {
291        f_statistic: f,
292        p_value: fisher_f::upper_p(f, df_num, df_den),
293        df_num,
294        df_den,
295    })
296}
297
298/// Residual symmetry: one-sample t of (residuals − median) vs 0 is weak;
299/// here: skewness t-approx and mean-vs-median absolute gap.
300#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
301pub struct SymmetryResult {
302    pub skewness: f64,
303    pub mean_minus_median: f64,
304    pub t_statistic: f64,
305    pub p_value: f64,
306}
307
308/// Symmetry diagnostic on residuals.
309pub fn residual_symmetry(residuals: &[f64]) -> Option<SymmetryResult> {
310    let n = residuals.len();
311    if n < 5 {
312        return None;
313    }
314    let mu = mean(residuals)?;
315    let mut sorted = residuals.to_vec();
316    sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(core::cmp::Ordering::Equal));
317    let med = crate::solvers::statistics::descriptive::median_sorted(&sorted)?;
318    let s = skewness(residuals)?;
319    let var = variance(residuals, true)?;
320    if var <= 0.0 {
321        return None;
322    }
323    // Test H0: mean = median via SE of mean.
324    let se = (var / n as f64).sqrt();
325    let t = (mu - med) / se;
326    let p = students_t::two_sided_p(t, (n - 1) as f64);
327    Some(SymmetryResult {
328        skewness: s,
329        mean_minus_median: mu - med,
330        t_statistic: t,
331        p_value: p,
332    })
333}
334
335/// Wald–Wolfowitz runs test on residual signs (above/below median).
336#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
337pub struct RunsResult {
338    pub n_runs: usize,
339    pub n_pos: usize,
340    pub n_neg: usize,
341    pub z_statistic: f64,
342    pub p_value: f64,
343}
344
345/// Runs test on residual signs.
346pub fn residual_runs(residuals: &[f64]) -> Option<RunsResult> {
347    let n = residuals.len();
348    if n < 8 {
349        return None;
350    }
351    let mut sorted = residuals.to_vec();
352    sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(core::cmp::Ordering::Equal));
353    let med = crate::solvers::statistics::descriptive::median_sorted(&sorted)?;
354    let mut signs: Vec<i8> = Vec::with_capacity(n);
355    for &r in residuals {
356        if (r - med).abs() < 1e-15 {
357            continue; // skip exact median ties
358        }
359        signs.push(if r > med { 1 } else { -1 });
360    }
361    if signs.len() < 8 {
362        return None;
363    }
364    let mut n_pos = 0usize;
365    let mut n_neg = 0usize;
366    let mut n_runs = 1usize;
367    for (i, &s) in signs.iter().enumerate() {
368        if s > 0 {
369            n_pos += 1;
370        } else {
371            n_neg += 1;
372        }
373        if i > 0 && s != signs[i - 1] {
374            n_runs += 1;
375        }
376    }
377    let n1 = n_pos as f64;
378    let n2 = n_neg as f64;
379    let nn = n1 + n2;
380    if n1 == 0.0 || n2 == 0.0 {
381        return None;
382    }
383    let expected = 1.0 + 2.0 * n1 * n2 / nn;
384    let var = (2.0 * n1 * n2 * (2.0 * n1 * n2 - nn)) / (nn * nn * (nn - 1.0));
385    if var <= 0.0 {
386        return None;
387    }
388    let z = (n_runs as f64 - expected) / var.sqrt();
389    Some(RunsResult {
390        n_runs,
391        n_pos,
392        n_neg,
393        z_statistic: z,
394        p_value: crate::solvers::statistics::distributions::normal::two_sided_p(z),
395    })
396}
397
398#[cfg(test)]
399mod tests {
400    use super::*;
401
402    #[test]
403    fn jb_near_zero_for_near_normal() {
404        // Roughly symmetric small sample.
405        let r = [-1.2, -0.5, 0.1, 0.4, 0.8, -0.2, 0.3, -0.7, 0.6, -0.1];
406        let jb = jarque_bera(&r).unwrap();
407        assert!(jb.p_value > 0.05, "p={}", jb.p_value);
408    }
409
410    #[test]
411    fn dw_near_two_for_white_noise() {
412        let r = [
413            0.1, 0.05, -0.02, 0.08, -0.04, 0.01, -0.06, 0.03, -0.01, 0.02,
414        ];
415        let dw = durbin_watson(&r).unwrap();
416        assert!((dw.statistic - 2.0).abs() < 1.2, "dw={}", dw.statistic);
417    }
418
419    #[test]
420    fn vif_flags_collinear_pair() {
421        // x2 ≈ x1 → high VIF.
422        let x = [
423            1.0, 1.01, 2.0, 2.02, 3.0, 2.99, 4.0, 4.01, 5.0, 5.02, 6.0, 5.98,
424        ];
425        let v = vif_columns(&x, 6, 2).unwrap();
426        assert!(v.vif[0] > 10.0 && v.vif[1] > 10.0, "vif={:?}", v.vif);
427    }
428}