visualize_distances: Visualize Distance Matrices via MDS, Heatmap, or Network Graph

Description

This function provides a unified interface to visualize distance matrices using classical or weighted Multidimensional Scaling (MDS), heatmaps, or network graphs. Group annotations can be provided for coloring.

Usage

visualize_distances(
  dist_mat,
  method = c("mds_classic", "mds_weighted", "heatmap", "qgraph"),
  k = 3,
  weights = NULL,
  group = NULL,
  main_title = NULL,
  tol = 1e-10,
  ...
)

Value

The plotting object is returned and automatically printed:

MDS plots return a ggmatrix from GGally.
Heatmaps return a pheatmap object.
Network graphs are plotted directly (returns NULL).

Arguments

dist_mat

A square distance matrix (numeric matrix) or a dist object.

method

Character string specifying the visualization method. Options are:

"mds_classic": Classical MDS (cmdscale).
"mds_weighted": Weighted MDS (wcmdscale, requires weights).
"heatmap": Heatmap with optional clustering and group annotations.
"qgraph": Network graph representation of similarity.

k

Integer. Number of dimensions to retain for MDS (default 3). Must be >=1 and <= min(4, n_obs-1).

weights

Optional numeric vector of weights for weighted MDS. Must match the number of observations.

group

Optional factor or vector indicating group membership for coloring plots.

main_title

Optional character string specifying the main title of the plot.

tol

Numeric tolerance for checking approximate symmetry (default 1e-10).

...

Additional arguments passed to internal plotting functions (plot_heatmap or plot_qgraph).

Details

visualize_distances is a wrapper around three internal plotting functions:

plot_mds: Creates a pairwise scatterplot matrix of MDS coordinates with density plots on the diagonal.
plot_heatmap: Plots a heatmap of the distance matrix with hierarchical clustering and optional group annotations.
plot_qgraph: Plots a network graph where nodes represent observations and edges represent similarity.

The function validates that dist_mat is square, symmetric, and has zero diagonal elements. If a distance matrix has a trimmed_idx attribute and group is not provided, a factor indicating "Trimmed" vs "Outlier" is created automatically.

Examples

Run this code

# Load iris dataset
data(iris)

# Compute Euclidean distances on numeric columns
dist_iris <- dist(iris[, 1:4])

# Create a grouping factor based on Species
group_species <- iris$Species

# --------------------------------------
# Classical MDS (2D)
# --------------------------------------
visualize_distances(
  dist_mat = dist_iris,
  method = "mds_classic",
  k = 2,
  group = group_species,
  main_title = "Classical MDS - Iris Dataset - Euclidean Distance"
)

# --------------------------------------
# Weighted MDS (uniform weights)
# --------------------------------------
weights <- rep(1, nrow(iris))
visualize_distances(
  dist_mat = dist_iris,
  method = "mds_weighted",
  k = 2,
  weights = weights,
  group = group_species,
  main_title = "Weighted MDS - Iris Dataset - Euclidean Distance"
)

# --------------------------------------
# Heatmap (limit rows to 30)
# --------------------------------------
visualize_distances(
  dist_mat = dist_iris,
  method = "heatmap",
  group = group_species,
  main_title = "Iris Heatmap by Species - Euclidean Distance",
  max_n = 30,
  palette = "YlGnBu",
  clustering_method = "complete",
  annotation_legend = TRUE,
  stratified_sampling = TRUE,
  seed = 123
)

# --------------------------------------
# Network Graph (limit nodes to 30)
# --------------------------------------
visualize_distances(
  dist_mat = dist_iris,
  method = "qgraph",
  group = group_species,
  max_nodes = 30,
  label_size = 2,
  edge_threshold = 0.1,
  layout = "spring",
  seed = 123,
  main_title = "Iris Network Graph by Species - Euclidean Distance"
)