% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa_nest.R
\name{efa_nest}
\alias{efa_nest}
\title{Next eigenvalue sufficiency test (NEST)}
\source{
Achim, A. (2017). Testing the number of required dimensions in exploratory factor analysis. The Quantitative Methods for Psychology, 13(1), 64–74. https://doi.org/10.20982/tqmp.13.1.p064

Brandenburg, N., & Papenberg, M. (2024). Reassessment of innovative methods to determine the number of factors: A simulation-based comparison of exploratory graph analysis and Next Eigenvalue Sufficiency Test. Psychological Methods, 29(1), 21–47. https://doi.org/10.1037/met0000527

Caron, P.-O. (2025). A Comparison of the Next Eigenvalue Sufficiency Test to Other Stopping Rules for the Number of Factors in Factor Analysis.
Educational and Psychological Measurement, Online-first publication. https://doi.org/10.1177/00131644241308528
}
\usage{
efa_nest(
  x,
  N = NA,
  alpha = 0.05,
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra"),
  n_datasets = 1000,
  estimate_control = NULL,
  ...
)
}
\arguments{
\item{x}{data.frame or matrix. Dataframe or matrix of raw data or matrix with
correlations.}

\item{N}{numeric. The number of observations. Only needed if x is a correlation
matrix. Must be larger than the number of variables.}

\item{alpha}{numeric. The alpha level to use (i.e., 1-alpha percentile of eigenvalues is used for reference values).}

\item{use}{character. Passed to \code{\link[stats:cor]{stats::cor()}} if raw
data is given as input. Default is "pairwise.complete.obs".}

\item{cor_method}{character. One of \code{"pearson"}, \code{"spearman"}, or \code{"kendall"},
passed to \code{\link[stats:cor]{stats::cor()}}. \code{"poly"} and \code{"tetra"} are not supported because
\code{NEST} compares the data against simulated continuous reference data.
Default is  \code{"pearson"}.}

\item{n_datasets}{numeric. The number of datasets to simulate. Default is 1000.}

\item{estimate_control}{an \code{\link[=estimate_control]{estimate_control()}} object with the estimation settings for the
\code{\link[=efa_fit]{efa_fit()}} reference-model fits. \code{NULL} (default) uses the \code{\link[=efa_fit]{efa_fit()}} defaults. The
reference models are unrotated, so no rotation settings apply.}

\item{...}{Additional arguments passed to \code{\link[=efa_fit]{efa_fit()}}. For example,
\code{estimator}, to change the estimator (default is "PAF"). PAF is more
robust, but it will take longer compared to the other estimators
available ("ML" and "ULS"). The estimation tuning knobs are not passed here; they
live in \code{estimate_control}, and the standard-error arguments (\code{se}, \code{b_boot}, \code{ci},
\code{seed}) are not accepted because the reference-model fits are internal steps.}
}
\value{
An object of class \code{efa_retention} (see \code{\link[=print.efa_retention]{print.efa_retention()}} and
\code{\link[=plot.efa_retention]{plot.efa_retention()}} for the print and plot methods). Its main fields are:
\item{n_factors}{A named numeric vector (\code{"NEST"}) with the suggested number of
factors according to the NEST procedure.}
\item{results}{A list with a single record holding the empirical eigenvalues
and the reference eigenvalues. Only the positions the search actually tested
carry a reference value; beyond the position at which it stopped the series is
\code{NA}.}
\item{settings}{A list of control settings used.}
}
\description{
NEST uses many synthetic datasets to generate reference eigenvalues against
which to compare the empirical eigenvalues. This is similar to parallel
analysis, but other than parallel analysis, NEST does not just rely on
synthetic eigenvalues based on an identity matrix as null model.
It was introduced by Achim (2017), see also Brandenburg and Papenberg (2024) and
Caron (2025) for further simulation studies including NEST.
}
\details{
NEST compares the first empirical eigenvalue against the first eigenvalues
of \code{n_dataset} synthetic datasets based on a null model  (i.e.,
with uncorrelated variables; same as in parallel analysis, see \code{\link[=efa_parallel]{efa_parallel()}}).
The following eigenvalues are compared against synthetic datasets based on an EFA-model with one fewer factors
than the position of the respective empirical eigenvalue. E.g, the second
empirical eigenvalue is compared against synthetic data based on a one-factor
model. In each comparison the \eqn{k}-th empirical eigenvalue is tested against
the \eqn{k}-th largest eigenvalue of the synthetic datasets. The \code{alpha}-level
defines against which percentile of the synthetic
eigenvalue distribution to compare the empirical eigenvalues against, i.e., an
alpha of .05 (the default) uses the 95th percentile as reference value.

The number of factors tested is capped at \eqn{\lfloor 0.8 \times p \rfloor}
(with \eqn{p} the number of variables; Achim, 2017) and additionally limited so
that the \eqn{(k - 1)}-factor reference model used at each step stays
over-identified. If no empirical eigenvalue falls at or below its reference
within this range, every tested factor is accepted and this capped number is
returned.

Because each reference model carries the factors already retained, NEST does not
lose accuracy for the strongly correlated factor structures where parallel
analysis tends to under-extract, and it was among the more accurate criteria in
the simulation studies of Brandenburg and Papenberg (2024) and Caron (2025). The
price is runtime: a fresh set of \code{n_datasets} reference datasets is drawn and
eigen-decomposed at every candidate factor count, which makes NEST one of the
slowest criteria available here.

The reference models are fitted without inequality constraints. A Heywood case in
one of them leaves no unique variance to simulate the reference data from, so
NEST aborts rather than continuing from an inadmissible reference.

The reference eigenvalues are obtained from simulated data, so the suggested number
of factors varies slightly from run to run. Call \code{\link[base:set.seed]{base::set.seed()}} beforehand to make a
run reproducible.

For details on the method, including simulation studies, see Achim (2017),
Brandenburg and Papenberg (2024), and Caron (2025).

The \code{efa_nest} function can also be called together with other factor
retention criteria in the \code{\link[=efa_retain]{efa_retain()}} function.
}
\examples{
\donttest{
# with correlation matrix
efa_nest(test_models$baseline$cormat, N = 500)

# with raw data
efa_nest(GRiPS_raw)
}
}
\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_map]{efa_map()}},
\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}
