Compare multiple layout candidates across seeds

compare.layouts() computes layouts for several candidate presets or parameter lists, optionally expands a local parameter search, scores each run with score.layout(), and summarizes both quality metrics and seed-to-seed stability. This is the main real-data workflow for graphs where no canonical embedding is known.

Usage

compare.layouts(
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  dim = 2,
  candidates = c("default"),
  search = NULL,
  clusters = NULL,
  seeds = 1:3,
  sample.size.stress = 2000L,
  sample.size.nonedge = 5000L,
  edge.crossings = c("auto", "always", "never"),
  edge.crossings.max.edges = 1000L,
  score.weights = grip.default.compare.score.weights(),
  return.layouts = FALSE,
  disconnected = c("components", "error")
)

Arguments

edges: Two-column integer matrix of edges (1-based vertex ids).
n: Number of vertices.
adj_list: Adjacency list (1-based) for undirected graphs.
weight_list: Optional parallel list of positive edge weights.
edge_weights: Optional positive edge-weight vector parallel to edges.
dim: Layout dimension (2 or 3).
candidates: Either a character vector such as c("default", "mesh", "tree") or a named list of candidate layout specifications. Each list element may be NULL (use defaults), a single preset name, or a named list of grip() tuning arguments such as preset, placement, rounds, or repulsion_factor.
search: Optional named list describing a grid search over layout settings. Any of preset, placement, rounds, final_rounds, num_init, num_nbrs, r, s, repulsion_factor, and tinit_factor may be supplied as vectors. All combinations are expanded into candidates. Special fields candidate.prefix and include.base control candidate naming and whether the all-first-values setting is guaranteed to appear.
clusters: Optional cluster or community labels used to compute cluster.separation.
seeds: Integer seeds used for repeated runs.
sample.size.stress: Number of sampled pairs used for sampled.stress.
sample.size.nonedge: Number of sampled non-edge pairs used for sampled.nonedge.sep.ratio.
edge.crossings: How to compute edge.crossings for 2D layouts.
edge.crossings.max.edges: Edge-count threshold for edge.crossings = "auto".
score.weights: Optional named numeric vector used to compute score.composite. Set to NULL to omit the composite score.
return.layouts: If TRUE, include the realized coordinate matrices in the return value.
disconnected: Passed through to grip().

Value

A list with runs and summary data frames and, optionally, realized layouts.

Details

Procrustes stability is the mean pairwise root-mean-square vertex distance after centering each layout, scaling it to unit maximum radius, and applying the optimal orthogonal rotation or reflection. The default composite score converts each available summary metric to average ranks on \([0,1]\), reverses ranks for higher-is-better metrics, applies the documented weights, and renormalizes the weights after omitting unavailable metrics. Lower composite scores are better.

Examples

edges <- edges.path(5)
cmp <- compare.layouts(
  edges = edges,
  n = 5,
  dim = 2,
  candidates = c("default", "tree"),
  seeds = 1L
)
cmp$summary[, c("candidate", "rounds", "final.rounds")]
#>   candidate rounds final.rounds
#> 1   default     20           25
#> 2      tree     64          160

search.cmp <- compare.layouts(
  edges = edges,
  n = 5,
  dim = 2,
  search = list(
    candidate.prefix = "path.search",
    rounds = c(4L, 6L),
    final_rounds = c(4L, 6L)
  ),
  seeds = 1L
)
search.cmp$summary[, c("candidate", "rounds", "final.rounds")]
#>                             candidate rounds final.rounds
#> 1 path.search.rounds.6.final_rounds.4      6            4
#> 2 path.search.rounds.6.final_rounds.6      6            6
#> 3 path.search.rounds.4.final_rounds.4      4            4
#> 4 path.search.rounds.4.final_rounds.6      4            6