grip (version 0.2.0)

graph.riemannian.star.structure: 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
)

Value

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

Arguments

graph

Optional graph/prepared object containing `adj_list` and `weight_list`, or `edges`/`edge_targets` when it is a prepared GMDS graph.

X

Numeric matrix used to estimate local target angles.

prepared

Optional prepared GMDS object. Used when `graph` is omitted.

edges, n, edge_weights

Optional edge representation used when `graph` and `prepared` are omitted.

adj_list, weight_list

Optional adjacency-list representation.

angle.power

Non-negative exponent `q` in the antipodal kernel.

reliability

Reliability weighting rule. `"length.balance"` multiplies by `min(w_1, w_2) / max(w_1, w_2)`; `"none"` uses one.

min.angle.weight

Pairs with final angle weight at or below this value are omitted from the returned table.

star.quantile

Optional quantile in `[0, 1)`. When positive, retain only star pairs whose angle weight is at least this empirical quantile after applying `min.angle.weight`.

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)