Skip to contents

Score a single layout using graph-aware quality heuristics

Source: R/grip_quality.R
score.layout.Rd

score.layout() evaluates a realized layout without assuming a canonical embedding. It is the low-level scoring helper behind compare.layouts() and is most useful when you already have one realized layout in hand, for example from a cached run or another graph drawing tool. For real-world graphs, quality is judged by graph-distance faithfulness, edge-length consistency, separation of non-neighbors, and optionally edge crossings or cluster separation.

Usage

score.layout(
  coords,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  clusters = NULL,
  sample.size.stress = 2000L,
  sample.size.nonedge = 5000L,
  stress.seed = 1L,
  nonedge.seed = 1L,
  edge.crossings = c("auto", "always", "never"),
  edge.crossings.max.edges = 1000L
)

Arguments

coords

Numeric coordinate matrix with 2 or 3 columns.

edges

Two-column integer matrix of edges (1-based vertex ids).

n

Number of vertices. If omitted with adj_list, defaults to length(adj_list). If omitted with edges, defaults to nrow(coords).

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.

clusters

Optional cluster or community labels of length nrow(coords). When supplied, cluster.separation is reported.

sample.size.stress

Number of vertex pairs sampled for sampled.stress.

sample.size.nonedge

Number of non-edge pairs sampled for sampled.nonedge.sep.ratio.

stress.seed

RNG seed used for the stress sample.

nonedge.seed

RNG seed used for the non-edge sample.

edge.crossings

How to compute edge.crossings for 2D layouts: "auto" computes exact crossings only when the graph is small enough, "always" always computes them, and "never" skips them.

edge.crossings.max.edges

Edge-count threshold used by edge.crossings = "auto".

Value

A one-row data frame with dot-delimited metric names.

Details

The sampled stress is scale invariant. For sampled pairs \(p\), let \(d_p\) be graph distance and \(e_p\) be Euclidean layout distance. The fitted scale is \(a = \sum_p e_p d_p / \sum_p d_p^2\), and the reported value is \(\sqrt{\sum_p(e_p-a d_p)^2 / \sum_p e_p^2}\). Edge-length CV is the standard deviation divided by the mean of embedded edge lengths. The sampled non-edge separation ratio is the minimum sampled non-edge distance divided by the median embedded edge length. Cluster separation is the mean pairwise distance between group centroids divided by the mean within-group radius.

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

edges <- edges.mesh(5, 5)
coords <- grip(edges, n = 25, dim = 2, preset = "mesh", seed = 1)
score.layout(coords, edges = edges, n = 25)
#>   n.vertices n.edges dim sampled.stress edge.length.cv median.edge.length
#> 1         25      40   2      0.1184891     0.05524193           26.51208
#>   sampled.nonedge.sep.ratio edge.crossings cluster.separation
#> 1                   1.28633              0                 NA