Skip to contents

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

Source: R/export_examples.R, R/grip_geodesic_misf_kk.R
misf.geodesic.kk.Rd

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

prepared

Optional prepared object. This can be either a full geodesic-KK prepared object or a MISF-GKK prepared object.

edges

Two-column integer matrix of edges (1-based vertex ids).

n

Number of vertices. If omitted with adj.list, defaults to length(adj.list). If omitted with edges, defaults to max(edges).

adj.list

Adjacency list (1-based) for an undirected graph.

weight.list

Optional parallel list of positive edge weights.

edge.weights

Optional positive edge-weight vector parallel to edges.

tie.mode

Shortest-path aggregation mode inherited from prepare.geodesic.kk().

num.init

Target top-level active-set size passed to build.misf.

num.nbrs

Per-level local-neighborhood schedule metadata passed to build.misf.

dim

Target embedding dimension (2 or 3) for the multiscale solve.

top.level.pair.mode

Optional override for the top-level pair policy.

top.level.full.limit

Optional override for the top-level exact/sparse threshold.

top.level.local.nbrs

Optional override for the sparse top-level local neighborhood size.

top.level.landmark.count

Optional override for the sparse top-level landmark count.

top.level.restarts

Number of top-level restarts used by the coarse MISF-GKK solve.

top.level.max.iter

Top-level iteration budget.

top.level.init

Optional override for the top-level initializer.

insertion.anchor.policy

Optional insertion anchor policy.

insertion.anchor.count

Optional insertion anchor count.

insertion.anchor.weight.mode

Optional insertion anchor weighting mode.

insertion.max.iter

Optional per-vertex insertion iteration budget.

insertion.mode

Optional insertion warm-start mode.

insertion.layout.k

Optional active-level layout graph size used by layout-based insertion modes.

insertion.weighted.preset

Optional preset passed to weighted GRIP insertion.

insertion.grip.args

Optional named list of extra arguments passed to combinatorial GRIP insertion.

insertion.weighted.args

Optional named list of extra arguments for weighted GRIP insertion.

insertion.fr.niter

Optional FR iteration budget for FR-based insertion.

refinement.pair.mode

Optional active-level pair policy.

refinement.full.limit

Optional active-level exact/sparse threshold.

refinement.local.nbrs

Optional active-level sparse local neighborhood size.

refinement.landmark.count

Optional active-level sparse landmark count.

refinement.anchor.weight

Optional initial anchor weight used to pin inactive and coarser-level vertices during KK refinement.

refinement.anchor.weight.end

Optional final anchor weight used at the end of the active-level continuation schedule.

refinement.continuation

Optional continuation schedule used for the active-level anchor penalty.

refinement.max.iter

Optional active-level refinement iteration budget.

final.pair.mode

Optional final full-graph pair policy.

final.full.limit

Optional final full-graph exact/sparse threshold.

final.local.nbrs

Optional final full-graph sparse local neighborhood size.

final.landmark.count

Optional final full-graph sparse landmark count.

final.max.iter

Optional final polish iteration budget.

stiffness

Global stiffness constant \(K\).

distance.floor

Small positive floor used in k_ij = K / max(g_ij, distance.floor)^2.

edge.length.epsilon

Small positive stabilizer added inside each embedded edge length.

initial.step

Initial line-search step size.

step.shrink

Multiplicative shrink factor in (0, 1) for backtracking.

armijo.factor

Non-negative Armijo decrease constant.

grad.tol

Non-negative stopping tolerance on the gradient norm.

min.step

Positive minimum accepted line-search step before giving up.

recenter

If TRUE, recenter accepted proposals to zero mean after each accepted step.

return.trace

If TRUE, retain detailed stage traces.

return.frames

If TRUE, retain intermediate coordinate frames.

seed

Optional integer seed reused for MISF extraction.

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
)