Skip to main content

solow_multivariate/
manova.rs

1//! Multivariate analysis of variance (MANOVA).
2//!
3//! Mirrors the reference's `multivariate.manova.MANOVA`. For the multivariate
4//! linear model `Y = X · B` (with `Y` the `nobs × k_endog` dependent variables
5//! and `X` the `nobs × k_exog` design matrix), [`Manova::mv_test`] tests, for
6//! each exogenous column `i`, the hypothesis `L · B = 0` where `L` selects that
7//! column. Each test reports the four classical statistics — Wilks' lambda,
8//! Pillai's trace, the Hotelling-Lawley trace and Roy's greatest root — with
9//! their F-approximations and p-values.
10//!
11//! The estimation reproduces the reference's singular-value-decomposition fit:
12//! given `X = U diag(s) Vᵀ`, the coefficient matrix is
13//! `B = V diag(1/s) Uᵀ Y`, the (scaled) inverse cross-product is
14//! `inv_cov = V diag(1/s²) Vᵀ`, and the residual sums of squares and
15//! cross-products are `sscpr = YᵀY - (diag(s) V B)ᵀ (diag(s) V B)`.
16
17use ndarray::{Array1, Array2};
18use solow_core::error::{Error, Result};
19use solow_linalg::{cholesky, eigh, inv, matrix_rank, solve_matrix, svd};
20
21use crate::mvstats::{multivariate_stats, MultivariateStats};
22
23/// A fitted multivariate OLS, holding the quantities needed for hypothesis
24/// testing.
25#[derive(Clone, Debug)]
26pub struct Manova {
27    params: Array2<f64>,
28    df_resid: f64,
29    inv_cov: Array2<f64>,
30    sscpr: Array2<f64>,
31    k_exog: usize,
32}
33
34impl Manova {
35    /// Fit the multivariate linear model `endog = exog · B` by SVD.
36    ///
37    /// `endog` is `nobs × k_endog` (at least two dependent variables) and
38    /// `exog` is `nobs × k_exog` (typically including an intercept column).
39    pub fn new(endog: Array2<f64>, exog: Array2<f64>) -> Result<Self> {
40        let (nobs, k_endog) = endog.dim();
41        let (nobs1, k_exog) = exog.dim();
42        if k_endog < 2 {
43            return Err(Error::Shape(
44                "there must be more than one dependent variable to fit MANOVA".into(),
45            ));
46        }
47        if nobs != nobs1 {
48            return Err(Error::Shape(
49                "endog and exog must have the same number of rows".into(),
50            ));
51        }
52        let df_resid = (nobs - k_exog) as f64;
53
54        // SVD fit (method='svd'): X = U diag(s) Vt.
55        let (u, s, vt) = svd(&exog)?;
56        let tolerance = 1e-8;
57        if s.iter().filter(|&&x| x > tolerance).count() < s.len() {
58            return Err(Error::Singular("covariance of exog singular".into()));
59        }
60        let k = s.len();
61        let invs = s.mapv(|x| 1.0 / x);
62
63        // v = vt.T (k_exog × k). params = v · diag(invs) · uᵀ · y.
64        // Compute uᵀ y (k × k_endog).
65        let uty = u.t().dot(&endog);
66        // diag(invs) · uᵀy.
67        let mut dinv_uty = uty.clone();
68        for i in 0..k {
69            for j in 0..k_endog {
70                dinv_uty[[i, j]] *= invs[i];
71            }
72        }
73        // params = vt.T · (diag(invs) uᵀy)  -> (k_exog × k_endog).
74        let params = vt.t().dot(&dinv_uty);
75
76        // inv_cov = vt.T · diag(invs²) · vt   (k_exog × k_exog).
77        let mut vt_scaled = vt.clone();
78        for i in 0..k {
79            let w = invs[i] * invs[i];
80            for j in 0..vt.ncols() {
81                vt_scaled[[i, j]] *= w;
82            }
83        }
84        let inv_cov = vt.t().dot(&vt_scaled);
85
86        // t = diag(s) · vt · params  (k × k_endog); sscpr = YᵀY - tᵀt.
87        let vt_params = vt.dot(&params);
88        let mut t = vt_params.clone();
89        for i in 0..k {
90            for j in 0..k_endog {
91                t[[i, j]] *= s[i];
92            }
93        }
94        let yty = endog.t().dot(&endog);
95        let sscpr = &yty - &t.t().dot(&t);
96
97        Ok(Manova {
98            params,
99            df_resid,
100            inv_cov,
101            sscpr,
102            k_exog,
103        })
104    }
105
106    /// Number of exogenous variables.
107    pub fn k_exog(&self) -> usize {
108        self.k_exog
109    }
110
111    /// Run the default multivariate tests: one hypothesis per exogenous column.
112    ///
113    /// Returns a vector with one [`ManovaTest`] per column of `exog`, in order
114    /// (named `x0`, `x1`, …, matching the reference).
115    pub fn mv_test(&self) -> Result<Vec<ManovaTest>> {
116        let mut out = Vec::with_capacity(self.k_exog);
117        for i in 0..self.k_exog {
118            // L is a 1 × k_exog row selecting column i; M = I (k_endog); C = 0.
119            let mut l = Array2::<f64>::zeros((1, self.k_exog));
120            l[[0, i]] = 1.0;
121            out.push(self.test_contrast(&l, format!("x{i}"))?);
122        }
123        Ok(out)
124    }
125
126    /// Test the contrast `L · B · M = 0` with `M = I` (identity transform on the
127    /// dependent variables) and `C = 0`.
128    pub fn test_contrast(&self, l: &Array2<f64>, name: String) -> Result<ManovaTest> {
129        // t1 = L · params   (rows_L × k_endog).
130        let t1 = l.dot(&self.params);
131        // t2 = L · inv_cov · Lᵀ ; q = rank(t2).
132        let t2 = l.dot(&self.inv_cov).dot(&l.t());
133        let q = matrix_rank(&t2)?;
134        // H = t1ᵀ · inv(t2) · t1   (k_endog × k_endog).
135        let inv_t2 = inv(&t2)?;
136        let h = t1.t().dot(&inv_t2).dot(&t1);
137        // E = sscpr (since M = I).
138        let e = self.sscpr.clone();
139
140        let eh = &e + &h;
141        let p = matrix_rank(&eh)?;
142
143        // Eigenvalues of inv(E + H) · H. Both symmetric; E+H is SPD, so use the
144        // Cholesky reduction to a symmetric standard eigenproblem.
145        let eigvals = gen_sym_eigvals(&h, &eh)?;
146        let eigvals_s = eigvals
147            .as_slice()
148            .ok_or_else(|| Error::Value("eigvals must be contiguous".into()))?;
149        let stat = multivariate_stats(eigvals_s, p, q, self.df_resid);
150
151        Ok(ManovaTest {
152            name,
153            stats: stat,
154            e,
155            h,
156        })
157    }
158}
159
160/// Eigenvalues of `inv(B) · A` where `A` (= H) is symmetric and `B` (= E + H) is
161/// symmetric positive definite. Reduces to the symmetric standard eigenproblem
162/// `C = L⁻¹ A L⁻ᵀ` with `B = L Lᵀ`, whose eigenvalues are real and equal those
163/// of `inv(B) · A`. Returned in ascending order (matching the reference's
164/// `np.sort(eigvals(...))`).
165fn gen_sym_eigvals(a: &Array2<f64>, b: &Array2<f64>) -> Result<Array1<f64>> {
166    let l = cholesky(b)?; // B = L Lᵀ, L lower-triangular.
167                          // Solve L · Y = A  ->  Y = L⁻¹ A.
168    let y = solve_matrix(&l, a)?;
169    // Solve L · Z = Yᵀ -> Z = L⁻¹ Yᵀ = L⁻¹ A L⁻ᵀ (since (L⁻¹A)ᵀ = Aᵀ L⁻ᵀ = A L⁻ᵀ).
170    let yt = y.t().to_owned();
171    let c = solve_matrix(&l, &yt)?;
172    // Symmetrise to kill rounding asymmetry, then eigendecompose.
173    let mut csym = c.clone();
174    let n = c.nrows();
175    for i in 0..n {
176        for j in 0..n {
177            csym[[i, j]] = 0.5 * (c[[i, j]] + c[[j, i]]);
178        }
179    }
180    let (w, _v) = eigh(&csym)?;
181    Ok(w) // ascending
182}
183
184/// A single MANOVA hypothesis result.
185#[derive(Clone, Debug)]
186pub struct ManovaTest {
187    /// Name of the hypothesis (e.g. `x0`).
188    pub name: String,
189    /// The four multivariate statistics with their F-approximations.
190    pub stats: MultivariateStats,
191    /// Error sums-of-squares-and-cross-products matrix `E`.
192    pub e: Array2<f64>,
193    /// Hypothesis sums-of-squares-and-cross-products matrix `H`.
194    pub h: Array2<f64>,
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200    use ndarray::array;
201
202    #[test]
203    fn two_group_two_dv_runs() {
204        // Two groups, intercept + dummy, two dependent variables.
205        let exog = array![
206            [1.0, 0.0],
207            [1.0, 0.0],
208            [1.0, 0.0],
209            [1.0, 1.0],
210            [1.0, 1.0],
211            [1.0, 1.0],
212        ];
213        let endog = array![
214            [1.0, 2.0],
215            [1.2, 1.9],
216            [0.9, 2.1],
217            [3.0, 0.5],
218            [3.1, 0.6],
219            [2.9, 0.4],
220        ];
221        let m = Manova::new(endog, exog).unwrap();
222        let tests = m.mv_test().unwrap();
223        assert_eq!(tests.len(), 2);
224        // Wilks lambda is in (0, 1].
225        for t in &tests {
226            assert!(t.stats.wilks_lambda.value > 0.0 && t.stats.wilks_lambda.value <= 1.0 + 1e-9);
227            assert!(t.stats.pillai_trace.value >= -1e-12);
228        }
229    }
230
231    #[test]
232    fn rejects_single_dependent_variable() {
233        let exog = array![[1.0], [1.0], [1.0]];
234        let endog = array![[1.0], [2.0], [3.0]];
235        assert!(Manova::new(endog, exog).is_err());
236    }
237}