compute.graph.endpoint.scores: Compute Graph Endpoint Scores from a 3D Embedding

In dgraphs: Data-Derived Graph Construction Utilities

Compute Graph Endpoint Scores from a 3D Embedding

Description

Computes endpointness diagnostics for graph vertices by selecting graph-geodesic neighborhoods and evaluating how concentrated the corresponding 3D embedding directions are. This targets terminal arm tips in an embedding rather than graph-theoretic degree-1 vertices.

For each vertex x, let u_1, \dots, u_m be unit vectors in the embedding from x to graph-geodesic neighbors of x. The function computes:

s_{\min}(x) = \min_{i < j} u_i^\top u_j

s_q(x) = \mathrm{quantile}\{u_i^\top u_j : i < j\}

m(x) = \left\| \frac{1}{\sum_i w_i} \sum_i w_i u_i \right\|

\mathrm{score}(x) = m(x)\, \frac{1 + s_q(x)}{2}

Neighborhoods are selected in graph-geodesic space while directions are taken from the supplied 3D embedding.

Usage

compute.graph.endpoint.scores(
  adj.list,
  weight.list,
  layout.3d,
  neighborhood = c("geodesic_k", "geodesic_radius"),
  k = c(10L, 20L, 30L),
  radius = NULL,
  q = 0.1,
  neighbor.weighting = c("uniform", "inverse_distance", "gaussian"),
  gaussian.sigma = NULL,
  min.neighborhood.size = 3L,
  scale.aggregate = c("mean", "median", "min", "max"),
  verbose = FALSE
)

Arguments

adj.list	Graph adjacency list (1-based vertex indices).
weight.list	Edge-length list aligned with adj.list.
layout.3d	Numeric matrix or data frame with 3 columns giving the 3D embedding coordinates for graph vertices.
neighborhood	Character string. Either "geodesic_k" (default) or "geodesic_radius".
k	Integer vector of geodesic neighborhood sizes used when neighborhood = "geodesic_k".
radius	Positive numeric vector of geodesic radii used when neighborhood = "geodesic_radius".
q	Quantile used for s.q. Must lie in ⁠[0, 1]⁠. Default is 0.1.
neighbor.weighting	Character string controlling neighbor weights for m and weighted pair quantiles. One of "uniform" (default), "inverse_distance", or "gaussian".
gaussian.sigma	Optional positive numeric scale used when neighbor.weighting = "gaussian". If NULL, the median positive geodesic neighborhood distance is used per vertex and scale.
min.neighborhood.size	Minimum number of usable neighbors required after removing zero-length embedding vectors. Must be at least 2.
scale.aggregate	How to aggregate scores across multiple neighborhood scales. One of "mean" (default), "median", "min", or "max".
verbose	Logical; if TRUE, prints progress.

Value

A list with aggregated per-vertex scores, per-scale score matrices, and neighborhood diagnostics.

dgraphs documentation built on Aug. 21, 2026, 1:08 a.m.