Package 'grip'

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 [email protected]

Authors:

• Pawel Gajer [email protected]

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

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

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
)

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)

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

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
)

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

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

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
)

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

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

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

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)

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
)

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)

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
)

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)

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)

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
)

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.

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.

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

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

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

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

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)

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

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)

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

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

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)

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
)

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
)

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
)

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

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
)

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)

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)

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