Skip to contents

Plot Aligned Basis Heatmaps

Source: R/visualize_twostep_diagnostics.R
plot_aligned_basis_heatmaps.Rd

Creates heatmaps of basis vectors (W matrices) for each subject and component, showing how well the Two-step alignment procedure worked. Compares aligned basis vectors with true synergies (if available) to diagnose alignment failures.

Usage

plot_aligned_basis_heatmaps(
  W_list,
  W_true = NULL,
  z_true = NULL,
  z_est = NULL,
  max_subjects = 30,
  theme_base_size = 10
)

Arguments

W_list

List of basis matrices, one per subject. Each matrix should be M x r (M channels/muscles, r components/synergies). This is typically the output from fit_two_step_baseline()$W_list.

W_true

Optional list of true basis matrices for comparison (from simulation data, e.g., sim$Lambda_list). If provided, true synergies will be shown alongside estimated ones. Default is NULL.

z_true

Optional vector of true cluster assignments (length N). Used to organize subjects by cluster. If NULL, subjects are shown in original order.

z_est

Optional vector of estimated cluster assignments (length N). Used to show clustering results alongside basis vectors. Default is NULL.

max_subjects

Maximum number of subjects to display. If N > max_subjects, a random sample will be shown. Default is 30.

theme_base_size

Base font size for the plot theme. Default is 10.

Value

A ggplot object showing heatmaps of basis vectors organized by subject and component, with optional comparison to true synergies.

Details

This function visualizes the output of the Two-step alignment procedure (align_basis_across_subjects()) to diagnose alignment failures. Each row represents one subject's basis vector for a specific component. Columns represent muscles/channels. Colors indicate the weight/loading values.

When W_true is provided, the function creates a side-by-side comparison showing true synergies (left panel) and estimated aligned basis vectors (right panel). This helps identify whether alignment failures are due to:

  • Poor individual decomposition (Step 1)

  • Alignment algorithm issues (Step 1.5)

  • Fundamental differences between true and estimated structures

Examples

if (FALSE) { # \dontrun{
# Simulate data with known ground truth
sim <- simulate_dynamic_synergy_data(N=30, K=3, r=3, M=8, T_each=200)

# Fit Two-step baseline
fit <- fit_two_step_baseline(
  sim$list_of_data, r=3, K=3, method="PCA",
  z_true=sim$z_true, align_basis=TRUE
)

# Visualize aligned basis vectors
plot_aligned_basis_heatmaps(fit$W_list, z_est=fit$z_est)

# Compare with true synergies
plot_aligned_basis_heatmaps(
  fit$W_list, 
  W_true=sim$Lambda_list,
  z_true=sim$z_true,
  z_est=fit$z_est
)
} # }