Skip to main content

solow_multivariate/
cancorr.rs

1//! Canonical correlation analysis (CanCorr).
2//!
3//! Mirrors the reference's `multivariate.cancorr.CanCorr`. Given two sets of
4//! variables `endog` (`nobs × k_endog`) and `exog` (`nobs × k_exog`), the
5//! canonical correlations are the singular values of `Uxᵀ Uy`, where `Ux` and
6//! `Uy` are the left singular vectors of the column-centred `exog` and `endog`.
7//! There are `k = min(k_endog, k_exog)` of them, each clamped to `[0, 1]`.
8//!
9//! [`CanCorr::corr_test`] reports, for each canonical correlation, the
10//! approximate Wilks'-lambda F-test of the hypothesis that this and all smaller
11//! canonical correlations are zero.
12
13use ndarray::{Array1, Array2};
14use solow_core::error::{Error, Result};
15use solow_distributions::f_sf;
16use solow_linalg::svd;
17
18/// A fitted canonical correlation analysis.
19#[derive(Clone, Debug)]
20pub struct CanCorr {
21    /// Canonical correlations, descending, length `min(k_endog, k_exog)`.
22    pub cancorr: Array1<f64>,
23    k_endog: usize,
24    k_exog: usize,
25    nobs: usize,
26}
27
28impl CanCorr {
29    /// Fit a canonical correlation analysis of `endog` against `exog`.
30    ///
31    /// Returns an error if either set of variables is collinear (a singular
32    /// value below tolerance).
33    pub fn new(endog: &Array2<f64>, exog: &Array2<f64>) -> Result<Self> {
34        let (nobs, k_endog) = endog.dim();
35        let (nobs_x, k_exog) = exog.dim();
36        if nobs != nobs_x {
37            return Err(Error::Shape(
38                "endog and exog must have the same number of rows".into(),
39            ));
40        }
41        let tolerance = 1e-8;
42
43        let x = demean(exog);
44        let y = demean(endog);
45
46        let (ux, sx, _vx) = svd(&x)?;
47        if sx.iter().filter(|&&v| v > tolerance).count() < sx.len() {
48            return Err(Error::Singular("exog is collinear".into()));
49        }
50        let (uy, sy, _vy) = svd(&y)?;
51        if sy.iter().filter(|&&v| v > tolerance).count() < sy.len() {
52            return Err(Error::Singular("endog is collinear".into()));
53        }
54
55        // SVD of Uxᵀ Uy; the singular values are the canonical correlations.
56        let m = ux.t().dot(&uy);
57        let (_u, s, _v) = svd(&m)?;
58        let k = k_endog.min(k_exog);
59        let cancorr = Array1::from_iter((0..k).map(|i| s[i].clamp(0.0, 1.0)));
60
61        Ok(CanCorr {
62            cancorr,
63            k_endog,
64            k_exog,
65            nobs,
66        })
67    }
68
69    /// Approximate Wilks'-lambda F-test for each canonical correlation.
70    ///
71    /// Returns one [`CanCorrTestRow`] per canonical correlation, ordered from
72    /// the first (largest) to the last, matching the reference table.
73    pub fn corr_test(&self) -> Vec<CanCorrTestRow> {
74        let k_yvar = self.k_endog as f64;
75        let k_xvar = self.k_exog as f64;
76        let nobs = self.nobs as f64;
77        let eigenvals: Vec<f64> = self.cancorr.iter().map(|&c| c * c).collect();
78        let n = eigenvals.len();
79
80        // Accumulate the Wilks product from the smallest canonical correlation
81        // upward (matching the reference's reverse loop), then re-order.
82        let mut rows_rev: Vec<CanCorrTestRow> = Vec::with_capacity(n);
83        let mut prod = 1.0;
84        for i in (0..n).rev() {
85            prod *= 1.0 - eigenvals[i];
86            let p = k_yvar - i as f64;
87            let q = k_xvar - i as f64;
88            let r = (nobs - k_yvar - 1.0) - (p - q + 1.0) / 2.0;
89            let u = (p * q - 2.0) / 4.0;
90            let df1 = p * q;
91            let t = if p * p + q * q - 5.0 > 0.0 {
92                (((p * q).powi(2) - 4.0) / (p * p + q * q - 5.0)).sqrt()
93            } else {
94                1.0
95            };
96            let df2 = r * t - 2.0 * u;
97            let lmd = prod.powf(1.0 / t);
98            let f = (1.0 - lmd) / lmd * df2 / df1;
99            let pr_f = f_sf(f, df1, df2);
100            rows_rev.push(CanCorrTestRow {
101                index: i,
102                cancorr: self.cancorr[i],
103                wilks_lambda: prod,
104                num_df: df1,
105                den_df: df2,
106                f_value: f,
107                pr_f,
108            });
109        }
110        // rows_rev is ordered i = n-1, n-2, ..., 0. The reference returns them
111        // in ascending index order (0, 1, ..., n-1).
112        rows_rev.reverse();
113        rows_rev
114    }
115}
116
117/// Column-centred copy of `m` (subtract each column mean).
118fn demean(m: &Array2<f64>) -> Array2<f64> {
119    let (nobs, nvar) = m.dim();
120    let mut out = m.clone();
121    for j in 0..nvar {
122        let mean = m.column(j).sum() / nobs as f64;
123        for i in 0..nobs {
124            out[[i, j]] -= mean;
125        }
126    }
127    out
128}
129
130/// One row of the canonical-correlation approximate F-test table.
131#[derive(Clone, Copy, Debug, PartialEq)]
132pub struct CanCorrTestRow {
133    /// Index of the canonical correlation (0 = largest).
134    pub index: usize,
135    /// The canonical correlation.
136    pub cancorr: f64,
137    /// Wilks' lambda for this and all smaller canonical correlations.
138    pub wilks_lambda: f64,
139    /// Numerator degrees of freedom of the F-approximation.
140    pub num_df: f64,
141    /// Denominator degrees of freedom of the F-approximation.
142    pub den_df: f64,
143    /// Approximate F-value.
144    pub f_value: f64,
145    /// Upper-tail p-value.
146    pub pr_f: f64,
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152    use ndarray::array;
153
154    #[test]
155    fn cancorr_in_unit_interval_descending() {
156        let exog = array![
157            [1.0, 0.2],
158            [2.0, -0.1],
159            [3.0, 0.4],
160            [4.0, 0.9],
161            [2.5, -0.3],
162            [1.7, 0.6],
163        ];
164        let endog = array![
165            [0.9, 1.1],
166            [1.8, 0.7],
167            [3.2, 0.2],
168            [3.9, -0.4],
169            [2.4, 0.5],
170            [1.6, 0.8],
171        ];
172        let cc = CanCorr::new(&endog, &exog).unwrap();
173        assert_eq!(cc.cancorr.len(), 2);
174        for &c in cc.cancorr.iter() {
175            assert!((0.0..=1.0).contains(&c));
176        }
177        assert!(cc.cancorr[0] >= cc.cancorr[1]);
178        let rows = cc.corr_test();
179        assert_eq!(rows.len(), 2);
180        assert_eq!(rows[0].index, 0);
181        assert_eq!(rows[1].index, 1);
182    }
183}