% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa_cd.R
\name{efa_cd}
\alias{efa_cd}
\title{Comparison data}
\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. Psychological Methods, 24(4), 468–491.
https://doi.org/10.1037/met0000200

Ruscio, J., & Roche, B. (2012). Determining the number of factors to
retain in an exploratory factor analysis using comparison data of known
factorial structure. Psychological Assessment, 24, 282–292.
doi: 10.1037/a0025697
}
\usage{
efa_cd(
  x,
  n_factors_max = NA,
  N_pop = 10000,
  N_samples = 500,
  alpha = 0.3,
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra"),
  max_iter = 50
)
}
\arguments{
\item{x}{data.frame or matrix. Dataframe or matrix of raw data.}

\item{n_factors_max}{numeric. 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. Size of finite populations of comparison data. Default
is 10000.}

\item{N_samples}{numeric. Number of samples drawn from each population.
Default is 500.}

\item{alpha}{numeric. The alpha level used to test the significance of the
improvement added by an additional factor. Default is .30.}

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

\item{max_iter}{numeric. The maximum number of iterations after which the
iterative PAF procedure inside the comparison-data generation is halted; it
does not cap an EFA of \code{x}. Default is 50.}
}
\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{"CD"}) with the suggested number of
factors according to comparison data results.}
\item{results}{A list with a single record holding the mean RMSE between the
eigenvalues of the generated and the entered data per number of factors
(used for the plot) and, in \code{rmse_eigenvalues}, the per-sample RMSE matrix
(rows are samples, columns are factor counts; columns beyond the last tested
factor count are left as zero).}
\item{settings}{A list of the settings used.}
}
\description{
Factor retention method introduced by Ruscio and Roche (2012). The code was
adapted from the CD code published by Auerswald and Moshagen (2019), available
at \url{https://osf.io/x5cz2/}.
}
\details{
Comparison data (CD) extends parallel analysis by reproducing the
observed correlation matrix rather than generating random data: datasets with a
known factor structure are generated with an increasing number of factors, and
the smallest number for which adding a further factor no longer significantly
improves the reproduction of the observed eigenvalues is retained (Ruscio &
Roche, 2012).

Because it reproduces the observed correlation structure instead of a null model,
CD was among the more accurate criteria across a broad range of conditions in
Ruscio and Roche (2012). It is, however, the only criterion in this family that
requires raw data, and by some margin the most computationally intensive one: a
finite population of \code{N_pop} cases is generated and \code{N_samples} samples are drawn
from it at every candidate factor count. It is therefore a good choice when the
raw data are at hand and the runtime is acceptable, and a poor one for a quick
look at a correlation matrix.

The comparison data are obtained by simulation, 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.

Note that if the data contains missing values, these will be removed for the
comparison data procedure using \code{\link[stats:na.fail]{stats::na.omit()}}. If
missing data should be treated differently, e.g., by imputation, do this outside
\code{efa_cd()} and then pass the complete data.
}
\examples{
\donttest{
# determine n factors of the GRiPS
efa_cd(GRiPS_raw, N_pop = 500, N_samples = 20)

# determine n factors of the DOSPERT risk subscale
efa_cd(DOSPERT_raw, N_pop = 500, N_samples = 20)
}
}
\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_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_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}
