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

In dbrobust: Robust Distance-Based Visualization and Analysis of Mixed-Type Data

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,
  ...
)

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.

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).

See Also

cmdscale for classical MDS. wcmdscale for weighted MDS. pheatmap for heatmaps. qgraph for network graphs. ggpairs for MDS scatterplot matrices.

Examples

# 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"
)

dbrobust documentation built on Nov. 5, 2025, 6:24 p.m.