Align several loading matrices to a common Procrustes consensus target.
CONSENSUS_PROCRUSTES(
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,
oblique_maxit = 500,
oblique_eps = 1e-05,
oblique_max_line_search = 10,
oblique_step0 = 1,
oblique_normalize = FALSE,
oblique_random_starts = 0,
oblique_random_starts_stage = c("final", "none", "outer", "both"),
oblique_screen_keep = 2,
oblique_triage_maxit = 25,
oblique_triage_improve_tol = 0,
verbose = FALSE
)A list with the converged target, aligned matrices, pooled loadings, pooled `Phi`, convergence history, inner-alignment diagnostics, and hyperplane summaries. If `multi_start = TRUE`, the `multi_start` element also contains the per-start losses, convergence indicators, run summaries, all run objects, and between-run Tucker congruence matrices.
List of unrotated loading matrices to be aligned. All matrices must be numeric, finite, and have identical dimensions.
Optional list of starting target matrices. These are typically rotated loading matrices from the corresponding analyses. If `NULL`, `unrotated_list` is used.
Character string, either `"orthogonal"` or `"oblique"`.
Either a single integer selecting an element of `init_targets`, or an explicit target matrix. Used when `multi_start = FALSE`.
Logical. If `FALSE`, perform one consensus-target run. If `TRUE`, repeat the single-start algorithm for each element of `starts`.
Integer vector selecting elements of `init_targets` used as starting targets when `multi_start = TRUE`. If `NULL`, all elements of `init_targets` are used. Duplicate entries are removed.
Positive relative Frobenius-norm convergence tolerance for the outer target update.
Positive tolerance for the relative change in the outer consensus loss. If `NULL`, loss-based convergence is disabled. It cannot be `NULL` when `convergence` is `"loss"` or `"both"`.
Positive integer. Number of consecutive iterations with relative loss change below `loss_tol` required for loss-based convergence.
Character string controlling the stopping rule. `"either"` stops when either target or loss convergence is satisfied; `"target"` uses only target change; `"loss"` uses only loss change; `"both"` requires both.
Non-negative integer. Minimum number of outer iterations before convergence can be declared.
Positive integer. Maximum number of outer consensus iterations.
Damping factor for the target update. `alpha = 1` uses the full centroid update. Smaller values, such as `0.5`, can reduce oscillation.
Logical. If `TRUE`, the updated centroid is signed and column-matched to the previous target before convergence is evaluated.
Non-negative cutoff used by `.hyperplane_count()` for summary output.
Parameters passed to `PROCRUSTES()` when `rotation = "oblique"`.
Number of random starts used by the inner oblique solver. See `oblique_random_starts_stage` for when these are used.
Character string controlling whether random starts are used during the outer consensus loop, the final alignment pass, both, or neither. The default `"final"` keeps the outer loop smooth by using warm starts during iteration and applies random-start protection only in the final pass.
Screening and triage parameters passed to the compiled oblique solver when random starts are used.
Logical; if `TRUE`, print convergence messages for the outer loop.
The function iterates between two steps:
1. each loading matrix is independently aligned to the current target with `PROCRUSTES()`; and 2. the target is updated to the centroid, i.e., the elementwise average of the aligned matrices.
This makes the target symmetric across imputations or samples: no single solution is permanently privileged as the reference. The outer loop can stop when the target stabilizes, when the consensus loss stabilizes, or when both criteria are satisfied.
If `multi_start = FALSE`, one consensus run is performed. If `multi_start = TRUE`, the same single-start 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 `multi_start` component.
Gower, J. C. (1975). Generalized Procrustes analysis. *Psychometrika*, 40, 33-51.