Skip to contents

Summarize Basins of Attraction

Source: R/compute_basins_of_attraction.R
summary.basins_of_attraction.Rd

Generates a comprehensive summary data frame of basins of attraction, including basin characteristics and local density metrics for each extremum.

Usage

# S3 method for class 'basins_of_attraction'
summary(
  object,
  adj.list,
  edgelen.list,
  hop.k = 2,
  vertex.metrics = NULL,
  use.cpp = TRUE,
  ...
)

Arguments

object

An object of class "basins_of_attraction" returned by compute.basins.of.attraction.

adj.list

A list of integer vectors representing the graph adjacency structure. Element i contains the vertex indices of neighbors of vertex i. Must have length equal to the number of vertices in the graph.

edgelen.list

A list of numeric vectors containing edge lengths. Element i contains the lengths of edges incident to vertex i, parallel to adj.list[[i]]. Must have length equal to the number of vertices in the graph.

hop.k

Integer specifying the hop distance for computing extended neighborhood isolation. Default is 2. Must be a positive integer.

vertex.metrics

Optional precomputed vertex-level metrics from S_precompute_basin_vertex_metrics. If NULL and use.cpp = TRUE, metrics are computed internally.

use.cpp

Logical; if TRUE (default), use the C++ summary backend with fallback to the R implementation on error.

...

Additional arguments (currently unused).

Value

A data frame of class "basin_summary" with one row per local extremum and the following columns:

label

Character label for the extremum (m1, m2, ... for minima; M1, M2, ... for maxima)

vertex

Vertex index (1-based)

value

Function value at the extremum

rel.value

Function value relative to the mean (value / mean(y))

type

Extremum type: "min" or "max"

hop.idx

Maximum hop distance within the basin

basin.size

Number of vertices in the basin

p.mean.nbrs.dist

Percentile rank of mean neighbor distance (density measure)

p.mean.hopk.dist

Percentile rank of mean hop-k distance (extended isolation measure)

deg

Degree of the vertex

Details

This function processes the raw basin structures returned by compute.basins.of.attraction and produces a summary table suitable for analysis and reporting. The summary includes both basin-specific properties and local geometric characteristics of the graph at each extremum.

The density metrics provide information about the local sparsity of the graph around each extremum. The d1 measure represents the distance to the nearest neighbor, while mean.nbrs.dist captures the average distance to all neighbors. These are converted to percentile ranks (p.d1 and p.mean.nbrs.dist) to facilitate comparison across vertices. Higher percentile values indicate that an extremum lies in a sparser region of the graph.

The hop-k distance measure provides complementary information about isolation at a specified graph distance. By examining vertices at exactly hop_k steps from each extremum, we assess whether the extremum lies in a locally sparse or dense region at that specific scale. This measure is particularly informative when the immediate neighborhood (captured by mean.nbrs.dist) does not fully characterize the local geometry. The percentile rank p.mean.hopk.dist enables comparison of this extended neighborhood isolation across all vertices.

The basin size quantifies the extent of the extremum's region of influence. Larger basins suggest more prominent features in the function landscape. The hop index indicates the maximum graph distance from the extremum to any vertex within its basin, providing a measure of basin elongation.

Extrema are labeled systematically: minima receive lowercase labels (m1, m2, ...) in order of increasing function value, while maxima receive uppercase labels (M1, M2, ...) in order of decreasing function value. This labeling convention facilitates identification of the most significant extrema.

See also

compute.basins.of.attraction for computing the basins

Examples

if (FALSE) { # \dontrun{
# Compute basins (see compute.basins.of.attraction examples)
basins <- compute.basins.of.attraction(adj.list, weight.list, y)

# Create edge length list (Euclidean distances for example)
edgelen.list <- lapply(adj.list, function(nbrs) {
  rep(1.0, length(nbrs))  # uniform edge lengths
})

# Generate summary with default hop.k = 2
basin_summary <- summary(basins, adj.list, edgelen.list)
print(basin_summary)

# Generate summary with custom hop distance
basin_summary_h3 <- summary(basins, adj.list, edgelen.list, hop.k = 3)

# Identify most prominent maximum
max_basins <- subset(basin_summary, type == "max")
most_prominent <- max_basins[which.max(max_basins$basin.size), ]
cat("Most prominent maximum:", most_prominent$label, "\n")
cat("Basin size:", most_prominent$basin.size, "\n")

# Find extrema in sparse regions (both immediate and extended neighborhoods)
sparse_extrema <- subset(basin_summary,
                         p.mean.nbrs.dist > 0.75 & p.mean.hopk.dist > 0.75)
print(sparse_extrema[, c("label", "type", "value",
                         "p.mean.nbrs.dist", "p.mean.hopk.dist")])
} # }