Build a local Riemannian star structure for Gram-gKK layouts

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

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.

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)