Skip to main content

solow_multivariate/
mvstats.rs

1//! Shared helpers for the four classical multivariate test statistics.
2//!
3//! Both [`crate::manova`] and [`crate::cancorr`] reduce to a set of eigenvalues
4//! `λ_i` of `inv(E + H) · H` (equivalently, the squared canonical correlations)
5//! from which Wilks' lambda, Pillai's trace, the Hotelling-Lawley trace and
6//! Roy's greatest root are computed together with their F-approximations and
7//! p-values. This module follows the reference's `multivariate_stats` exactly.
8
9use solow_distributions::f_sf;
10
11/// One row of a multivariate statistics table: the statistic value, the
12/// numerator and denominator degrees of freedom of its F-approximation, the
13/// F-value and the upper-tail p-value.
14#[derive(Clone, Copy, Debug, PartialEq)]
15pub struct MvStat {
16    /// The statistic value.
17    pub value: f64,
18    /// Numerator degrees of freedom of the F-approximation.
19    pub num_df: f64,
20    /// Denominator degrees of freedom of the F-approximation.
21    pub den_df: f64,
22    /// The approximate F-value.
23    pub f_value: f64,
24    /// Upper-tail p-value `P(F > f_value)`.
25    pub pr_f: f64,
26}
27
28/// The four classical multivariate test statistics for a single hypothesis.
29#[derive(Clone, Copy, Debug, PartialEq)]
30pub struct MultivariateStats {
31    /// Wilks' lambda (product of `1 / (1 + λ_i)` in eigenvalue-of-`inv(E)H`
32    /// form; here `prod(1 - e_i)` with `e_i` the eigenvalues of `inv(E+H)H`).
33    pub wilks_lambda: MvStat,
34    /// Pillai's trace.
35    pub pillai_trace: MvStat,
36    /// Hotelling-Lawley trace.
37    pub hotelling_lawley: MvStat,
38    /// Roy's greatest root.
39    pub roy_greatest_root: MvStat,
40}
41
42/// Compute the four multivariate statistics from the eigenvalues of
43/// `inv(E + H) · H`.
44///
45/// * `eigenvals` — eigenvalues of `inv(E + H) · H` (each in `[0, 1)`);
46/// * `r_err_sscp` — rank of `E + H` (`p`);
47/// * `r_contrast` — rank of the contrast matrix `T` (`q`);
48/// * `df_resid` — residual degrees of freedom (`v`).
49///
50/// Mirrors the reference `multivariate.multivariate_ols.multivariate_stats`.
51pub fn multivariate_stats(
52    eigenvals: &[f64],
53    r_err_sscp: usize,
54    r_contrast: usize,
55    df_resid: f64,
56) -> MultivariateStats {
57    let tolerance = 1e-8;
58    let v = df_resid;
59    let p = r_err_sscp as f64;
60    let q = r_contrast as f64;
61    let s = p.min(q);
62
63    // Keep eigenvalues above tolerance (the `e_i`), and their `λ_i = e/(1-e)`.
64    let eigv2: Vec<f64> = eigenvals
65        .iter()
66        .copied()
67        .filter(|&x| x > tolerance)
68        .collect();
69    let eigv1: Vec<f64> = eigv2.iter().map(|&e| e / (1.0 - e)).collect();
70
71    let m = (((p - q).abs()) - 1.0) / 2.0;
72    let n = (v - p - 1.0) / 2.0;
73
74    // ---- Wilks' lambda. ----
75    let wilks_value: f64 = eigv2.iter().map(|&e| 1.0 - e).product();
76    let r = v - (p - q + 1.0) / 2.0;
77    let u = (p * q - 2.0) / 4.0;
78    let mut df1 = p * q;
79    let t = if p * p + q * q - 5.0 > 0.0 {
80        ((p * p * q * q - 4.0) / (p * p + q * q - 5.0)).sqrt()
81    } else {
82        1.0
83    };
84    let df2 = r * t - 2.0 * u;
85    let lmd = wilks_value.powf(1.0 / t);
86    let f = (1.0 - lmd) / lmd * df2 / df1;
87    let wilks = MvStat {
88        value: wilks_value,
89        num_df: df1,
90        den_df: df2,
91        f_value: f,
92        pr_f: f_sf(f, df1, df2),
93    };
94
95    // ---- Pillai's trace. ----
96    let pillai_value: f64 = eigv2.iter().sum();
97    df1 = s * (2.0 * m + s + 1.0);
98    let df2 = s * (2.0 * n + s + 1.0);
99    let f = df2 / df1 * pillai_value / (s - pillai_value);
100    let pillai = MvStat {
101        value: pillai_value,
102        num_df: df1,
103        den_df: df2,
104        f_value: f,
105        pr_f: f_sf(f, df1, df2),
106    };
107
108    // ---- Hotelling-Lawley trace. ----
109    let hl_value: f64 = eigv1.iter().sum();
110    let (df1, df2, f) = if n > 0.0 {
111        let b = (p + 2.0 * n) * (q + 2.0 * n) / 2.0 / (2.0 * n + 1.0) / (n - 1.0);
112        let df1 = p * q;
113        let df2 = 4.0 + (p * q + 2.0) / (b - 1.0);
114        let c = (df2 - 2.0) / 2.0 / n;
115        let f = df2 / df1 * hl_value / c;
116        (df1, df2, f)
117    } else {
118        let df1 = s * (2.0 * m + s + 1.0);
119        let df2 = s * (s * n + 1.0);
120        let f = df2 / df1 / s * hl_value;
121        (df1, df2, f)
122    };
123    let hotelling = MvStat {
124        value: hl_value,
125        num_df: df1,
126        den_df: df2,
127        f_value: f,
128        pr_f: f_sf(f, df1, df2),
129    };
130
131    // ---- Roy's greatest root. ----
132    let roy_value: f64 = eigv1.iter().copied().fold(f64::NEG_INFINITY, f64::max);
133    let rmax = p.max(q);
134    let df1 = rmax;
135    let df2 = v - rmax + q;
136    let f = df2 / df1 * roy_value;
137    let roy = MvStat {
138        value: roy_value,
139        num_df: df1,
140        den_df: df2,
141        f_value: f,
142        pr_f: f_sf(f, df1, df2),
143    };
144
145    MultivariateStats {
146        wilks_lambda: wilks,
147        pillai_trace: pillai,
148        hotelling_lawley: hotelling,
149        roy_greatest_root: roy,
150    }
151}