Getting Started with grip • grip

What this vignette covers

grip has four main user workflows:

grip(metric = "hop") for ordinary unweighted or topology-first graphs,
grip(metric = "edge_length") when edge lengths carry geometry you want to keep,
compare.layouts() and score.layout() when you want a disciplined real-data shortlist,
trace.grip() with the corresponding metric when you need diagnostics rather than just a final picture.

This vignette is the shortest path through the default workflow. It shows how to:

compute a first unweighted layout,
score it,
compare a few plausible candidates,
and decide when to switch to the specialist guides.

For weighted layouts, real-data search, tracing, and interactive exploration, the later guides go deeper. Advanced GKK/LGKK tools are public, but they are treated as later-stage experimental helpers rather than the default starting point.

library(grip)

A first unweighted layout

For an ordinary unweighted graph, grip() is the default starting point. Here is a small mesh in 2D.

mesh.edges <- edges.mesh(5, 5)
mesh.coords <- grip(
  mesh.edges,
  n = 25,
  dim = 2,
  preset = "mesh",
  seed = 1
)

mesh.score <- score.layout(mesh.coords, edges = mesh.edges, n = 25)
knitr::kable(mesh.score[, c(
  "sampled.stress",
  "edge.length.cv",
  "sampled.nonedge.sep.ratio"
)], digits = 3)

sampled.stress	edge.length.cv	sampled.nonedge.sep.ratio
0.118	0.055	1.286

plot.layout(
  mesh.coords,
  mesh.edges,
  main = "grip() on a 5x5 mesh",
  pch = 16,
  cex = 0.65,
  edge.col = "gray82"
)

For small and medium unweighted graphs, that is often all you need:

choose dim = 2 or dim = 3,
optionally start from a preset,
and score or compare a few candidate settings if the graph is important.

Compare a few plausible candidates

If the first picture matters, it is usually better to compare a short candidate list than to tune blindly. compare.layouts() runs several seeds and summarizes the results in a score table.

mesh.cmp <- compare.layouts(
  edges = mesh.edges,
  n = 25,
  dim = 2,
  candidates = c("default", "mesh", "tree"),
  seeds = 1:2,
  sample.size.stress = 500L,
  sample.size.nonedge = 1000L,
  edge.crossings = "never"
)

knitr::kable(mesh.cmp$summary[, c(
  "candidate",
  "sampled.stress.mean",
  "edge.length.cv.mean",
  "sampled.nonedge.sep.ratio.mean",
  "score.composite"
)], digits = 3)

candidate	sampled.stress.mean	edge.length.cv.mean	sampled.nonedge.sep.ratio.mean	score.composite
mesh	0.119	0.055	1.289	0.000
tree	0.386	0.321	0.233	0.722
default	0.403	0.166	0.247	0.778

That same pattern scales to real graphs:

shortlist a few plausible presets,
run several seeds,
inspect the summary table before choosing a favorite picture,
then search locally only if the graph is important enough to justify it.

What if the graph is weighted?

If edge values are only metadata, omit them for an unweighted baseline. Supplying edge_weights even with metric = "hop" changes adjacent-edge force targets; those values must be positive lengths, not strengths. When the edge lengths represent geometry that the layout should preserve, the default path changes:

start from grip(metric = "edge_length"),
prefer 3D when the graph geometry is genuinely three-dimensional,
and add GKK/LGKK only later if you need advanced geodesic-aware scoring or polish on a smaller weighted candidate set.

When should you switch workflows?

Start with grip() when the graph is fundamentally unweighted and you mainly care about its combinatorial structure.

Switch to the other guides when the task changes:

use grip(metric = "edge_length") when edge lengths encode geometry you care about,
use compare.layouts() on real graphs when you want a disciplined shortlist rather than a single run,
use trace.grip() or trace.grip(metric = "edge_length") when you want to inspect how a solve evolves,
use GKK/LGKK only after you already have weighted candidate layouts and need advanced experimental geodesic-aware scoring or polish,
use run_gripui() or run_gripui_family() in an interactive R session when you want app-based exploration.

Where to go next

For an API map, see Finding your way around grip. For reproducible bundles and reference scoring, see Synthetic graph families and layout examples. Both are installed vignettes; the broader gallery and interactive explorer are website-only articles.

Weighted Graph Layouts with grip covers weighted solving, geodesic scoring, and 2D-versus-3D decisions.
Choosing Layouts for Real Data focuses on candidate shortlisting, local search, and real-data evaluation.
Tracing and Diagnosing Layouts covers trace objects and per-frame diagnostics.
Interactive Exploration with gripui is a website article about the package’s Shiny tools.
Synthetic Graph Families and Geometries is a website article about the benchmark and geometry library.