\encoding{UTF-8}
\name{00.GPArotation}
\alias{GPArotation}
\alias{GPArotation-package}
\alias{GPArotation.Intro}
\docType{package}
\title{Gradient Projection Algorithms for Factor Rotation}
\description{GPA Rotation for Factor Analysis

The GPArotation package contains functions for the rotation of factor loadings
matrices. The functions implement Gradient Projection (GP) algorithms for orthogonal
and oblique rotation. Additionally, a number of rotation criteria are provided.
The GP algorithms minimize the rotation criterion function and provide the
corresponding rotation matrix. For oblique rotation, the covariance/correlation matrix
of the factors is also provided. The rotation criteria implemented in this package
are described in Bernaards and Jennrich (2005) in addition to a number of others. 
Theory of the GP algorithm is described in Jennrich (2001, 2002).

Vignettes are provided covering general usage, local minima
diagnostics, bifactor rotation and reliability, and a visual walkthrough
of the gradient projection algorithm.
Access them via \code{browseVignettes("GPArotation")}.

\tabular{ll}{
Package: \tab GPArotation\cr
Depends: \tab R (>= 3.5.0)\cr
License: \tab GPL Version 2.\cr
}

Index of functions:

Rotations using gradient projection algorithms\cr
\tabular{ll}{
\code{\link{oblimin}}    \tab Oblimin rotation \cr
\code{\link{quartimin}}  \tab Quartimin rotation \cr
\code{\link{targetT}}    \tab Orthogonal target rotation \cr
\code{\link{targetQ}}    \tab Oblique target rotation \cr
\code{\link{pstT}}       \tab Orthogonal partially specified target rotation \cr
\code{\link{pstQ}}       \tab Oblique partially specified target rotation \cr
\code{\link{oblimax}}    \tab Oblimax rotation \cr
\code{\link{entropy}}    \tab Minimum entropy rotation \cr
\code{\link{quartimax}}  \tab Quartimax rotation \cr
\code{\link{Varimax}}    \tab Varimax rotation \cr
\code{\link{simplimax}}  \tab Simplimax rotation \cr
\code{\link{bentlerT}}   \tab Orthogonal Bentler invariant pattern simplicity rotation \cr
\code{\link{bentlerQ}}   \tab Oblique Bentler invariant pattern simplicity rotation \cr
\code{\link{tandemI}}    \tab Tandem criteria principle I rotation \cr
\code{\link{tandemII}}   \tab Tandem criteria principle II rotation \cr
\code{\link{geominT}}    \tab Orthogonal Geomin rotation \cr
\code{\link{geominQ}}    \tab Oblique Geomin rotation \cr
\code{\link{bigeominT}}  \tab Orthogonal Bi-Geomin rotation \cr
\code{\link{bigeominQ}}  \tab Oblique Bi-Geomin rotation \cr
\code{\link{cfT}}        \tab Orthogonal Crawford-Ferguson family rotation \cr
\code{\link{cfQ}}        \tab Oblique Crawford-Ferguson family rotation \cr
\code{\link{equamax}}    \tab Equamax rotation \cr
\code{\link{parsimax}}   \tab Parsimax rotation \cr
\code{\link{infomaxT}}   \tab Orthogonal Infomax rotation \cr
\code{\link{infomaxQ}}   \tab Oblique Infomax rotation \cr
\code{\link{mccammon}}   \tab McCammon minimum entropy ratio rotation \cr
\code{\link{varimin}}    \tab Varimin rotation \cr
\code{\link{bifactorT}}  \tab Orthogonal bifactor rotation \cr
\code{\link{bifactorQ}}  \tab Oblique bifactor rotation \cr
\code{\link{lpT}}        \tab Orthogonal \eqn{L^p}{Lp} rotation \cr
\code{\link{lpQ}}        \tab Oblique \eqn{L^p}{Lp} rotation \cr
}

Core gradient projection algorithms\cr
\tabular{ll}{
\code{\link{GPForth}} \tab Orthogonal rotation function \cr
\code{\link{GPFoblq}} \tab Oblique rotation function \cr
}

Random-start wrappers and internal engine\cr
\tabular{ll}{
\code{\link{GPFRSorth}}  \tab Random-start wrapper for orthogonal rotation \cr
\code{\link{GPFRSoblq}}  \tab Random-start wrapper for oblique rotation \cr
}

2D orthogonal trajectory plot \cr
\tabular{ll}{
\code{\link{plot2fOrthComparison}}		\tab 2D trajectory plot for 2 factor orthogonal rotation\cr
}

S3 methods\cr
\tabular{ll}{
\code{\link{print.GPArotation}}     \tab Print rotated solution with simple structure measures \cr
\code{\link{summary.GPArotation}}   \tab Summary with pattern, structure, and diagnostics \cr
\code{\link{plot.GPArotation}}      \tab Plot: salient, pairs, profile, vector, target,
                                         heatmap, trajectory, diagnostics, residuals \cr
\code{residuals.GPArotation}        \tab Observed minus modeled residual of correlation matrix \cr
\code{\link[stats]{update}} 		\tab update [The R Stats Package] \cr
}

Data sets\cr
\tabular{ll}{
\code{\link{Harman8}}       \tab Harman's 8 physical variables; centroid loadings \cr
\code{\link{NetherlandsTV}} \tab Wansbeek and Meijer Netherlands TV viewership; correlation matrix \cr
\code{\link{box26}}         \tab Thurstone's 26 box variables; unrotated factor loadings \cr
\code{\link{CCAI}}          \tab CCAI Climate-Friendly Purchasing Choices domain;
                                 correlation matrix, pattern matrix, and factor intercorrelations \cr
\code{\link{GriffithMulaik}} \tab Griffith and Mulaik interpersonal personality
                                   traits; 24-variable correlation matrix \cr
}

Other rotations not using gradient projection algorithms\cr
\tabular{ll}{
\code{\link{eiv}}              \tab Errors-in-variables rotation \cr
\code{\link{echelon}}          \tab Echelon rotation \cr
\code{\link[stats]{varimax}}   \tab varimax [The R Stats Package] \cr
\code{\link[stats]{promax}}    \tab promax [The R Stats Package] \cr
}

Legacy gradient projection algorithms (code unchanged since 2008)\cr
\tabular{ll}{
\code{GPForth.legacy} \tab Orthogonal rotation, original implementation (not exported) \cr
\code{GPFoblq.legacy} \tab Oblique rotation, original implementation (not exported) \cr
}

Utility functions\cr
\tabular{ll}{
\code{\link{Random.Start}}        \tab Random starting matrix for factor rotation \cr
\code{\link{GPForth.lp}}          \tab Single-start \eqn{L^p}{Lp} orthogonal rotation \cr
\code{\link{GPFoblq.lp}}          \tab Single-start \eqn{L^p}{Lp} oblique rotation \cr
}

Utility functions (not exported)\cr
\tabular{ll}{
\code{.GPA_RS_engine}    		  \tab Internal random-start engine  \cr
\code{.sortGPALoadings}           \tab Sort and sign-correct factors  \cr
\code{\link{NormalizingWeight}}   \tab Normalizing weights utility \cr
\code{\link{calc_AUC}}            \tab AUC simple structure measure  \cr
\code{\link{calc_FSI}}            \tab Factor Simplicity Index  \cr
\code{\link{calc_simplicity}}     \tab Hoffman, Gini, Bentler simplicity indices  \cr
\code{\link{calc_hyperplane}}     \tab Hyperplane count  \cr
\code{\link{calc_fitstats}}		  \tab ML fit statistics: RMSEA, SRMR  \cr
\code{plot_trajectory}			  \tab Helper function for plot2fOrthComparison  \cr
\code{plot_gpa_diagnostics}	      \tab Helper function for plot2fOrthComparison  \cr
\code{plot_algorithm_comparison}  \tab Helper function for plot2fOrthComparison  \cr
\code{.reconstruct_trajectory}    \tab Helper function for plot2fOrthComparison  \cr
\code{plotRotationLandscape}      \tab Helper function for plot2fOrthComparison  \cr
\code{plot_landscape_trajectory}  \tab Helper function for plot2fOrthComparison  \cr
}

Value, gradient, rotation criterion functions (not exported)\cr
\tabular{ll}{
\code{\link{vgQ.oblimin}}   \tab Oblimin \cr
\code{\link{vgQ.quartimin}} \tab Quartimin \cr
\code{\link{vgQ.target}}    \tab Target \cr
\code{\link{vgQ.pst}}       \tab Partially specified target \cr
\code{\link{vgQ.oblimax}}   \tab Oblimax \cr
\code{\link{vgQ.entropy}}   \tab Minimum entropy \cr
\code{\link{vgQ.quartimax}} \tab Quartimax \cr
\code{\link{vgQ.varimax}}   \tab Varimax \cr
\code{\link{vgQ.simplimax}} \tab Simplimax \cr
\code{\link{vgQ.bentler}}   \tab Bentler invariant pattern simplicity \cr
\code{\link{vgQ.tandemI}}   \tab Tandem criteria principle I \cr
\code{\link{vgQ.tandemII}}  \tab Tandem criteria principle II \cr
\code{\link{vgQ.geomin}}    \tab Geomin \cr
\code{\link{vgQ.bigeomin}}  \tab Bi-Geomin \cr
\code{\link{vgQ.cf}}        \tab Crawford-Ferguson family \cr
\code{\link{vgQ.infomax}}   \tab Infomax \cr
\code{\link{vgQ.mccammon}}  \tab McCammon minimum entropy ratio \cr
\code{\link{vgQ.varimin}}   \tab Varimin \cr
\code{\link{vgQ.bifactor}}  \tab Bifactor \cr
\code{\link{vgQ.lp.wls}}    \tab Weighted least squares for \eqn{L^p}{Lp} rotation \cr
}

Vignettes\cr
\tabular{ll}{
\code{GPA1guide}    \tab Gradient Projection Factor Rotation (main guide) \cr
\code{GPA2local}    \tab Assessing Local Minima in Factor Rotation \cr
\code{GPA3bifactor} \tab Bifactor Rotation and Reliability Coefficients \cr
\code{GPA4fitstats} \tab Factor Model Fit and Simple Structure Diagnostics \cr
}

}

\author{Coen A. Bernaards and Robert I. Jennrich
        with some R modifications by Paul Gilbert.
}

\references{
   The software reference is:

   Bernaards, C.A. and Jennrich, R.I. (2005). Gradient projection algorithms
     and software for arbitrary rotation criteria in factor analysis.
     \emph{Educational and Psychological Measurement}, \bold{65}, 676--696.
     \doi{10.1177/0013164404272507}

   Theory of gradient projection algorithms:

   Jennrich, R.I. (2001). A simple general procedure for orthogonal rotation.
     \emph{Psychometrika}, \bold{66}, 289--306.
     \doi{10.1007/BF02294840}

   Jennrich, R.I. (2002). A simple general method for oblique rotation.
     \emph{Psychometrika}, \bold{67}, 7--19.
     \doi{10.1007/BF02294706}

   A clear and accessible introduction to gradient projection algorithms
   for factor rotation is provided in:

   Mansolf, M. and Reise, S.P. (2016). Exploratory bifactor analysis:
     The Schmid-Leiman orthogonalization and Jennrich-Bentler analytic
     rotations. \emph{Multivariate Behavioral Research}, \bold{51}(5),
     698--717.
     \doi{10.1080/00273171.2016.1215898}

   Barzilai-Borwein step size:

   Barzilai, J. and Borwein, J.M. (1988). Two-point step size gradient
     methods. \emph{IMA Journal of Numerical Analysis}, \bold{8}, 141--148.
     \doi{10.1093/imanum/8.1.141}

   Cayley transform retraction:

   Wen, Z. and Yin, W. (2013). A feasible method for optimization with
     orthogonality constraints. \emph{Mathematical Programming},
     \bold{142}, 397--434.
     \doi{10.1007/s10107-012-0584-1}

   Non-monotone line search:

   Grippo, L., Lampariello, F., and Lucidi, S. (1986).  A nonmonotone 
     line search technique for Newton's method. 
     \emph{SIAM Journal on Numerical Analysis}, \bold{23}(4), 707--716.
     \doi{10.1137/0723046}

   Zhang, H. and Hager, W.W. (2004). A nonmonotone line search technique
     and its application to unconstrained optimization.
     \emph{SIAM Journal on Optimization}, \bold{14}(4), 1043--1056.
     \doi{10.1137/S1052623403428208}

   Simple structure measures:

  Liu, X., Wallin, G., Chen, Y., and Moustaki, I. (2023). Rotation to
    sparse loadings using \eqn{L^p}{Lp} losses and related inference
    problems. \emph{Psychometrika}, \bold{88}(2), 527--553.
    \doi{10.1007/s11336-023-09911-y}

   Lorenzo-Seva, U. (2003). A factor simplicity index.
     \emph{Psychometrika}, \bold{68}(1), 49--60.
     \doi{10.1007/BF02296652}

}

\keyword{package}

\seealso{
   \code{\link{GPFRSorth}},
   \code{\link{GPFRSoblq}},
   \code{\link{rotations}},
   \code{\link{vgQ}},
   \code{\link{simple_structure}},
   \code{\link{plot.GPArotation}}
   \code{browseVignettes("GPArotation")}
}