1use ndarray::{s, Array1, Array2};
22use solow_core::error::{Error, Result};
23use solow_linalg::svd;
24
25#[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 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 pub fn ncomp(mut self, ncomp: usize) -> Self {
54 self.ncomp = Some(ncomp);
55 self
56 }
57
58 pub fn standardize(mut self, standardize: bool) -> Self {
61 self.standardize = standardize;
62 self
63 }
64
65 pub fn demean(mut self, demean: bool) -> Self {
68 self.demean = demean;
69 self
70 }
71
72 pub fn normalize(mut self, normalize: bool) -> Self {
75 self.normalize = normalize;
76 self
77 }
78
79 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 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 let (_u, s, vt) = svd(&transformed)?;
125 let eig_all = s.mapv(|x| x * x);
126 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 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 let mut factors = transformed.dot(&eigenvecs);
146 let loadings = eigenvecs.clone();
147 let mut coeff = eigenvecs.t().to_owned();
149
150 if self.normalize {
151 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 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 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 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
204fn 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#[derive(Clone, Debug)]
213pub struct PcaResults {
214 pub eigenvals: Array1<f64>,
216 pub eigenvecs: Array2<f64>,
218 pub loadings: Array2<f64>,
220 pub factors: Array2<f64>,
222 pub scores: Array2<f64>,
224 pub coeff: Array2<f64>,
226 pub rsquare: Array1<f64>,
228 pub explained_variance_ratio: Array1<f64>,
230 pub mu: Array1<f64>,
232 pub sigma: Array1<f64>,
234 pub ncomp: usize,
236 pub nobs: usize,
238 pub nvar: usize,
240 standardize: bool,
241 demean: bool,
242}
243
244impl PcaResults {
245 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 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 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 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 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}