grip (version 0.2.0)

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.

Examples

cycle_edges <- edges.cycle(6)
theta <- seq(0, 2 * pi, length.out = 7)[-7]
coords <- cbind(cos(theta), sin(theta))
prepared <- prepare.geodesic.kk(cycle_edges, n = 6)
score <- score.geodesic.kk(coords, prepared = prepared)