metric.mds: Metric-MDS baseline layout for GMDS experiments

Description

`metric.mds()` computes the current metric-MDS baseline using `stats::cmdscale()` on the graph shortest-path distance matrix and returns a common `"grip_gmds_layout"` result.

Usage

metric.mds(
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  dim = 2L,
  add = FALSE,
  eig = TRUE,
  diagnostics = TRUE,
  scale_mode = c("profiled", "identity", "user"),
  distance_floor = 1e-08,
  edge_length_epsilon = 1e-08,
  band_quantiles = c(1/3, 2/3)
)

Value

A `"grip_gmds_layout"` object.

Arguments

prepared: Optional all-pairs prepared object returned by [prepare.graph.geodesic.mds()] or [prepare.geodesic.kk()]. Edge-only objects from [prepare.edge.kk()] are intentionally rejected because metric MDS requires a graph distance matrix.
edges: Two-column edge matrix used when `prepared` is omitted.
n: Number of vertices used when `prepared` is omitted.
adj_list: Optional adjacency list used when `prepared` is omitted.
weight_list: Optional edge-weight list parallel to `adj_list`.
edge_weights: Optional positive edge weights parallel to `edges`.
dim: Target embedding dimension. Values greater than 3 are supported for GMDS and edge-KK workflows.
add, eig: Passed to `stats::cmdscale()`.
diagnostics: If `TRUE`, attach the common GMDS diagnostic panel. If `FALSE` and raw graph inputs are supplied, `metric.mds()` uses a distance-matrix-only preparation path and does not build the full all-pairs path cache.
scale_mode: Scale policy for edge, path, and chord targets: `"profiled"` fits one scalar for each diagnostic family, `"identity"` uses scale one, and `"user"` uses the corresponding supplied scale.
distance_floor: Positive floor for relative residuals.
edge_length_epsilon: Small stabilizer for fixed-path embedded lengths.
band_quantiles: Two quantiles splitting graph distances into short, mid, and long bands.