Skip to main content

solow_multivariate/
factor.rs

1//! Factor analysis via the iterative principal-axis (`method='pa'`) method.
2//!
3//! The implementation mirrors the reference's
4//! `multivariate.factor.Factor` with `method='pa'` and no rotation. Given a
5//! correlation matrix `R` (or raw data, from which the correlation matrix is
6//! formed) and a requested number of factors, communalities are estimated
7//! iteratively:
8//!
9//! 1. Initialise communalities. With squared multiple correlations
10//!    (`smc = true`, the default) the initial communality of variable `j` is
11//!    `1 - 1 / (R^{-1})_{jj}`; otherwise communalities start at one.
12//! 2. Replace the diagonal of `R` with the current communalities, take the
13//!    symmetric eigendecomposition, and keep the `n` leading eigenvectors with
14//!    positive eigenvalues (`n = min(n_factor, #positive eigenvalues)`).
15//! 3. Form the loadings `A = V diag(sqrt(L))` and the new communalities as the
16//!    row sums of `A^2`.
17//! 4. Stop when `‖c_last - c‖ < tol`, otherwise repeat.
18//!
19//! The fitted [`FactorResults`] expose the loadings, communalities,
20//! uniquenesses and the eigenvalues of the final adjusted correlation matrix.
21
22use ndarray::{Array1, Array2};
23use solow_core::error::{Error, Result};
24use solow_linalg::{eigh, inv, matrix_rank};
25
26/// A principal-axis factor analysis awaiting estimation.
27///
28/// Construct from a correlation matrix with [`Factor::from_corr`] or from a raw
29/// `nobs × nvar` data matrix with [`Factor::from_data`] (which standardises the
30/// columns into a Pearson correlation matrix), set the number of factors, then
31/// call [`Factor::fit`].
32#[derive(Clone, Debug)]
33pub struct Factor {
34    corr: Array2<f64>,
35    n_factor: usize,
36    smc: bool,
37}
38
39impl Factor {
40    /// A factor analysis on a correlation (or covariance) matrix `corr`.
41    ///
42    /// `n_factor` is the number of factors to extract; `smc` selects squared
43    /// multiple correlations as the initial communality estimate (matching the
44    /// reference default `smc=True`).
45    pub fn from_corr(corr: Array2<f64>, n_factor: usize, smc: bool) -> Self {
46        Factor {
47            corr,
48            n_factor,
49            smc,
50        }
51    }
52
53    /// A factor analysis on a raw `nobs × nvar` data matrix. The columns are
54    /// turned into a Pearson correlation matrix (population covariance scaled by
55    /// the standard deviations) before estimation.
56    pub fn from_data(data: &Array2<f64>, n_factor: usize, smc: bool) -> Self {
57        let corr = corrcoef(data);
58        Factor {
59            corr,
60            n_factor,
61            smc,
62        }
63    }
64
65    /// Estimate the factor model with the iterative principal-axis method.
66    ///
67    /// `maxiter` bounds the number of communality-update iterations and `tol`
68    /// is the convergence threshold on the change in communalities (the
69    /// reference requires `0 < tol <= 0.01`).
70    pub fn fit(&self, maxiter: usize, tol: f64) -> Result<FactorResults> {
71        let p = self.corr.nrows();
72        if self.corr.ncols() != p {
73            return Err(Error::Shape("corr must be square".into()));
74        }
75        if maxiter == 0 {
76            return Err(Error::Shape("maxiter must be larger than 0".into()));
77        }
78        if tol <= 0.0 || tol > 0.01 {
79            return Err(Error::Shape(
80                "tol must be larger than 0 and smaller than 0.01".into(),
81            ));
82        }
83        let n_comp = matrix_rank(&self.corr)?;
84        if self.n_factor > n_comp {
85            return Err(Error::Shape(
86                "n_factor must be smaller or equal to the rank of the data".into(),
87            ));
88        }
89        if self.n_factor == 0 {
90            return Err(Error::Shape("n_factor must be positive".into()));
91        }
92
93        let mut r = self.corr.clone();
94
95        // Initial communality estimate.
96        let mut c = if self.smc {
97            let rinv = inv(&self.corr)?;
98            Array1::from_iter((0..p).map(|j| 1.0 - 1.0 / rinv[[j, j]]))
99        } else {
100            Array1::<f64>::ones(p)
101        };
102
103        let mut eigenvals = Array1::<f64>::zeros(p);
104        let mut loadings = Array2::<f64>::zeros((p, self.n_factor));
105
106        for _ in 0..maxiter {
107            // Replace the diagonal of R with the current communalities.
108            for j in 0..p {
109                r[[j, j]] = c[j];
110            }
111
112            // Symmetric eigendecomposition; `eigh` returns ascending order.
113            let (l_asc, v_asc) = eigh(&r)?;
114            let c_last = c.clone();
115
116            // Sort eigenvalues / eigenvectors descending.
117            let mut order: Vec<usize> = (0..p).collect();
118            order.sort_by(|&a, &b| l_asc[b].total_cmp(&l_asc[a]));
119
120            let l_desc = Array1::from_iter(order.iter().map(|&i| l_asc[i]));
121            eigenvals = l_desc.clone();
122
123            let n_pos = l_desc.iter().filter(|&&x| x > 0.0).count();
124            let n = n_pos.min(self.n_factor);
125
126            // A = V[:, :n] diag(sqrt(L[:n])).
127            let mut a = Array2::<f64>::zeros((p, self.n_factor));
128            for k in 0..n {
129                let col = order[k];
130                let sl = l_desc[k].sqrt();
131                for row in 0..p {
132                    a[[row, k]] = v_asc[[row, col]] * sl;
133                }
134            }
135            // Columns beyond `n` (only possible when n_factor exceeds the number
136            // of positive eigenvalues) stay zero, matching the reference, which
137            // keeps fewer columns; here the trailing columns contribute nothing
138            // to the communalities.
139            loadings = a.clone();
140
141            // New communalities: row sums of A^2.
142            for row in 0..p {
143                let mut s = 0.0;
144                for k in 0..self.n_factor {
145                    s += a[[row, k]] * a[[row, k]];
146                }
147                c[row] = s;
148            }
149
150            // Convergence: ‖c_last - c‖ < tol.
151            let diff: f64 = (0..p)
152                .map(|i| (c_last[i] - c[i]).powi(2))
153                .sum::<f64>()
154                .sqrt();
155            if diff < tol {
156                break;
157            }
158        }
159
160        let uniqueness = c.mapv(|x| 1.0 - x);
161
162        Ok(FactorResults {
163            eigenvals,
164            communality: c,
165            uniqueness,
166            loadings,
167            n_factor: self.n_factor,
168        })
169    }
170}
171
172/// Pearson correlation matrix of the columns of `data` (population convention,
173/// matching `numpy.corrcoef` on `rowvar=False`).
174fn corrcoef(data: &Array2<f64>) -> Array2<f64> {
175    let (nobs, nvar) = data.dim();
176    let mut means = Array1::<f64>::zeros(nvar);
177    for j in 0..nvar {
178        means[j] = data.column(j).sum() / nobs as f64;
179    }
180    // Centred data.
181    let mut centred = data.clone();
182    for j in 0..nvar {
183        for i in 0..nobs {
184            centred[[i, j]] -= means[j];
185        }
186    }
187    // Covariance (un-normalised cross products) then scale by column norms.
188    let mut cov = Array2::<f64>::zeros((nvar, nvar));
189    for a in 0..nvar {
190        for b in a..nvar {
191            let mut s = 0.0;
192            for i in 0..nobs {
193                s += centred[[i, a]] * centred[[i, b]];
194            }
195            cov[[a, b]] = s;
196            cov[[b, a]] = s;
197        }
198    }
199    let mut std = Array1::<f64>::zeros(nvar);
200    for j in 0..nvar {
201        std[j] = cov[[j, j]].sqrt();
202    }
203    let mut corr = Array2::<f64>::zeros((nvar, nvar));
204    for a in 0..nvar {
205        for b in 0..nvar {
206            let denom = std[a] * std[b];
207            corr[[a, b]] = if denom > 0.0 {
208                cov[[a, b]] / denom
209            } else {
210                0.0
211            };
212        }
213    }
214    corr
215}
216
217/// A fitted principal-axis factor model.
218#[derive(Clone, Debug)]
219pub struct FactorResults {
220    /// Eigenvalues of the final adjusted correlation matrix, descending,
221    /// length `nvar`.
222    pub eigenvals: Array1<f64>,
223    /// Estimated communalities (variance of each variable explained by the
224    /// retained factors), length `nvar`.
225    pub communality: Array1<f64>,
226    /// Uniquenesses `1 - communality`, length `nvar`.
227    pub uniqueness: Array1<f64>,
228    /// Factor loadings, `nvar × n_factor`.
229    pub loadings: Array2<f64>,
230    /// Number of factors extracted.
231    pub n_factor: usize,
232}
233
234#[cfg(test)]
235mod tests {
236    use super::*;
237    use ndarray::array;
238
239    #[test]
240    fn communality_plus_uniqueness_is_one() {
241        let corr = array![[1.0, 0.6, 0.5], [0.6, 1.0, 0.4], [0.5, 0.4, 1.0],];
242        let res = Factor::from_corr(corr, 1, true).fit(500, 1e-10).unwrap();
243        for i in 0..3 {
244            assert!((res.communality[i] + res.uniqueness[i] - 1.0).abs() < 1e-12);
245        }
246    }
247
248    #[test]
249    fn loadings_reproduce_communalities() {
250        let corr = array![[1.0, 0.6, 0.5], [0.6, 1.0, 0.4], [0.5, 0.4, 1.0],];
251        let res = Factor::from_corr(corr, 2, true).fit(500, 1e-10).unwrap();
252        for i in 0..3 {
253            let s: f64 = (0..res.n_factor)
254                .map(|k| res.loadings[[i, k]].powi(2))
255                .sum();
256            assert!((s - res.communality[i]).abs() < 1e-10);
257        }
258    }
259
260    #[test]
261    fn eigenvals_descending() {
262        let corr = array![[1.0, 0.6, 0.5], [0.6, 1.0, 0.4], [0.5, 0.4, 1.0],];
263        let res = Factor::from_corr(corr, 2, true).fit(500, 1e-10).unwrap();
264        for i in 1..res.eigenvals.len() {
265            assert!(res.eigenvals[i - 1] >= res.eigenvals[i]);
266        }
267    }
268
269    #[test]
270    fn from_data_matches_corr_construction() {
271        let data = array![
272            [1.0, 2.0, 0.5],
273            [2.0, 1.0, 1.5],
274            [3.0, 0.0, 2.5],
275            [4.0, 1.0, 0.0],
276            [2.0, 3.0, 1.0],
277        ];
278        let corr = corrcoef(&data);
279        let a = Factor::from_data(&data, 1, true).fit(500, 1e-10).unwrap();
280        let b = Factor::from_corr(corr, 1, true).fit(500, 1e-10).unwrap();
281        for i in 0..3 {
282            assert!((a.communality[i] - b.communality[i]).abs() < 1e-12);
283        }
284    }
285}