Skip to contents

Run Geometric Harmonized Tensors SVD Alignment (Geo-HATSA) Core Algorithm

Source: R/geo_hatsa_core_algorithm.R
run_geo_hatsa_core.Rd

This function implements a variant of the HATSA core algorithm where the Generalized Procrustes Analysis (GPA) step for refining rotations and the group anchor template uses a geometric approach on SO(k) via `perform_geometric_gpa_refinement`.

Usage

run_geo_hatsa_core(
  subject_data_list,
  anchor_indices,
  spectral_rank_k,
  k_conn_pos = 10,
  k_conn_neg = 10,
  n_refine = 10,
  V_p = NULL,
  use_dtw = FALSE,
  graph_mode = "anchor_block",
  schur_eps = 0.01,
  eigengap_tol = 1e-09,
  rotation_mode = "svd",
  verbose = TRUE,
  frechet_mean_options = list(),
  gpa_tol = 1e-07
)

Arguments

subject_data_list

A list of subject-level parcel time-series matrices. Each element is a numeric matrix (T_i time points x V_p parcels).

anchor_indices

A numeric vector of indices for the anchor parcels (1-based, referring to columns of matrices in `subject_data_list`).

spectral_rank_k

Integer, the number of spectral components (k) to retain.

k_conn_pos

Integer, number of positive degree neighbors for k-NN graph construction.

k_conn_neg

Integer, number of negative degree neighbors (if applicable, often same as pos).

n_refine

Integer, number of GPA refinement iterations.

V_p

Integer, number of parcels (vertices per subject). If NULL, inferred.

use_dtw

Logical, whether to use Dynamic Time Warping for FC graph (passed to `compute_subject_connectivity_graph_sparse`). Default FALSE.

graph_mode

Character string, specifies the graph construction method. Options include `"anchor_block"` (default), `"schur"` (Schur complement), `"full"` (standard kNN graph). Passed to `compute_subject_connectivity_graph_sparse`.

schur_eps

Numeric, epsilon for Schur complement graph construction if `graph_mode = "schur"`. Default: 0.01.

eigengap_tol

Numeric, tolerance for checking the eigengap after spectral sketch computation. If `lambda_k - lambda_k+1 < eigengap_tol`, a warning is issued for that subject. Default: 1e-9.

rotation_mode

Character string, passed to `perform_geometric_gpa_refinement`. One of `"svd"` (default) or `"riemannian"`. See that function for details.

verbose

Logical, if TRUE, prints progress messages. Default TRUE.

frechet_mean_options

A list of options to pass to `hatsa::frechet_mean_so_k` within `perform_geometric_gpa_refinement`. Default: `list()`.

gpa_tol

Numeric, tolerance for convergence in `perform_geometric_gpa_refinement`. Default: 1e-7.

Value

A list containing the core Geo-HATSA results and QC metrics:

  • U_aligned_list: List of subject-specific aligned sketch matrices (V_p x k).

  • R_final_list: List of subject-specific rotation matrices (k x k).

  • U_original_list: List of subject-specific original sketch matrices (V_p x k).

  • Lambda_original_list: List of subject-specific original eigenvalues (length k).

  • Lambda_original_gaps_list: List of subject-specific eigengap ratios.

  • T_anchor_final: The final group anchor template matrix (N_anchors x k).

  • R_bar_final: The final Fréchet mean of rotation matrices from Geo-GPA.

  • qc_metrics: A data frame with per-subject QC flags (laplacian_computed_ok, sketch_computed_ok, eigengap_sufficient).

This list is intended to be used as input to the `hatsa_projector` constructor, though `R_bar_final` is an additional output specific to Geo-HATSA.

See also

perform_geometric_gpa_refinement, hatsa_projector