HATSA Quality Control and Stability Plots

This file contains functions for generating QC plots, such as k-stability plots, for HATSA results.

Usage

plot_k_stability_hatsa(
  projector_list_over_k,
  metrics_to_plot = c("Hk", "CV_eigen_cov"),
  Hk_dispersion_stat = "mean",
  spd_cov_coeffs_options = list(),
  Hk_options = list(),
  verbose = FALSE
)

Arguments

projector_list_over_k

A list of hatsa_projector objects. Each object should be the result of a HATSA run with a different 'k'. The list can be named with k values, or k will be extracted from each object.

metrics_to_plot

A character vector specifying which metrics to plot. Possible values are "Hk" (Alignment Homogeneity based on Riemannian dispersion of covariance of aligned coefficients) and/or "CV_eigen_cov" (Mean Coefficient of Variation of eigenvalues of covariance of aligned coefficients). Default is c("Hk", "CV_eigen_cov").

Hk_dispersion_stat

Character, either "mean" (default) or "median". Specifies which statistic from riemannian_dispersion_spd to use for Hk.

spd_cov_coeffs_options

A list of additional arguments to pass to hatsa::get_spd_representations(..., type = "cov_coeffs"). For example, list(spd_regularize_epsilon = 1e-6).

Hk_options

A list of additional arguments to pass to hatsa::riemannian_dispersion_spd(...). For example, list(tangent_metric = "logeuclidean", use_geometric_median = FALSE). Note that `use_geometric_median` will be overridden by `Hk_dispersion_stat == "median"`.

verbose

Logical, if TRUE, prints progress messages. Default is FALSE.

Value

A ggplot object containing the stability plots, or NULL if no valid metrics can be computed.

Examples

# Conceptual example:
# Assume projector_k3, projector_k4, projector_k5 are hatsa_projector objects
# k_list <- list("3" = projector_k3, "4" = projector_k4, "5" = projector_k5)
# plot_k_stability_hatsa(k_list)

# To run if example data were available:
# if (requireNamespace("ggplot2", quietly = TRUE) &&
#     exists("generate_synthetic_hatsa_output_list")) {
#   example_projector_list <- generate_synthetic_hatsa_output_list(
#      k_values = c(3, 4, 5, 6), N_subjects = 5, V_p = 20
#   )
#   plot_k_stability_hatsa(example_projector_list)
# }