Score a layout with the common GMDS diagnostic panel

score.gmds() provides a common diagnostic panel for GMDS-oriented layouts. It summarizes edge-length fidelity, fixed-path geodesic stress, short/mid/long geodesic bands, ordinary metric-MDS chord stress, and simple spread/shortcut diagnostics for any coordinate matrix on a prepared graph.

Usage

score.gmds(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  scale_mode = c("profiled", "identity", "user"),
  edge_scale = NULL,
  path_scale = NULL,
  chord_scale = NULL,
  distance_floor = 1e-08,
  edge_length_epsilon = 1e-08,
  band_quantiles = c(1/3, 2/3)
)

Arguments

coords: Numeric coordinate matrix.
prepared: Optional object returned by prepare.edge.kk(), prepare.graph.geodesic.mds() or prepare.geodesic.kk(). Edge-only objects from prepare.edge.kk() report only edge diagnostics; all-pairs GMDS path and chord diagnostics are unavailable.
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.
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.
edge_scale, path_scale, chord_scale: Optional user scales used when scale_mode = "user".
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 one-row data frame. Lower residual errors indicate closer agreement with the stated targets; no single column certifies geometric recovery.

Diagnostic columns

A chord is the straight-line distance between two coordinates. A retained path adds embedded edge lengths along a route stored in the preparation. These can disagree on a folded graph. The diagnostic targets use the stored route convention and can differ slightly from strict shortest distances near ties. Compare candidates with the same graph, preparation, and scale policy.

n.vertices, n.edges, n.pairs: graph size and numbers of stored edges and retained pairs (before exclusion of invalid or near-zero targets).
scale.mode: the requested scale policy. edge.scale, gmds.scale, and metric.chord.scale multiply edge, path, and chord targets separately.
edge.rel.rmse, gmds.stress, metric.chord.stress: root sum squared residual divided by root sum squared scaled target, a dimensionless error. This is not the mean of squared pairwise relative errors and is not the raw stress minimized by metric.mds().
edge.rmse, gmds.rmse, metric.chord.rmse: root mean squared residual in drawn-coordinate units against the scaled targets.
edge.mean.abs.error, gmds.mean.abs.error: mean absolute residual in drawn-coordinate units. The corresponding mean.rel.abs.error columns (also available for metric.chord) average absolute residual/target ratios.
edge.signed.bias, gmds.signed.bias: mean residual/target ratio; positive values indicate lengths greater than their scaled targets.
gmds.short.stress, gmds.mid.stress, gmds.long.stress and their signed.bias counterparts: the path statistics restricted to bands defined by band_quantiles; ties at a boundary belong to the lower band.
shortcut.fraction: fraction of evaluated retained paths more than 5% shorter than their scaled target, between zero and one.
spread.score: RMS chord length divided by RMS unscaled graph target; it changes with drawing scale and is not a universal quality grade.

Residual summaries exclude nonfinite values, nonpositive weights, and targets no larger than distance_floor. Unavailable summaries are NA, including path/chord diagnostics for edge-only preparations. No reference alignment is performed. Use score.coordinates() or score.surface() for reference agreement, keeping their alignment and units explicit.

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

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
prepared <- prepare.graph.geodesic.mds(cycle_edges, n = 6)
score <- score.gmds(coords, prepared = prepared)
score[, c("scale.mode", "edge.rel.rmse", "gmds.stress", "metric.chord.stress")]
#>   scale.mode edge.rel.rmse  gmds.stress metric.chord.stress
#> 1   profiled  3.451824e-16 1.807013e-16           0.1519999
# These dimensionless errors assess edges, retained paths, and chords;
# they do not measure agreement with reference coordinates.