Perform Geometric Generalized Procrustes Analysis (Geo-GPA) on SO(k) — perform_geometric_gpa

Refines a set of rotation matrices and a group anchor template using either an SVD-based iterative Procrustes approach (default) or a variant where the template update is oriented by the Frechet mean of rotations. The SVD mode minimizes the Frobenius distance between rotated subject anchors and the template. The Riemannian mode aims to make the template's orientation consistent with the Frechet mean of subject rotations, which implicitly relates to minimizing intrinsic SO(k) geodesic distances for the rotations' central tendency.

Usage

perform_geometric_gpa_refinement(
  A_originals_list,
  n_refine = 10,
  k,
  m_rows,
  tol = 1e-07,
  rotation_mode = c("svd", "riemannian"),
  frechet_mean_options = list(),
  verbose = TRUE,
  initial_R_list = NULL
)

Arguments

A_originals_list: A list of subject-specific anchor matrices (m_rows x k). Each matrix `A_i` contains the rows from `U_original_list[[i]]` corresponding to the `unique_anchor_indices`.
n_refine: Integer, number of GPA refinement iterations. Default: 10.
k: Integer, the dimensionality of the sketch space (number of columns in A_i and R_i).
m_rows: Integer, number of anchor features (number of rows in A_i).
tol: Numeric, tolerance for convergence based on the relative Frobenius norm change in the template `T_template`. Default: 1e-7.
rotation_mode: Character string, one of `"svd"` (default) or `"riemannian"`. - `"svd"`: Uses SVD to find the closest SO(k) rotation for each subject to align `A_i` with `T_template`. `T_template` is the Euclidean mean of `A_i R_i`. This mode minimizes the sum of squared Frobenius distances `sum(||A_i R_i - T||_F^2)`. - `"riemannian"`: Individual rotations `R_i` are updated as in `"svd"` mode. However, `T_template` is updated by first computing the Frechet mean (`R_bar`) of the current `R_list`, then averaging `A_i R_i R_bar^T` (configurations aligned to `R_bar`'s frame), and finally rotating this average back by `R_bar`. This mode seeks to make the template orientation consistent with the intrinsic mean of the rotation ensemble.
frechet_mean_options: A list of options to pass to `hatsa::frechet_mean_so_k`, used if `rotation_mode = "riemannian"` or for the final `R_bar_final` computation. Example: `list(max_iter = 20, tol = 1e-5)`. Defaults are used if not provided.
verbose: Logical, if TRUE, prints progress messages. Default TRUE.
initial_R_list: Optional list of initial k x k rotation matrices. If NULL, identity matrices are used.

Value

A list containing: - `R_final_list`: List of final subject-specific rotation matrices (k x k). - `T_anchor_final`: The final group anchor template matrix (m_rows x k). - `R_bar_final`: The Fréchet mean of the final `R_final_list`.

Details

Matrices in `A_originals_list` are checked to be numeric and to have dimensions `m_rows x k` before the initial template is computed. Invalid matrices are ignored with their indices reported in a warning. If all matrices are invalid, the function returns identity rotations and an `NA` template rather than stopping with an error.