score.geodesic.kk: Score a layout under the full geodesic KK energy

Description

score.geodesic.kk() evaluates a layout using the full all-pairs geodesic Kamada--Kawai objective. Distances are measured along fixed chosen graph shortest paths, not by straight-line chord length.

Usage

score.geodesic.kk(
  coords,
  prepared = NULL,
  edges = NULL,
  n = NULL,
  adj_list = NULL,
  weight_list = NULL,
  edge_weights = NULL,
  stiffness = 1,
  distance_floor = 1e-08,
  edge_length_epsilon = 1e-08,
  scale_mode = c("profiled", "user"),
  scale.L0 = NULL,
  return_pair_details = FALSE
)

Value

A one-row data frame with the fitted or user-supplied scale factor and full geodesic KK energy summary.

Arguments

coords: Numeric coordinate matrix with 2 or 3 columns.
prepared: Optional object returned by prepare.geodesic.kk().
edges: Two-column integer matrix of edges (1-based vertex ids).
n: Number of vertices.
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.
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.
scale_mode: Either "profiled" to fit L0 analytically for the supplied layout or "user" to use scale.L0.
scale.L0: Optional user-supplied geodesic KK scale, required when scale_mode = "user".
return_pair_details: If TRUE, include pairwise path lengths and residuals in a list column.

Details

By default the global target scale L0 is fit analytically for the supplied layout. Alternatively, the score can be evaluated at a user-supplied scale.