Skip to contents

Extract Basin of Attraction for a Specific Extremum

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

Retrieves the basin of attraction associated with a specified local extremum from a basins_of_attraction object. The extremum can be identified either by its vertex index or by its character label when a summary data frame is provided.

Usage

# S3 method for class 'basins_of_attraction'
basin(object, id, summary.df = NULL, type = c("full", "vertices"), ...)

Arguments

object

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

id

Either an integer specifying the vertex index (1-based) of a local extremum, or a character string specifying the extremum label (e.g., "m1", "M2") when summary.df is provided.

summary.df

Optional data frame of class "basin_summary" returned by summary.basins_of_attraction. Required when id is a character label. Default is NULL.

type

Character string specifying the return type. Either "full" to return the complete basin structure, or "vertices" to return only the vector of basin vertex indices. Default is "full".

...

Additional arguments (currently unused).

Value

Depending on type:

type = "full"

A list containing the complete basin structure: vertex (extremum index), value (function value at extremum), hop_idx (maximum hop distance), basin_df (matrix of basin vertices and hop distances), and basin_bd_df (matrix of boundary vertices and function values).

type = "vertices"

An integer vector of 1-based vertex indices belonging to the basin.

Details

This method provides convenient access to individual basins within a basins_of_attraction object. When working interactively with basin analysis results, users often need to extract specific basins for further examination or visualization. The function supports two identification methods to accommodate different workflows.

Direct vertex identification requires knowing the 1-based vertex index of the local extremum. This approach is useful when the extremum of interest was identified through other means, such as domain knowledge or visualization.

Label-based identification uses the systematic labels assigned by summary.basins_of_attraction: lowercase labels (m1, m2, ...) for minima ordered by increasing function value, and uppercase labels (M1, M2, ...) for maxima ordered by decreasing function value. This approach requires passing the summary data frame and is particularly convenient when referencing extrema by their relative prominence.

The type argument controls what information is returned. The "full" option returns the complete basin structure including the extremum vertex, function value, hop index, basin membership with hop distances, and boundary vertices. The "vertices" option returns only the vector of vertex indices belonging to the basin, which is useful for subsetting other data structures or for visualization purposes.

See also

compute.basins.of.attraction for computing basins, summary.basins_of_attraction for generating basin summaries, find.basin.by.vertex.in.basins.of.attraction, get.basin.vertex.from.label

Examples

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

# Extract basin by vertex index (vertex 42 is a local minimum)
basin.full <- basin(basins, id = 42)
basin.verts <- basin(basins, id = 42, type = "vertices")

# Extract basin by label using summary
summ <- summary(basins, adj.list, edgelen.list)
basin.m1 <- basin(basins, id = "m1", summary.df = summ)
basin.M1.verts <- basin(basins, id = "M1", summary.df = summ, type = "vertices")

# Use basin vertices for subsetting
verts <- basin(basins, id = "m1", summary.df = summ, type = "vertices")
y.in.basin <- y[verts]
} # }