% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/EFA_POOLED.R
\name{EFA_POOLED}
\alias{EFA_POOLED}
\title{Exploratory factor analysis on multiple data imputations}
\usage{
EFA_POOLED(
  data_list,
  p = 0.05,
  target_method = c("consensus", "first_target"),
  align_unrotated = c("signed_tucker_congruence", "none", "procrustes"),
  fit_pool_method = c("D2"),
  consensus_args = list(),
  procrustes_args = list(),
  rmsea_ci_level = 0.9,
  rmsr_upper = TRUE,
  ...
)
}
\arguments{
\item{data_list}{A list of length \eqn{m}, where \eqn{m} is the number of
imputations. Each list element is a data frame or matrix of raw data, or a
correlation matrix. See argument \code{x} in \code{\link{EFA}}.}

\item{p}{Numeric in \eqn{(0, 1)}. One minus the confidence level used for
pooled Wald-type bootstrap/MI confidence intervals when bootstrap arrays are
available. For example, \code{p = .05} gives 95\% intervals.}

\item{target_method}{Character. \code{"consensus"} aligns all solutions to an
iteratively updated consensus target. \code{"first_target"} aligns all
solutions to the first imputation's rotated solution.}

\item{align_unrotated}{Character. How to align unrotated loadings before
pooling. \code{"signed_tucker_congruence"} preserves the unrotated axes up
to factor reordering and sign changes using Tucker congruence.
\code{"procrustes"} aligns the unrotated matrices to the first imputation by
orthogonal Procrustes rotation. \code{"none"} averages unrotated loadings as
returned by \code{EFA}.}

\item{fit_pool_method}{Character. Currently only \code{"D2"} is implemented
for chi-square-type fit. If no chi-square is available, only residual-based
fit and descriptive quantities are returned.}

\item{consensus_args}{List of additional arguments passed to
\code{CONSENSUS_PROCRUSTES}.}

\item{procrustes_args}{List of additional arguments passed to \code{PROCRUSTES}
for fixed-target alignment.}

\item{rmsea_ci_level}{Numeric. Confidence level for the RMSEA CI.}

\item{rmsr_upper}{Logical. If \code{TRUE}, compute RMSR from the unique
off-diagonal residual correlations. If \code{FALSE}, use the full off-diagonal
matrix.}

\item{...}{Additional arguments passed to \code{\link{EFA}}.}
}
\value{
A list of class \code{"EFA_POOLED"} containing pooled estimates,
residuals, fit indices, the individual fits, and MI diagnostics.
}
\description{
Fits \code{\link{EFA}} to each of several imputed datasets, aligns the
factor solutions to a common factor space, and pools the resulting estimates
and selected fit quantities across imputations.
}
\details{
The function first fits the same \code{\link{EFA}} model to each imputed
dataset. Unrotated loading matrices can optionally be put into a common
signed/permuted factor order before averaging. Rotated loading matrices are
aligned with either a consensus Procrustes target or with the first
imputation's rotated solution as a fixed target. For oblique solutions,
factor intercorrelations are transformed/aligned together with the loading
matrices so that the factor model remains internally consistent.

Point estimates are pooled by arithmetic averaging after alignment. For
oblique rotations, the returned structure matrix is computed from the pooled
aligned pattern matrix and the pooled factor correlation matrix,
\eqn{Structure = \Lambda \Phi}. Communalities are always computed as the
diagonal of the common-factor reproduced correlation matrix,
\eqn{diag(\Lambda \Phi \Lambda')} for oblique rotations and
\eqn{diag(\Lambda \Lambda')} otherwise.

Residuals are not averaged from the per-imputation residual matrices. Instead,
the observed correlation matrices are averaged across imputations and residuals
are calculated from the pooled observed correlation matrix minus the
model-implied correlation matrix of the pooled solution. Consequently,
residual-based fit indices such as RMSR/SRMR are based on pooled residuals.

Fit indices based on the model chi-square are not arithmetic means of the
per-imputation fit indices. If possible, chi-square-type fit is pooled with
the D2 rule. For CFI, the null-model chi-square is D2-pooled as well when
complete-data null-model chi-squares are available. The asymptotic
chi-square approximation to D2 is then used for RMSEA and CFI. AIC and BIC,
if returned, are chi-square-derived descriptive quantities based on this D2
approximation and should not be interpreted as likelihood-based MI
information criteria. D3/D4 pooling is not implemented here because the
current \code{EFA} objects do not expose the likelihood quantities needed
for those methods.

If each component \code{EFA} call was run with \code{se = "np-boot"} and
returned \code{boot.arrays}, pooled bootstrap SEs and Wald-type MI confidence
intervals are computed for loadings, communalities, residuals, and, when
applicable, factor correlations and structure coefficients. Importantly, the
rotated bootstrap loading matrices stored by the component \code{EFA} calls
are not reused directly, because they were aligned to imputation-specific
targets. Instead, the unrotated bootstrap loading matrices are re-aligned to
the final MI target before estimating within-imputation bootstrap covariance
matrices. Rubin-type MI pooling is then applied with
\eqn{T = Ubar + (1 + 1 / m) B}. Confidence intervals for loadings, Phi,
communalities, residuals, and structure coefficients are Wald-type MI
intervals. The confidence level of these pooled intervals is controlled by
\code{p}; the \code{ci} argument passed through \code{...} to the component
\code{EFA} calls is not used for the pooled intervals.
\code{boot.CI$fit_indices_pooled_algorithm}, when available, is a
percentile-style summary obtained by re-running the pooled-fit algorithm over
matched bootstrap replicate indices.
}
\examples{

# create a list of three datasets, mimicking a list you would obtain from
# e.g. mice.
dat_list <- lapply(1:3, function(x) GRiPS_raw[sample(1:nrow(GRiPS_raw), replace = TRUE),])
mod <- EFA_POOLED(dat_list, n_factors = 1, method = "ML")
mod

\donttest{
# add computation of standard errors and CIs
mod <- EFA_POOLED(dat_list, n_factors = 1, method = "ML", se = "np-boot")
mod
}
}
\author{
Andreas Soteriades, Markus Steiner
}
