% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/EFAtools-superseded.R
\name{N_FACTORS}
\alias{N_FACTORS}
\title{Various factor retention criteria}
\usage{
N_FACTORS(
  x,
  criteria = c("CD", "EKC", "HULL", "MAP", "NEST", "PARALLEL"),
  suitability = TRUE,
  N = NA,
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra"),
  n_factors_max = NA,
  N_pop = 10000,
  N_samples = 500,
  alpha = 0.3,
  max_iter_CD = 50,
  n_fac_theor = NA,
  method = c("ML", "PAF", "ULS"),
  gof = c("CAF", "CFI", "RMSEA"),
  eigen_type_HULL = c("SMC", "PCA", "EFA"),
  eigen_type_other = c("SMC"),
  n_factors = 1,
  n_datasets = 1000,
  percent = 95,
  decision_rule = c("means", "percentile", "crawford"),
  ekc_type = lifecycle::deprecated(),
  n_datasets_nest = 1000,
  alpha_nest = 0.05,
  show_progress = FALSE,
  ...
)
}
\arguments{
\item{x}{data.frame or matrix. Raw data, or a correlation matrix. If \code{"CD"} is
included as a criterion, x must be raw data.}

\item{criteria}{character. A vector with the factor retention methods to
perform. Possible inputs are: \code{"CD"}, \code{"EKC"}, \code{"HULL"}, \code{"KGC"}, \code{"MAP"},
\code{"NEST"}, \code{"PARALLEL"}, \code{"SCREE"}, and \code{"SMT"} (see the details in
\code{\link[=efa_retain]{efa_retain()}}). By default, a subset of often used, well-performing
methods are performed.}

\item{suitability}{logical. Whether the data should be checked for suitability
for factor analysis using Bartlett's test of sphericity and the
Kaiser-Meyer-Olkin criterion (see details). Default is \code{TRUE}.}

\item{N}{numeric. The number of observations. Only needed if x is a
correlation matrix.}

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

\item{cor_method}{character. Correlation computed from raw data: \code{"pearson"},
\code{"spearman"}, or \code{"kendall"} (passed to \code{\link[stats:cor]{stats::cor()}}), or \code{"poly"} /
\code{"tetra"} for polychoric / tetrachoric correlations (a two-step estimator).
\code{CD}, \code{PARALLEL}, \code{NEST}, \code{HULL}, and \code{SMT} do not support \code{"poly"} / \code{"tetra"}
and are skipped automatically if you request them together.
Default is \code{"pearson"}.}

\item{n_factors_max}{numeric. Passed to \code{\link[=efa_cd]{efa_cd()}}. The maximum number
of factors to test against.
Larger numbers will increase the duration the procedure takes, but test more
possible solutions. If left NA (default), the maximum number of factors for
which the model is still over-identified (df > 0) is used.}

\item{N_pop}{numeric. Passed to \code{\link[=efa_cd]{efa_cd()}}. Size of finite populations
of comparison data. Default is 10000.}

\item{N_samples}{numeric. Passed to \code{\link[=efa_cd]{efa_cd()}}. Number of samples drawn
from each population. Default is 500.}

\item{alpha}{numeric. Passed to \code{\link[=efa_cd]{efa_cd()}}. The alpha level used to test
the significance of the improvement added by an additional factor.
Default is .30.}

\item{max_iter_CD}{numeric. Passed to \code{\link[=efa_cd]{efa_cd()}}. The maximum number of
iterations to perform after which the iterative PAF procedure is halted.
Default is 50.}

\item{n_fac_theor}{numeric. Passed to \code{\link[=efa_hull]{efa_hull()}}. Theoretical number
of factors to retain. The Hull method uses one plus the larger of this
number and the number of factors suggested by \code{\link[=efa_parallel]{efa_parallel()}} as its
upper bound.}

\item{method}{character. The estimator to use in the criteria that fit EFA models;
passed to \code{\link[=efa_retain]{efa_retain()}} as its \code{estimator} argument. One of \code{"ML"}, \code{"PAF"}, or
\code{"ULS"}.}

\item{gof}{character. Passed to \code{\link[=efa_hull]{efa_hull()}}. The goodness of fit index
to use. Either \code{"CAF"}, \code{"CFI"}, or \code{"RMSEA"}, or any
combination of them. With the \code{"PAF"} estimator, only
the CAF can be used as goodness of fit index. For details on the CAF, see
Lorenzo-Seva, Timmerman, and Kiers (2011).}

\item{eigen_type_HULL}{character. Passed to \code{\link[=efa_parallel]{efa_parallel()}} in
\code{\link[=efa_hull]{efa_hull()}}. What the eigenvalues in the parallel analysis are based on.
One of \code{"SMC"}, \code{"PCA"}, or \code{"EFA"} -- different ways of estimating how much
variance each indicator shares with the others before the eigenvalues are
computed. \code{"SMC"} (default) uses each indicator's squared multiple
correlation with the others (its diagonal value in the correlation matrix).
\code{"PCA"} leaves the diagonal at 1, so each indicator's total variance -- not
just the shared part -- feeds into the eigenvalues. \code{"EFA"} uses the
communalities from a fitted EFA solution instead.}

\item{eigen_type_other}{character. Passed to \code{\link[=efa_kgc]{efa_kgc()}},
\code{\link[=efa_scree]{efa_scree()}}, and \code{\link[=efa_parallel]{efa_parallel()}}. The same as eigen_type_HULL,
but multiple inputs are possible here (any combination of \code{"PCA"}, \code{"SMC"},
and \code{"EFA"}). Default is \code{"SMC"}.}

\item{n_factors}{numeric. Passed to \code{\link[=efa_parallel]{efa_parallel()}} (also within
\code{\link[=efa_hull]{efa_hull()}}), \code{\link[=efa_kgc]{efa_kgc()}}, and \code{\link[=efa_scree]{efa_scree()}}. Number of
factors to extract if \code{"EFA"} is included in \code{eigen_type_HULL} or
\code{eigen_type_other}. Default is 1.}

\item{n_datasets}{numeric. Passed to \code{\link[=efa_parallel]{efa_parallel()}} (also within
\code{\link[=efa_hull]{efa_hull()}}). The number of datasets to simulate. Default is 1000.}

\item{percent}{numeric. Passed to \code{\link[=efa_parallel]{efa_parallel()}} (also within
\code{\link[=efa_hull]{efa_hull()}}). The percentile to take from the simulated eigenvalues.
Default is 95.}

\item{decision_rule}{character. Passed to \code{\link[=efa_parallel]{efa_parallel()}} (also within
\code{\link[=efa_hull]{efa_hull()}}). Which rule to use to determine the number of
factors to retain. Default is \code{"means"}, which uses the average simulated
eigenvalues. \code{"percentile"} uses the percentiles specified in \code{percent}.
\code{"crawford"} uses the 95th percentile for the first factor and the mean
afterwards (based on Crawford et al., 2010).}

\item{ekc_type}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Accepted and ignored. It
used to select between two ways to compute the \code{\link[=efa_ekc]{efa_ekc()}} reference values.
The \code{"AM2019"} reference values do not depend on the observed eigenvalues.
They therefore skip the empirical correction that defines the criterion, so
they are no longer computed.}

\item{n_datasets_nest}{numeric. Passed to \code{\link[=efa_nest]{efa_nest()}}. The number of
datasets to simulate. Default is 1000.}

\item{alpha_nest}{numeric. Passed to \code{\link[=efa_nest]{efa_nest()}}. The alpha level to use.
The reference values are the eigenvalues at the (1 - alpha_nest)
percentile. Default is .05.}

\item{show_progress}{logical. Whether a progress bar should be shown in the
console. Default is FALSE.}

\item{...}{Further arguments passed on to the \code{\link[=efa_fit]{efa_fit()}} fits, including the
estimation tuning knobs (\code{type}, \code{init_comm}, \code{criterion}, \code{criterion_type},
\code{abs_eigen}, \code{start_method}), which are repacked into an \code{\link[=estimate_control]{estimate_control()}} object
so that they tune the fits exactly as they always did. The estimator is selected with
\code{method}; \code{max_iter} is taken by the \code{max_iter_CD} argument (R matches an abbreviated
name against the arguments before \code{...}) and so does not reach the fits.}
}
\value{
A list of class \code{c("efa_retain", "N_FACTORS")}, identical to the
value of \code{\link[=efa_retain]{efa_retain()}}; see there for the components.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}

\code{N_FACTORS()} has been superseded by \code{\link[=efa_retain]{efa_retain()}}, which is the recommended
interface going forward. It remains available and unchanged so existing code
keeps working.
}
\seealso{
\code{\link[=efa_retain]{efa_retain()}}
}
