Compute Graph Endpoint Scores from a 3D Embedding — compute.graph.endpoint.scores • dgraphs

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,
  length.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).
length.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.

Examples

chain <- create.graph("chain", n = 8)
layout <- cbind(seq_len(8), 0, 0)
scores <- compute.graph.endpoint.scores(graph.adjacency(chain), graph.lengths(chain), layout,
    k = c(2, 3), min.neighborhood.size = 2)
head(scores$summary)
#>   vertex s.min s.q         m score scale.coverage mean.neighborhood.size
#> 1      1     1   1 1.0000000     1              1                    2.5
#> 2      2    -1  -1 0.1666667     0              1                    2.5
#> 3      3    -1  -1 0.1666667     0              1                    2.5
#> 4      4    -1  -1 0.1666667     0              1                    2.5
#> 5      5    -1  -1 0.1666667     0              1                    2.5
#> 6      6    -1  -1 0.1666667     0              1                    2.5