Metric stress MDS using SMACOF

metric.mds() minimizes unweighted raw distance stress on a graph's all-pairs shortest-path distances using smacof::mds(type = "ratio"). It requires the optional smacof package. Before version 0.2.0.9000, this name performed classical scaling; use classical.mds() to retain that behavior. The add and eig arguments belong to classical.mds() only.

Usage

metric.mds(
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  dim = 2L,
  init = c("classical", "random"),
  n_init = 1L,
  max_iter = 1000L,
  eps = 1e-08,
  seed = 1L,
  diagnostics = TRUE,
  scale_mode = c("profiled", "identity"),
  distance_floor = 1e-08,
  edge_length_epsilon = 1e-08,
  band_quantiles = c(1/3, 2/3)
)

Arguments

prepared: An all-pairs prepared graph object containing distance_matrix. Edge-only preparations are not supported.
edges: Two-column integer edge matrix used when prepared is omitted. Supply either edges/edge_weights or adj_list/weight_list, not both. Raw graph inputs cannot be combined with a prepared object.
n: Finite positive integer vertex count. When supplied with a prepared object, it must match the stored graph size.
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.
init: "classical" (default), "random", or a finite numeric matrix with n rows and dim columns in input-distance units.
n_init: Positive integer number of starts, including the first start.
max_iter: Positive integer iteration limit for each SMACOF run.
eps: Positive tolerance for the backend's change in normalized stress.
seed: Integer random seed, or NULL to use the current RNG stream. With a non-NULL seed, random starts do not change the caller's RNG state.
diagnostics: Attach the common GMDS diagnostic panel. With FALSE and raw graph inputs, prepare only the distance matrix, without path caches.
scale_mode: Diagnostic scale policy: "profiled" fits a separate scalar for each diagnostic family, and "identity" uses scale one. To evaluate user-specified scales, call score.gmds() on the returned coordinates separately. This argument never changes the fitted coordinates.
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.

Value

A "grip_gmds_layout" object with method "metric_mds". metadata records the objective, backend/version, achieved raw stress, target-normalized RMSE, both Stress-1 conventions, selected start, coordinate scale multiplier, and per-start losses and stopping information.

Details

The objective is $$S(Z) = \sum_{i<j}(\|z_i-z_j\|_2-\delta_{ij})^2.$$ Edge weights define graph distances, not pair stiffnesses in this objective. SMACOF normalizes targets internally. Returned coordinates are rescaled to minimize raw stress against the original input distances. scale_mode controls the optional diagnostic panel only, not the optimization objective.

Target-normalized raw stress and scale-profiled Stress-1 select the same shapes when global scale is free and pair weights agree. Their values at a fixed coordinate scale need not agree. Both the literal and target-profiled Stress-1 values are independently calculated in metadata; the backend's own reported stress is retained separately in the start summaries.

The first run uses init; subsequent runs use random configurations. The smallest achieved raw stress selects the result. A backend result that increases stress beyond numerical tolerance is rejected in favor of its scaled start and marked accordingly. Failed starts are recorded, and all failing starts cause an error. Iteration limits are not convergence or global optimality certificates. Collinear or planar starts may remain in their initial span; use multiple starts to investigate this sensitivity.

Newly prepared graph objects supply symmetric strict shortest distances, separately from retained-route lengths used in path diagnostics. Rebuild older cached preparations if their near-tie distance matrix is asymmetric.

Targets must be finite, symmetric, and nonnegative, with zero diagonal and at least one positive distance. Missing and infinite distances are rejected. Supplied starts may have coincident points but must not be wholly collapsed. The implementation uses dense all-pairs matrices; edge-only refinement with edge.kk() is preferable when that preparation is too large.

Workflow guides

Start with vignette("function-guide", package = "grip") to choose a layout, diagnostic, or reference comparison. List installed guides with vignette(package = "grip").

Examples

if (requireNamespace("smacof", quietly = TRUE)) {
  prepared <- prepare.graph.geodesic.mds(edges.cycle(6), n = 6)
  fit <- metric.mds(prepared = prepared, dim = 2)
  fit$metadata$raw_stress
}
#> [1] 1.287187