% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/EFAtools-superseded.R
\name{EFA_AVERAGE}
\alias{EFA_AVERAGE}
\title{Model averaging across different EFA methods and types}
\usage{
EFA_AVERAGE(
  x,
  n_factors,
  N = NA,
  method = "PAF",
  rotation = "promax",
  type = "none",
  averaging = c("mean", "median"),
  trim = 0,
  salience_threshold = 0.3,
  max_iter = 10000,
  init_comm = c("smc", "mac", "unity"),
  criterion = c(0.001),
  criterion_type = c("sum", "max_individual"),
  abs_eigen = c(TRUE),
  varimax_type = c("svd", "kaiser"),
  normalize = TRUE,
  k_promax = 2:4,
  k_simplimax = ncol(x),
  P_type = c("norm", "unnorm"),
  precision = 1e-05,
  start_method = c("psych", "factanal"),
  use = c("pairwise.complete.obs", "all.obs", "complete.obs", "everything",
    "na.or.complete"),
  cor_method = c("pearson", "spearman", "kendall", "poly", "tetra", "fiml"),
  show_progress = TRUE
)
}
\arguments{
\item{x}{data.frame or matrix. Dataframe or matrix of raw data or matrix with
correlations. If raw data is entered, the correlation matrix is found from the
data.}

\item{n_factors}{numeric. Number of factors to extract.}

\item{N}{numeric. The number of observations. Needs only be specified if a
correlation matrix is used. If input is a correlation matrix and \code{N} = NA
(default), not all fit indices can be computed.}

\item{method}{character vector. Any combination of \code{"PAF"}, \code{"ML"}, and \code{"ULS"},
the estimators to average across; passed to \code{\link[=efa_average]{efa_average()}} as its \code{estimator}
argument. Default is \code{"PAF"}.}

\item{rotation}{character vector. Either perform no rotation ("none"),
any combination of orthogonal rotations ("varimax", "equamax", "quartimax", "geominT",
"bentlerT", and "bifactorT"; using "orthogonal" runs all of these), or of
oblique rotations ("promax", "oblimin", "quartimin", "simplimax", "bentlerQ",
"geominQ", and "bifactorQ"; using "oblique" runs all of these). Rotation types
(no rotation, orthogonal rotations, and oblique rotations) cannot be mixed.
Default is "promax".}

\item{type}{character vector. Any combination of "none" (default), "EFAtools",
"psych", and "SPSS" can be entered. "none" allows the specification of various
combinations of the arguments controlling both factor extraction methods and
the rotations. The others ("EFAtools", "psych", and "SPSS") take the extraction
and rotation tuning of the respective implementation: this package's default
procedure, the psych package's, and SPSS's. A specific psych implementation
exists for PAF, ML, varimax, and promax. The SPSS implementation exists for
PAF, varimax, and promax. For details, see \code{\link[=efa_fit]{efa_fit()}}. The factor ordering is
the one setting a named \code{type} does not bring here: every solution in the grid
is fitted with the eigenvalue-based ordering, so that the solutions can be
realigned to a common target before averaging.}

\item{averaging}{character. One of "mean" (default), and "median". Controls
whether the different results should be averaged using the (trimmed) mean,
or the median.}

\item{trim}{numeric. If averaging is set to "mean", this argument controls
the trimming of extremes (for details see \code{\link[base:mean]{base::mean()}}).
By default no trimming is done (i.e., trim = 0).}

\item{salience_threshold}{numeric. The threshold to use to classify a pattern
coefficient or loading as salient (i.e., substantial enough to assign it to
a factor). Default is 0.3. Indicator-to-factor correspondences will be inferred
based on this threshold. Note that this may not be meaningful if rotation = "none"
and n_factors > 1 are used, as no simple structure is present there.}

\item{max_iter}{numeric. The maximum number of iterations to perform after which
the iterative PAF procedure is halted with a warning. Default is 10,000. It is
only evaluated for the "PAF" solutions run under \code{type} "none": a named \code{type}
brings the iteration cap that defines it ("SPSS" 25, "psych" 50, and
"EFAtools" 300), and "ML" and "ULS" do not iterate this way. Note
that non-converged procedures are excluded from the averaging procedure.}

\item{init_comm}{character vector. Any combination of "smc", "mac", and "unity".
Controls the methods to estimate the initial communalities in \code{PAF} if
"none" is among the specified types. "smc" will use squared multiple
correlations, "mac" will use maximum absolute correlations, "unity" will use
1s (for details see \code{\link[=efa_fit]{efa_fit()}}). Default is \code{c("smc", "mac", "unity")}.}

\item{criterion}{numeric vector. The convergence criterion used for PAF if
"none" is among the specified types.
If the change in communalities from one iteration to the next is smaller than
this criterion the solution is accepted and the procedure ends.
Default is \code{0.001}.}

\item{criterion_type}{character vector. Any combination of "max_individual" and
"sum". Type of convergence criterion used for PAF if "none" is among the
specified types. "max_individual" selects the maximum change in any of the
communalities from one iteration to the next and tests it against the
specified criterion. "sum" takes the difference of
the sum of all communalities in one iteration and the sum of all communalities
in the next iteration and tests this against the criterion
(for details see \code{\link[=efa_fit]{efa_fit()}}). Default is \code{c("sum", "max_individual")}.}

\item{abs_eigen}{logical vector. Any combination of TRUE and FALSE.
Which algorithm to use in the PAF iterations if "none" is among the specified
types. If FALSE, the loadings are computed from the eigenvalues. This is also
used by the \code{\link[psych:fa]{psych::fa()}} function. If TRUE the
loadings are computed with the absolute eigenvalues as done by SPSS
(for details see \code{\link[=efa_fit]{efa_fit()}}). Default is \code{TRUE}.}

\item{varimax_type}{character vector. Any combination of "svd" and "kaiser".
The type of the varimax rotation performed if "none" is among the specified
types and "varimax", "promax", "orthogonal", or "oblique" is among the specified
rotations. "svd" uses singular value decomposition, as
\code{\link[stats:varimax]{stats::varimax()}} does, and "kaiser" uses the varimax
procedure performed in SPSS. This is the original procedure from Kaiser (1958),
but with slight alterations in the varimax criterion (for details, see
\code{\link[=efa_fit]{efa_fit()}} and Grieder & Steiner, 2022).
Default is \code{c("svd", "kaiser")}.}

\item{normalize}{logical vector. Any combination of TRUE and FALSE.
\code{TRUE} performs a kaiser normalization before the specified rotation(s).
Default is \code{TRUE}.}

\item{k_promax}{numeric vector. The power used for computing the target matrix
P in the promax rotation if "none" is among the specified types and "promax"
or "oblique" is among the specified rotations. Default is \code{2:4}.}

\item{k_simplimax}{numeric. The number of 'close to zero loadings' for the
simplimax rotation if "simplimax" or "oblique" is among the specified rotations. Default
is \code{ncol(x)}, where x is the entered data. It counts loadings, so each value must be a
whole number no larger than the number of loadings in the solution; a simplimax fit
given anything else fails and is reported as an errored solution in the grid.}

\item{P_type}{character vector. Any combination of \code{"norm"} and \code{"unnorm"}.
How the promax target matrix P is computed if \code{"none"} is among the specified
types and \code{"promax"} or \code{"oblique"} is among the specified rotations:
\code{"unnorm"} uses the unnormalized target matrix of Hendrickson and White
(1964), \code{"norm"} a normalized one. This frozen argument keeps its original
name; \code{\link[=efa_average]{efa_average()}} takes the same setting as \code{p_type}. Default is
\code{c("norm", "unnorm")}.}

\item{precision}{numeric vector. The tolerance for stopping in the rotation
procedure(s). Default is 10^-5.}

\item{start_method}{character vector. Any combination of "psych" and "factanal".
How to specify the starting values for the optimization procedure for ML.
"psych" takes the starting values specified in \code{\link[psych:fa]{psych::fa()}}.
"factanal" takes the starting values specified in the
\code{\link[stats:factanal]{stats::factanal()}} function. Default is
\code{c("psych", "factanal")}.}

\item{use}{character. Passed to \code{\link[stats:cor]{stats::cor()}} if raw data
is given as input. Default is "pairwise.complete.obs". It is ignored when
\code{cor_method = "fiml"}, which handles the missingness itself, so every case
contributes.}

\item{cor_method}{character. Correlation computed from raw data: \code{"pearson"},
\code{"spearman"}, or \code{"kendall"} (passed to \code{\link[stats:cor]{stats::cor()}}), \code{"poly"} /
\code{"tetra"} for polychoric / tetrachoric correlations of ordinal / binary data
(a two-step estimator), or \code{"fiml"}
for a two-stage full-information maximum-likelihood correlation from raw data
with missing values. With \code{"fiml"} the saturated multivariate-normal mean and
covariance are estimated by an EM algorithm assuming the data are missing at
random and the standardized covariance is analysed, reproducing
\code{psych::corFiml()} followed by \code{psych::fa()} and
\code{lavaan(missing = "two.stage")}, \emph{not} \code{lavaan::efa(missing = "ml")} (see
\code{\link[=efa_fit]{efa_fit()}} and the details). Default is "pearson".}

\item{show_progress}{logical. Whether a progress bar should be shown in the
console. Default is TRUE.}
}
\value{
The value of \code{\link[=efa_average]{efa_average()}}, normally a list of class
\code{c("efa_average", "EFA_AVERAGE")}; 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{EFA_AVERAGE()} has been superseded by \code{\link[=efa_average]{efa_average()}}, which is the recommended
interface going forward. It remains available and unchanged so existing code
keeps working.
}
\seealso{
\code{\link[=efa_average]{efa_average()}}
}
