Package {grip}

grip: Graph dRawing with Intelligent Placement

Description

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

vignette("grip-real-data", package = "grip").

Trace the construction

vignette("grip-trace-and-diagnostics", package = "grip").

Construct graph examples

vignette("synthetic-graph-families", package = "grip").

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, the graph gallery, comparisons, case study, and explorer walkthrough from the same installed vignette sources. 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.

Author(s)

Maintainer: Pawel Gajer pgajer@gmail.com

Authors:

• Pawel Gajer pgajer@gmail.com

Other contributors:

• Jonathan Zheng (Author and copyright holder of MIT-licensed s_gd2 code adapted for the metric-MDS SGD backend) [contributor, copyright holder]

• Daniel Hangan (Author of the SGD-MDS implementation in his scikit-learn fork adapted for the metric-MDS SGD backend) [contributor]

• The scikit-learn developers (Copyright holders of BSD-3-Clause code adapted from Daniel Hangan's scikit-learn fork for the metric-MDS SGD backend) [copyright holder]

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.

See Also

Useful links:

• https://pgajer.github.io/grip/

• https://github.com/pgajer/grip

• Report bugs at https://github.com/pgajer/grip/issues

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")]

Build a maximal independent set filtration (MISF) for a graph

Description

build.misf() exposes the maximal independent set filtration already constructed internally by the GRIP layout engine. The result is graph-first: you can supply either an edge list plus n, or an adjacency/weight-list pair.

Usage

build.misf(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  num.init = 24L,
  num.nbrs = 20L,
  seed = 6L
)

Arguments

Details

The current implementation returns the same MISF structure used by GRIP's multiscale layout core. Edge weights are accepted and passed through the underlying graph object, but the current MISF construction itself is driven by the graph topology and hop-distance thresholds rather than weighted shortest-path distances.

Value

An object of class "grip_misf" containing:

levels

Named list ⁠V0, V1, ...⁠ of nested vertex sets (1-based).

vertex_depth

Integer vector giving the highest MISF level containing each vertex.

mish_order

The internal GRIP MISF order (1-based vertex ids).

misf_size

Sizes of the nested levels.

num_nbrs_schedule

Per-level retained neighborhood counts used by the current GRIP engine.

misf_height

Highest MISF level index.

top_level_size

Size of the highest MISF level.

Examples

edges <- edges.mesh(4, 4)
misf <- build.misf(edges = edges, n = 16, num.init = 6, seed = 1)
misf$misf_size
misf$levels[[1L]]

Build a weighted MISF hierarchy

Description

build.weighted.misf() builds the weighted max-independent-set filtration used by the weighted GRIP layout core. It is primarily a diagnostic and benchmarking helper for comparing weighted and combinatorial hierarchies on the same graph.

Usage

build.weighted.misf(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  num.init = 24,
  num.nbrs = 20,
  length.normalization = c("median", "mean", "none"),
  seed = 6
)

Arguments

Value

A list with weighted MISF levels, vertex_depth, mish_order, misf_size, num_nbrs_schedule, misf_height, top_level_size, weight_scale, and length_normalization.

Examples

cycle_edges <- edges.cycle(6)
cycle_lengths <- seq(0.8, 1.3, length.out = nrow(cycle_edges))
levels <- build.weighted.misf(
  edges = cycle_edges, n = 6, edge.weights = cycle_lengths,
  num.init = 3, num.nbrs = 2, seed = 1
)

Classical-MDS baseline layout for GMDS experiments

Description

classical.mds() computes the classical-MDS baseline using stats::cmdscale() on the graph shortest-path distance matrix and returns a common "grip_gmds_layout" result.

Usage

classical.mds(
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 2L,
  add = FALSE,
  eig = TRUE,
  diagnostics = TRUE,
  scale.mode = c("profiled", "identity", "user"),
  distance.floor = 1e-08,
  edge.length.epsilon = 1e-08,
  band.quantiles = c(1/3, 2/3)
)

Arguments

Value

A "grip_gmds_layout" object.

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

cycle_edges <- edges.cycle(6)
prepared <- prepare.graph.geodesic.mds(cycle_edges, n = 6)
fit <- classical.mds(prepared = prepared, dim = 2)

Compare multiple layout candidates across seeds

Description

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

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.

Value

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

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")]

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")]

Cube mask pattern helpers for recursive porous families

Description

Convenience constructors for cubic keep-arrays that can be passed to recursive.cube.mask.surface.graph() to build cubical porous benchmark families. These helpers encode three qualitatively different void patterns: repeated tunnel lattices, interior asymmetric cavities, and deterministic channel networks.

Usage

mask.cube.periodic.tunnels(
  side = 5,
  tunnel.width = 1,
  tunnel.period = 2,
  tunnel.offset = 2
)

mask.cube.asymmetric.cavities(
  side = 5,
  cavity.size = 2,
  pocket.size = max(1L, cavity.size - 1L)
)

mask.cube.channel.network(side = 5, channel.width = 1, branch.offset = 2)

Arguments

Details

The returned arrays use the same orientation as the recursive cube-mask helpers: the first dimension runs from top to bottom, the second from left to right, and the third from front to back.

Value

A logical cubic keep-array.

Examples

cavities <- mask.cube.asymmetric.cavities(
  side = 5, cavity.size = 1, pocket.size = 1
)
channels <- mask.cube.channel.network(
  side = 5, channel.width = 1, branch.offset = 2
)
tunnels <- mask.cube.periodic.tunnels(
  side = 5, tunnel.width = 1, tunnel.period = 2, tunnel.offset = 1
)

Weighted cylinder surface helpers

Description

Convenience helpers that embed a cylindrical grid graph into \mathbb{R}^3 and use the induced Euclidean edge lengths as positive graph weights. These helpers are intended for benchmark families where the graph topology is cylindrical but the intended metric comes from a curved or spatially varying 3D realization.

Usage

cylinder.surface.graph(
  h,
  w = h,
  surface = c("barrel", "hourglass", "wavy"),
  radius = 1,
  height = 2,
  amplitude = 0.3,
  freq.theta = 2,
  freq.z = 1,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)

Arguments

Details

The coords.surface component contains the 3D coordinates of the embedded cylindrical grid. cylinder.surface.graph() returns a reusable weighted-graph bundle containing the cylinder edges, induced edge weights, the 3D surface coordinates, and a 2D unwrapped parameterization.

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

cylinder.surface.graph() returns a list with components:

• edges: the undirected cylindrical-grid edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the 2D unwrapped parameter coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "cylinder",

• surface: the chosen surface name,

• label: a human-readable family label.

Examples

cylinder <- cylinder.surface.graph(4, 5, surface = "hourglass")

Optimize an edge-KK local repair layout

Description

edge.kk() is the edge-restricted Kamada–Kawai local repair operator for the experimental GMDS layout program. Earlier notes called this operator edge-gKK or edge-isometric GMDS; edge-KK is the preferred name because the objective is restricted to graph edges rather than all graph-geodesic pairs. It minimizes weighted edge-length stress

\frac{1}{2}\sum_{(i,j)\in E} k_{ij} \left(\|z_i-z_j\|_2 - s w_{ij}\right)^2

using deterministic gradient descent with Armijo backtracking. The default density.mix.schedule runs a continuation from density-weighted stiffnesses toward uniform stiffnesses.

Usage

edge.kk(
  coords = NULL,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 2L,
  init = c("classical_mds", "metric_mds", "weighted_grip", "random"),
  weighted.grip.args = list(),
  stiffness.method = c("density", "uniform", "distance_power"),
  stiffness.transform = c("identity", "sqrt", "log"),
  density.mix.schedule = c(0, 0.25, 0.5, 0.75, 1),
  bandwidth = NULL,
  density.n = 512L,
  distance.power = 0,
  stiffness.floor = 0,
  stiffness.ceiling = Inf,
  scale.mode = c("profiled", "identity", "fixed_initial", "user"),
  scale = NULL,
  max.iter = 50L,
  initial.step = 1,
  step.shrink = 0.5,
  armijo.factor = 1e-04,
  grad.tol = 1e-08,
  min.step = 1e-08,
  edge.length.epsilon = 1e-08,
  distance.floor = 1e-08,
  recenter = TRUE,
  return.trace = TRUE,
  diagnostics = TRUE,
  seed = 1L,
  engine = c("cpp", "R"),
  ...
)

Arguments

Details

For scalable repair from an existing layout, pass coords or an edge-only object from prepare.edge.kk(). When raw graph inputs are supplied, edge.kk() uses edge-only preparation whenever coords are supplied or init is "weighted_grip" or "random". Use init = "weighted_grip" for a scalable weighted-GRIP warm start followed by edge-KK polish. If coords is omitted and either MDS initializer is requested, use an all-pairs prepared object from prepare.graph.geodesic.mds() or prepare.geodesic.kk() instead.

Value

A "grip_gmds_layout" object with method "edge_kk".

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
prepared <- prepare.edge.kk(cycle_edges, n = 6)
fit <- edge.kk(
  coords = initial, prepared = prepared,
  max.iter = 1, density.n = 32, engine = "R"
)

Construct edge-length stiffnesses for edge-isometric GMDS layouts

Description

edge.length.density.stiffness() constructs stiffnesses for edge-only geodesic-MDS layouts. It turns positive edge lengths into spring stiffnesses normalized to mean one. The "density" method emphasizes edge lengths near the empirical edge-length density mode, and mix provides a continuation path from that density-weighted signal to uniform stiffness.

Usage

edge.length.density.stiffness(
  edge.weights,
  method = c("density", "uniform", "distance_power"),
  mix = 0,
  bandwidth = NULL,
  density.n = 512L,
  transform = c("identity", "sqrt", "log"),
  distance.power = 0,
  stiffness.floor = 0,
  stiffness.ceiling = Inf
)

Arguments

Value

A list with stiffness, raw signal diagnostics, estimated mode, and clipping/normalization metadata.

Examples

stiffness <- edge.length.density.stiffness(
  c(0.8, 0.9, 1, 1.1, 1.2, 1.3), density.n = 32
)

Optimize one edge-isometric repulsive unfolding stage

Description

edge.repulsive.stage() performs one gradient-descent stage for the objective evaluated by edge.repulsive.state(). It uses Armijo backtracking, optionally recenters coordinates after each proposal, and returns the final coordinates plus a per-iteration trace.

Usage

edge.repulsive.stage(
  coords,
  edges,
  edge.lengths,
  edge.weights = NULL,
  lambda = 0,
  edge.family = c("quadratic", "upper_barrier"),
  eps.plus = 0.35,
  beta = 0,
  pair.index = NULL,
  pair.weights = NULL,
  repulsion.family = c("log", "inverse_power"),
  repulsion.delta = 0.001,
  repulsion.power = 1,
  max.iter = 80L,
  initial.step = 0.02,
  step.shrink = 0.5,
  armijo = 1e-04,
  min.step = 1e-08,
  grad.tol = 1e-07,
  recenter = TRUE,
  distance.eps = 1e-10,
  return.frames = FALSE,
  engine = c("cpp", "R")
)

Arguments

Value

A list with coords, final state, a data-frame trace, and, when requested, a list of coordinate frames.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
fit <- edge.repulsive.stage(
  initial, cycle_edges, rep(1, nrow(cycle_edges)),
  lambda = 0.1, max.iter = 1, engine = "R"
)

Evaluate an edge-isometric repulsive unfolding objective

Description

edge.repulsive.state() evaluates an experimental GMDS objective that combines an edge-isometric term with a configurable repulsion term. The edge term penalizes deviation of embedded edge lengths from graph edge lengths. The repulsion term can be evaluated on all vertex pairs or on a selected pair set.

Usage

edge.repulsive.state(
  coords,
  edges,
  edge.lengths,
  edge.weights = NULL,
  edge.family = c("quadratic", "upper_barrier"),
  eps.plus = 0.35,
  beta = 0,
  lambda = 0,
  pair.index = NULL,
  pair.weights = NULL,
  repulsion.family = c("log", "inverse_power"),
  repulsion.delta = 0.001,
  repulsion.power = 1,
  distance.eps = 1e-10,
  engine = c("cpp", "R")
)

Arguments

Details

The default engine = "cpp" uses the compiled backend. engine = "R" keeps a reference implementation available for diagnostics and regression tests.

Value

A list containing total energy, edge and repulsion energies, gradient, gradient norm, feasibility flag, embedded edge lengths, relative edge lengths, edge residuals, and number of upper-barrier wall violations.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
state <- edge.repulsive.state(
  coords, cycle_edges, rep(1, nrow(cycle_edges)),
  lambda = 0.1, engine = "R"
)

Estimate preparation storage before allocating graph distances

Description

Reports a lower bound for dense distance storage, not peak memory or runtime. This arithmetic-only helper does not construct a graph or allocate its cache.

Usage

estimate.preparation(
  n,
  n.edges = NA_integer_,
  pair.mode = c("all_pairs", "landmark_sparse", "distance_matrix_only", "edge_only"),
  local.nbrs = 20L,
  landmark.count = 8L
)

Arguments

Details

One dense double matrix needs 8 * n^2 bytes. Full and landmark preparations currently compute dense distances; landmark mode reduces retained pairs, not that matrix. Trees, routes, copies, R object overhead, and solver workspace require additional memory and are not estimated. Edge-only preparation has no dense distance matrix, but still stores the graph. Use prepare.edge.kk() when only edge constraints are needed, or ordinary grip() when a full geodesic cache is unnecessary.

Dense preparation warns before its searches/allocations when this bound exceeds getOption("grip.preparation.warn.bytes", 512 * 1024^2). Set that option to another positive byte count, or Inf to acknowledge and disable the advisory warning. It is not a hard memory limit. Small calls are quiet. Native refinement checks for cancellation between rounds or optimizer evaluations; worker threads finish an evaluation before interruption is raised on the main thread. Cancellation does not return a partial fit.

Value

A one-row data frame containing graph counts, pair mode, a pair-count upper bound, and the dense-distance storage lower bound in bytes and GiB.

See Also

prepare.graph.geodesic.mds(), prepare.landmark.geodesic.kk()

Examples

estimate.preparation(10000, n.edges = 20000)
estimate.preparation(10000, n.edges = 20000, pair.mode = "edge_only")

Optimize a layout under the full geodesic KK energy

Description

geodesic.kk() applies a deterministic gradient-descent polish under the full all-pairs geodesic Kamada–Kawai objective.

Usage

geodesic.kk(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  max.iter = 16L,
  stiffness = 1,
  distance.floor = 1e-08,
  edge.length.epsilon = 1e-08,
  initial.step = 1,
  step.shrink = 0.5,
  armijo.factor = 1e-04,
  grad.tol = 1e-08,
  min.step = 1e-08,
  recenter = TRUE,
  return.trace = FALSE,
  scale.mode = c("fixed_initial", "profiled", "user"),
  scale.L0 = NULL
)

Arguments

Details

The optimizer supports three scale policies. With scale.mode = "fixed_initial" the target scale is fit once from the starting layout and then held fixed during optimization, matching the landmark geodesic KK behavior. With scale.mode = "profiled" the scale is re-fit analytically at each evaluation. With scale.mode = "user", a fixed user-supplied scale.L0 is used throughout.

Value

A list with coords, trace, frames, prepared, and score.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
prepared <- prepare.geodesic.kk(cycle_edges, n = 6)
fit <- geodesic.kk(initial, prepared = prepared, max.iter = 1)

Geometry-aware diagnostics against a canonical target

Description

geometry.diagnostics() augments the graph-aware quality measures in score.layout() with target-aware geometric diagnostics. The function aligns coords to target.coords using an orthogonal Procrustes fit, then reports global symmetry, local angle preservation, edge-axis concentration, and, for Sierpinski carpet layouts, boundary, corridor, and hole-center diagnostics.

Usage

geometry.diagnostics(
  coords,
  target.coords,
  edges,
  family = NULL,
  sample.size.symmetry = 512L,
  sample.size.wedges = 4000L,
  rng.seed = 1L
)

Arguments

Details

Metrics are reported so that larger global.symmetry.score and edge.axis.concentration are better, while smaller procrustes.rmse, local.angle.deviation, boundary.waviness, corridor.waviness, hole.center.error, central.hole.skew, central.hole.aspect.error, and central.hole.center.error are better.

Value

A one-row data frame of geometric diagnostics.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
target <- cbind(cos(theta), sin(theta))
diagnostics <- geometry.diagnostics(
  target + 0.01, target, cycle_edges,
  sample.size.symmetry = 10, sample.size.wedges = 10
)

Compute a GRIP layout with coarse global repulsion

Description

This compatibility entry point is equivalent to grip(..., metric = "hop"). It keeps the old global-repulsion name available while using the same quality-first multiscale GRIP engine and adaptive final.rounds schedule as the primary layout API.

Usage

globalrep.grip(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 3,
  placement = c("barycenter", "circle"),
  preset = NULL,
  rounds = 160,
  final.rounds = 384,
  num.init = 24,
  num.nbrs = 20,
  r = 0.03,
  s = 7.5,
  repulsion.factor = 2.5,
  coarse.repulsion.factor = 1.5,
  coarse.repulsion.sample = 16,
  coarse.repulsion.exact.below = 64,
  final.anchor.factor = 0,
  final.move.scale.after.first = 1,
  final.mode = c("fr", "kk_repulse"),
  insertion.anchor.count = 3,
  insertion.anchor.scope = c("any_higher", "prev_misf"),
  insertion.anchor.strategy = c("first", "distance_band", "balanced_band", "spread_prev"),
  level0.insertion.mode = c("inherit", "barycenter", "least_squares"),
  level0.anchor.count = insertion.anchor.count,
  level0.local.kk.steps = 3,
  lgkk.polish.rounds = 0L,
  lgkk.multiscale.rounds = 0L,
  lgkk.rounds.coarse = NULL,
  lgkk.rounds.pre.final = NULL,
  lgkk.rounds.final = NULL,
  lgkk.local.nbrs = 20L,
  lgkk.landmark.count = 8L,
  lgkk.multiscale.scope = c("all", "coarse"),
  lgkk.active.limit = 4096L,
  tinit.factor = 6,
  seed = 6,
  disconnected = c("components", "error")
)

Arguments

Value

A numeric matrix with n rows and dim columns.

Examples

edges <- edges.mesh(4, 4)
coords <- globalrep.grip(edges, n = max(edges), dim = 2,
                                rounds = 8, final.rounds = 8,
                                num.init = 6, num.nbrs = 8,
                                coarse.repulsion.factor = 0.2,
                                coarse.repulsion.sample = 8,
                                coarse.repulsion.exact.below = 32,
                                seed = 1)
round(coords, 3)

Compute a weighted geometry-aware GRIP layout

Description

globalrep.weighted.grip() is the compatibility backend equivalent to grip(..., metric = "edge_length"). It runs the edge-length multiscale core, which uses edge lengths in the filtration, local neighborhoods, insertion, refinement forces, and optional in-core multiscale LGKK refinement.

Usage

globalrep.weighted.grip(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 3,
  placement = c("barycenter", "circle"),
  preset = NULL,
  rounds = 160,
  final.rounds = 384,
  num.init = 24,
  num.nbrs = 20,
  r = 0.03,
  s = 7.5,
  repulsion.factor = 2.5,
  coarse.repulsion.factor = 1.5,
  coarse.repulsion.sample = 16,
  coarse.repulsion.exact.below = 64,
  final.anchor.factor = 0,
  final.move.scale.after.first = 1,
  final.mode = c("fr", "kk_repulse"),
  insertion.anchor.count = 3,
  insertion.anchor.scope = c("any_higher", "prev_misf"),
  insertion.anchor.strategy = c("first", "distance_band", "balanced_band", "spread_prev"),
  level0.insertion.mode = c("inherit", "barycenter", "least_squares"),
  level0.anchor.count = insertion.anchor.count,
  level0.local.kk.steps = 3,
  lgkk.polish.rounds = 0L,
  lgkk.multiscale.rounds = 0L,
  lgkk.rounds.coarse = NULL,
  lgkk.rounds.pre.final = NULL,
  lgkk.rounds.final = NULL,
  lgkk.local.nbrs = 20L,
  lgkk.landmark.count = 8L,
  lgkk.multiscale.scope = c("all", "coarse"),
  lgkk.active.limit = 4096L,
  metric.neighbor.cap = NULL,
  length.normalization = c("median", "mean", "none"),
  tinit.factor = 6,
  seed = 6,
  disconnected = c("components", "error")
)

Arguments

Value

A numeric matrix with n rows and dim columns.

Examples

cycle_edges <- edges.cycle(6)
cycle_lengths <- seq(0.8, 1.3, length.out = nrow(cycle_edges))
layout <- globalrep.weighted.grip(
  edges = cycle_edges, n = 6, edge.weights = cycle_lengths,
  dim = 2, rounds = 1, final.rounds = 1,
  num.init = 3, num.nbrs = 2, seed = 1
)

Build a local Riemannian star structure for Gram-gKK layouts

Description

graph.riemannian.star.structure() builds the local star-pair table used by kernel Gram-gKK. For each center vertex u, it considers unordered neighbor pairs ⁠(v, v')⁠ in the graph star and stores the target edge lengths, target cosine angle, and kernel weight

r_u(v,v')\left(\frac{1-\cos\alpha_u(v,v')}{2}\right)^q.

In the first implementation, target angles are estimated from the ambient coordinates X. The optimizer is intentionally agnostic to where those cosines came from, so later graph constructors can attach a different Riemannian source without changing the layout backend.

Usage

graph.riemannian.star.structure(
  graph = NULL,
  X,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  angle.power = 4,
  reliability = c("length.balance", "none"),
  min.angle.weight = 0,
  star.quantile = 0
)

Arguments

Value

A list of class "grip_riemannian_star" with the star-pair table and construction metadata.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
prepared <- prepare.graph.geodesic.mds(cycle_edges, n = 6)
star <- graph.riemannian.star.structure(X = coords, prepared = prepared)

Sample graph generators

Description

Convenience helpers that build small undirected graph families as two-column integer edge matrices suitable for grip(). These helpers are meant for examples, experiments, and reproducible tests.

Usage

edges.path(n)

edges.cycle(n)

edges.mesh(h, w = h, connectivity = c("orthogonal", "diagonal"))

edges.cylinder(h, w = h)

edges.torus(h, w = h)

edges.cube(side = 2)

edges.kary.tree(k = 2, depth = 2)

edges.sierpinski.triangle(level = 2)

edges.sierpinski.tetrahedron(level = 2)

edges.sierpinski.carpet(level = 2)

Arguments

Details

The exported generators cover primitive paths, cycles, regular meshes, cylinders, tori, cubes, trees, and the standard Sierpinski families. Specialized weighted benchmark families are exposed through complete ⁠*.surface.graph()⁠ and ⁠*.solid.graph()⁠ bundles instead of separate edge-list and embedding functions. edges.sierpinski.triangle() builds the 2-simplex family, edges.sierpinski.tetrahedron() builds the 3-simplex family, and edges.sierpinski.carpet() builds a 2D cell-adjacency carpet graph.

Value

A two-column integer matrix of undirected edges. Vertex labels are consecutive integers starting at 1.

Functions

• edges.path(): Path graph on n vertices.

• edges.cycle(): Cycle graph on n vertices.

• edges.mesh(): Rectangular grid graph with h rows and w columns.

• edges.cylinder(): Cylindrical grid graph with h rows and wrapped width w.

• edges.torus(): Toroidal grid graph with wrapped height and width.

• edges.cube(): Cube surface graph on the boundary of a side x side x side lattice.

• edges.kary.tree(): Full k-ary tree of depth depth.

• edges.sierpinski.triangle(): Two-dimensional Sierpinski triangle graph at recursion depth level.

• edges.sierpinski.tetrahedron(): Three-dimensional tetrahedral Sierpinski graph at recursion depth level.

• edges.sierpinski.carpet(): Two-dimensional Sierpinski carpet graph whose vertices are occupied cells and whose edges connect orthogonally adjacent cells.

Examples

cube_edges <- edges.cube(3)
cycle_edges <- edges.cycle(6)
cylinder_edges <- edges.cylinder(3, 4)
tree_edges <- edges.kary.tree(k = 2, depth = 2)
mesh_edges <- edges.mesh(3, 4)
carpet_edges <- edges.sierpinski.carpet(level = 1)
tetrahedron_edges <- edges.sierpinski.tetrahedron(level = 1)
torus_edges <- edges.torus(3, 4)
edges <- edges.path(6)
coords <- grip(edges, n = 6, dim = 2, seed = 1)
plot.layout(coords, edges, main = "Path graph", pch = 16, cex = 0.8)
edges <- edges.sierpinski.triangle(2)
n <- max(edges)
coords <- grip(edges, n = n, dim = 2,
                      placement = "circle",
                      seed = 1)
plot.layout(coords, edges, main = "Sierpinski triangle", pch = 16, cex = 0.7)

Compute a GRIP layout

Description

This is the primary layout API. It uses the quality-first multiscale GRIP engine with extra coarse-level global repulsion to reduce foldovers while preserving the usual GRIP refinement structure. With preset = NULL, the default profile is tuned for higher-quality layouts and automatically tapers final.rounds on larger graphs.

Usage

grip(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 3,
  placement = c("barycenter", "circle"),
  preset = NULL,
  rounds = 160,
  final.rounds = 384,
  num.init = 24,
  num.nbrs = 20,
  r = 0.03,
  s = 7.5,
  repulsion.factor = 2.5,
  coarse.repulsion.factor = 1.5,
  coarse.repulsion.sample = 16,
  coarse.repulsion.exact.below = 64,
  final.anchor.factor = 0,
  final.move.scale.after.first = 1,
  final.mode = c("fr", "kk_repulse"),
  insertion.anchor.count = 3,
  insertion.anchor.scope = c("any_higher", "prev_misf"),
  insertion.anchor.strategy = c("first", "distance_band", "balanced_band", "spread_prev"),
  level0.insertion.mode = c("inherit", "barycenter", "least_squares"),
  level0.anchor.count = insertion.anchor.count,
  level0.local.kk.steps = 3,
  lgkk.polish.rounds = 0L,
  lgkk.multiscale.rounds = 0L,
  lgkk.rounds.coarse = NULL,
  lgkk.rounds.pre.final = NULL,
  lgkk.rounds.final = NULL,
  lgkk.local.nbrs = 20L,
  lgkk.landmark.count = 8L,
  lgkk.multiscale.scope = c("all", "coarse"),
  lgkk.active.limit = 4096L,
  tinit.factor = 6,
  seed = 6,
  disconnected = c("components", "error"),
  metric = c("hop", "edge_length"),
  metric.neighbor.cap = NULL,
  length.normalization = c("median", "mean", "none"),
  ...
)

Arguments

Details

Edge-length semantics

The arguments edge.weights and weight.list are historically named but represent positive edge lengths or traversal costs, not connection strengths, capacities, or similarities. A larger value requests a longer geometric edge. If the available values are strengths for which a larger value means a closer connection, convert them to positive lengths before calling grip(), for example with a scientifically appropriate reciprocal or other monotone decreasing transformation.

With metric = "hop", the standard GRIP hierarchy, insertion anchors, and retained local neighborhoods use combinatorial shortest-path distance: every traversed edge contributes one hop. When edge lengths are supplied, they are nevertheless used as the desired lengths of adjacent vertex pairs in the attractive force calculation. Thus this mode is useful when topology should determine the multiscale organization but adjacent edges should have unequal target lengths. No global length normalization is performed in this mode. If no lengths are supplied, every edge has desired length one. Optional LGKK stages use the supplied edge lengths for their geodesic distances even though the standard GRIP stages remain hop based.

With metric = "edge_length", positive edge lengths are required. The same lengths determine desired adjacent-edge lengths and the shortest-path metric used for the MISF hierarchy, insertion anchors, retained graph neighborhoods, and LGKK stages. Dijkstra-style weighted shortest paths are used instead of hop-count breadth-first searches. By default, all lengths are divided by their median before layout; this preserves relative geometry while placing the numerical scale near the solver's unit scale. Use length.normalization = "mean" for mean scaling or "none" when the absolute supplied scale is intentional. Multiplying all input lengths by the same positive constant therefore leaves the default normalized solve unchanged.

For edges input, provide one value per row through edge.weights. For adj.list input, provide a parallel weight.list: weight.list[[i]][j] is the length of the edge from vertex i to adj.list[[i]][j]. For an undirected graph, the adjacency and length entries should be symmetric.

Value

A numeric matrix with n rows and dim columns.

Workflow guides

Start with vignette("function-guide", package = "grip") to choose a layout, diagnostic, or reference comparison. List installed guides with vignette(package = "grip").

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, 4)
coords <- grip(edges, n = max(edges), dim = 2,
                      coarse.repulsion.factor = 0.2,
                      coarse.repulsion.sample = 8,
                      coarse.repulsion.exact.below = 32,
                      seed = 1)
round(coords, 3)

# Use edge lengths throughout the multiscale graph metric.
path <- cbind(1:5, 2:6)
lengths <- c(1, 1, 2, 1, 1)
weighted.coords <- grip(
  path, n = 6, edge.weights = lengths,
  metric = "edge_length", dim = 2,
  rounds = 4, final.rounds = 4, num.init = 3, seed = 1
)

Migrate code to the grip 0.2 API

Description

Version 0.2.0 removes the long-form compatibility aliases that were deprecated in the 0.1 series and narrows the exported graph-family API. The canonical replacements are listed below.

Removed aliases

• grip.layout() -> grip()

• grip.layout.globalrep() -> globalrep.grip()

• grip.layout.globalrep.weighted() -> globalrep.weighted.grip()

• grip.layout.legacy() -> legacy.grip()

• grip.layout.trace() -> trace.grip()

• grip.layout.trace.legacy() -> trace.legacy.grip()

• grip.layout.trace.weighted() -> trace.grip(metric = "edge_length")

• grip.layout.weighted() -> grip(metric = "edge_length")

• grip.layout.weighted.nd() -> weighted.grip.nd()

• grip.plot() -> plot.layout()

• grip.project.3d() -> project.3d()

• grip.metric.mds.layout() -> classical.mds() (classical scaling)

• grip.optimize.kernel.gram.gkk.layout() -> kernel.gram.gkk()

• grip.score.gmds.layout() -> score.gmds()

• grip.gmds.layout.result() -> gmds.result() (now internal)

• grip.edge.length.density.stiffness() -> edge.length.density.stiffness()

• grip.prepare.landmark.geodesic.kk() -> prepare.landmark.geodesic.kk()

• grip.prepare.geodesic.kk() -> prepare.geodesic.kk()

• grip.prepare.graph.geodesic.mds() -> prepare.graph.geodesic.mds()

• grip.prepare.misf.geodesic.kk() -> prepare.misf.geodesic.kk()

• grip.prepare.edge.kk() -> prepare.edge.kk()

• grip.score.landmark.geodesic.kk() -> score.landmark.geodesic.kk()

• grip.score.geodesic.kk() -> score.geodesic.kk()

• grip.score.misf.geodesic.kk() -> score.misf.geodesic.kk()

• grip.optimize.landmark.geodesic.kk() -> landmark.geodesic.kk()

• grip.optimize.geodesic.kk() -> geodesic.kk()

• grip.optimize.misf.geodesic.kk() -> misf.geodesic.kk()

• grip.optimize.edge.kk.layout() -> edge.kk()

• grip.optimize.edge.gkk.layout() -> edge.kk()

• grip.optimize.edge.isometric.layout() -> edge.kk()

• grip.optimize.edge.repulsive.stage() -> edge.repulsive.stage()

• grip.optimize.repulsive.stage() -> repulsive.stage()

• grip.edge.repulsive.state() -> edge.repulsive.state()

• grip.repulsive.state() -> repulsive.state()

• grip.build.misf.weighted() -> build.weighted.misf()

• grip.build.misf() -> build.misf()

• grip.geometry.diagnostics() -> geometry.diagnostics()

• grip.params.from.summary() -> params.from.summary()

• grip.score.layout() -> score.layout()

• grip.compare.layouts() -> compare.layouts()

Graph-family helpers

Complete ⁠*.surface.graph()⁠ and ⁠*.solid.graph()⁠ constructors remain public and return reusable bundles. Use the bundle's edges, coords.surface, and coords.param components instead of the former specialized edge-list, standalone embedding, and parameter-coordinate exports. Primitive generators such as edges.path(), edges.cycle(), edges.mesh(), and edges.cube() remain public.

Migrating classical and metric stress MDS workflows

Description

In grip through version 0.2.0, metric.mds() used stats::cmdscale(). From version 0.2.0.9000, that algorithm is named classical.mds(), and metric.mds() minimizes raw distance stress, using native SGD by default. This is an intentional behavioral change rather than a deprecated alias.

Preserve an existing analysis

Replace metric.mds(...) with classical.mds(...), and explicit init = "metric_mds" with init = "classical_mds". Both edge.kk() and kernel.gram.gkk() default to classical initialization, preserving their previous default algorithm without requiring smacof. add and eig are classical-scaling arguments and are accepted only by classical.mds(). Existing saved coordinates, figure labels, and cache fields named metric_mds from older versions remain classical results. Renaming a call does not require recomputing those fits.

Request stress minimization

Use metric.mds(...) or edge.kk(init = "metric_mds", ...) to use the default native SGD backend. For control over multiple starts and budgets, call metric.mds() first and pass coords = fit$coords to edge.kk(). Check metadata$starts, metadata$termination, and the independently calculated stress diagnostics. Both backends are local optimizers; an iteration limit or a finite result does not certify an optimum.

Preserve a previous SMACOF analysis

Install the optional smacof package and explicitly request metric.mds(backend = "smacof", ...). The eps tolerance belongs to that backend and must not be supplied to SGD. To retain a SMACOF initializer in a refinement workflow, compute it explicitly and pass its coordinates to edge.kk() or kernel.gram.gkk(). No automatic backend fallback is made.

Native SGD backend

metric.mds(backend = "sgd", max.iter = 30, ...) explicitly selects the default backend with a short trial budget, without requiring smacof. SGD uses the same uniform pair weights and shortest-path targets. Its controls remain provisional calibration choices, and max.iter counts complete pair passes. Schedule completion is reported as iteration_limit, not convergence. Inspect per-start records and metadata$sgd checkpoint histories. Selecting init = "metric_mds" in refinement methods follows the default SGD backend; their default init = "classical_mds" is unchanged. A different optimizer cannot repair inaccurate graph distances.

Reproducibility

Raw stress is measured against the original graph-distance units after restoring scale from the backend. Target-normalized raw stress and scale-profiled Stress-1 have the same optimal shapes when scale is free and pair weights match, but literal Stress-1 at the returned raw-stress scale is a different diagnostic value. Record the algorithm, objective, backend/package versions, graph identity, scale policy, and start settings in new result manifests. Recompute downstream refinement when changing its initializer, and use new cache identities rather than replacing historical classical results in place.

Build the gripui Shiny application

Description

Build the gripui Shiny application

Usage

gripui.app(project)

Arguments

Value

A shiny.appobj.

Examples

graph <- list(adj_list = list(2L, c(1L, 3L), 2L))
layouts <- data.frame(
  candidate = "toy.layout",
  stage = "layout",
  seed = 1L,
  status = "ok",
  stringsAsFactors = FALSE
)
project <- gripui.project(graph = graph, layouts = layouts, title = "Toy project")
app <- gripui.app(project)
inherits(app, "shiny.appobj")

Build the graph-family geometry explorer Shiny application

Description

Build the graph-family geometry explorer Shiny application

Usage

gripui.family.app(
  catalog = gripui.graph.family.catalog(),
  title = "Graph Family Geometry Explorer",
  subtitle = "Interactive geometry browser for synthetic benchmark families."
)

Arguments

Value

A shiny.appobj.

Examples

app <- gripui.family.app()
inherits(app, "shiny.appobj")

Catalog of graph families for the geometry explorer app

Description

The catalog is a registry used by gripui.family.app() to populate its family selector, presets, parameter controls, builder calls, and source references.

Usage

gripui.graph.family.catalog()

Value

A named list of family descriptors.

Examples

catalog <- gripui.graph.family.catalog()
names(catalog)
catalog$mesh$function_name

Create a normalized gripui project object

Description

Create a normalized gripui project object

Usage

gripui.project(
  graph = NULL,
  layouts,
  title = NULL,
  subtitle = NULL,
  notes = NULL
)

Arguments

Value

An object of class gripui_project.

Examples

graph <- list(adj_list = list(2L, c(1L, 3L), c(2L, 4L), 3L))
layouts <- data.frame(
  candidate = "path.default",
  stage = "layout",
  seed = 1L,
  status = "ok",
  stringsAsFactors = FALSE
)
project <- gripui.project(graph = graph, layouts = layouts, title = "Path graph")
project$meta$title

Convert compare.layouts() output into a gripui_project

Description

Convert compare.layouts() output into a gripui_project

Usage

gripui.project.from.compare(
  compare.obj,
  graph = NULL,
  vertex.data = NULL,
  graph.info = NULL,
  title = NULL
)

Arguments

Value

A gripui_project.

Examples

edges <- edges.path(5)
cmp <- compare.layouts(
  edges = edges,
  n = 5,
  candidates = "default",
  seeds = 1L,
  return.layouts = TRUE
)
graph <- list(
  adj_list = list(2L, c(1L, 3L), c(2L, 4L), c(3L, 5L), 4L)
)
project <- gripui.project.from.compare(cmp, graph = graph, title = "Path compare")
nrow(project$layouts)

Create a gripui_project from a directory of saved artifacts

Description

Create a gripui_project from a directory of saved artifacts

Usage

gripui.project.from.dir(root, graph = NULL, title = NULL, subtitle = NULL)

Arguments

Value

A gripui_project.

Examples

root <- tempfile("gripui-bundle-")
dir.create(root)
on.exit(unlink(root, recursive = TRUE, force = TRUE), add = TRUE)
dir.create(file.path(root, "catalog"), recursive = TRUE, showWarnings = FALSE)
dir.create(file.path(root, "graph"), recursive = TRUE, showWarnings = FALSE)
dir.create(file.path(root, "artifacts", "layouts"), recursive = TRUE, showWarnings = FALSE)

graph <- list(adj_list = list(2L, c(1L, 3L), 2L))
saveRDS(graph, file.path(root, "graph", "graph.rds"))

coords.path <- file.path(root, "artifacts", "layouts", "toy_embedding.tsv")
utils::write.table(
  data.frame(
    vertex_id = c("v1", "v2", "v3"),
    x = c(1, 2, 3),
    y = c(0, 0, 0),
    stringsAsFactors = FALSE
  ),
  file = coords.path,
  sep = "\t",
  quote = TRUE,
  row.names = FALSE,
  col.names = TRUE
)
utils::write.table(
  data.frame(
    candidate = "toy.layout",
    stage = "bundle",
    seed = 1L,
    status = "ok",
    coords_path = file.path("artifacts", "layouts", "toy_embedding.tsv"),
    stringsAsFactors = FALSE
  ),
  file = file.path(root, "catalog", "layout_catalog.tsv"),
  sep = "\t",
  quote = TRUE,
  row.names = FALSE,
  col.names = TRUE
)

project <- gripui.project.from.dir(root, title = "My project")
project$layouts$availability

Validate a gripui_project

Description

Validate a gripui_project

Usage

gripui.validate.project(project)

Arguments

Value

Invisibly returns TRUE when validation succeeds.

Examples

layouts <- data.frame(
  candidate = "test.layout",
  stage = "layout",
  seed = 1L,
  status = "ok",
  stringsAsFactors = FALSE
)
project <- gripui.project(graph = NULL, layouts = layouts, title = "Validation example")
gripui.validate.project(project)

HMP Illumina 16S Giant-Component Graph

Description

A symmetric k-nearest-neighbor graph constructed from samples from the Ravel-led University of Maryland Baltimore Human Microbiome Project (UMB-HMP) longitudinal vaginal cohort, generated by Illumina 16S rRNA amplicon sequencing. Rows without an explicit HMP project label, rows from the related U01 cohort, and legacy 454 runs are excluded before preprocessing.

Usage

hmp.gc

Format

A named list with components:

adj_list

Adjacency list with 1-based integer neighbor indices.

weight_list

Parallel list of Euclidean edge lengths in the ten-component PCA representation.

vertex_data

Data frame with one row per HMP sample and columns for sample identifier, HMP project, sequencing platform and phase, CST and subCST annotations, and retained-read diagnostics.

graph_info

Named list recording the cohort filter, representation, graph constructor, selected k, and graph dimensions.

Details

Taxonomic count features detected in at least one percent of the retained HMP samples are converted to relative abundance and represented by ten principal components. A symmetric k = 3 nearest-neighbor graph is built in that representation, and the largest connected component is retained.

Source

Derived from Illumina 16S rRNA amplicon profiles from the Ravel-led UMB-HMP longitudinal vaginal cohort. Exact graph edges, sample metadata, feature screening results, and provenance are distributed under ⁠inst/extdata/hmp_gc/⁠.

Examples

data(hmp.gc)
length(hmp.gc$adj_list)
hmp.gc$graph_info[c("assay", "graph_constructor", "selected_k")]

HMP/U01 Coarsened Giant-Component Graph

Description

A bundled coarsened graph derived from the giant connected component of the HMP+U01 16S amplicon iKNN graph used in the HMP/U01 layout-selection study. The upstream graph came from the ⁠>=1%⁠ relative-abundance plus PCA branch with k = 3, after restricting to the biologically meaningful major component. The graph was then greedily coarsened in two rounds from 6474 vertices to 1828 supernodes.

Usage

hmp.u01.gc.coarse

Format

A named list with components:

adj_list

Adjacency list of length 1828, with 1-based integer neighbor indices.

weight_list

Parallel list of positive edge weights.

vertex_data

Data frame with one row per coarse vertex and columns vertex_id, size, cst, subcst, dcst.depth1.absorb, dcst.depth1.rare, dcst.depth2.absorb, dcst.depth2.rare, ph, and log10_reads.

graph_info

Named list summarizing provenance and graph-level metadata, including the original and coarsened vertex counts, selected k, edge count, and coarsening rounds.

Details

The object is intended for examples and vignettes on real-world 3D layout comparison. It is small enough to ship with the package while preserving the arm-like graph structure that motivated the tuned preset analysis.

Source

Derived from the publicly available HMP+U01 16S amplicon analysis workflow used in the chm_paper project. Raw bundled artifacts and a provenance note are available under ⁠inst/extdata/hmp_u01_gc_coarse/⁠.

Examples

data(hmp.u01.gc.coarse)
length(hmp.u01.gc.coarse$adj_list)
head(hmp.u01.gc.coarse$vertex_data[, c("vertex_id", "size", "cst", "subcst")])

Weighted irregular annulus surface helpers

Description

Convenience helpers that build an annulus from deterministically irregular concentric rings with varying sample counts, stitch adjacent rings into a locally triangulated graph, and then optionally lift the resulting irregular planar parameterization into \mathbb{R}^3. This provides a non-lattice annulus family with boundary and nonuniform local valence.

Usage

irregular.annulus.surface.graph(
  rings = 6,
  outer.count = 28,
  outer.radius = 1,
  inner.radius = 0.45,
  count.irregularity = 0.2,
  radial.irregularity = 0.35,
  phase.twist = 0.35,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.6,
  freq.u = 1,
  freq.v = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.annulus.surface.graph() returns a list with components:

• edges: the irregular annulus edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the irregular planar annulus coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.annulus",

• surface: the chosen surface name,

• rings: number of concentric rings,

• ring_sizes: sample counts on each ring,

• label: a human-readable family label.

Examples

annulus <- irregular.annulus.surface.graph(rings = 3, outer.count = 12)

Weighted irregular ball solid helpers

Description

Convenience helpers that build a layered simplicial ball by taking a subdivided triangulated polyhedron, normalizing its vertices to directions on the sphere, placing those directions on nested radial layers, and connecting adjacent layers by a deterministic prism-to-tetrahedra edge pattern. The center vertex is included explicitly, so the resulting graph is genuinely volumetric rather than just a closed surface.

Usage

irregular.ball.solid.graph(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1,
  layers = 3,
  outer.radius = 1,
  radial.irregularity = 0.25,
  layer.twist = 0.35,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq.theta = 2,
  freq.phi = 2,
  twist = 0.6,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.ball.solid.graph() returns a list with components:

• edges: the irregular ball edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the canonical 3D ball coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.ball",

• surface: the chosen solid geometry family,

• base: the chosen base polyhedron,

• level: the surface subdivision depth,

• layers: number of non-center radial layers,

• radii: the radial layer values,

• label: a human-readable family label.

Examples

ball <- irregular.ball.solid.graph(
  base = "tetrahedron", level = 0, layers = 2
)

Weighted irregular double-torus surface helpers

Description

Convenience helpers that build a closed genus-2 surface from a deterministically irregular slice family whose cyclic cross-sections follow a 1 -> 3 -> 1 loop transition between two poles. This gives a non-lattice, point-sampled double-torus graph together with either the canonical 3D embedding or simple bulged, twisted, and wavy deformations of that geometry.

Usage

irregular.double.torus.surface.graph(
  slices = 11,
  tube.count = 14,
  branch.length = 0.85,
  branch.offset = 0.72,
  tube.radius = 0.28,
  transition.width = 0.42,
  count.irregularity = 0.2,
  axial.irregularity = 0.3,
  phase.twist = 0.35,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.25,
  freq.x = 2,
  freq.theta = 2,
  twist = 0.6,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.double.torus.surface.graph() returns a list with components:

• edges: the irregular double-torus edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the canonical 3D double-torus coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.double.torus",

• surface: the chosen surface name,

• slices: number of non-pole slices,

• slice_sizes: vertex counts in each slice,

• slice_components: number of cyclic components in each slice,

• label: a human-readable family label.

Examples

double_torus <- irregular.double.torus.surface.graph(
  slices = 7, tube.count = 8
)

Weighted irregular pair-of-pants surface helpers

Description

Convenience helpers that build a pair-of-pants domain from deterministically irregular horizontal slices, sample each surviving slice interval with varying point counts, and stitch adjacent slices into a locally triangulated surface-with-boundary graph. The resulting irregular planar parameterization can then be lifted into \mathbb{R}^3 using the same planar surface families as the triangulated annulus and irregular annulus helpers.

Usage

irregular.pair.of.pants.surface.graph(
  slices = 11,
  outer.count = 28,
  outer.radius = 1.1,
  hole.radius = 0.24,
  hole.offset = 0.38,
  hole.height = 0.18,
  count.irregularity = 0.2,
  vertical.irregularity = 0.35,
  phase.twist = 0.35,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.6,
  freq.u = 1,
  freq.v = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.pair.of.pants.surface.graph() returns a list with components:

• edges: the irregular pair-of-pants edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the irregular planar pair-of-pants coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.pair.of.pants",

• surface: the chosen surface name,

• slices: number of horizontal sample slices,

• slice_sizes: vertex counts in each slice,

• slice_components: number of connected slice intervals in each slice,

• label: a human-readable family label.

Examples

pair_of_pants <- irregular.pair.of.pants.surface.graph(
  slices = 5, outer.count = 12
)

Irregular rectangle surface helpers

Description

Convenience helpers that keep ordinary rectangular-mesh adjacency but replace the regular parameter grid by a deterministic irregular rectangle. The resulting family stays simply connected and rectangular in topology while breaking the strongest row/column symmetries of the lattice.

Usage

irregular.rectangle.surface.graph(
  h,
  w = h,
  surface = c("flat", "saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  x.scale = 1,
  y.scale = 1,
  row.irregularity = 0.2,
  col.irregularity = 0.2,
  row.phase = 0.35,
  col.phase = 0.65,
  interior.warp = 0.08,
  shear = 0,
  min.step.ratio = 0.3,
  connectivity = c("orthogonal", "diagonal"),
  normalize = c("median", "mean", "none")
)

Arguments

Details

The coords.param component contains the irregular planar parameter coordinates. The coords.surface component lifts those coordinates into \mathbb{R}^3. irregular.rectangle.surface.graph() returns a reusable weighted-graph bundle with the induced Euclidean edge lengths.

Value

The coords_param component is an n x 2 numeric matrix with columns u and v.

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.rectangle.surface.graph() returns a list with components:

• edges: the undirected rectangular-mesh edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the irregular 2D parameter coordinates,

• coords_regular_param: the underlying regular 2D parameter coordinates used to define the boundary-vanishing warp,

• row_breaks: per-row parameter coordinates in row order,

• col_breaks: per-column parameter coordinates in column order,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.rectangle",

• surface: the chosen surface name,

• connectivity: the chosen mesh connectivity rule,

• label: a human-readable family label.

Examples

rectangle <- irregular.rectangle.surface.graph(4, 5, surface = "ripple")

Weighted irregular shell solid helpers

Description

Convenience helpers that build a layered simplicial shell by placing the vertices of a subdivided triangulated polyhedron on nested inner-to-outer radial layers and connecting adjacent layers by the same deterministic prism-to-tetrahedra edge pattern used for irregular.ball.solid.*(). The result is a genuinely volumetric shell graph with a hollow interior.

Usage

irregular.shell.solid.graph(
  base = c("tetrahedron", "octahedron", "icosahedron"),
  level = 1,
  layers = 3,
  inner.radius = 0.45,
  outer.radius = 1,
  radial.irregularity = 0.25,
  layer.twist = 0.35,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq.theta = 2,
  freq.phi = 2,
  twist = 0.6,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.shell.solid.graph() returns the same components as irregular.ball.solid.graph(), with family set to "irregular.shell".

Examples

shell <- irregular.shell.solid.graph(
  base = "tetrahedron", level = 0, layers = 2
)

Weighted irregular sphere surface helpers

Description

Convenience helpers that build a sphere from deterministically irregular latitude bands with varying sample counts, stitch adjacent bands into a locally triangulated graph, and then realize that graph in \mathbb{R}^3 using either a standard sphere, an ellipsoid, or a wavy radial modulation.

Usage

irregular.sphere.surface.graph(
  bands = 6,
  equator.count = 28,
  count.irregularity = 0.2,
  lat.irregularity = 0.35,
  phase.twist = 0.35,
  surface = c("standard", "ellipsoid", "wavy"),
  radius = 1,
  amplitude = 0.2,
  freq.theta = 3,
  freq.lat = 2,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.sphere.surface.graph() returns a list with components:

• edges: the irregular sphere edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the irregular angular parameter coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.sphere",

• surface: the chosen surface name,

• bands: number of non-pole latitude bands,

• band_sizes: sample counts in each latitude band,

• label: a human-readable family label.

Examples

sphere <- irregular.sphere.surface.graph(bands = 3, equator.count = 12)

Weighted irregular torus surface helpers

Description

Convenience helpers that build a torus from deterministically irregular major-cycle rings with varying sample counts, stitch adjacent rings into a locally triangulated toroidal graph, and then realize that graph in \mathbb{R}^3 using either a standard, pinched, or wavy tube geometry.

Usage

irregular.torus.surface.graph(
  major.rings = 8,
  tube.count = 16,
  count.irregularity = 0.2,
  major.irregularity = 0.25,
  phase.twist = 0.35,
  surface = c("standard", "pinched", "wavy"),
  major.radius = 2,
  minor.radius = 0.75,
  amplitude = 0.2,
  freq.major = 2,
  freq.minor = 1,
  twist = 0.25,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

irregular.torus.surface.graph() returns a list with components:

• edges: the irregular torus edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the irregular angular parameter coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "irregular.torus",

• surface: the chosen surface name,

• major_rings: number of major-cycle rings,

• ring_sizes: sample counts around each ring,

• label: a human-readable family label.

Examples

torus <- irregular.torus.surface.graph(major.rings = 4, tube.count = 8)

Intrinsically weighted k-ary tree helpers

Description

Convenience helpers that keep the exact edges.kary.tree() topology but assign edge lengths directly from combinatorial tree metadata rather than from an ambient Euclidean embedding. Each edge weight is constructed as

\mathrm{base\_length} \times \mathrm{depth\_factor(child\ depth)} \times \mathrm{branch\_factor(child\ slot)}

so the user can control tapering with depth separately from child-slot asymmetry.

Usage

kary.tree.weighted.graph(
  k = 2,
  depth = 2,
  base.length = 1,
  depth.rule = c("geometric", "constant", "custom"),
  depth.decay = 0.85,
  depth.factors = NULL,
  branch.rule = c("linear", "uniform", "custom"),
  branch.spread = 0.3,
  branch.factors = NULL,
  normalize = c("median", "mean", "none")
)

Arguments

Details

The returned object is intended as an intrinsic weighted-tree benchmark family. It exposes the same edge matrix as edges.kary.tree() together with edge weights, vertex depths, parent indices, and an edge table that records the depth and branch slot associated with each tree edge.

Value

A list with components:

• edges: the k-ary tree edges,

• n: number of vertices,

• edge_weights: normalized positive intrinsic edge lengths,

• weight_scale: normalization constant applied to the raw edge lengths,

• vertex_depth: depth of each vertex, with the root at depth 0,

• parent: parent vertex index for each vertex, with the root parent recorded as 0,

• edge_table: data frame containing parent, child, parent_depth, child_depth, branch_index, raw_weight, and normalized edge_weight,

• depth_factors: the applied per-depth multipliers,

• branch_factors: the applied per-child-slot multipliers,

• family: always "kary.tree.weighted",

• k: the branching factor,

• depth: the requested tree depth,

• label: a human-readable family label.

Examples

tree <- kary.tree.weighted.graph(k = 2, depth = 2)

Optimize a kernel Gram-gKK layout

Description

kernel.gram.gkk() extends edge-only gKK with a local Riemannian star penalty. The off-diagonal Gram term preserves target inner products between pairs of incident edge directions:

\frac{\lambda_{\mathrm{gram}}}{2}\sum_{u}\sum_{v<v'\in N(u)} \omega_u(v,v')\left( \langle z_v-z_u,z_{v'}-z_u\rangle - s^2 w_{uv}w_{uv'}\cos\alpha_u(v,v')\right)^2.

The star weights are built by graph.riemannian.star.structure(), usually with an antipodal kernel controlled by angle.power.

Usage

kernel.gram.gkk(
  coords = NULL,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  X = NULL,
  star = NULL,
  dim = 2L,
  init = c("classical_mds", "metric_mds", "random"),
  angle.power = 4,
  reliability = c("length.balance", "none"),
  min.angle.weight = 0,
  star.quantile = 0,
  lambda.edge = 1,
  lambda.gram = 1,
  stiffness.method = c("density", "uniform", "distance_power"),
  stiffness.transform = c("identity", "sqrt", "log"),
  density.mix = 1,
  bandwidth = NULL,
  density.n = 512L,
  distance.power = 0,
  stiffness.floor = 0,
  stiffness.ceiling = Inf,
  scale.mode = c("profiled", "identity", "user"),
  scale = NULL,
  max.iter = 50L,
  initial.step = 0.1,
  step.shrink = 0.5,
  armijo.factor = 1e-04,
  grad.tol = 1e-08,
  min.step = 1e-08,
  edge.length.epsilon = 1e-08,
  distance.floor = 1e-08,
  recenter = TRUE,
  return.trace = TRUE,
  diagnostics = TRUE,
  seed = 1L,
  engine = c("cpp", "R")
)

Arguments

Value

A "grip_gmds_layout" object with method "kernel_gram_gkk".

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
prepared <- prepare.graph.geodesic.mds(cycle_edges, n = 6)
fit <- kernel.gram.gkk(
  coords = initial, prepared = prepared, X = initial,
  max.iter = 1, density.n = 32, engine = "R"
)

Optimize a layout under the landmark geodesic KK energy

Description

landmark.geodesic.kk() applies a deterministic warm-started gradient-descent polish under the sparse landmark geodesic KK energy. It starts from an existing layout and refines it, rather than replacing the full multiscale GRIP refinement pipeline.

Usage

landmark.geodesic.kk(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  local.nbrs = 20L,
  landmark.count = 8L,
  max.iter = 16L,
  stiffness = 1,
  distance.floor = 1e-08,
  edge.length.epsilon = 1e-08,
  initial.step = 1,
  step.shrink = 0.5,
  armijo.factor = 1e-04,
  grad.tol = 1e-08,
  min.step = 1e-08,
  recenter = TRUE,
  return.trace = FALSE
)

Arguments

Details

The implementation fits the LGKK target scale L0 once from the starting layout and then optimizes against those fixed target path lengths. That keeps the gradient simple and makes the resulting line search robust for an initial implementation.

Value

A list with coords, trace, frames, prepared, and score.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
prepared <- prepare.landmark.geodesic.kk(
  cycle_edges, n = 6, local.nbrs = 2, landmark.count = 2
)
fit <- landmark.geodesic.kk(initial, prepared = prepared, max.iter = 1)

Construct sparse MDS targets from landmark distances

Description

Converts supplied distances into soft pairwise fitting targets for [metric.mds()]. No distances are recomputed and no graph paths are inferred. With 'weighting = "uniform"', every retained unordered pair has endpoint multiplicities one, giving inverse-squared distance stress on those pairs. With 'weighting = "region"', samples belong to their nearest landmark (ties use landmark row order). The update at a non-landmark endpoint represents the number of samples in the landmark's region at most half the target distance from that landmark. Opposite landmark directions are combined. Optional local pairs replace landmark contributions for that pair with multiplicities one at each endpoint. Actual fitting weights divide these multiplicities by squared target distances. Region weighting can give asymmetric endpoint updates; it is not ordinary symmetric weighted stress.

Usage

landmark.mds.constraints(
  distance.matrix,
  landmarks,
  local.pairs = NULL,
  local.distances = NULL,
  weighting = c("uniform", "region")
)

Arguments

Value

List with 'pairs', 'targets', 'count_i', and 'count_j', suitable for 'metric.mds(n = ncol(distance.matrix), constraints = ..., approximation = "sparse")'. Distances are retained in their supplied units.

Examples

X <- matrix(sin(seq_len(24)), 8, 3)
D <- as.matrix(dist(X))
C <- landmark.mds.constraints(D[c(1, 5), ], c(1, 5))
fit <- metric.mds(n = 8, constraints = C, approximation = "sparse",
                  dim = 3, max.iter = 5)

Extract coordinates from a layout result

Description

Use one extraction step for ordinary layouts, traces, MDS fits, and supported refinement results. Existing return types and direct field access are unchanged.

Usage

layout.coords(x)

Arguments

Details

For traces the final frame is selected. For MDS and refinement fits the fitted coords are selected. A plain list containing only coords is not a recognized result; pass that matrix explicitly instead.

Keep graph vertex order when reusing coordinates. MDS result fields method, coords, diagnostics, and metadata remain directly available. Stopping information in metadata is method-dependent. Trace ⁠$final⁠ and refinement ⁠$coords⁠ remain supported. Prepared caches and internal state fields are version-dependent: rebuild them when the graph or package contract changes.

Value

The coordinate matrix, unchanged, including vertex order, dimensions, dimnames, and attributes. No projection, alignment, scaling, or scoring is performed. Malformed, ambiguous, or unsupported objects produce an error.

See Also

grip(), trace.grip(), classical.mds(), geodesic.kk()

Examples

edges <- edges.path(6)
fits <- list(grip(edges, n = 6, dim = 2, seed = 1),
             trace.grip(edges, n = 6, dim = 2, seed = 1),
             classical.mds(edges = edges, n = 6))
first <- layout.coords(fits[[1]])
coords <- lapply(fits, layout.coords)
plot.layout(coords[[1]], edges = edges)
vapply(coords, function(z) score.layout(z, edges = edges, n = 6,
    sample.size.stress = 15, stress.seed = 1,
    edge.crossings = "never")$sampled.stress, numeric(1))

Compute the legacy GRIP layout

Description

This function preserves the original local-force wrapper and historical default values that were previously exposed as grip(). Use it for backwards-compatible comparisons or when you explicitly want the pre-global-repulsion behavior.

Usage

legacy.grip(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 3,
  placement = c("barycenter", "circle"),
  preset = NULL,
  rounds = 20,
  final.rounds = 25,
  num.init = 36,
  num.nbrs = 10,
  r = 0.15,
  s = 3,
  repulsion.factor = 1,
  tinit.factor = 6,
  seed = 6,
  disconnected = c("components", "error")
)

Arguments

Value

A numeric matrix with n rows and dim columns.

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 <- cbind(1:5, 2:6)
coords <- legacy.grip(edges, n = 6, dim = 2,
                             placement = "barycenter",
                             rounds = 5, final.rounds = 5,
                             num.init = 3, num.nbrs = 4,
                             seed = 1)
round(coords, 3)

Mask pattern helpers for recursive grid families

Description

Convenience constructors for connected k \times k keep-masks that can be passed to recursive.mask.grid.surface.graph() to build generalized mask carpets. These helpers are meant to provide explicit benchmark motifs such as cross, border, corner, and asymmetric-hole patterns.

Usage

mask.cross(k = 5, arm.width = 1)

mask.border(k = 5, thickness = 1)

mask.corner(
  k = 5,
  width = 2,
  corner = c("top_left", "top_right", "bottom_left", "bottom_right")
)

mask.asymmetric.holes(k = 5, hole.size = 1)

Arguments

Details

The returned masks use standard matrix display orientation: rows run from top to bottom and columns run from left to right.

Value

A logical k \times k keep-mask.

Examples

asymmetric <- mask.asymmetric.holes(k = 5, hole.size = 1)
border <- mask.border(k = 5, thickness = 1)
corner <- mask.corner(k = 5, width = 2, corner = "top_left")
cross <- mask.cross(k = 5, arm.width = 1)

Weighted Menger sponge surface helpers

Description

Convenience wrappers around recursive.cube.mask.surface.*() using the classic 3 \times 3 \times 3 Menger-sponge keep-mask. These helpers provide a named cubical 3D benchmark family whose vertices are occupied subcubes and whose edges connect face-adjacent occupied cells.

Usage

menger.sponge.surface.graph(
  level = 2,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x.scale = 1,
  y.scale = 1,
  z.scale = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z, where n = 20^level.

menger.sponge.surface.graph() returns the same components as recursive.cube.mask.surface.graph(), with family set to "menger.sponge" and a family-specific class and label.

Examples

sponge <- menger.sponge.surface.graph(level = 1)

Weighted mesh surface helpers

Description

Convenience helpers that lift a rectangular mesh parameter grid into \mathbb{R}^3 and use the induced Euclidean edge lengths as positive graph weights. These helpers are intended for benchmark families where the topology is a plain mesh but the intended metric comes from a curved ambient geometry.

Usage

mesh.surface.graph(
  h,
  w = h,
  surface = c("saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  x.scale = 1,
  y.scale = 1,
  connectivity = c("orthogonal", "diagonal"),
  normalize = c("median", "mean", "none")
)

Arguments

Details

The coords.surface component contains the 3D coordinates of the lifted grid. mesh.surface.graph() returns a reusable weighted-graph bundle containing the mesh edges, induced edge weights, the 3D surface coordinates, and the 2D parameter coordinates.

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

mesh.surface.graph() returns a list with components:

• edges: the undirected mesh edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the 2D parameter-grid coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "mesh",

• surface: the chosen surface name,

• connectivity: the chosen mesh connectivity rule,

• label: a human-readable family label.

Examples

mesh <- mesh.surface.graph(4, 5, surface = "saddle")

Metric stress MDS using stochastic gradient descent or SMACOF

Description

metric.mds() fits Euclidean coordinates to graph distances. The default approximation = "full" minimizes raw stress over all shortest-path distances, using native stochastic gradient descent (SGD, the default) or smacof::mds(type = "ratio"). With approximation = "sparse", pivots and sparse SGD approximate long-range interactions without constructing an all-pairs distance matrix. Only the SMACOF backend requires the optional smacof package. Before version 0.2.0.9000, this name performed classical scaling; use classical.mds() to retain that behavior. The add and eig arguments belong to classical.mds() only.

Usage

metric.mds(
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  dim = 2L,
  init = c("classical", "random"),
  n.init = 1L,
  max.iter = 1000L,
  eps = 1e-08,
  seed = 1L,
  diagnostics = TRUE,
  scale.mode = c("profiled", "identity"),
  distance.floor = 1e-08,
  edge.length.epsilon = 1e-08,
  band.quantiles = c(1/3, 2/3),
  backend = c("sgd", "smacof"),
  sgd.control = list(),
  pair.weights = c("uniform", "inverse_squared"),
  approximation = c("full", "sparse"),
  sparse.control = list(),
  constraints = NULL,
  distance.matrix = NULL,
  resume = NULL
)

Arguments

Details

With approximation = "full", the objective is

S(Z) = \sum_{i<j}w_{ij}(\|z_i-z_j\|_2-\delta_{ij})^2.

By default, all pair weights are one. With pair.weights = "inverse_squared", w_{ij}=1/\delta_{ij}^2, as in Zheng et al. (2018); stress is then the sum of squared relative distance errors. Edge weights define graph distances; pair.weights separately specifies their importance in the stress objective. Both backends, coordinate rescaling, checkpoint/start selection, and stress metadata use the selected weights. The common score.gmds() diagnostic panel retains its own definitions and does not become a weighted objective report. SMACOF normalizes targets internally. Returned coordinates are rescaled to minimize raw stress against the original input distances. scale.mode controls the optional diagnostic panel only, not the optimization objective.

Target-normalized raw stress and scale-profiled Stress-1 select the same shapes when global scale is free and pair weights agree. Their values at a fixed coordinate scale need not agree. Both the literal and target-profiled Stress-1 values are independently calculated in metadata; the backend's own reported stress is retained separately in the start summaries.

The first run uses init; subsequent runs use random configurations. The smallest achieved raw stress selects the result. A backend result that increases stress beyond numerical tolerance is rejected in favor of its scaled start and marked accordingly. Failed starts are recorded, and all failing starts cause an error. Iteration limits are not convergence or global optimality certificates. Collinear or planar starts may remain in their initial span; use multiple starts to investigate this sensitivity.

Newly prepared graph objects supply symmetric strict shortest distances, separately from retained-route lengths used in path diagnostics. Rebuild older cached preparations if their near-tie distance matrix is asymmetric.

Targets must be finite, symmetric, and nonnegative, with zero diagonal and at least one positive distance. Missing and infinite distances are rejected. Inverse-squared weighting requires strictly positive off-diagonal targets; zero distances are rejected, not floored. Uniform weighting still allows zero distances. Extreme ratios that overflow or underflow the normalized weights are rejected. Supplied starts may have coincident points but must not be wholly collapsed. Full MDS uses dense all-pairs matrices; use approximation = "sparse" when that preparation is too large. Sparse behavior is described below.

Value

A "grip_gmds_layout" object with method "metric_mds". metadata$engine and metadata$approximation identify both choices. In full mode, metadata records the objective, backend/version, achieved raw stress, weighted target-normalized RMSE, both weighted Stress-1 conventions, selected start, coordinate scale multiplier, and per-start losses and stopping information. SGD adds per-start elapsed seconds (native fitting including scoring), native seeds, pair-update counts, best epochs, and checkpoint histories in metadata$sgd. Histories use RMS-normalized target-distance units and include both raw and scale-profiled stress. Internally, inverse-squared weights are 1 / (distance / input_rms_distance)^2; the corresponding stress is already dimensionless. Uniform raw stress is converted to squared input-distance units for public metadata. Weighted target-normalized RMSE takes the square root of the ratio of stress to the sum of weighted squared target distances. SGD reports iteration_limit and converged = FALSE when its schedule finishes, including when an earlier checkpoint is returned.

Full SGD behavior

Every pass visits all unordered pairs in shuffled order. The pair step is clipped at min(rate * normalized_pair_weight, 1). Rates use RMS-normalized distance units for both weighting choices; changing input distance units therefore preserves the optimization trajectory up to scale. The default schedule is shared across weighting choices, not a reproduction of the graph-dependent annealing schedule used in Zheng et al. (2018). Symmetric clipped updates follow Zheng et al. (2018); the hybrid exponential/harmonic schedule follows Hangan et al. (2026). The terminal epoch is always scored. The best independently scored checkpoint, including initialization, is retained using scale-profiled stress; checkpoint scoring does not rescale the ongoing search. The R wrapper independently rescales and recomputes its returned stress. The legacy user-controlled exponential schedule's final rate is its boundary value after the planned passes, not its last applied rate. The hybrid schedule switches after floor(switch.ratio * schedule.epochs) passes, at one tenth the initial rate (or the initial rate if the switch is immediate). Its harmonic segment approaches final.rate at the boundary only when the switch rate exceeds final.rate; otherwise that segment stays constant at the switch rate. With switch.ratio = 1, no harmonic segment occurs and final.rate is unused. Coincident points with positive target distance are separated along a seeded direction; zero targets are not floored. Without such collisions, updates preserve a deficient initial affine span. Use full-dimensional random starts to examine this sensitivity. This backend retains quadratic pair storage and work per pass. It does not validate the supplied graph distances.

Sparse approximation

Sparse SGD implements the asymmetric updates of Zheng et al. (2018), Algorithm 2, based on the model of Ortmann et al. (2017). The graph must have positive finite edge lengths and be connected. Disconnected graphs are rejected without repair. Pivots are chosen with probability proportional to distance to the nearest selected pivot, starting from a uniform random vertex. Graph lengths are normalized by their maximum before shortest-path calculations. Exact distance ties in region assignment go to the earliest selected pivot. Near floating-point boundaries, general weighted graphs can still be sensitive to arithmetic. Each nonadjacent vertex receives an influence from a pivot weighted by the number of vertices in that pivot's region within half their separation, divided by squared separation. The reverse influence can be zero or different. Edges have inverse-squared weights at both endpoints.

Edge targets are the supplied edge lengths, as in the upstream sparse implementation. For a weighted edge with a shorter alternative route, that target differs from the shortest-path target of full MDS. Exact full-pivot update parity requires every edge to be a shortest path, as with unit lengths or Euclidean chord lengths, and matched starts, rates and order.

Targets are normalized by RMS over the retained unordered pairs; endpoint weights use the same units. Legacy graph calls default to grip's hybrid schedule; prepare.sparse.mds() inputs default to the published fixed-budget "zheng" schedule. Select the schedule explicitly when comparing methods. The terminal iterate is returned, centered and converted back to input units, with no fitted scale. A checkpoint proxy averages the two endpoint weights for each pair. Asymmetric updates are not claimed to follow the gradient of that proxy, or to decrease it monotonically. This diagnostic is not full stress or equation (19) of Zheng et al. Use independent distance evaluation to compare sparse and full layouts. No dense diagnostics or classical initialization run implicitly.

Sparse results share the metric_mds method name. coords is the terminal layout. prepared contains an edge-only graph, without a distance matrix. metadata$sparse records retained pairs, original-unit targets, endpoint multiplicities, selected pivots and region owners. Metadata also records seeds, controls, preparation/fitting seconds, native workspace estimates (separately checked for preparation and fitting), sparse_proxy_stress, its normalized root error, and stopping status. By default termination = "iteration_limit" and converged = FALSE. trace reports checkpoint proxy stress, epochs, rates and pair updates.

Recording individual SGD updates

Set sgd.control = list(trace = list(every = 100L)) to record coordinates after every 100 examined pairs in each epoch, plus the initial state and each epoch endpoint. Set every = 1L to record every pair, including no-op pairs. Tracing requires n.init = 1. It is independent of checkpoint.every. The native solver dispatches once to a compile-time specialization: when tracing is disabled, no tracing checks, copies or buffers occur in the update loop. When enabled, recording adds time and memory but never changes solver arithmetic, the random stream, stopping or the selected result.

fit$update_trace$coordinates is a list of matrices in input-distance units; fit$update_trace$steps gives the epoch, examined pairs within that epoch, and cumulative pair_updates. These are raw iterates, without Procrustes alignment, recentering or the final best-checkpoint scale adjustment; the last frame can therefore differ from fit$coords. Stress is not recomputed at each frame. The existing fit$trace remains the epoch-level diagnostic history. A resumed fit records only its new call, starting at the saved terminal state, with absolute epoch/update counts. Keep earlier fits to retain their frames.

trace$max.bytes defaults to 64 MiB. Before fitting, the solver checks an upper-bound allocation for the requested epoch budget (even with early stopping), including coordinate payloads and a conservative per-frame allowance. This allocation also counts against max.workspace.bytes. R result conversion, older retained traces and serialization need additional memory. Increase every to reduce the number of frames. Completing the epoch budget is not a convergence certificate.

Stopping, histories and continuation

Default SGD calls still exhaust the prescribed epoch budget. This is reported as metadata$stopping$reason = "epoch_budget", separately from whether the planned schedule has completed or a stopping rule was assessed. SGD always reports converged = FALSE and stopping$certified = FALSE: neither budget exhaustion nor practical stabilization certifies convergence or optimality. Full SGD returns its best scale-profiled checkpoint; sparse SGD returns its terminal iterate. Stopping uses current checkpoint diagnostics, not the running best. Metadata identifies the returned iterate and reports both best and terminal diagnostics in normalized target units.

Checkpoint history is preserved in both trace and metadata$history; full multi-start runs also retain every start's trace in metadata$sgd. History includes global epoch, diagnostic, learning rate, pair updates, checkpoint type, relative diagnostic change, centered motion, update residual and consecutive successful checks. Unassessed quantities are NA.

Opt in with stopping = list() inside sgd.control, or supply any of relative.tol (1e-6), motion.tol (1e-5), residual.tol (1e-5), patience (5), and min.epochs (10). At scheduled checkpoints after at least min.epochs, all three diagnostics must pass for patience consecutive checks. Relative change is the absolute change in current diagnostic divided by max(abs(previous), 1e-12). Motion is RMS point displacement after removing translation, without rotation alignment. The residual is the largest norm of each vertex's endpoint-weighted mean distance-error vector. Motion and residual use RMS-normalized target units. The residual is independent of learning rate, preventing a tiny rate alone from passing the rule. Positive-target collisions fail the residual check. For asymmetric sparse updates it is an update-field diagnostic, not a gradient certificate; the sparse stress proxy need not decrease. Defaults are practical safeguards, not universally calibrated scientific thresholds.

With keep.state = TRUE, the result retains terminal coordinates, native RNG, normalized targets and endpoint weights, schedule, checkpoint/stopping state, best checkpoint and preparation provenance. saveRDS()/readRDS() preserve this state. Resume with metric.mds(resume = fit, max.iter = extra). State version, platform and an integrity fingerprint are checked; the fingerprint detects accidental edits and is not a security mechanism. Reproducibility is supported on the same platform with a compatible state version. Already stabilized runs cannot resume under altered controls.

schedule.epochs fixes the initial schedule horizon, independently of call size. Pausing and resuming continues the same RNG and rate sequence without restarting or stretching its prefix. Beyond this horizon, rate at extra epoch j is last.rate / (1 + j / schedule.epochs). This extension is a practical harmonic tail, not the published unlimited-iteration schedule or a convergence guarantee. A larger fresh horizon is a different experiment. Checkpoints occur at global multiples of checkpoint.every and at the schedule horizon. Other call boundaries are recorded with scheduled = 0; they do not affect stopping or checkpoint selection in a continued run. Full fits may return such a boundary when it improves the best diagnostic for that call, but continuation always uses terminal solver state. With the same horizon and final budget, split and uninterrupted runs match; split histories additionally preserve intermediate call boundaries.

Learning-rate schedules and evidence

The original full-SGD backend adapted exponential and hybrid schedules from the implementation accompanying Hangan et al. (2026). The graph sparse-SGD extension retained those controls. The hybrid default is preserved for existing callers; it is not a demonstrated improvement over Zheng et al.'s weight-dependent schedule. The original package design records its settings as provisional calibration choices.

scheduler = "hybrid" starts at learning.rate (0.5), uses exponential decay during the first floor(switch.ratio * schedule.epochs) epochs (default fraction 0.4), then a harmonic tail toward final.rate (0.01). The switch and rate endpoints are user controls, not derived from endpoint weight extrema. scheduler = "exponential" instead uses the controlled rates in a single exponential phase. For these legacy schedules, the final rate is a planned boundary value at epoch schedule.epochs, not necessarily the last applied rate. These schedules are distinct from "zheng".

Hangan et al. motivate a fixed switch for the usual uniform-weight MDS setting, where the weight ratio does not distinguish pairs. That rationale does not establish better performance for inverse-squared, region-weighted sparse stress. Package backend comparisons and the earlier sparse-MDS comparison used hybrid controls; they did not isolate schedule effects. The October 2026 observation-method validation used "zheng" throughout. These experiments do not establish that either schedule outperforms the other. A schedule comparison must hold targets, pivots, endpoint weights, starting coordinates, update-order seeds and budgets fixed, and report independently evaluated error and runtime.

Set sgd.control = list(scheduler = "zheng", schedule.epsilon = 0.1) to use Zheng et al.'s Section II-A1 fixed-budget exponential schedule. Its rates run from ⁠1 / min(positive endpoint weights)⁠ to ⁠schedule.epsilon / max(positive endpoint weights)⁠, including both endpoints; one epoch uses the first rate. Weights are computed after grip's target normalization. schedule.epsilon defaults to 0.1; learning.rate, final.rate and switch.ratio must be omitted with this schedule. This is the default for prepare.sparse.mds() inputs, including uniform, Euclidean regional and geodesic regional preparations. Other inputs retain the hybrid default, including raw graphs and explicit constraints. Fits from observation preparations retain constraint pairs and connectivity metadata but omit duplicate constraint adjacency lists. The local-neighbor graph remains available in the original preparation's graph field.

Choosing "zheng" reproduces that schedule's rule, not every published solver setting or trajectory: epoch budget, initialization and scale, random-number generator and update order can differ. It does not implement the paper's separate Section II-A2 unlimited-iteration schedule or certify convergence. Prefer the named published schedule when the purpose is sparse-stress analysis following Zheng et al.; label hybrid runs as an alternative configuration rather than assuming they are better.

Workflow guides

Start with vignette("function-guide", package = "grip") to choose a layout, diagnostic, or reference comparison. List installed guides with vignette(package = "grip").

References

Ortmann, M., Klimenta, M. and Brandes, U. (2017). A Sparse Stress Model. doi:10.7155/jgaa.00440. Zheng, J. X., Pawar, S. and Goodman, D. F. (2018). Graph Drawing by Stochastic Gradient Descent. doi:10.1109/TVCG.2018.2859997. Hangan, D., Kobourov, S. and Miller, J. (2026). Bridging Graph Drawing and Dimensionality Reduction with Stochastic Stress Optimization. https://arxiv.org/abs/2605.00641.

See Also

prepare.sparse.mds(), classical.mds(), edge.kk(), smacof::mds()

Examples

prepared <- prepare.graph.geodesic.mds(edges.cycle(6), n = 6)
fit <- suppressWarnings(metric.mds(prepared = prepared, dim = 2, max.iter = 30))
fit$metadata$raw_stress
fit$metadata$termination # Schedule completion is not a convergence certificate.
# Schedule completion is reported explicitly, not as convergence.
fit <- suppressWarnings(metric.mds(edges = edges.cycle(8), n = 8,
  dim = 3, init = "random", backend = "sgd", max.iter = 30,
  diagnostics = FALSE))
fit$metadata$engine
fit$metadata$target_normalized_rmse
sparse <- metric.mds(edges = edges.path(30), dim = 3,
  approximation = "sparse", sparse.control = list(n.pivots = 5))
sparse$metadata$sparse_proxy_stress
# Pause after 5 epochs of a 20-epoch schedule, then continue the same run.
first <- suppressWarnings(metric.mds(edges = edges.cycle(8), n = 8,
  diagnostics = FALSE, max.iter = 5,
  sgd.control = list(keep.state = TRUE, schedule.epochs = 20)))
continued <- metric.mds(resume = first, max.iter = 15)
continued$metadata$stopping
tail(continued$metadata$history)

Optimize an embedding with the MISF-based geodesic-KK pipeline

Description

misf.geodesic.kk() runs a multiscale MISF-based geodesic-KK pipeline. It solves the top MISF graph with either full GKK or sparse LGKK, inserts lower-level vertices with the existing MISF placement helpers, refines each active MISF level under a GKK/LGKK objective, and finishes with a final full-graph polish.

Usage

misf.geodesic.kk(
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  tie.mode = NULL,
  num.init = 24L,
  num.nbrs = 20L,
  dim = NULL,
  top.level.pair.mode = NULL,
  top.level.full.limit = NULL,
  top.level.local.nbrs = NULL,
  top.level.landmark.count = NULL,
  top.level.restarts = NULL,
  top.level.max.iter = NULL,
  top.level.init = NULL,
  insertion.anchor.policy = NULL,
  insertion.anchor.count = NULL,
  insertion.anchor.weight.mode = NULL,
  insertion.max.iter = NULL,
  insertion.mode = NULL,
  insertion.layout.k = NULL,
  insertion.weighted.preset = NULL,
  insertion.grip.args = NULL,
  insertion.weighted.args = NULL,
  insertion.fr.niter = NULL,
  refinement.pair.mode = NULL,
  refinement.full.limit = NULL,
  refinement.local.nbrs = NULL,
  refinement.landmark.count = NULL,
  refinement.anchor.weight = NULL,
  refinement.anchor.weight.end = NULL,
  refinement.continuation = NULL,
  refinement.max.iter = NULL,
  final.pair.mode = NULL,
  final.full.limit = NULL,
  final.local.nbrs = NULL,
  final.landmark.count = NULL,
  final.max.iter = NULL,
  stiffness = 1,
  distance.floor = 1e-08,
  edge.length.epsilon = 1e-08,
  initial.step = 1,
  step.shrink = 0.5,
  armijo.factor = 1e-04,
  grad.tol = 1e-08,
  min.step = 1e-08,
  recenter = TRUE,
  return.trace = FALSE,
  return.frames = FALSE,
  seed = 6L
)

Arguments

Value

A list with coords, prepared, the per-stage multiscale results, the stage trace, optional trace/frame details, timing, and the final MISF score summary.

Examples

mesh_edges <- edges.mesh(4, 4)
fit <- misf.geodesic.kk(
  edges = mesh_edges, n = 16, num.init = 4, dim = 2,
  top.level.restarts = 2, top.level.max.iter = 3,
  insertion.mode = "geodesic", insertion.max.iter = 6,
  refinement.pair.mode = "auto", refinement.full.limit = 4,
  refinement.max.iter = 3, final.pair.mode = "landmark",
  final.full.limit = 4, final.max.iter = 3,
  return.trace = TRUE, seed = 1
)

Occupied-mesh and perforated-grid helpers

Description

occupied.mesh.surface.graph() builds a finite occupied-grid graph on the retained cells of a rectangular occupancy matrix and lifts those cells into \mathbb{R}^3 using the same "saddle", "paraboloid", and "ripple" families used for regular meshes.

Usage

occupied.mesh.surface.graph(
  keep,
  surface = c("saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  x.scale = 1,
  y.scale = 1,
  connectivity = c("orthogonal", "diagonal"),
  normalize = c("median", "mean", "none")
)

Arguments

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

occupied.mesh.surface.graph() returns a list with components:

• edges: the occupied-cell mesh edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the 2D parameter coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "occupied.mesh",

• surface: the chosen surface name,

• connectivity: the chosen occupied-mesh connectivity rule,

• keep: the logical occupancy matrix,

• label: a human-readable family label.

Examples

keep <- matrix(TRUE, nrow = 4, ncol = 5)
keep[2, 3] <- FALSE
occupied <- occupied.mesh.surface.graph(keep, surface = "paraboloid")

Extract layout parameters from a comparison summary row

Description

Converts one row of the summary data frame returned by compare.layouts into a named list of parameters suitable for passing to grip or back into a compare.layouts(candidates = ...) call.

Usage

params.from.summary(summary.row)

Arguments

Value

A named list with elements placement, rounds, final_rounds, num_init, num_nbrs, r, s, repulsion_factor, tinit_factor, and optionally preset (included only when the summary row records a non-empty preset).

Examples

edges <- edges.path(5)
cmp <- compare.layouts(edges, n = 5, dim = 2,
                            candidates = "default",
                            seeds = 1L)
params <- params.from.summary(cmp$summary[1, ])
coords <- do.call(
  grip,
  c(list(edges = edges, n = 5, dim = 2, seed = 42L), params)
)
round(coords, 2)

Deterministic perforated-grid occupancy helpers

Description

Convenience constructors for finite occupied grids with non-random holes or channels. These matrices can be passed to occupied.mesh.surface.graph().

Usage

keep.periodic.holes(
  h,
  w = h,
  hole.period = 4,
  hole.height = 1,
  hole.width = hole.height,
  row.offset = 2,
  col.offset = 2
)

keep.staggered.windows(
  h,
  w = h,
  window.height = 1,
  window.width = 2,
  row.period = 4,
  col.period = 5,
  row.offset = 2,
  col.offset = 2
)

keep.slit.channels(
  h,
  w = h,
  orientation = c("vertical", "horizontal"),
  slit.period = 5,
  slit.width = 1,
  bridge.spacing = 4,
  bridge.size = 1,
  offset = 2
)

keep.asymmetric.notches(h, w = h, notch.depth = 3, notch.width = 2)

Arguments

Value

A logical occupancy matrix whose TRUE entries represent retained cells.

Examples

notches <- keep.asymmetric.notches(7, 8, notch.depth = 2, notch.width = 2)
holes <- keep.periodic.holes(7, 8, hole.period = 3)
slits <- keep.slit.channels(7, 8, slit.period = 3)
windows <- keep.staggered.windows(7, 8, row.period = 3, col.period = 4)

Quick plot for graph layouts

Description

For 2D layouts, draws vertices and edges using base graphics. For 3D layouts, the behaviour depends on the projection argument:

"rgl" (default)

Opens an interactive rgl scene when that package is installed. Falls back to "ortho" with a warning if rgl is not available.

"ortho"

Projects the 3D coordinates to 2D with project.3d and draws them with base graphics, giving a static figure suitable for vignettes and non-interactive reports.

Usage

## S3 method for class 'layout'
plot(x, ..., edges = NULL,
  projection = c("rgl", "ortho"), azimuth = 35, elevation = 22,
  vertex.col = "black", edge.col = "gray70")

Arguments

Value

NULL (called for side effects).

Examples

edges <- cbind(1:5, 2:6)
coords <- grip(edges, n = 6, dim = 2,
                      placement = "barycenter",
                      rounds = 5, final.rounds = 5,
                      num.init = 3, num.nbrs = 4,
                      seed = 1)
plot.layout(coords, edges, main = "Path graph", pch = 16, cex = 0.8)

Weighted porous cube-mask surface helpers

Description

Convenience wrappers around recursive.cube.mask.surface.*() for three named porous cubical families: a periodic tunnel lattice, an asymmetric cavity family, and a deterministic channel network. Each family uses a reusable base keep-array and then recurses it in exactly the same way as the generic cube-mask helpers.

Usage

cube.periodic.tunnels.surface.graph(
  level = 2,
  side = 5,
  tunnel.width = 1,
  tunnel.period = 2,
  tunnel.offset = 2,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x.scale = 1,
  y.scale = 1,
  z.scale = 1,
  normalize = c("median", "mean", "none")
)

cube.asymmetric.cavities.surface.graph(
  level = 2,
  side = 5,
  cavity.size = 2,
  pocket.size = max(1L, cavity.size - 1L),
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x.scale = 1,
  y.scale = 1,
  z.scale = 1,
  normalize = c("median", "mean", "none")
)

cube.channel.network.surface.graph(
  level = 2,
  side = 5,
  channel.width = 1,
  branch.offset = 2,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x.scale = 1,
  y.scale = 1,
  z.scale = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Value

Each graph bundle's coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

Each *.surface.graph() helper returns the same components as recursive.cube.mask.surface.graph(), with a family-specific family field, class, and label.

Examples

asymmetric <- cube.asymmetric.cavities.surface.graph(
  level = 1, side = 5, cavity.size = 1, pocket.size = 1
)
channels <- cube.channel.network.surface.graph(
  level = 1, side = 5, channel.width = 1, branch.offset = 2
)
tunnels <- cube.periodic.tunnels.surface.graph(
  level = 1, side = 5, tunnel.width = 1,
  tunnel.period = 2, tunnel.offset = 1
)

Prepare an edge-only graph for edge-KK repair

Description

prepare.edge.kk() validates an undirected weighted graph and returns the lightweight prepared object used by edge.kk() when only graph-edge targets are needed. Unlike prepare.graph.geodesic.mds(), this helper does not compute all-pairs shortest paths, path caches, or a dense graph distance matrix.

Usage

prepare.edge.kk(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL
)

Arguments

Details

Use this helper when a starting layout is already available, for example from grip(..., metric = "edge_length"), and the next step is scalable edge-KK local repair. Edge-only objects support edge-fidelity diagnostics through score.gmds(); all-pairs GMDS path and chord diagnostics are unavailable and are reported as NA.

Value

A lightweight prepared object of class "grip_edge_kk_prepared" layered on the common "grip_gmds_prepared" graph class. It contains canonical graph edges and edge targets but no all-pairs geodesic cache.

Examples

cycle_edges <- edges.cycle(6)
prepared <- prepare.edge.kk(cycle_edges, n = 6)

Prepare full geodesic KK data for repeated layout evaluation

Description

prepare.geodesic.kk() builds the deterministic all-pairs shortest path cache needed to evaluate or optimize the full geodesic Kamada–Kawai objective repeatedly on the same connected graph.

Usage

prepare.geodesic.kk(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  tie.mode = c("single", "average")
)

Arguments

Details

For each unordered vertex pair, the prepared object stores either one deterministic chosen graph shortest path (tie.mode = "single") or the exact uniform average over all tied shortest paths (tie.mode = "average"), together with the graph distance and the corresponding cached edge realization. This is the full all-pairs analogue of the sparse landmark cache used by prepare.landmark.geodesic.kk().

Value

A list with the all-pairs graph distances, chosen paths, and cached path-edge realizations. The object has class "grip_gkk_prepared".

Examples

cycle_edges <- edges.cycle(6)
prepared <- prepare.geodesic.kk(cycle_edges, n = 6)

Prepare a graph-first geodesic-MDS path cache

Description

prepare.graph.geodesic.mds() prepares the full all-pairs chosen geodesic cache for an arbitrary connected weighted graph. This is the graph-first entry point corresponding to the manuscript's definition of GMDS on a connected weighted graph together with a chosen geodesic family (G, \Gamma).

Usage

prepare.graph.geodesic.mds(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  tie.mode = c("single", "average")
)

Arguments

Details

The graph can be supplied either as an edge list plus parallel weights or as an adjacency-list representation. The returned object stores the all-pairs graph distances, the chosen shortest-path family, and the flattened edge-path cache reused by the GMDS scorer and optimizer.

The all-pairs distance.matrix contains symmetric strict graph distances. Retained-route lengths in pair_graph_distance follow the deterministic near-tie path convention and can differ slightly from these targets. Route selection and path diagnostics are not changed by this distinction.

Value

A prepared object with class "grip_gmds_prepared" layered on top of the existing full geodesic path-cache structure.

Examples

cycle_edges <- edges.cycle(6)
prepared <- prepare.graph.geodesic.mds(cycle_edges, n = 6)

Prepare sparse landmark-geodesic KK data for repeated layout evaluation

Description

prepare.landmark.geodesic.kk() builds the deterministic shortest path trees, graph-distance cache, sparse local-plus-landmark pair set, and chosen path realizations needed to evaluate the landmark geodesic KK energy repeatedly on the same graph. This is intended as a reusable preparation step for experiments where many layouts of the same graph are compared.

Usage

prepare.landmark.geodesic.kk(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  local.nbrs = 20L,
  landmark.count = 8L
)

Arguments

Details

The sparse set follows the implementation choice recorded in landmark\_geodesic\_kk\_spec\_2026-03-30.tex: each vertex contributes its local.nbrs nearest active vertices in graph distance and its landmark.count farthest-point landmarks, both selected deterministically.

Value

A list with the sparse pair set, graph distances, chosen paths, and other cached data. The object has class "grip_lgkk_prepared".

Examples

cycle_edges <- edges.cycle(6)
prepared <- prepare.landmark.geodesic.kk(
  cycle_edges, n = 6, local.nbrs = 2, landmark.count = 2
)

Prepare a MISF-based multiscale geodesic-KK object

Description

prepare.misf.geodesic.kk() builds the prepared state for a MISF-based geodesic-KK pipeline by layering the maximal independent set filtration (MISF) on top of the existing full geodesic-KK cache. The prepared object stores the graph metadata, the coarsest admissible top-level graph, the exact and sparse top-level prepared caches, and the default controls used by the multiscale MISF-GKK optimizer.

Usage

prepare.misf.geodesic.kk(
  edges = NULL,
  n = NULL,
  adj.list = NULL,
  weight.list = NULL,
  edge.weights = NULL,
  tie.mode = c("single", "average"),
  num.init = 24L,
  num.nbrs = 20L,
  dim = 2L,
  top.level.mode = c("solve", "skip"),
  top.level.pair.mode = c("auto", "full", "landmark"),
  top.level.full.limit = 512L,
  top.level.local.nbrs = 20L,
  top.level.landmark.count = 8L,
  top.level.restarts = 8L,
  top.level.max.iter = 16L,
  top.level.init = c("geometric", "cmdscale", "random"),
  seed = 6L
)

Arguments

Value

An object of class "grip_misf_gkk_prepared" layered on top of the full geodesic-KK prepared structure, with added MISF metadata, top-level coarse-graph caches, and stored default controls for the MISF-GKK optimizer.

Examples

edges <- edges.mesh(4, 4)
prepared <- prepare.misf.geodesic.kk(
  edges = edges,
  n = 16,
  tie.mode = "average",
  num.init = 4,
  top.level.mode = "skip",
  seed = 1
)
prepared$top_level_vertices

Prepare sparse metric MDS directly from observations

Description

Selects pivots and computes fitting weights internally, without constructing a full distance matrix. Pass the result to [metric.mds()] with 'approximation = "sparse"'. Preparation can be reused across dimensions and fit seeds. The default fit schedule for this preparation is '"zheng"'.

Usage

prepare.sparse.mds(
  X,
  method = c("euclidean", "uniform", "geodesic", "linf"),
  n.pivots = 200L,
  pivot.selection = c("randomized", "farthest"),
  q = 10L,
  neighbor.variance.target = 0.9,
  seed = 1L,
  max.workspace.bytes = 512 * 1024^2
)

Arguments

Details

The geodesic method uses exact component-MST repair in 'dgraphs'. Its streaming implementation can evaluate quadratically many distances but never retains their full matrix. A recent local 'dgraphs' implementation supporting 'search.data' and streaming component repair is required. Uniform and Euclidean modes compute one Euclidean distance row per pivot. L-infinity mode performs exact neighbor search in the supplied coordinates, breaking equal-distance ties by row index, and computes L-infinity pivot distances. Search streams candidates, with quadratic worst-case work but no full distance matrix, and does not require 'dgraphs'. No normalization is applied internally; normalize observations before preparation if needed. All modes use inverse-squared target weights. Regional counts are asymmetric endpoint multipliers, not ordinary symmetric stress weights.

Value

A 'grip_sparse_mds_preparation' list containing constraints, pivot distance rows, pivots, regions, graph (when used), PCA information and metadata. For '"linf"', 'graph' is a list with an 'edges' data frame ('from', 'to', 'length') and search 'metadata'; Euclidean and geodesic methods return a 'dgraphs' graph. Input coordinates and settings are retained for cache validation.

See Also

[metric.mds()], [landmark.mds.constraints()]

Examples

X <- cbind(seq_len(12), sin(seq_len(12)))
prep <- prepare.sparse.mds(X, method = "uniform", n.pivots = 3)
fit <- metric.mds(prepared = prep, approximation = "sparse", max.iter = 5)
fit$metadata$data_preparation$method

Print a geodesic-MDS layout summary

Description

Reports the fitted objective, available stopping information, coordinate dimensions, and separately labeled graph diagnostics. Missing convergence metadata is reported as such; finite coordinates do not imply convergence. Printing never recomputes diagnostics. Raw metric-MDS stress has squared input-distance units. The displayed graph RMSE values are divided by the root mean squared target distance and are dimensionless. Extract x$coords to plot or score the coordinates.

Usage

## S3 method for class 'grip_gmds_layout'
print(x, ...)

Arguments

Value

The input object, invisibly.

See Also

classical.mds, metric.mds

Print a multiscale hierarchy summary

Description

Summarizes the vertices and levels of a hop-distance MISF hierarchy.

Usage

## S3 method for class 'grip_misf'
print(x, ...)

Arguments

Value

The input object, invisibly.

See Also

build.misf

Project 3D coordinates to 2D for static plotting

Description

Applies a rotation defined by azimuth and elevation angles and returns the first two columns of the rotated matrix.

Usage

project.3d(coords, azimuth = 35, elevation = 22)

Arguments

Details

This is the projection used internally by plot.layout when projection = "ortho" and is exported so that users can pre-project coordinates for custom plotting.

Value

A two-column numeric matrix of projected (x, y) coordinates.

Examples

edges <- edges.torus(6, 10)
coords3d <- grip(edges, n = max(edges), dim = 3,
                        preset = "torus", seed = 1)
xy <- project.3d(coords3d)
plot(xy, asp = 1, pch = 16, cex = 0.5)

Weighted recursive cube-mask surface helpers

Description

Convenience helpers that recursively subdivide a cube into a regular k \times k \times k array of subcubes according to a cubic keep-mask, retain the selected cells at each recursion step, and deform the resulting face-adjacency graph inside \mathbb{R}^3. This provides a generic cubical 3D family that includes Menger-sponge-style cell adjacency as a named special case.

Usage

recursive.cube.mask.surface.graph(
  mask,
  level = 2,
  surface = c("standard", "bulged", "twisted", "wavy"),
  amplitude = 0.2,
  freq = 2,
  twist = 0.6,
  x.scale = 1,
  y.scale = 1,
  z.scale = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Details

The mask is interpreted as a cubic array whose first dimension runs from top to bottom, second from left to right, and third from front to back. Non-zero entries are retained at each recursive step.

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

recursive.cube.mask.surface.graph() returns a list with components:

• edges: the retained recursive cube-mask face-adjacency edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D embedding,

• coords_param: the canonical 3D voxel-center coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "recursive.cube.mask",

• surface: the chosen surface name,

• level: the recursion depth,

• mask: the logical keep-array,

• mask_side: side length of the base keep-mask,

• side: side length of the fully refined cube grid,

• label: a human-readable family label.

Examples

mask <- mask.cube.channel.network(
  side = 5, channel.width = 1, branch.offset = 2
)
cube <- recursive.cube.mask.surface.graph(mask, level = 1)

Weighted recursive mask-grid surface helpers

Description

Convenience helpers that recursively subdivide a square grid according to a square keep-mask, retain the occupied cells, and then lift those cells into \mathbb{R}^3. The induced Euclidean edge lengths become positive graph weights. This provides a generic mesh-derived family that includes the Sierpinski carpet and related masked-grid fractals such as Vicsek-style cross families.

Usage

recursive.mask.grid.surface.graph(
  mask,
  level = 2,
  surface = c("saddle", "paraboloid", "ripple"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  x.scale = 1,
  y.scale = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Details

The mask is interpreted in standard matrix display orientation: rows run from top to bottom and columns run from left to right. Non-zero entries are retained at each recursive subdivision step.

The coords.surface component contains the 3D coordinates of the occupied cells in the same vertex order as edges. recursive.mask.grid.surface.graph() returns a reusable weighted-graph bundle containing the masked-grid edges, induced edge weights, the 3D surface coordinates, and the 2D parameter coordinates of the occupied cells.

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

recursive.mask.grid.surface.graph() returns a list with components:

• edges: the occupied-cell masked-grid edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the 2D parameter coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "recursive.mask.grid",

• surface: the chosen surface name,

• level: the recursion depth,

• mask: the logical keep-mask,

• mask_size: the side length of the mask,

• side: the side length of the fully refined grid,

• label: a human-readable family label.

Examples

grid <- recursive.mask.grid.surface.graph(mask.cross(3), level = 1)

Weighted recursive tetrahedron-mask surface helpers

Description

Convenience helpers that recursively subdivide a tetrahedron into four corner subtetrahedra according to a four-corner keep-mask, retain the selected subtetrahedra at each recursion step, and deform the resulting simplicial graph inside \mathbb{R}^3. This provides a generic tetrahedral gasket family that includes the classic Sierpinski tetrahedron together with corner-omission variants.

Usage

recursive.tetrahedron.mask.surface.graph(
  mask = mask.tetrahedron.classic(),
  level = 2,
  surface = c("standard", "squashed", "twisted", "wavy"),
  amplitude = 0.3,
  freq = 2,
  twist = 0.6,
  normalize = c("median", "mean", "none")
)

Arguments

Details

The mask entries are interpreted in the order base_left, base_right, base_back, and apex. Named masks are reordered automatically to match that convention.

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

recursive.tetrahedron.mask.surface.graph() returns a list with components:

• edges: the retained recursive tetrahedron-mask edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the canonical 3D tetrahedron coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "recursive.tetrahedron.mask",

• surface: the chosen surface name,

• level: the recursion depth,

• mask: the logical keep-mask,

• label: a human-readable family label.

Examples

tetrahedron <- recursive.tetrahedron.mask.surface.graph(level = 1)

Weighted recursive triangle-mask surface helpers

Description

Convenience helpers that recursively subdivide an equilateral triangle into three corner subtriangles plus one central inverted subtriangle according to a four-slot keep-mask, retain the selected subtriangles at each recursion step, and lift the resulting vertex graph into \mathbb{R}^3. This provides a generic gasket-style triangular family that includes the classic Sierpinski triangle together with bridge and asymmetric variants.

Usage

recursive.triangle.mask.surface.graph(
  mask = mask.triangle.classic(),
  level = 2,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  x.scale = 1,
  y.scale = 1,
  normalize = c("median", "mean", "none")
)

Arguments

Details

The mask entries are interpreted in the order left, right, top, and center. Named masks are reordered automatically to match that convention.

Value

The coords_surface component is an n x 3 numeric matrix with columns x, y, and z.

recursive.triangle.mask.surface.graph() returns a list with components:

• edges: the retained recursive triangle-mask edges,

• n: number of vertices,

• edge_weights: induced positive edge lengths,

• coords_surface: the 3D surface embedding,

• coords_param: the canonical 2D triangle coordinates,

• weight_scale: the normalization constant applied to the raw edge lengths,

• family: always "recursive.triangle.mask",

• surface: the chosen surface name,

• level: the recursion depth,

• mask: the logical keep-mask,

• label: a human-readable family label.

Examples

triangle <- recursive.triangle.mask.surface.graph(level = 1)

Optimize one pure repulsive layout stage

Description

repulsive.stage() performs a gradient-descent stage for the pure repulsion objective evaluated by repulsive.state(). It is intended for GMDS experiments that need to inspect repulsion separately from edge-length repair.

Usage

repulsive.stage(
  coords,
  lambda = 1,
  pair.index = NULL,
  pair.weights = NULL,
  repulsion.family = c("log", "inverse_power"),
  repulsion.delta = 0.001,
  repulsion.power = 1,
  max.iter = 80L,
  initial.step = 0.02,
  step.shrink = 0.5,
  armijo = 1e-04,
  min.step = 1e-08,
  grad.tol = 1e-07,
  recenter = TRUE,
  distance.eps = 1e-10,
  return.frames = FALSE,
  engine = c("cpp", "R")
)

Arguments

Value

A list with coords, final state, a data-frame trace, and, when requested, a list of coordinate frames.

Examples

theta <- seq(0, 2 * pi, length.out = 7)[-7]
initial <- cbind(cos(theta), sin(theta))
fit <- repulsive.stage(
  initial, lambda = 0.1, max.iter = 1, engine = "R"
)

Evaluate a pure repulsive layout objective

Description

repulsive.state() evaluates only the repulsion term used by the experimental GMDS repulsive-unfolding operators. Unlike edge.repulsive.state(), this function has no graph-edge term and does not require placeholder edges or edge lengths.

Usage

repulsive.state(
  coords,
  lambda = 1,
  pair.index = NULL,
  pair.weights = NULL,
  repulsion.family = c("log", "inverse_power"),
  repulsion.delta = 0.001,
  repulsion.power = 1,
  distance.eps = 1e-10,
  engine = c("cpp", "R")
)

Arguments

Value

A list containing energy, unscaled repulsion energy, gradient, gradient norm, and embedded pair lengths.

Examples

theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
state <- repulsive.state(coords, lambda = 0.1, engine = "R")

Run the gripui Shiny application

Description

Run the gripui Shiny application

Usage

run.gripui(
  project,
  host = "127.0.0.1",
  port = getOption("shiny.port"),
  launch.browser = interactive(),
  auto.stop.after = NULL,
  ...
)

Arguments

Value

Invisibly returns the result of shiny::runApp().

Examples

graph <- list(adj_list = list(2L, c(1L, 3L), 2L))
layouts <- data.frame(
  candidate = "toy.layout",
  stage = "layout",
  seed = 1L,
  status = "ok",
  stringsAsFactors = FALSE
)
project <- gripui.project(graph = graph, layouts = layouts, title = "Toy project")
run.gripui(
  project,
  launch.browser = FALSE,
  quiet = TRUE,
  auto.stop.after = 0.1
)

Run the graph-family geometry explorer Shiny application

Description

Run the graph-family geometry explorer Shiny application

Usage

run.gripui.family(
  catalog = gripui.graph.family.catalog(),
  title = "Graph Family Geometry Explorer",
  subtitle = "Interactive geometry browser for synthetic benchmark families.",
  host = "127.0.0.1",
  port = getOption("shiny.port"),
  launch.browser = interactive(),
  auto.stop.after = NULL,
  ...
)

Arguments

Value

Invisibly returns the result of shiny::runApp().

Examples

run.gripui.family(launch.browser = FALSE, quiet = TRUE, auto.stop.after = 0.1)

Sampled rectangle surface helpers

Description

Convenience helpers that sample points uniformly from a user-specified rectangle, lift the sampled planar coordinates into \mathbb{R}^3, and then build exact intersection-kNN graphs on either the planar or embedded coordinates. The lifted surface uses normalized rectangle coordinates for the non-flat z-displacement while preserving the original rectangle in the returned x and y coordinates.

Usage

sampled.rectangle.surface.graph(
  n,
  k,
  xmin = -1,
  xmax = 1,
  ymin = -1,
  ymax = 1,
  seed = NULL,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  graph.space = c("surface", "param"),
  max.path.edge.ratio.deviation.thld = 0.1,
  path.edge.ratio.percentile = 0.5,
  threshold.percentile = 0,
  normalize = c("median", "mean", "none")
)

sampled.rectangle.surface.graphs(
  n,
  k,
  xmin = -1,
  xmax = 1,
  ymin = -1,
  ymax = 1,
  seed = NULL,
  surface = c("flat", "saddle", "paraboloid", "ripple", "folded"),
  amplitude = 0.75,
  freq.u = 1,
  freq.v = 1,
  graph.space = c("surface", "param"),
  max.path.edge.ratio.deviation.thld = 0.1,
  path.edge.ratio.percentile = 0.5,
  threshold.percentile = 0,
  normalize = c("median", "mean", "none")
)

Arguments