Skip to contents

HATSA Projector Object

Source: R/hatsa_projector.R
hatsa_projector.Rd

An S3 object of class hatsa_projector that stores the results of a Harmonized Tensors SVD Alignment (HATSA) analysis. This object inherits from multiblock_biprojector (from the `multivarious` package) and is designed to integrate HATSA outputs into a common framework for multiblock data analysis.

Creates a hatsa_projector object, which stores the results of the HATSA algorithm and is designed to integrate with the multivarious package, inheriting from multiblock_biprojector.

Usage

hatsa_projector(hatsa_core_results, parameters)

Arguments

hatsa_core_results

A list containing the core outputs from the HATSA algorithm. Expected elements include:

  • 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 (length k-1).

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

parameters

A list of parameters used to run HATSA. Expected elements include:

  • k: The number of spectral components (rank).

  • N_subjects: The number of subjects.

  • V_p: The number of parcels/vertices per subject.

  • method: A string, typically hatsa_core.

Value

A `hatsa_projector` object.

An object of class c("hatsa_projector", "multiblock_biprojector", "projector", "list"). This object contains:

  • v: The group-level loading matrix (mean aligned sketch, V_p x k).

  • s: The stacked scores matrix (concatenated aligned sketches, (N*V_p) x k).

  • sdev: Component standard deviations (defaulted to 1s, length k).

  • preproc: A preprocessing object, set to multivarious::prep(multivarious::pass()).

  • block_indices: A list defining rows in s corresponding to each subject block.

  • R_final_list: Stored from input.

  • U_original_list: Stored from input.

  • Lambda_original_list: Stored from input (crucial for voxel projection).

  • Lambda_original_gaps_list: Stored from input.

  • T_anchor_final: Stored from input.

  • parameters: Stored from input.

  • method: Stored from input parameters, typically hatsa_core.

Fields

v

A numeric matrix (V_p x k) representing the mean aligned sketch, serving as the group-level template or common loadings.

s

A numeric matrix ((N*V_p) x k) of stacked aligned sketches for all subjects. These are the subject-specific parcel scores in the common space.

sdev

A numeric vector of length k, representing component-wise standard deviations (or scales). Currently defaults to a vector of 1s.

preproc

A pre_processor object (from `multivarious`). For HATSA, this is typically `prep(pass())` as the input data to `run_hatsa_core` is already processed up to the point of raw time-series per subject.

block_indices

A list defining which rows in the scores matrix `s` belong to which subject (block).

R_final_list

A list of subject-specific rotation matrices (k x k) used to align each subject's original sketch to the common space.

U_original_list

A list of subject-specific original (unaligned) sketch matrices (V_p x k) derived from their parcel-level graph Laplacians.

Lambda_original_list

A list of numeric vectors, where each vector contains the k original eigenvalues corresponding to the eigenvectors in `U_original_list` for that subject. These are crucial for Nyström voxel projection.

Lambda_original_gaps_list

A list of numeric vectors. Each vector contains the k-1 eigengap ratios `(λ_j+1 - λ_j) / λ_j` for the corresponding subject's original eigenvalues. Useful for assessing spectral stability.

T_anchor_final

A numeric matrix (V_a x k, where V_a is the number of anchors) representing the final group anchor template after Procrustes alignment.

parameters

A list containing the input parameters used for the HATSA run (e.g., `k`, `V_p`, `N_subjects`, `anchor_indices`, `k_conn_pos`, `k_conn_neg`, `n_refine`).

method

A character string, typically "hatsa_core", indicating the method used to generate the projector.

U_aligned_list

(Internal) A list of subject-specific aligned sketch matrices (V_p x k). While `s` provides the stacked version, this list might be retained internally from the `run_hatsa_core` output passed to the constructor. For user access to aligned sketches per subject, one would typically use `project_block(object, block = i)` or segment `scores(object)` using `block_indices(object)`.

See also

run_hatsa_core, predict.hatsa_projector, project_voxels.hatsa_projector

Examples

# This is a conceptual example, as real data structures are complex.
# Assuming hatsa_results and params are populated from run_hatsa_core:
# projector_obj <- hatsa_projector(
#   hatsa_core_results = list(
#     U_aligned_list = replicate(5, matrix(rnorm(100*10), 100, 10), simplify=FALSE),
#     R_final_list = replicate(5, diag(10), simplify=FALSE),
#     U_original_list = replicate(5, matrix(rnorm(100*10), 100, 10), simplify=FALSE),
#     Lambda_original_list = replicate(5, runif(10, 0.1, 1), simplify=FALSE), # example
#     Lambda_original_gaps_list = replicate(5, runif(9, 0.05, 0.5), simplify=FALSE), # example
#     T_anchor_final = matrix(rnorm(5*10), 5, 10)
#   ),
#   parameters = list(
#     k=10,
#     N_subjects=5,
#     V_p=100,
#     method="hatsa_core"
#   )
# )
# class(projector_obj)
# names(projector_obj)