Skip to main content

solow_multivariate/
pca.rs

1//! Principal component analysis (PCA).
2//!
3//! The implementation mirrors the reference's `multivariate.pca.PCA` with the
4//! singular-value-decomposition method, supporting the `standardize`, `demean`
5//! and `normalize` options. Given an `nobs × nvar` data matrix it produces, for
6//! a requested number of components `ncomp`:
7//!
8//! * [`PcaResults::eigenvals`] — the eigenvalues of the (transformed) cross
9//!   product, sorted in descending order (squared singular values);
10//! * [`PcaResults::eigenvecs`] / [`PcaResults::loadings`] — the right singular
11//!   vectors (one per column), the principal axes;
12//! * [`PcaResults::factors`] / [`PcaResults::scores`] — the projection of the
13//!   transformed data onto the components;
14//! * [`PcaResults::coeff`] — the loadings used to reconstruct the data from the
15//!   factors;
16//! * [`PcaResults::rsquare`] — the cumulative fraction of variance explained as
17//!   components are added (length `ncomp + 1`, starting at `0`);
18//! * [`PcaResults::explained_variance_ratio`] — the per-component fraction of
19//!   total variance, derived from the eigenvalues.
20
21use ndarray::{s, Array1, Array2};
22use solow_core::error::{Error, Result};
23use solow_linalg::svd;
24
25/// A principal component analysis awaiting estimation.
26///
27/// Construct with [`Pca::new`] (which mirrors the reference defaults:
28/// `standardize = true`, `demean = true`, `normalize = true`, all components),
29/// optionally adjust the builder options, then call [`Pca::fit`].
30#[derive(Clone, Debug)]
31pub struct Pca {
32    data: Array2<f64>,
33    ncomp: Option<usize>,
34    standardize: bool,
35    demean: bool,
36    normalize: bool,
37}
38
39impl Pca {
40    /// A PCA on `data` (an `nobs × nvar` matrix) with the reference defaults:
41    /// standardized columns, all components, normalized factors.
42    pub fn new(data: Array2<f64>) -> Self {
43        Pca {
44            data,
45            ncomp: None,
46            standardize: true,
47            demean: true,
48            normalize: true,
49        }
50    }
51
52    /// Set the number of components to retain. Defaults to `min(nobs, nvar)`.
53    pub fn ncomp(mut self, ncomp: usize) -> Self {
54        self.ncomp = Some(ncomp);
55        self
56    }
57
58    /// Whether to standardize each column to unit variance (population, ddof 0)
59    /// before decomposition. When `true`, this implies demeaning. Default `true`.
60    pub fn standardize(mut self, standardize: bool) -> Self {
61        self.standardize = standardize;
62        self
63    }
64
65    /// Whether to subtract each column's mean before decomposition. Ignored when
66    /// `standardize` is `true` (standardizing already demeans). Default `true`.
67    pub fn demean(mut self, demean: bool) -> Self {
68        self.demean = demean;
69        self
70    }
71
72    /// Whether to normalize the factors to unit inner product, scaling the
73    /// coefficients by `sqrt(eigenvalue)`. Default `true`.
74    pub fn normalize(mut self, normalize: bool) -> Self {
75        self.normalize = normalize;
76        self
77    }
78
79    /// Estimate the PCA via SVD.
80    pub fn fit(&self) -> Result<PcaResults> {
81        let (nobs, nvar) = self.data.dim();
82        if nobs == 0 || nvar == 0 {
83            return Err(Error::Shape("data must be non-empty".into()));
84        }
85        let min_dim = nobs.min(nvar);
86        let ncomp = match self.ncomp {
87            None => min_dim,
88            Some(c) => {
89                if c == 0 {
90                    return Err(Error::Shape("ncomp must be positive".into()));
91                }
92                c.min(min_dim)
93            }
94        };
95
96        // --- Prepare data: standardize / demean (population statistics). ---
97        let mut mu = Array1::<f64>::zeros(nvar);
98        let mut sigma = Array1::<f64>::ones(nvar);
99        for j in 0..nvar {
100            let col = self.data.column(j);
101            let m = col.sum() / nobs as f64;
102            mu[j] = m;
103            let var = col.iter().map(|&x| (x - m) * (x - m)).sum::<f64>() / nobs as f64;
104            sigma[j] = var.sqrt();
105        }
106
107        let mut transformed = self.data.clone();
108        if self.standardize {
109            for j in 0..nvar {
110                let s = sigma[j];
111                for i in 0..nobs {
112                    transformed[[i, j]] = (transformed[[i, j]] - mu[j]) / s;
113                }
114            }
115        } else if self.demean {
116            for j in 0..nvar {
117                for i in 0..nobs {
118                    transformed[[i, j]] -= mu[j];
119                }
120            }
121        }
122
123        // --- SVD: eigenvals = s^2, eigenvecs = V (columns are axes). ---
124        let (_u, s, vt) = svd(&transformed)?;
125        let eig_all = s.mapv(|x| x * x);
126        // `vt` is k × nvar (k = min(nobs, nvar)); columns of `v = vt.T` are the
127        // right singular vectors. Sort by eigenvalue descending (SVD already
128        // returns descending, but sort explicitly to match the reference).
129        let k = s.len();
130        let mut order: Vec<usize> = (0..k).collect();
131        order.sort_by(|&a, &b| eig_all[b].total_cmp(&eig_all[a]));
132
133        // Build sorted, truncated eigenvalues and eigenvectors.
134        let mut eigenvals = Array1::<f64>::zeros(ncomp);
135        let mut eigenvecs = Array2::<f64>::zeros((nvar, ncomp));
136        for (c, &idx) in order.iter().take(ncomp).enumerate() {
137            eigenvals[c] = eig_all[idx];
138            for r in 0..nvar {
139                eigenvecs[[r, c]] = vt[[idx, r]];
140            }
141        }
142
143        // --- factors / loadings / coeff. ---
144        // factors = scores = transformed @ vecs   (nobs × ncomp)
145        let mut factors = transformed.dot(&eigenvecs);
146        let loadings = eigenvecs.clone();
147        // coeff = vecs.T   (ncomp × nvar)
148        let mut coeff = eigenvecs.t().to_owned();
149
150        if self.normalize {
151            // coeff = (coeff.T * sqrt(vals)).T  -> scale row c by sqrt(vals[c]).
152            for c in 0..ncomp {
153                let sc = eigenvals[c].sqrt();
154                for j in 0..nvar {
155                    coeff[[c, j]] *= sc;
156                }
157                let inv = 1.0 / sc;
158                for i in 0..nobs {
159                    factors[[i, c]] *= inv;
160                }
161            }
162        }
163        let scores = factors.clone();
164
165        // --- R-square (cumulative) and explained variance ratio. ---
166        // TSS uses the transformed data (weights are unity).
167        let tss_indiv: Array1<f64> = (0..nvar)
168            .map(|j| transformed.column(j).iter().map(|&x| x * x).sum::<f64>())
169            .collect();
170        let tss: f64 = tss_indiv.sum();
171
172        let mut rsquare = Array1::<f64>::zeros(ncomp + 1);
173        for i in 0..=ncomp {
174            // Projection onto the first i factors, in transformed space.
175            let proj = project(&factors, &coeff, i);
176            let rss: f64 = proj.iter().map(|&x| x * x).sum::<f64>();
177            let ess = tss - rss;
178            rsquare[i] = 1.0 - ess / tss;
179        }
180
181        // Per-component fraction of total variance from the eigenvalues.
182        let explained_variance_ratio = eigenvals.mapv(|v| v / tss);
183
184        Ok(PcaResults {
185            eigenvals,
186            eigenvecs,
187            loadings,
188            factors,
189            scores,
190            coeff,
191            rsquare,
192            explained_variance_ratio,
193            mu,
194            sigma,
195            ncomp,
196            nobs,
197            nvar,
198            standardize: self.standardize,
199            demean: self.demean,
200        })
201    }
202}
203
204/// Reconstruct `factors[:, :ncomp] @ coeff[:ncomp, :]` (in transformed space).
205fn project(factors: &Array2<f64>, coeff: &Array2<f64>, ncomp: usize) -> Array2<f64> {
206    let f = factors.slice(s![.., 0..ncomp]);
207    let c = coeff.slice(s![0..ncomp, ..]);
208    f.dot(&c)
209}
210
211/// Fitted principal component analysis.
212#[derive(Clone, Debug)]
213pub struct PcaResults {
214    /// Eigenvalues (squared singular values), descending, length `ncomp`.
215    pub eigenvals: Array1<f64>,
216    /// Eigenvectors / principal axes, `nvar × ncomp` (one axis per column).
217    pub eigenvecs: Array2<f64>,
218    /// Loadings, identical to [`Self::eigenvecs`] (`nvar × ncomp`).
219    pub loadings: Array2<f64>,
220    /// Factor scores, `nobs × ncomp` (normalized when `normalize` is set).
221    pub factors: Array2<f64>,
222    /// Alias of [`Self::factors`].
223    pub scores: Array2<f64>,
224    /// Reconstruction coefficients, `ncomp × nvar`.
225    pub coeff: Array2<f64>,
226    /// Cumulative variance explained, length `ncomp + 1` (starts at `0`).
227    pub rsquare: Array1<f64>,
228    /// Per-component fraction of total variance, length `ncomp`.
229    pub explained_variance_ratio: Array1<f64>,
230    /// Column means of the input data.
231    pub mu: Array1<f64>,
232    /// Column population standard deviations of the input data.
233    pub sigma: Array1<f64>,
234    /// Number of components retained.
235    pub ncomp: usize,
236    /// Number of observations.
237    pub nobs: usize,
238    /// Number of variables.
239    pub nvar: usize,
240    standardize: bool,
241    demean: bool,
242}
243
244impl PcaResults {
245    /// Project the (possibly fewer) factors back into the original data space,
246    /// undoing the standardize/demean transformation. Returns an `nobs × nvar`
247    /// reconstruction using the first `ncomp` components.
248    pub fn project(&self, ncomp: usize) -> Result<Array2<f64>> {
249        if ncomp > self.ncomp {
250            return Err(Error::Shape(
251                "ncomp must not exceed the number of fitted components".into(),
252            ));
253        }
254        let mut projection = project(&self.factors, &self.coeff, ncomp);
255        if self.standardize {
256            for j in 0..self.nvar {
257                for i in 0..self.nobs {
258                    projection[[i, j]] *= self.sigma[j];
259                }
260            }
261        }
262        if self.standardize || self.demean {
263            for j in 0..self.nvar {
264                for i in 0..self.nobs {
265                    projection[[i, j]] += self.mu[j];
266                }
267            }
268        }
269        Ok(projection)
270    }
271}
272
273#[cfg(test)]
274mod tests {
275    use super::*;
276    use ndarray::array;
277
278    fn check_close(a: &Array1<f64>, b: &[f64], tol: f64) {
279        assert_eq!(a.len(), b.len());
280        for i in 0..a.len() {
281            assert!((a[i] - b[i]).abs() <= tol, "idx {i}: {} vs {}", a[i], b[i]);
282        }
283    }
284
285    #[test]
286    fn eigenvals_descending() {
287        let data = array![
288            [1.0, 2.0, 0.5],
289            [2.0, 1.0, 1.5],
290            [3.0, 0.0, 2.5],
291            [4.0, 1.0, 0.0],
292            [2.0, 3.0, 1.0],
293        ];
294        let res = Pca::new(data).fit().unwrap();
295        for c in 1..res.eigenvals.len() {
296            assert!(res.eigenvals[c - 1] >= res.eigenvals[c]);
297        }
298    }
299
300    #[test]
301    fn rsquare_monotone_and_full() {
302        let data = array![
303            [1.0, 2.0, 0.5],
304            [2.0, 1.0, 1.5],
305            [3.0, 0.0, 2.5],
306            [4.0, 1.0, 0.0],
307            [2.0, 3.0, 1.0],
308        ];
309        let res = Pca::new(data).fit().unwrap();
310        // First entry is 0, monotone increasing, last reaches 1 (full rank).
311        assert!((res.rsquare[0]).abs() < 1e-12);
312        for i in 1..res.rsquare.len() {
313            assert!(res.rsquare[i] >= res.rsquare[i - 1] - 1e-12);
314        }
315        let last = res.rsquare[res.rsquare.len() - 1];
316        assert!((last - 1.0).abs() < 1e-9);
317    }
318
319    #[test]
320    fn explained_variance_sums_to_one_full_rank() {
321        let data = array![
322            [1.0, 2.0, 0.5],
323            [2.0, 1.0, 1.5],
324            [3.0, 0.0, 2.5],
325            [4.0, 1.0, 0.0],
326            [2.0, 3.0, 1.0],
327        ];
328        let res = Pca::new(data).fit().unwrap();
329        let total: f64 = res.explained_variance_ratio.sum();
330        assert!((total - 1.0).abs() < 1e-9);
331    }
332
333    #[test]
334    fn standardize_demeans_and_scales() {
335        // With standardize, transformed columns have zero mean, unit variance,
336        // so eigenvalues sum to nobs * nvar (trace of correlation * nobs).
337        let data = array![[1.0, 5.0], [2.0, 3.0], [3.0, 4.0], [4.0, 1.0],];
338        let res = Pca::new(data).fit().unwrap();
339        let sum: f64 = res.eigenvals.sum();
340        // trace of X'X where each column standardized (population) = nobs per col.
341        assert!((sum - (res.nobs * res.nvar) as f64).abs() < 1e-9);
342    }
343
344    #[test]
345    fn reconstruction_recovers_data_full_rank() {
346        let data = array![
347            [1.0, 2.0, 0.5],
348            [2.0, 1.0, 1.5],
349            [3.0, 0.0, 2.5],
350            [4.0, 1.0, 0.0],
351            [2.0, 3.0, 1.0],
352        ];
353        let res = Pca::new(data.clone()).fit().unwrap();
354        let recon = res.project(res.ncomp).unwrap();
355        for i in 0..data.nrows() {
356            for j in 0..data.ncols() {
357                assert!((recon[[i, j]] - data[[i, j]]).abs() < 1e-7);
358            }
359        }
360    }
361
362    #[test]
363    fn no_standardize_no_demean() {
364        let data = array![[2.0, 0.0], [0.0, 2.0], [1.0, 1.0]];
365        let res = Pca::new(data)
366            .standardize(false)
367            .demean(false)
368            .normalize(false)
369            .fit()
370            .unwrap();
371        // mu computed but not applied; check eigenvecs orthonormal.
372        let v = &res.eigenvecs;
373        let mut dot = 0.0;
374        for r in 0..v.nrows() {
375            dot += v[[r, 0]] * v[[r, 0]];
376        }
377        check_close(&array![dot], &[1.0], 1e-9);
378    }
379}