Add orthomax factor rotations

docs/make.jl

@@ -5,20 +5,21 @@ if Base.HOME_PROJECT[] !== nothing
 end
 
 makedocs(
-    sitename = "MultivariateStats.jl",
-    modules = [MultivariateStats],
-    pages = ["Home"=>"index.md",
-             "whiten.md",
-             "lreg.md",
-             "lda.md",
-             "pca.md",
-             "ica.md",
-             "cca.md",
-             "fa.md",
-             "mds.md",
-             "Development"=>"api.md"]
+    sitename="MultivariateStats.jl",
+    modules=[MultivariateStats],
+    pages=["Home" => "index.md",
+        "whiten.md",
+        "lreg.md",
+        "lda.md",
+        "pca.md",
+        "ica.md",
+        "cca.md",
+        "fa.md",
+        "facrot.md",
+        "mds.md",
+        "Development" => "api.md"]
 )
 
 deploydocs(
-    repo = "github.com/JuliaStats/MultivariateStats.jl.git"
+    repo="github.com/JuliaStats/MultivariateStats.jl.git"
 )

docs/src/facrot.md

@@ -0,0 +1,85 @@
+# Factor Rotation
+
+[Factor rotations](https://en.wikipedia.org/wiki/Factor_analysis#Rotation_methods)
+are used for post-processing of a factor matrix obtained by
+[`FactorAnalysis`](@ref) or [`PCA`](@ref).
+
+Let ``L`` be a matrix of factor loadings. Two common methods of factor rotation[^1]
+are typically considered:
+- A matrix ``\Lambda`` is an *orthogonal rotation*[^2] of ``L`` if
+  ``\Lambda = L R`` for some orthogonal matrix ``R``, i.e. ``R^{-1} = R^\top``.
+- A matrix ``\Lambda`` is an *oblique rotation*[^3] of ``L`` if
+  ``\Lambda = L (R')^{-1}`` for some matrix ``R`` that has columns of length 1.
+
+The matrix ``R`` is chosen by minimizing a factor rotation criterion
+``Q(\Lambda)``. This package uses a gradient projection algorithm[^1]
+to minimize the criterion ``Q``. 
+
+## Applying factor rotations
+
+This package defines the function [`rotate`](@ref) which can be used to rotate
+a matrix of loadings.
+
+```@docs
+rotate(::AbstractMatrix, ::FactorRotationCriterion{T}) where {T<:FactorRotationMethod}
+FactorRotation
+loadings
+rotation
+```
+
+[`rotate!`](@ref) modifies the supplied model in place.
+
+```@docs
+rotate!(::FactorAnalysis, ::FactorRotationCriterion{T}) where {T<:FactorRotationMethod}
+rotate!(::PCA, ::FactorRotationCriterion{T}) where {T<:FactorRotationMethod}
+```
+
+## Factor rotation methods
+
+There are two types of factor rotations: *orthogonal* and *oblique*.
+Which type of rotation method should be used can be chosen by setting the
+appropriate subtype of [`FactorRotationMethod`](@ref).
+
+```@docs
+FactorRotationMethod
+Orthogonal
+Oblique
+```
+
+## Factor rotation criteria
+
+The actual factor rotation criteria are described by subtypes of
+[`FactorRotationCriterion`](@ref) and many parametrized forms of standard
+rotation methods are provided.
+
+```@docs
+FactorRotationCriterion{T} where {T<:FactorRotationMethod}
+```
+
+Sometimes, factor rotation criteria can be used as orthogonal and oblique methods.
+
+```@docs
+CrawfordFerguson{T} where {T<:FactorRotationMethod}
+Oblimin{T} where {T<:FactorRotationMethod}
+```
+
+### Orthogonal factor rotation criteria
+
+```@docs
+Varimax
+Quartimax
+MinimumEntropy
+```
+
+### Oblique factor rotation criteria
+
+```@docs
+Quartimin
+```
+
+## References
+
+[^1] Bernaards, C.A. and Jennrich, R.I. (2005) Gradient Projection Algorithms and Software for Arbitrary Rotation Criteria in Factor Analysis. Educational and Psychological Measurement, 65, 676-696. doi [10.1177/0013164404272507](https://doi.org/10.1177/0013164404272507)
+[^2] Jennrich, R. I. (2001). A simple general procedure for orthogonal rotation. Psychometrika, 66, 289-306. doi [10.1007/BF02294840](https://doi.org/10.1007/BF02294840)
+[^3] Jennrich, R. I. (2002). A simple general method for oblique rotation. Psychometrika, 67, 7-19. doi [10.1007/BF02294706](https://doi.org/10.1007/BF02294706)
+

docs/src/index.md

@@ -11,7 +11,7 @@ end
 [MultivariateStats.jl](https://github.com/JuliaStats/MultivariateStats.jl) is a Julia package for multivariate statistical analysis. It provides a rich set of useful analysis techniques, such as PCA, CCA, LDA, ICA, etc.
 
 ```@contents
-Pages = ["whiten.md", "lreg.md", "lda.md", "pca.md", "ica.md", "cca.md", "fa.md", "mds.md", "api.md"]
+Pages = ["whiten.md", "lreg.md", "lda.md", "pca.md", "ica.md", "cca.md", "fa.md", "facrot.md", "mds.md", "api.md"]
 Depth = 2
 ```
 

src/MultivariateStats.jl

@@ -11,6 +11,10 @@ module MultivariateStats
     import Base: length, size, show
     import StatsAPI: fit, predict, coef, weights, dof, r2
     import LinearAlgebra: eigvals, eigvecs
+
+    @static if VERSION ≥ v"1.5"
+        import LinearAlgebra: rotate!
+    end
 
     export
 
@@ -105,7 +109,26 @@ module MultivariateStats
     FactorAnalysis,         # Type: the Factor Analysis model
 
     faem,                   # EM algorithm for factor analysis
-    facm                    # CM algorithm for factor analysis
+    facm,                   # CM algorithm for factor analysis
+
+    ## facrot
+    FactorRotationMethod,    # Type: a factor rotation method
+    Orthogonal,              # Type: Orthogonal factor rotation method
+    Oblique,                 # Type: Oblique factor rotation method
+
+    FactorRotationCriterion, # Type: a factor rotation criterion
+    CrawfordFerguson,        # Type: Crawford-Fergusion rotation criteria
+    Varimax,                 # Type: Varimax rotation criterion
+    Quartimax,               # Type: Quartimax rotation criterion
+    MinimumEntropy,          # Type: MinimumEntropy rotation criterion
+    Oblimin,                 # Type: Oblimin rotation criteria
+    Quartimin,               # Type: Quartimin rotation criterion
+
+    FactorRotation,          # Type: Result of a general factor rotation
+    rotation,                # Extract rotation matrix
+
+    rotate,                  # Rotate factors
+    rotate!                  # Rotate in-place
 
     ## source files
     include("types.jl")
@@ -121,6 +144,7 @@ module MultivariateStats
     include("lda.jl")
     include("ica.jl")
     include("fa.jl")
+    include("facrot.jl")
 
     ## deprecations
     @deprecate indim(f) size(f,1)