% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa_map.R
\name{efa_map}
\alias{efa_map}
\title{Velicer's minimum average partial (MAP) criterion}
\source{
Auerswald, M., & Moshagen, M. (2019). How to determine the number of
factors to retain in exploratory factor analysis: A comparison of extraction
methods under realistic conditions. \emph{Psychological Methods, 24}(4), 468--491.
https://doi.org/10.1037/met0000200

Velicer, W. F. (1976). Determining the number of components from the matrix of partial correlations.
\emph{Psychometrika, 41}, 321--327.

Velicer, W. F., Eaton, C. A., & Fava, J. L. (2000). Construct explication through factor or component analysis: A review and evaluation of alternative procedures for determining the number of factors or components. In Goffin, R. D. & Helmes, E. (Eds.), \emph{Problems and Solutions in
Human Assessment: Honoring Douglas N. Jackson at Seventy} (pp. 41--71). Boston: Kluwer.

Zwick, W. R., & Velicer, W. F. (1986). Comparison of five rules for
determining the number of components to retain. \emph{Psychological Bulletin, 99},
432--442. https://doi.org/10.1037/0033-2909.99.3.432
}
\usage{
efa_map(
  x,
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra")
)
}
\arguments{
\item{x}{A numeric \code{matrix} or \code{data.frame}. Can be either (a) a correlation matrix, or
(b) raw data (rows = observations, columns = variables) from which correlations are computed.}

\item{use}{Character string specifying the treatment of missing values when computing correlations.
Passed to \code{\link[stats:cor]{stats::cor()}}. Defaults to \code{"pairwise.complete.obs"}.}

\item{cor_method}{Character string specifying the correlation coefficient to be computed if raw
data are supplied. One of \code{"pearson"}, \code{"spearman"}, or \code{"kendall"} (passed to
\code{\link[stats:cor]{stats::cor()}}), or \code{"poly"} / \code{"tetra"} for polychoric / tetrachoric correlations
of ordinal / binary data (a two-step estimator). Defaults to \code{"pearson"}.}
}
\value{
An object of class \code{efa_retention} (see \code{\link[=print.efa_retention]{print.efa_retention()}} for the
print method). MAP has no plot; \code{\link[=plot.efa_retention]{plot.efa_retention()}} returns \code{NULL} with a
message for it. Its main elements are:
\itemize{
\item \code{n_factors}: A named numeric vector (\code{"TR2"}, \code{"TR4"}) with the index
\eqn{m} that minimizes the original (TR2) and revised (TR4) MAP criterion.
\item \code{results}: A list with one record per criterion, each holding the
criterion values over \eqn{m} and, in \code{m_last}, the largest \eqn{m} at which
the criterion could be evaluated (see details).
\item \code{settings}: A list containing \code{use} and \code{cor_method}.
}
}
\description{
Computes Velicer's Minimum Average Partial (MAP) criterion for determining the number of
factors/components to retain. The function implements the original MAP criterion
(Velicer, 1976), expressed via the \eqn{\mathrm{TR2}} representation, and the revised
\eqn{\mathrm{TR4}} variant proposed by Velicer, Eaton, and Fava (2000).
}
\details{
MAP partials successive principal components out of the correlation matrix and,
after removing \eqn{m} components, summarizes the off-diagonal partial
correlations \eqn{r^*_{ij}} that remain in the \eqn{m}-th partial correlation
matrix \eqn{M} (which has a unit diagonal); the suggested number of factors is
the \eqn{m} that minimizes the criterion. Two criteria are returned, each
rescaling the trace of a matrix power of \eqn{M} by the number of off-diagonal
cells \eqn{p(p-1)}:
\itemize{
\item \strong{TR2 (original MAP; Velicer, 1976):} the average squared off-diagonal
partial correlation,
\deqn{\mathrm{TR2}_m = \frac{\mathrm{tr}(M^2) - p}{p(p-1)} = \frac{\sum_{i \neq j} (r^*_{ij})^2}{p(p-1)},}
where subtracting \eqn{p} removes the \eqn{p} unit diagonal entries.
\item \strong{TR4 (revised MAP; Velicer, Eaton, & Fava, 2000):} the analogous
fourth-power summary, formed from the trace of the fourth matrix power,
\deqn{\mathrm{TR4}_m = \frac{\mathrm{tr}(M^4) - p}{p(p-1)}.}
Moving from the squared to the fourth power downweights the small partial
correlations relative to the large ones, which can sharpen the minimum.
Unlike TR2, \eqn{\mathrm{tr}(M^4)} is \emph{not} the sum of the fourth powers of the
individual partial correlations; the matrix power is intended and is what
Velicer, Eaton, and Fava (2000) describe.
}

Both criteria are returned for every call and they can suggest different numbers
of factors on the same correlation matrix. Both are in use in the literature and
neither is treated as the default here, so be sure to state which of the two you
report, as you would for any other analysis choice.

MAP is most dependable when the components are well determined, that is with many
indicators per factor and substantial loadings. It has a well-documented tendency
to under-extract, particularly with few indicators per factor or weak loadings
(Zwick & Velicer, 1986; Auerswald & Moshagen, 2019), so it is best read as a lower
bound and paired with a criterion that errs in the other direction, such as the
Kaiser-Guttman criterion (\code{\link[=efa_kgc]{efa_kgc()}}).

The criterion is evaluated over \eqn{m = 0, \ldots, p - 1}. Each step standardizes
the partial covariance matrix by its residual standard deviations, which requires
every residual variance to stay positive. Partialling out all but one component
leaves a rank-one residual, so the final point \eqn{m = p - 1} is undefined for
most correlation matrices and is routinely returned as \code{NA}. A residual variance
can also reach zero earlier, most often on a near-singular matrix; the search then
stops there, the criterion values that could be computed are kept, the remaining
values stay \code{NA}, and a warning (class \code{efa_map_truncated}) reports how far the
grid was searched. In that case the suggested \eqn{m} is the minimum over the
evaluated range only, so it should be read together with the returned series.

A non-positive-definite input correlation matrix (e.g. from sampling error) is
smoothed with \code{\link[psych:cor.smooth]{psych::cor.smooth()}}.
}
\examples{
## Example with raw data
res <- efa_map(GRiPS_raw)
res

## Example with a correlation matrix
res2 <- efa_map(test_models$baseline$cormat)
res2

}
\seealso{
\code{\link[=efa_retain]{efa_retain()}} as a wrapper function for this and the other factor
retention criteria.

Other factor retention criteria:
\code{\link[=efa_cd]{efa_cd()}},
\code{\link[=efa_ekc]{efa_ekc()}},
\code{\link[=efa_hull]{efa_hull()}},
\code{\link[=efa_kgc]{efa_kgc()}},
\code{\link[=efa_nest]{efa_nest()}},
\code{\link[=efa_parallel]{efa_parallel()}},
\code{\link[=efa_retain]{efa_retain()}},
\code{\link[=efa_scree]{efa_scree()}},
\code{\link[=efa_smt]{efa_smt()}}
}
\concept{factor retention criteria}
