% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa_parallel.R
\name{efa_parallel}
\alias{efa_parallel}
\title{Parallel analysis}
\source{
Braeken, J., & van Assen, M. A. (2017). An empirical Kaiser criterion.
Psychological Methods, 22, 450--466. https://doi.org/10.1037/met0000074

Crawford, A. V., Green, S. B., Levy, R., Lo, W. J., Scott, L.,
Svetina, D., & Thompson, M. S. (2010). Evaluation of parallel analysis methods
for determining the number of factors. Educational and Psychological
Measurement, 70(6), 885-901.

Glorfeld, L. W. (1995). An improvement on Horn's parallel analysis
methodology for selecting the correct number of factors to retain. Educational
and Psychological Measurement, 55(3), 377-393.

Horn, J. L. (1965). A rationale and test for the number of factors in
factor analysis. Psychometrika, 30(2), 179--185. https://doi.org/10.1007/BF02289447
}
\usage{
efa_parallel(
  x = NULL,
  N = NA,
  n_vars = NA,
  n_datasets = 1000,
  percent = 95,
  eigen_type = c("PCA", "SMC", "EFA"),
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra"),
  decision_rule = c("means", "percentile", "crawford"),
  n_factors = 1,
  estimate_control = NULL,
  ...
)
}
\arguments{
\item{x}{matrix or data.frame. The real data to compare the simulated eigenvalues
against. Must not contain variables of classes other than numeric. Can be a
correlation matrix or raw data.}

\item{N}{numeric. The number of cases / observations to simulate. Only has to
be specified if \code{x} is either a correlation matrix or \code{NULL}. If
x contains raw data, \code{N} is found from the dimensions of \code{x}. Must be larger
than the number of variables.}

\item{n_vars}{numeric. The number of variables / indicators to simulate.
Only has to be specified if \code{x} is left as \code{NULL} as otherwise the
dimensions are taken from \code{x}.}

\item{n_datasets}{numeric. The number of datasets to simulate. Must be at
least 1. Default is 1000.}

\item{percent}{numeric. The percentile to take from the simulated eigenvalues.
Default is 95.}

\item{eigen_type}{character. On what the eigenvalues should be found. Can be
either "SMC", "PCA", or "EFA". If using "SMC", the diagonal of the correlation
matrix is replaced by the squared multiple correlations (SMCs) of the
indicators. If using "PCA", the diagonal values of the correlation matrices
are left to be 1. If using "EFA", eigenvalues are found on the correlation
matrices with the final communalities of an EFA solution as diagonal. Default
is \code{c("PCA", "SMC", "EFA")}, i.e. all three, which costs roughly six times a
single non-EFA type: \code{"EFA"} fits an EFA to every simulated dataset and
dominates that total. Pass a single type if the run is time-critical.}

\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{PARALLEL} compares the data against simulated continuous reference data.
Default is "pearson".}

\item{decision_rule}{character. Which rule to use to determine the number of
factors to retain. Default is \code{"means"}, which will use the average
simulated eigenvalues. \code{"percentile"}, uses the percentiles specified
in percent. \code{"crawford"} uses the 95th percentile for the first factor
and the mean afterwards (based on Crawford et al, 2010). All three rules retain
the factors up to the first observed eigenvalue that fails to exceed its
reference value; an eigenvalue further down the series that rises above its own
reference again therefore adds no factor. Because the average simulated
eigenvalue is a lower reference than the percentile, \code{"means"} tends to retain
more factors than the more conservative \code{"percentile"} rule (Glorfeld, 1995).}

\item{n_factors}{numeric. Number of factors to extract if "EFA" is included in
\code{eigen_type}. Default is 1.}

\item{estimate_control}{an \code{\link[=estimate_control]{estimate_control()}} object with the estimation settings for the
\code{\link[=efa_fit]{efa_fit()}} fits (of both the real and the simulated data) when \code{"EFA"} is included in
\code{eigen_type}. \code{NULL} (default) uses the \code{\link[=efa_fit]{efa_fit()}} defaults. The fits 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 fits are internal steps that keep only their eigenvalues.}
}
\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 with the suggested number of factors for
each requested eigenvalue type (\code{"PCA"}, \code{"SMC"}, and/or \code{"EFA"}). These are
\code{NA} when no real data are supplied (i.e. only \code{N} and \code{n_vars} are given). When
every observed eigenvalue exceeds its reference value (no crossing is found), all
\code{n_vars} components are retained and a warning is issued.}
\item{results}{A list with one record per eigenvalue type, each holding the
observed eigenvalues (when real data were supplied) and the simulated reference
values (means and percentiles) used for printing and plotting.}
\item{settings}{A list of the settings used.}
}
\description{
Various methods for performing parallel analysis. This function uses
\link[future.apply:future_lapply]{future_lapply()} for which a parallel processing plan can
be selected. To do so, register a plan with \code{\link[future:plan]{future::plan()}}, for example
\code{future::plan(future::multisession, workers = 2)}; see examples.
}
\details{
Parallel analysis (Horn, 1965) compares the eigenvalues obtained from
the sample
correlation matrix against those of null model correlation matrices (i.e.,
with uncorrelated variables) of the same sample size. This way, it accounts
for the variation in eigenvalues introduced by sampling error and thus
eliminates the main problem inherent in the Kaiser-Guttman criterion
(\code{\link[=efa_kgc]{efa_kgc()}}).

Parallel analysis is often argued to be one of the most accurate factor
retention criteria. However, for highly correlated
factor structures it has been shown to underestimate the correct number of
factors. The reason for this is that a null model (uncorrelated variables)
is used as reference. However, when factors are highly correlated, the first
eigenvalue will be much larger compared to the following ones, as
later eigenvalues are conditional on the earlier ones in the sequence and thus
the shared variance is already accounted in the first eigenvalue (e.g.,
Braeken & van Assen, 2017).

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; the result is then also independent of the parallel plan set via
\code{\link[future:plan]{future::plan()}}, so it can be reproduced on a machine with a different number of
cores. For \code{"PCA"} and \code{"SMC"} the simulation is drawn in independently seeded blocks;
a block that fails -- which happens when a simulated correlation matrix is singular, so
that no eigenvalues can be taken from it -- is redrawn on its own, leaving the blocks
that succeeded with the draws they already made. The \code{"EFA"} series instead redraws the
single dataset that could not be fitted; if that dataset still cannot be fitted, the
call stops with an error.

When both \code{"PCA"} and \code{"SMC"} are requested, the two are read off the \emph{same} simulated
datasets rather than from two independent simulations: they differ only in the diagonal
substituted into the simulated correlation matrix, so one set of draws serves both and
the two reference series are paired dataset by dataset. A draw that cannot be used for
the SMC series -- a simulated matrix with no inverse, and hence no squared multiple
correlations -- is discarded for the \code{"PCA"} series as well, so that the pairing stays
exact. \code{"EFA"} fits a model to each simulated dataset and draws its own.

The \code{efa_parallel} function can also be called together with other factor
retention criteria in the \code{\link[=efa_retain]{efa_retain()}} function.
}
\examples{
\donttest{
# example without real data
pa_unreal <- efa_parallel(N = 500, n_vars = 10, n_datasets = 100)

# example with correlation matrix with all eigen_types and PAF estimation
pa_paf <- efa_parallel(test_models$case_11b$cormat, N = 500, n_datasets = 100)

# example with correlation matrix with all eigen_types and ML estimation
# this will be faster than the above with PAF)
pa_ml <- efa_parallel(test_models$case_11b$cormat, N = 500, estimator = "ML",
                      n_datasets = 100)
}

\dontrun{
# for parallel computation. future::plan() returns the plan it replaces, so
# on.exit() puts the session back as it was -- also if the call fails.
pa_faster <- local({
  old_plan <- future::plan(future::multisession, workers = 2)
  on.exit(future::plan(old_plan), add = TRUE)
  efa_parallel(test_models$case_11b$cormat, N = 500)
})
}
}
\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_nest]{efa_nest()}},
\code{\link[=efa_retain]{efa_retain()}},
\code{\link[=efa_scree]{efa_scree()}},
\code{\link[=efa_smt]{efa_smt()}}
}
\concept{factor retention criteria}
