% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/MAP.R
\name{MAP}
\alias{MAP}
\title{Velicer's Minimum Average Partial (MAP) Criterion}
\usage{
MAP(
  x,
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall")
)
}
\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}}. Defaults to \code{"pairwise.complete.obs"}.}

\item{cor_method}{Character string specifying the correlation coefficient to be computed if raw
data are supplied. Passed to \code{\link[stats]{cor}}. Defaults to \code{"pearson"}.}
}
\value{
An object of class \code{"MAP"} with the following elements:
\itemize{
  \item \code{eigenvalues}: Eigenvalues of the (possibly smoothed) correlation matrix.
  \item \code{n_factors_TR2}: Index \eqn{m} that minimizes the TR2 (original MAP) criterion.
  \item \code{n_factors_TR4}: Index \eqn{m} that minimizes the TR4 (revised MAP) criterion.
  \item \code{criteria}: A \code{matrix} with columns \code{m}, \code{TR2 (orig. MAP)}, and
  \code{TR4 (revised MAP)}.
  \item \code{settings}: A list containing \code{use}, \code{cor_method}, and \code{N}.
}
}
\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 is based on the idea that systematic common variance is increasingly removed from a
correlation matrix \eqn{R} as principal components are partialled out. After removing the
first \eqn{m} components, a residual (partial) covariance matrix is obtained as
\deqn{C_m = R - A_m A_m',}
where \eqn{A_m} contains the first \eqn{m} principal component loading vectors (PCA loadings).
This residual matrix is then standardized to a partial correlation matrix
\deqn{R^*_m = D_m^{-1/2} \, C_m \, D_m^{-1/2},}
with \eqn{D_m = \mathrm{diag}(C_m)}. The MAP criteria summarize the off-diagonal association
remaining in \eqn{R^*_m}. The recommended number of factors/components is the \eqn{m} that
minimizes the chosen criterion.

This function returns two MAP criteria:
\itemize{
  \item \strong{TR2 (original MAP):} \deqn{\mathrm{MAP}_m = \frac{\mathrm{Trace}(R^{*2}_m) - p}{p(p-1)}}
  which is algebraically equivalent to the mean squared off-diagonal partial correlations and
  corresponds to Velicer's original MAP procedure.
  \item \strong{TR4 (revised MAP):} \deqn{\mathrm{MAP4}_m = \frac{\mathrm{Trace}(R^{*4}_m) - p}{p(p-1)}}
  a higher-order variant that places more weight on dominant residual association structure.
}

\strong{Input handling.} \code{x} can be a correlation matrix or raw data. If \code{x} is not a
correlation matrix, correlations are computed using \code{\link[stats]{cor}} with the requested
missing-data handling (\code{use}) and association measure (\code{cor_method}). If a correlation
matrix is supplied, \code{N} must be provided.

\strong{Matrix conditioning.} The function stops if the correlation matrix is singular (non-invertible),
because subsequent computations rely on stable matrix operations. If the correlation matrix is not
positive definite (e.g., due to sampling error), it is smoothed using \code{\link[psych]{cor.smooth}}.

\strong{PCA-based partialing.} The PCA loading matrix \eqn{A} is obtained from the eigen-decomposition
of \eqn{R} as \eqn{A = V \Lambda^{1/2}}. For each \eqn{m = 0, \dots, p-1}, the first \eqn{m} columns
of \eqn{A} are used to compute \eqn{C_m = R - A_m A_m'}. The residual is re-standardized to the
partial correlation matrix \eqn{R^*_m} using \eqn{D_m^{-1/2}} (i.e., dividing by the square roots of
residual variances).

\strong{Termination.} If residual variances (the diagonal of \eqn{C_m}) become non-positive or
numerically unstable, the loop terminates early because \eqn{R^*_m} cannot be formed reliably.
}
\examples{
## Example with raw data
res <- MAP(GRiPS_raw)
res

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

}
\references{
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.
}
