Extract All Basins of Attraction

Retrieves vertex membership for all basins of attraction, returning a named list where each element contains the vertex indices belonging to that basin.

Usage

# S3 method for class 'basins_of_attraction'
basins(object, summary.df, ...)

Arguments

object

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

summary.df

A data frame of class "basin_summary" returned by summary.basins_of_attraction. Required for basin labeling.

...

Additional arguments (currently unused).

Value

A named list where each element is an integer vector of 1-based vertex indices belonging to that basin. Names correspond to basin labels from the summary (e.g., "m1", "m2", "M1", "M2").

Details

This function provides a convenient way to extract all basin memberships simultaneously. In the statistical Morse-Smale framework, basins of attraction are not necessarily disjoint: a vertex may belong to multiple basins when the function landscape contains saddle regions or when noise creates ambiguous gradient directions. The list structure accommodates this overlapping membership.

The returned list is named using the systematic labels from the basin summary: lowercase labels (m1, m2, ...) for minima ordered by increasing function value, and uppercase labels (M1, M2, ...) for maxima ordered by decreasing function value. The list ordering follows the summary data frame, with minima appearing before maxima by default.

This function is particularly useful for visualization tasks where basin membership needs to be mapped to colors or symbols, for computing overlap statistics between basins, or for subsetting data by basin membership.

See also

basin.basins_of_attraction for extracting a single basin, compute.basins.of.attraction for computing basins, summary.basins_of_attraction for generating basin summaries

Examples

if (FALSE) { # \dontrun{
basins <- compute.basins.of.attraction(adj.list, weight.list, y)
summ <- summary(basins, adj.list, edgelen.list)

# Get all basin memberships
all.basins <- basins(basins, summary.df = summ)

# Access individual basins by name
m1.verts <- all.basins[["m1"]]
M1.verts <- all.basins[["M1"]]

# Compute basin sizes
basin.sizes <- sapply(all.basins, length)

# Find vertices in multiple basins (overlap)
all.verts <- unlist(all.basins)
overlap.verts <- unique(all.verts[duplicated(all.verts)])

# Create basin membership indicator matrix
n <- length(y)
membership <- sapply(all.basins, function(b) seq_len(n) %in% b)
} # }