Compute a trace for the legacy GRIP layout

Usage

trace.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,
  trace = c("round", "level"),
  trace.every = 1
)

Arguments

edges: Two-column integer matrix of edges (1-based vertex ids). Supply either edges/edge.weights or adj.list/weight.list, not both. Fractional, nonfinite, and out-of-range vertex ids are rejected before integer conversion.
n: Number of vertices, a finite positive integer.
adj.list: Adjacency list (1-based) for undirected graphs.
weight.list: Optional parallel list of edge weights (edge lengths). If NULL, all edges are treated as weight 1. All weights must be finite and strictly positive.
edge.weights: Optional vector of edge weights for edges. All weights must be finite and strictly positive.
dim: Layout dimension (2 or 3). Default is 3.
placement: Initial placement strategy. "circle" is only used for 2D.
preset: Optional tuning preset. NULL uses the historical defaults. "carpet" applies a preset tuned for Sierpinski-carpet-like graphs and validated on carpet levels 3 and 4. "mesh" applies a preset tuned for rectangular lattice graphs and validated on 8x8 and 12x12 mesh layouts. "torus" applies a preset tuned for 3D torus layouts and validated on torus sizes from 8x8 through 20x20. "tree" applies a preset tuned for symmetric force-directed layouts of tree-like graphs and validated on binary trees of depths 5 and 6. Presets only fill in tuning arguments that you did not supply explicitly.
rounds: Initial rounds for refinement.
final.rounds: Final rounds for refinement.
num.init: Number of initial vertices in the coarsest level.
num.nbrs: Maximum number of graph-distance neighbors retained for local refinement at each filtration level.
r: Main local temperature adaptation rate in [0, 1].
s: Non-negative boost factor applied when successive displacements have a consistent direction.
repulsion.factor: Non-negative multiplier applied to GRIP's finest-level repulsive force scale. 1 keeps the historical repulsion strength; 0 disables that repulsive term.
tinit.factor: Initial temperature factor.
seed: Optional RNG seed for reproducibility. If NULL, uses current time.
trace: Snapshot granularity. "round" records the coarsest initialization, each level start, every trace.every completed rounds, and the final layout. "level" records the coarsest initialization, every trace.everyth level start, and the final layout.
trace.every: Positive integer thinning factor for recorded rounds or levels. Initial and final snapshots are always included.

Value

A list with final, frames, meta, trace, and trace.every. final is the final coordinate matrix. frames is a list of coordinate matrices with NA rows for vertices that have not yet been introduced by GRIP. meta is a data frame describing each frame with columns frame, phase, level_index, misf_level, round_in_level, and active_vertices.

Examples

edges <- cbind(1:5, 2:6)
tr <- trace.legacy.grip(edges, n = 6, dim = 2,
                               placement = "barycenter",
                               rounds = 3, final.rounds = 2,
                               num.init = 3, num.nbrs = 4,
                               trace = "level",
                               trace.every = 1,
                               seed = 1)
tr$meta
#>   frame       phase level_index misf_level round_in_level active_vertices
#> 1     1        init           1          1              0               3
#> 2     2 level_start           2          0              0               6
#> 3     3       final           2          0              2               6