Skip to contents

Align Basis Vectors Across Subjects Using Hungarian Algorithm

Source: R/alignment_utils.R
align_basis_across_subjects.Rd

This function aligns the columns (basis vectors) of each subject's basis matrix to a reference basis using the Hungarian algorithm for optimal assignment. This ensures that corresponding components across subjects are in the same order, which improves clustering accuracy in two-step methods.

Usage

align_basis_across_subjects(
  W_list,
  reference = 1,
  method = "correlation",
  verbose = FALSE
)

Arguments

W_list

A list of basis matrices, one per subject. Each matrix should be M x r (M channels, r components). These are typically the output from individual PCA or FA decompositions in Step 1 of the two-step baseline method.

reference

Integer index of the reference subject (default: 1). The basis of this subject will be used as the reference for alignment. All other subjects' basis vectors will be reordered to match this reference.

method

Character string specifying the similarity metric. Currently only "correlation" is supported (Pearson correlation between basis vectors). Future versions may support "cosine" similarity.

verbose

Logical. If TRUE, prints informational messages during alignment. Default is FALSE to avoid spamming output during parameter sweeps.

Value

A list of aligned basis matrices with the same structure as W_list, but with columns reordered to match the reference basis. The reference subject's basis remains unchanged. Each element is an M x r matrix where columns have been permuted to maximize correspondence with the reference.

Details

## When This Function Is Called

This function is automatically called in Step 1.5 of the two-step baseline method (fit_two_step_baseline), between individual decomposition (Step 1) and clustering (Step 2). It is called regardless of the refine_assignments parameter setting, as alignment improves clustering accuracy in both modes.

## Why Alignment Is Necessary

Individual PCA/FA produces basis vectors in arbitrary order. Without alignment, the first component of subject A may represent a different pattern than the first component of subject B. This arbitrary ordering causes k-means clustering in Step 2 to group unrelated components together, leading to poor cluster assignments and low ARI (Adjusted Rand Index).

## How Alignment Works

The alignment process works as follows:

  1. Select a reference basis (default: first subject).

  2. For each subject, compute a similarity matrix between the reference basis columns and the subject's basis columns using Pearson correlation.

  3. Use the Hungarian algorithm (clue::solve_LSAP) to find the optimal column permutation that maximizes total similarity.

  4. Reorder the subject's basis columns according to this permutation.

The Hungarian algorithm solves the linear sum assignment problem, finding the permutation that maximizes the sum of similarities. The correlation matrix is transformed from [-1, 1] to [0, 1] to satisfy solve_LSAP's requirement for nonnegative entries. This affine transformation preserves the optimal matching. After permutation, column signs are corrected to ensure positive correlation with the reference, preventing k-means from splitting components by arbitrary sign.

## Relationship with refine_assignments

This alignment step is independent of the refine_assignments parameter in fit_two_step_baseline():

  • refine_assignments = FALSE: Alignment is applied, then k-means clustering is performed on aligned basis vectors. No reassignment after cluster-specific model fitting.

  • refine_assignments = TRUE: Alignment is applied, k-means clustering is performed, cluster-specific models are fitted, and then subjects are reassigned based on reconstruction error.

In both cases, alignment ensures that corresponding components are in the same order before clustering, which significantly improves clustering accuracy.

See also

fit_two_step_baseline for the two-step baseline method that uses this alignment function.

Examples

if (FALSE) { # \dontrun{
# Example 1: Basic usage with simulated data
library(synergyMixR)

# Simulate some basis matrices (8 channels, 2 components, 3 subjects)
set.seed(123)
W_list <- list(
  matrix(rnorm(8*2), 8, 2),
  matrix(rnorm(8*2), 8, 2),
  matrix(rnorm(8*2), 8, 2)
)

# Align to first subject
W_aligned <- align_basis_across_subjects(W_list, reference = 1)

# Check that dimensions are preserved
sapply(W_aligned, dim)  # Each should be 8 x 2

# Example 2: Usage within two-step baseline
# This is done automatically in fit_two_step_baseline()
sim_data <- simulate_mixture_data(N = 50, K = 2, r = 2, M = 6, T_each = 100)

# Extract individual basis vectors (Step 1)
W_list_individual <- lapply(sim_data$list_of_data, function(X) {
  pca_res <- prcomp(X, center = TRUE, scale. = FALSE)
  pca_res$rotation[, 1:2]  # First 2 components
})

# Align basis vectors (Step 1.5) - this happens automatically in fit_two_step_baseline
W_list_aligned <- align_basis_across_subjects(W_list_individual, reference = 1)

# Now W_list_aligned can be used for clustering (Step 2)
# with improved accuracy due to aligned components
} # }