Skip to contents

Plot Basis UMAP Embedding

Source: R/visualize_twostep_diagnostics.R
plot_basis_umap.Rd

Creates a UMAP or PCA embedding of basis vectors at the component level (not subject level) to visualize clustering quality. Each point represents one basis vector (subject x component), colored by true cluster and shaped by estimated cluster. This helps diagnose clustering failures in the Two-step algorithm.

Usage

plot_basis_umap(
  W_list,
  z_true,
  z_est = NULL,
  method = "umap",
  theme_base_size = 14
)

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.

z_true

Vector of true cluster assignments (length N). Required for coloring points by true cluster.

z_est

Optional vector of estimated cluster assignments (length N). If provided, points will be shaped by estimated cluster to show mismatches. Default is NULL.

method

Character string specifying the embedding method: "umap" or "pca". Default is "umap".

theme_base_size

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

Value

A ggplot object showing low-dimensional embedding of basis vectors (Nxr points), colored by true cluster and optionally shaped by estimated cluster.

Details

This function extends plot_cluster_embedding() to work at the basis vector level rather than the subject level. Instead of showing N points (one per subject), it shows Nxr points (one per basis vector).

This visualization is particularly useful for diagnosing Two-step clustering failures because it reveals:

  • Whether basis vectors from the same true cluster are close together

  • Whether k-means clustering in Step 2 correctly separated clusters

  • Which specific basis vectors were misclassified

  • Whether alignment in Step 1.5 successfully matched corresponding components

When z_est is provided, misclassified basis vectors are easy to spot as points with different colors (true cluster) and shapes (estimated cluster).

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 basis vector embedding
plot_basis_umap(fit$W_list, z_true=sim$z_true, z_est=fit$z_est)

# Use PCA instead of UMAP
plot_basis_umap(fit$W_list, z_true=sim$z_true, z_est=fit$z_est, method="pca")
} # }