Fast multiscale graph layouts in 2D and 3D.
Details
Use grip() to draw a graph, then
score.layout() to assess the result.
Start here
Open vignette("grip-examples", package = "grip") for a small
complete workflow, or vignette("function-guide", package = "grip")
to choose functions by task. The example below draws a 20-vertex mesh and
prints sampled graph-distance stress: zero means perfect agreement on the
sampled pairs after fitting a common scale, not a certificate for every pair.
Use metric = "hop" for connectivity or
metric = "edge_length" when positive lengths define the graph
metric. See vignette("weighted-grip-intro", package = "grip").
Find the next workflow
- Choose settings and seeds
- Trace the construction
- Construct graph examples
List available guides with vignette(package = "grip").
Development installations from GitHub include these guides only when built
with build_vignettes = TRUE. The
website also provides rendered guides,
a gallery, and website-only comparison and explorer articles. Check
packageVersion("grip") when using development documentation.
Advanced refinement
The public experimental edge-KK and geodesic-KK helpers provide weighted-layout evaluation and refinement. Choose these through the function guide after trying the main layout, scoring, and tracing workflows.
Graph input validation
Vertex indices and counts must be finite integers within the R integer
range. Adjacency must be reciprocal with matching lengths and multiplicity.
Self-loops are rejected; remove them explicitly. Supply either edges/edge_weights or
adj_list/weight_list, not both. Functions accepting a
prepared graph reject additional raw graph inputs; an explicit
n must match the stored vertex count. Rebuild the preparation when
changing topology, vertex order, or edge lengths.
GMDS thread control
The internal compiled GMDS optimizer, also used by the GMDS exploration
apps, uses at most two CPU threads. With automatic selection
(n_threads = 0), GRIP_GMDS_THREADS can be set to 1 or
2 to choose the thread count before hardware concurrency is consulted.
An explicit positive n_threads overrides the environment variable;
values above two are capped at two. Non-positive or nonnumeric environment
values fall back to hardware-based selection. The R optimization engine is
serial. This setting is not a package-wide control for GRIP layouts or for
third-party numerical libraries.
References
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.
Examples
edges <- edges.mesh(4, 5)
coords <- grip(edges, n = 20, dim = 2, preset = "mesh", seed = 11)
plot.layout(coords, edges = edges, pch = 16, main = "A 4 by 5 mesh")
quality <- score.layout(coords, edges = edges, n = 20,
sample.size.stress = 200, stress.seed = 11,
edge.crossings = "never")
quality[, c("sampled.stress", "edge.length.cv")]
#> sampled.stress edge.length.cv
#> 1 0.1376244 0.06182991