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(¶ms);
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}