Skip to main content

solow_multivariate/
rotation.rs

1//! Factor rotation by the gradient-projection algorithm (GPA).
2//!
3//! This is a port of the reference's `multivariate.factor_rotation`
4//! ([`rotate_factors`]) gradient-projection rotation of Bernaards & Jennrich
5//! (2005). Given an unrotated `p × k` loading matrix `A`, a rotation
6//! transforms it to a "simpler" loading matrix `L` together with a rotation
7//! matrix `T`.
8//!
9//! * For **orthogonal** rotations (`varimax`, `quartimax`) `T` is orthogonal
10//!   and `L = A T`.
11//! * For **oblique** rotations (`oblimin`, `quartimin`) `T` is a normal matrix
12//!   with unit-norm columns and `L = A (T^{-1})^\top`.
13//! * **promax** is an analytic oblique method: it first computes a varimax
14//!   solution, builds a power target, solves a Procrustes problem and
15//!   normalises; here `L = A T` with a non-orthogonal `T`.
16//!
17//! The orthogonal and oblique families minimise the *oblimin / orthomax*
18//! objective
19//!
20//! ```text
21//! phi(L) = (1/4) <L∘L, (I - gamma C)(L∘L) N>,
22//! ```
23//!
24//! where `N = ones(k,k) - I`, `C = ones(p,p)/p`, `∘` is the elementwise
25//! (Hadamard) product and `<X,Y> = tr(Xᵀ Y)`. For orthogonal rotations the
26//! orthomax form `phi(L) = -(1/4)<L∘L,(I - gamma C)(L∘L)>` is used, which is
27//! equivalent on the orthogonal manifold. With `gamma = 1` this is varimax and
28//! with `gamma = 0` quartimax (orthogonal) or quartimin (oblique).
29
30use ndarray::{Array1, Array2};
31use solow_core::error::{Error, Result};
32use solow_linalg::{inv, svd};
33
34/// The rotation method requested by [`rotate_factors`].
35#[derive(Clone, Copy, Debug, PartialEq, Eq)]
36pub enum RotationMethod {
37    /// Orthogonal varimax (orthomax with `gamma = 1`).
38    Varimax,
39    /// Orthogonal quartimax (orthomax with `gamma = 0`).
40    Quartimax,
41    /// Oblique oblimin with the default parameter `gamma = 0`
42    /// (equivalent to [`RotationMethod::Quartimin`]).
43    Oblimin,
44    /// Oblique quartimin (oblimin with `gamma = 0`).
45    Quartimin,
46    /// Analytic oblique promax with the default power `k = 4`.
47    Promax,
48}
49
50impl RotationMethod {
51    /// Parse the reference's string method names (case-insensitive).
52    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/// The result of a factor rotation: the rotated loadings `L` and the rotation
65/// matrix `T`.
66#[derive(Clone, Debug)]
67pub struct Rotation {
68    /// Rotated loadings, `p × k`. For orthogonal rotations and promax
69    /// `L = A T`; for oblique rotations `L = A (T^{-1})^\top`.
70    pub loadings: Array2<f64>,
71    /// Rotation matrix, `k × k`.
72    pub rotation: Array2<f64>,
73}
74
75/// Rotate the `p × k` loading matrix `loadings` with the named `method`.
76///
77/// Supported names (case-insensitive): `"varimax"`, `"quartimax"` (orthogonal),
78/// `"oblimin"`, `"quartimin"` (oblique) and `"promax"`. Mirrors the reference
79/// defaults: gradient-projection with `max_tries = 501`, `tol = 1e-5`, oblimin
80/// `gamma = 0`, and promax power `k = 2`.
81pub fn rotate_factors(loadings: &Array2<f64>, method: &str) -> Result<Rotation> {
82    rotate_with(loadings, RotationMethod::from_name(method)?)
83}
84
85/// Rotate using a parsed [`RotationMethod`].
86pub 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        // oblimin defaults to gamma = 0, which equals quartimin.
92        RotationMethod::Oblimin | RotationMethod::Quartimin => gpa(loadings, 0.0, false),
93    }
94}
95
96/// Rotate `A` to `L = A T` (orthogonal) or `L = A (T^{-1})^\top` (oblique).
97fn rotate_a(a: &Array2<f64>, t: &Array2<f64>, orthogonal: bool) -> Result<Array2<f64>> {
98    if orthogonal {
99        Ok(a.dot(t))
100    } else {
101        // L = A (T^{-1})^T.
102        let ti = inv(t)?;
103        Ok(a.dot(&ti.t()))
104    }
105}
106
107/// Oblimin / orthomax objective value and gradient `Gphi` with respect to `L`.
108///
109/// `orthogonal` selects the orthomax form (used on the orthogonal manifold);
110/// otherwise the oblimin form is used. Returns `(phi, Gphi)`.
111fn objective(l: &Array2<f64>, gamma: f64, orthogonal: bool) -> (f64, Array2<f64>) {
112    let (p, k) = l.dim();
113    // L2 = L ∘ L.
114    let l2 = l.mapv(|x| x * x);
115
116    if orthogonal {
117        // orthomax: X = (I - gamma C) L2 ; phi = -<L2, X>/4 ; Gphi = -L ∘ X.
118        let x = if gamma == 0.0 {
119            l2.clone()
120        } else {
121            // (I - gamma C) L2 = L2 - (gamma/p) * ones(p,p) @ L2.
122            // ones(p,p) @ L2 has every row equal to the column sums of L2.
123            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        // oblimin: X = (I - gamma C) L2 N ; phi = <L2, X>/4 ; Gphi = L ∘ X.
140        // First (I - gamma C) L2:
141        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        // Then multiply on the right by N = ones(k,k) - I:
157        // (M N)[i,c] = sum_{j != c} M[i,j] = rowsum(M)[i] - M[i,c].
158        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
171/// Elementwise (Hadamard) product `A ∘ B`.
172fn 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
178/// Frobenius inner product `sum_{ij} A_{ij} B_{ij}`.
179fn elem_dot(a: &Array2<f64>, b: &Array2<f64>) -> f64 {
180    a.iter().zip(b.iter()).map(|(&x, &y)| x * y).sum()
181}
182
183/// Frobenius norm of a matrix.
184fn fro_norm(a: &Array2<f64>) -> f64 {
185    a.iter().map(|&x| x * x).sum::<f64>().sqrt()
186}
187
188/// The gradient-projection algorithm (GPA) for the oblimin/orthomax family.
189///
190/// `gamma` is the oblimin parameter and `orthogonal` selects the rotation
191/// manifold. Mirrors the reference `GPA` with `max_tries = 501`, `tol = 1e-5`
192/// and the identity initial guess.
193fn 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    // Initialise f and G.
202    let (mut f, mut g) = compute_fg(a, &t, gamma, orthogonal)?;
203
204    for _ in 0..max_tries {
205        // Project the gradient onto the tangent space.
206        let gp = if orthogonal {
207            // M = Tᵀ G ; S = (M + Mᵀ)/2 ; Gp = G - T S.
208            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            // Gp = G - T diag(sum(T ∘ G, axis=0)).
213            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        // Line search. The reference always adopts the last `Tt` evaluated in
230        // the inner loop (whether or not it broke on sufficient decrease), so
231        // we carry the latest candidate out of the loop.
232        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                // Tt = U Vᵀ from the thin SVD of X.
240                let (u, _s, vt) = svd(&x)?;
241                u.dot(&vt)
242            } else {
243                // Tt = X diag(1/sqrt(colsumsq(X))).
244                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
276/// Compute the objective value `f` and the manifold gradient `G` at `T`.
277fn 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        // G = -((Lᵀ Gq Ti)ᵀ).
293        let inner = l.t().dot(&gq).dot(&ti);
294        let g = inner.t().mapv(|x| -x);
295        Ok((f, g))
296    }
297}
298
299/// Analytic promax rotation with power `power` (the reference default is 2).
300///
301/// Steps mirror the reference `promax`:
302/// 1. varimax-rotate `A` to `V`;
303/// 2. build the target `H = |V|^power / V`;
304/// 3. solve the Procrustes problem `S = (Aᵀ A)^{-1} Aᵀ H`;
305/// 4. normalise: `d = sqrt(diag((Sᵀ S)^{-1}))`, `T = (S diag(d))^{-1}ᵀ`;
306/// 5. return `(A T, T)`.
307fn promax(a: &Array2<f64>, power: f64) -> Result<Rotation> {
308    // 1. varimax target.
309    let v = gpa(a, 1.0, true)?.loadings;
310
311    // 2. H = |V|^power / V (elementwise). Where V == 0 the reference yields a
312    // NaN/inf; in practice varimax loadings are non-zero. Guard against zeros.
313    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    // 3. Procrustes: S = inv(Aᵀ A) Aᵀ H.
322    let ata = a.t().dot(a);
323    let ata_inv = inv(&ata)?;
324    let s = ata_inv.dot(&a.t()).dot(&h);
325
326    // 4. d = sqrt(diag(inv(Sᵀ S))) ; D = diag(d) ; T = inv(S D)ᵀ.
327    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    // S D scales column j of S by d[j].
335    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    // 5. L = A T.
345    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        // T orthogonal: TᵀT = I.
366        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        // L = A T.
374        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        // L = A inv(T)ᵀ.
399        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        // Oblique T has unit-norm columns.
406        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        // promax returns L = A T.
432        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}