% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/efa_procrustes.R
\name{.gpa_consensus_target}
\alias{.gpa_consensus_target}
\title{Generalized Procrustes Analysis consensus target across loading matrices}
\usage{
.gpa_consensus_target(
  unrotated_list,
  init_targets = NULL,
  rotation = c("orthogonal", "oblique"),
  start = 1,
  multi_start = FALSE,
  starts = NULL,
  tol = 0.001,
  loss_tol = 1e-06,
  loss_patience = 5,
  convergence = c("either", "target", "loss", "both"),
  min_iter = 2,
  max_iter = 200,
  alpha = 1,
  match_target = TRUE,
  hyper_cutoff = 0.15,
  verbose = FALSE
)
}
\arguments{
\item{unrotated_list}{List of unrotated loading matrices to be aligned. All
matrices must be numeric, finite, and have identical dimensions.}

\item{init_targets}{Optional list of starting target matrices. These are
typically rotated loading matrices from the corresponding analyses. If
\code{NULL}, \code{unrotated_list} is used.}

\item{rotation}{Character string, either \code{"orthogonal"} or \code{"oblique"}.}

\item{start}{Either a single integer selecting an element of \code{init_targets},
or an explicit target matrix. Used when \code{multi_start = FALSE}.}

\item{multi_start}{Logical. If \code{FALSE}, perform one consensus-target run. If
\code{TRUE}, repeat the single-start algorithm for each element of \code{starts}.}

\item{starts}{Integer vector selecting elements of \code{init_targets} used as
starting targets when \code{multi_start = TRUE}. If \code{NULL}, all elements of
\code{init_targets} are used. Duplicate entries are removed.}

\item{tol}{Positive relative Frobenius-norm convergence tolerance for the
outer target update.}

\item{loss_tol}{Positive tolerance for the relative change in the outer
consensus loss. If \code{NULL}, loss-based convergence is disabled. It cannot be
\code{NULL} when \code{convergence} is \code{"loss"} or \code{"both"}.}

\item{loss_patience}{Positive integer. Number of consecutive iterations with
relative loss change below \code{loss_tol} required for loss-based convergence.}

\item{convergence}{Character string controlling the stopping rule. \code{"either"}
stops when either target or loss convergence is satisfied; \code{"target"} uses
only target change; \code{"loss"} uses only loss change; \code{"both"} requires both.}

\item{min_iter}{Non-negative integer. Minimum number of outer iterations
before convergence can be declared.}

\item{max_iter}{Positive integer. Maximum number of outer consensus
iterations.}

\item{alpha}{Damping factor for the target update. \code{alpha = 1} uses the full
centroid update. Smaller values, such as \code{0.5}, can reduce oscillation.}

\item{match_target}{Logical. If \code{TRUE}, the updated centroid is signed and
column-matched to the previous target before convergence is evaluated.}

\item{hyper_cutoff}{Non-negative cutoff used by \code{.hyperplane_count()} for
summary output.}

\item{verbose}{Logical; if \code{TRUE}, print convergence messages for the outer
loop.}
}
\value{
A list with the converged target, aligned matrices, pooled loadings,
pooled \code{Phi}, convergence history, inner-alignment diagnostics, and
hyperplane summaries. If \code{multi_start = TRUE}, the \code{multi_start} element also
contains the per-start losses, convergence indicators, run summaries, all
run objects, and between-run Tucker congruence matrices.
}
\description{
Internal helper that constructs a Generalized Procrustes Analysis (GPA)
consensus target across a list of loading matrices and returns the aligned
loadings, the centroid target, and convergence diagnostics. Used by
\code{\link[=efa_mi]{efa_mi()}} under \code{target_method = "consensus"} to build a common
rotation target across imputations. Oblique rotations are not supported
here: the iteration is degenerate for oblique transforms with more than
one factor (cf. Lorenzo-Seva & Van Ginkel 2016, who use a Promin step on
top of the centroid rather than iterated oblique Procrustes); callers
should pass the unrotated solutions of an orthogonal rotation, or use
\code{target_method = "first_target"}.
}
\details{
The iteration alternates two steps:
\enumerate{
\item each loading matrix is aligned to the current target with \code{efa_procrustes()};
\item the target is updated to the elementwise centroid of the aligned matrices.
}

The outer loop stops when the target stabilises, when the consensus loss
stabilises, or when both criteria are satisfied.

If \code{multi_start = FALSE}, one consensus run is performed. If
\code{multi_start = TRUE}, the same engine is repeated for the selected starting
targets and the run with the smallest final mean loss is returned as the
main result; all runs and a between-run congruence summary are retained in
the \code{multi_start} component.
}
\references{
Gower, J. C. (1975). Generalized Procrustes analysis. \emph{Psychometrika}, 40,
33-51.

Van Ginkel, J. R., & Kroonenberg, P. M. (2014). Using Generalized
Procrustes Analysis for Multiple Imputation in Principal Component
Analysis. \emph{Journal of Classification}, 31, 242-269.

Lorenzo-Seva, U., & Van Ginkel, J. R. (2016). Multiple Imputation of
missing values in exploratory factor analysis of multidimensional scales:
estimating latent trait scores. \emph{Anales de Psicologia}, 32, 596-608.
}
\keyword{internal}
