Plot Multidimensional Scaling (MDS) of Subjects based on SPD Matrix Distances

Computes Riemannian distances between subjects based on their SPD matrix representations, performs classical MDS, and plots the subjects in a low-dimensional space (typically 2D).

Usage

plot_mds_spd_subjects(
  projector_object,
  k_mds = 2,
  spd_representation_type = "cov_coeffs",
  dist_mat_options = list(),
  subject_info = NULL,
  color_by_column = NULL,
  shape_by_column = NULL,
  plot_labels = FALSE,
  cmdscale_add = TRUE,
  verbose = FALSE
)

Arguments

projector_object: A hatsa_projector or task_hatsa_projector object.
k_mds: Integer, the number of MDS dimensions to compute (default: 2).
spd_representation_type: Character string, the type of SPD representation to use for distance calculation (e.g., "cov_coeffs", "fc_conn"). This is passed to hatsa::riemannian_distance_matrix_spd.
dist_mat_options: A list of additional arguments to pass to hatsa::riemannian_distance_matrix_spd. This can include arguments like spd_metric, subject_data_list (if needed for the chosen type), k_conn_params, spd_regularize_epsilon, verbose, etc.
subject_info: Optional. A data frame with N_subjects rows. If provided, it can contain a column named subject_label for text labels on the plot, and other columns that can be mapped to ggplot aesthetics (e.g., a column named by color_by_column or shape_by_column). Row names of subject_info should correspond to subject indices (1 to N) or be actual subject IDs if the distance matrix has them.
color_by_column: Character string. If subject_info is provided, the name of the column in subject_info to use for coloring points.
shape_by_column: Character string. If subject_info is provided, the name of the column in subject_info to use for point shapes.
plot_labels: Logical, whether to plot subject labels near points. Requires a subject_label column in subject_info or uses default labels. Consider using the ggrepel package for better label placement if many points overlap (not directly implemented here to reduce dependencies).
cmdscale_add: Logical, the add argument for stats::cmdscale (default: TRUE). Useful if distances are not perfectly Euclidean.
verbose: Logical, if TRUE, prints progress messages. Default is FALSE.

Value

A list containing:

plot: A ggplot object for the MDS plot.
mds_results: The output from stats::cmdscale, including coordinates (points), eigenvalues (eig), etc.
distance_matrix: The computed Riemannian distance matrix.
valid_subject_indices: Indices of subjects included in MDS (after NA removal).

Returns NULL if critical steps fail (e.g., distance matrix computation).

Examples

# Conceptual example, assuming 'proj_obj' is a hatsa_projector object
# and subject_covariates is a data frame with N_subjects rows
# and columns "ID" (for labels), "Group" (for color).

# if (requireNamespace("ggplot2", quietly = TRUE) &&
#     exists("generate_synthetic_hatsa_output") && # Assuming a single projector gen
#     exists("hatsa_projector")) { # Ensure constructor is available
#
#   # Generate a single projector object
#   N_subj_example <- 10
#   V_p_example <- 30
#   k_example <- 5
#   proj_params <- list(k = k_example, N_subjects = N_subj_example, V_p = V_p_example,
#                       method="hatsa_core", anchor_indices = 1:5)
#   proj_core_res <- list(
#      U_aligned_list = replicate(N_subj_example, matrix(rnorm(V_p_example*k_example), V_p_example, k_example), simplify=FALSE),
#      R_final_list = replicate(N_subj_example, diag(k_example), simplify=FALSE),
#      U_original_list = replicate(N_subj_example, matrix(rnorm(V_p_example*k_example), V_p_example, k_example), simplify=FALSE),
#      Lambda_original_list = replicate(N_subj_example, sort(runif(k_example, 0.1, 1), decreasing=TRUE), simplify=FALSE),
#      Lambda_original_gaps_list = replicate(N_subj_example, {
#         lams <- sort(runif(k_example, 0.1, 1), decreasing=TRUE); if(k_example>1) (lams[1:(k_example-1)] - lams[2:k_example])/lams[2:k_example] else numeric(0)
#         }, simplify=FALSE),
#      T_anchor_final = matrix(rnorm(min(5,V_p_example)*k_example), min(5,V_p_example), k_example)
#    )
#   proj_obj <- hatsa::hatsa_projector(proj_core_res, proj_params)
#
#   # Example subject_info
#   subject_covariates <- data.frame(
#     subject_label = paste0("S", 1:N_subj_example),
#     Group = factor(rep(c("A", "B"), each = N_subj_example / 2)),
#     stringsAsFactors = FALSE
#   )
#
#   # Run MDS plot
#   mds_plot_result <- plot_mds_spd_subjects(
#     projector_object = proj_obj,
#     spd_representation_type = "cov_coeffs",
#     dist_mat_options = list(spd_metric = "logeuclidean", spd_regularize_epsilon = 1e-6),
#     subject_info = subject_covariates,
#     color_by_column = "Group",
#     plot_labels = TRUE,
#     verbose = TRUE
#   )
#   if (!is.null(mds_plot_result)) print(mds_plot_result$plot)
# }