grip

grip (Graph dRawing with Intelligent Placement) is an R package for multiscale graph layout. Its primary unweighted and weighted workflows target 2D and 3D, while opt-in weighted-GRIP, metric-MDS, and edge-KK workflows also support higher-dimensional embeddings. The main workflow is:

• grip(metric = "hop") for topology-first layouts,
• grip(metric = "edge_length") when edge lengths define the graph metric,
• compare.layouts() and score.layout() for real-data layout selection,
• trace.grip() with the same metric choice for diagnostics.

The package also includes advanced public experimental geodesic-KK utilities for weighted-layout scoring and polish. It builds on the GRIP method described in Gajer & Kobourov (2002) and Gajer, Goodrich & Kobourov (2004).

Installation

# Install from GitHub
install.packages("remotes")
remotes::install_github("pgajer/grip")

Quick start

library(grip)

# Lay out a small mesh in 2D using the "mesh" preset
edges <- edges.mesh(8, 8)
coords <- grip(edges, n = 64, dim = 2, preset = "mesh", seed = 1)
plot.layout(coords, edges, pch = 16, cex = 0.6, main = "8x8 mesh")

Features

• Multiscale force-directed layout in 2D and 3D via C++ (Rcpp).
• A unified grip() interface for hop-metric and edge-length-metric layouts.
• Opt-in multiscale weighted layout in dimensions greater than 3 via weighted.grip.nd(), with higher-dimensional metric-MDS and edge-KK workflows available through metric.mds() and edge.kk().
• Layout comparison and quality scoring across seeds and parameter settings (compare.layouts(), score.layout()).
• Multiscale trace diagnostics for both metrics via trace.grip().
• Advanced public experimental geodesic-KK utilities for weighted-layout scoring and polish (prepare.geodesic.kk(), score.geodesic.kk(), prepare.landmark.geodesic.kk(), score.landmark.geodesic.kk()).
• Synthetic graph-family helpers for benchmark and geometry-rich examples.
• Handles disconnected graphs automatically (component packing).
• Tuned presets for common graph families (see table below).
• Static 3D projection for vignettes and reports (plot.layout(projection = "ortho"), project.3d()).

Presets

Presets set sensible defaults for the GRIP parameters. Any explicit argument you pass overrides the preset value.

Choosing a workflow

• Start with grip(metric = "hop"), the default, when topology should define the multiscale hierarchy and graph neighborhoods.
• Use grip(metric = "edge_length") when positive edge lengths should also define shortest-path distances, hierarchy construction, neighborhoods, and insertion anchors.
• Use compare.layouts() and score.layout() when the graph is important enough to justify a candidate shortlist rather than a single run.
• Use trace.grip() with the corresponding metric when you need to diagnose how a solve evolved.
• Add GKK/LGKK only after you already have weighted candidate layouts and need geodesic-aware scoring or polish; these are advanced public experimental tools rather than the default starting point.

The historical argument names edge_weights and weight_list represent positive edge lengths, not connection strengths. With metric = "hop", supplied lengths set adjacent-edge force targets while standard GRIP hierarchy and neighborhood searches still count hops. With metric = "edge_length", the lengths also define weighted shortest paths throughout the multiscale engine and are median-normalized by default. See ?grip for the complete semantics and normalization options.

Gallery

trace.grip() records the multiscale refinement process from coarse placement through the final layout. Local Sierpinski carpet and triangle animations can be generated with make readme-assets; generated animations are intentionally kept outside Git history.

More examples

Edge-list input (2D, circle placement)

edges <- edges.cycle(18)
coords <- grip(edges, n = 18, dim = 2, placement = "circle", seed = 2)
plot.layout(coords, edges, pch = 16, cex = 0.7)

Edge-length-metric adjacency list (geometry-aware)

adj_list <- list(c(2), c(1, 3), c(2, 4), c(3))
weight_list <- list(c(1.0), c(1.0, 2.0), c(2.0, 1.5), c(1.5))
coords <- grip(
  adj_list = adj_list, weight_list = weight_list,
  metric = "edge_length", n = 4, dim = 2, seed = 12
)
plot.layout(coords)

3D layout with static projection

edges <- edges.torus(8, 12)
coords <- grip(edges, n = max(edges), dim = 3, preset = "torus", seed = 3)
plot.layout(coords, edges, projection = "ortho", main = "Torus (8x12)")

Layout comparison

For real-world graphs without a known target layout, compare.layouts() compares candidates across seeds and reports quality metrics. Use params.from.summary() to extract the winning parameters for reuse.

edges <- edges.mesh(10, 10)
cmp <- compare.layouts(edges, n = 100, dim = 2,
                            candidates = c("default", "mesh"),
                            seeds = 1:3)
cmp$summary[, c("candidate", "score.composite", "sampled.stress.mean")]

Documentation

The package ships with four core vignettes:

• Getting Started with grip — the shortest path through the default unweighted workflow, with guidance on when to switch to weighted, trace, or comparison workflows.
• Weighted Graph Layouts with grip — geometry-aware layouts, geodesic scoring, and 2D-versus-3D decisions for weighted graphs.
• Choosing Layouts for Real Data — a step-by-step workflow using the Zachary karate club and Krackhardt kite examples, plus a larger weighted HMP/U01 case study.
• Tracing and Diagnosing Layouts — frame-by-frame tracing for understanding how a solve evolves.

The pkgdown site also includes companion articles such as the interactive explorer guide, the HMP/U01 object-structure note, the comparison article, and the synthetic-family gallery.

The geodesic-KK helpers are public and documented in the reference index, but they are intentionally positioned as advanced experimental tools layered on top of the main weighted workflow.

Citation

If you use grip in published work, please cite the underlying algorithm:

Gajer, P. and Kobourov, S.G. (2002). GRIP: Graph dRawing with Intelligent Placement. Journal of Graph Algorithms and Applications, 6(3), 203–224. doi: 10.7155/jgaa.00052

Gajer, P., Goodrich, M.T. and Kobourov, S.G. (2004). A multi-dimensional approach to force-directed layouts of large graphs. Computational Geometry, 29(1), 3–18. doi: 10.1016/j.comgeo.2004.03.014

License

GPL (>= 3)