Extract Gradient Flow Cells for a Local Maximum Basin

Identifies all gradient flow cells within a local maximum basin, where each cell corresponds to a terminal extremum and contains all vertices whose gradient trajectories pass through that extremum on their way to the maximum.

Usage

extract.gradient.flow.cells(basins.obj, max.basin.label, verbose = FALSE)

Arguments

basins.obj

Basin object containing the basin structure and predecessors vector from compute.basins.of.attraction

max.basin.label

Character string identifying the local maximum basin (e.g., "M1", "M2")

verbose

Logical indicating whether to print diagnostic information about the cell extraction process. Default is FALSE.

Value

A list with components:

max.basin.label

The label of the maximum basin

max.vertex

The vertex index of the local maximum

cells

A named list where each element corresponds to a terminal extremum

Details

For a descending basin from a local maximum, the predecessor chain points backward toward the maximum (i.e., predecessors[v] is the next vertex on the path from v to the maximum). Terminal extrema are local minima where gradient flow "starts" before flowing upward to the maximum.

To construct gradient flow cells, we build a reverse graph (successors) where successors[u] contains all vertices v such that predecessors[v] = u. Then, for each terminal extremum, we perform an upstream search to find all vertices whose path to the maximum passes through that terminal.