1use ndarray::{Array1, Array2};
31use solow_core::error::{Error, Result};
32use solow_linalg::{inv, svd};
33
34#[derive(Clone, Copy, Debug, PartialEq, Eq)]
36pub enum RotationMethod {
37 Varimax,
39 Quartimax,
41 Oblimin,
44 Quartimin,
46 Promax,
48}
49
50impl RotationMethod {
51 pub fn from_name(name: &str) -> Result<Self> {
53 match name.to_ascii_lowercase().as_str() {
54 "varimax" => Ok(RotationMethod::Varimax),
55 "quartimax" => Ok(RotationMethod::Quartimax),
56 "oblimin" => Ok(RotationMethod::Oblimin),
57 "quartimin" => Ok(RotationMethod::Quartimin),
58 "promax" => Ok(RotationMethod::Promax),
59 other => Err(Error::Shape(format!("unknown rotation method: {other}"))),
60 }
61 }
62}
63
64#[derive(Clone, Debug)]
67pub struct Rotation {
68 pub loadings: Array2<f64>,
71 pub rotation: Array2<f64>,
73}
74
75pub fn rotate_factors(loadings: &Array2<f64>, method: &str) -> Result<Rotation> {
82 rotate_with(loadings, RotationMethod::from_name(method)?)
83}
84
85pub fn rotate_with(loadings: &Array2<f64>, method: RotationMethod) -> Result<Rotation> {
87 match method {
88 RotationMethod::Promax => promax(loadings, 2.0),
89 RotationMethod::Varimax => gpa(loadings, 1.0, true),
90 RotationMethod::Quartimax => gpa(loadings, 0.0, true),
91 RotationMethod::Oblimin | RotationMethod::Quartimin => gpa(loadings, 0.0, false),
93 }
94}
95
96fn rotate_a(a: &Array2<f64>, t: &Array2<f64>, orthogonal: bool) -> Result<Array2<f64>> {
98 if orthogonal {
99 Ok(a.dot(t))
100 } else {
101 let ti = inv(t)?;
103 Ok(a.dot(&ti.t()))
104 }
105}
106
107fn objective(l: &Array2<f64>, gamma: f64, orthogonal: bool) -> (f64, Array2<f64>) {
112 let (p, k) = l.dim();
113 let l2 = l.mapv(|x| x * x);
115
116 if orthogonal {
117 let x = if gamma == 0.0 {
119 l2.clone()
120 } else {
121 let mut col_sums = Array1::<f64>::zeros(k);
124 for j in 0..k {
125 col_sums[j] = l2.column(j).sum();
126 }
127 let mut x = l2.clone();
128 for i in 0..p {
129 for j in 0..k {
130 x[[i, j]] -= (gamma / p as f64) * col_sums[j];
131 }
132 }
133 x
134 };
135 let phi = -elem_dot(&l2, &x) / 4.0;
136 let gphi = -hadamard(l, &x);
137 (phi, gphi)
138 } else {
139 let m = if gamma == 0.0 {
142 l2.clone()
143 } else {
144 let mut col_sums = Array1::<f64>::zeros(k);
145 for j in 0..k {
146 col_sums[j] = l2.column(j).sum();
147 }
148 let mut m = l2.clone();
149 for i in 0..p {
150 for j in 0..k {
151 m[[i, j]] -= (gamma / p as f64) * col_sums[j];
152 }
153 }
154 m
155 };
156 let mut x = Array2::<f64>::zeros((p, k));
159 for i in 0..p {
160 let row_sum: f64 = (0..k).map(|j| m[[i, j]]).sum();
161 for c in 0..k {
162 x[[i, c]] = row_sum - m[[i, c]];
163 }
164 }
165 let phi = elem_dot(&l2, &x) / 4.0;
166 let gphi = hadamard(l, &x);
167 (phi, gphi)
168 }
169}
170
171fn hadamard(a: &Array2<f64>, b: &Array2<f64>) -> Array2<f64> {
173 let mut out = a.clone();
174 out.zip_mut_with(b, |x, &y| *x *= y);
175 out
176}
177
178fn elem_dot(a: &Array2<f64>, b: &Array2<f64>) -> f64 {
180 a.iter().zip(b.iter()).map(|(&x, &y)| x * y).sum()
181}
182
183fn fro_norm(a: &Array2<f64>) -> f64 {
185 a.iter().map(|&x| x * x).sum::<f64>().sqrt()
186}
187
188fn gpa(a: &Array2<f64>, gamma: f64, orthogonal: bool) -> Result<Rotation> {
194 let max_tries = 501usize;
195 let tol = 1e-5;
196 let k = a.ncols();
197
198 let mut t = Array2::<f64>::eye(k);
199 let mut al = 1.0_f64;
200
201 let (mut f, mut g) = compute_fg(a, &t, gamma, orthogonal)?;
203
204 for _ in 0..max_tries {
205 let gp = if orthogonal {
207 let m = t.t().dot(&g);
209 let s = (&m + &m.t()).mapv(|x| x / 2.0);
210 &g - &t.dot(&s)
211 } else {
212 let tg = hadamard(&t, &g);
214 let mut gp = g.clone();
215 for j in 0..k {
216 let col_sum: f64 = tg.column(j).sum();
217 for i in 0..k {
218 gp[[i, j]] -= t[[i, j]] * col_sum;
219 }
220 }
221 gp
222 };
223
224 let s = fro_norm(&gp);
225 if s < tol {
226 break;
227 }
228
229 al *= 2.0;
233 let mut tt = t.clone();
234 let mut ft = f;
235 let mut g_next = g.clone();
236 for _ in 0..11 {
237 let x = &t - &gp.mapv(|v| v * al);
238 tt = if orthogonal {
239 let (u, _s, vt) = svd(&x)?;
241 u.dot(&vt)
242 } else {
243 let mut tt = x.clone();
245 for j in 0..k {
246 let nrm: f64 = (0..k).map(|i| x[[i, j]] * x[[i, j]]).sum::<f64>().sqrt();
247 let v = 1.0 / nrm;
248 for i in 0..k {
249 tt[[i, j]] = x[[i, j]] * v;
250 }
251 }
252 tt
253 };
254
255 let (fnew, gnew) = compute_fg(a, &tt, gamma, orthogonal)?;
256 ft = fnew;
257 g_next = gnew;
258 if ft < f - 0.5 * s * s * al {
259 break;
260 }
261 al /= 2.0;
262 }
263
264 t = tt;
265 f = ft;
266 g = g_next;
267 }
268
269 let loadings = rotate_a(a, &t, orthogonal)?;
270 Ok(Rotation {
271 loadings,
272 rotation: t,
273 })
274}
275
276fn compute_fg(
278 a: &Array2<f64>,
279 t: &Array2<f64>,
280 gamma: f64,
281 orthogonal: bool,
282) -> Result<(f64, Array2<f64>)> {
283 if orthogonal {
284 let l = a.dot(t);
285 let (f, gq) = objective(&l, gamma, true);
286 let g = a.t().dot(&gq);
287 Ok((f, g))
288 } else {
289 let ti = inv(t)?;
290 let l = a.dot(&ti.t());
291 let (f, gq) = objective(&l, gamma, false);
292 let inner = l.t().dot(&gq).dot(&ti);
294 let g = inner.t().mapv(|x| -x);
295 Ok((f, g))
296 }
297}
298
299fn promax(a: &Array2<f64>, power: f64) -> Result<Rotation> {
308 let v = gpa(a, 1.0, true)?.loadings;
310
311 let h = v.mapv(|x| {
314 if x == 0.0 {
315 0.0
316 } else {
317 x.abs().powf(power) / x
318 }
319 });
320
321 let ata = a.t().dot(a);
323 let ata_inv = inv(&ata)?;
324 let s = ata_inv.dot(&a.t()).dot(&h);
325
326 let sts = s.t().dot(&s);
328 let sts_inv = inv(&sts)?;
329 let k = s.ncols();
330 let mut d = Array1::<f64>::zeros(k);
331 for j in 0..k {
332 d[j] = sts_inv[[j, j]].sqrt();
333 }
334 let mut sd = s.clone();
336 for j in 0..k {
337 for i in 0..sd.nrows() {
338 sd[[i, j]] *= d[j];
339 }
340 }
341 let sd_inv = inv(&sd)?;
342 let t = sd_inv.t().to_owned();
343
344 let loadings = a.dot(&t);
346 Ok(Rotation {
347 loadings,
348 rotation: t,
349 })
350}
351
352#[cfg(test)]
353mod tests {
354 use super::*;
355 use ndarray::array;
356
357 fn sample() -> Array2<f64> {
358 array![[0.8, 0.1], [0.7, 0.2], [0.2, 0.9], [0.1, 0.8], [0.5, 0.5],]
359 }
360
361 #[test]
362 fn varimax_is_orthogonal_and_consistent() {
363 let a = sample();
364 let r = rotate_factors(&a, "varimax").unwrap();
365 let tt = r.rotation.t().dot(&r.rotation);
367 for i in 0..2 {
368 for j in 0..2 {
369 let want = if i == j { 1.0 } else { 0.0 };
370 assert!((tt[[i, j]] - want).abs() < 1e-9, "TᵀT not identity");
371 }
372 }
373 let l = a.dot(&r.rotation);
375 for i in 0..a.nrows() {
376 for j in 0..2 {
377 assert!((l[[i, j]] - r.loadings[[i, j]]).abs() < 1e-12);
378 }
379 }
380 }
381
382 #[test]
383 fn quartimax_runs() {
384 let a = sample();
385 let r = rotate_factors(&a, "quartimax").unwrap();
386 let l = a.dot(&r.rotation);
387 for i in 0..a.nrows() {
388 for j in 0..2 {
389 assert!((l[[i, j]] - r.loadings[[i, j]]).abs() < 1e-12);
390 }
391 }
392 }
393
394 #[test]
395 fn quartimin_is_oblique_consistent() {
396 let a = sample();
397 let r = rotate_factors(&a, "quartimin").unwrap();
398 let l = rotate_a(&a, &r.rotation, false).unwrap();
400 for i in 0..a.nrows() {
401 for j in 0..2 {
402 assert!((l[[i, j]] - r.loadings[[i, j]]).abs() < 1e-12);
403 }
404 }
405 for j in 0..2 {
407 let nrm: f64 = (0..2)
408 .map(|i| r.rotation[[i, j]].powi(2))
409 .sum::<f64>()
410 .sqrt();
411 assert!((nrm - 1.0).abs() < 1e-9);
412 }
413 }
414
415 #[test]
416 fn oblimin_defaults_to_quartimin() {
417 let a = sample();
418 let r1 = rotate_factors(&a, "oblimin").unwrap();
419 let r2 = rotate_factors(&a, "quartimin").unwrap();
420 for i in 0..a.nrows() {
421 for j in 0..2 {
422 assert!((r1.loadings[[i, j]] - r2.loadings[[i, j]]).abs() < 1e-12);
423 }
424 }
425 }
426
427 #[test]
428 fn promax_consistent() {
429 let a = sample();
430 let r = rotate_factors(&a, "promax").unwrap();
431 let l = a.dot(&r.rotation);
433 for i in 0..a.nrows() {
434 for j in 0..2 {
435 assert!((l[[i, j]] - r.loadings[[i, j]]).abs() < 1e-12);
436 }
437 }
438 }
439
440 #[test]
441 fn unknown_method_errs() {
442 let a = sample();
443 assert!(rotate_factors(&a, "nonsense").is_err());
444 }
445}