Compute Basin and Cell Membership from Gradient Basins

Converts gradient basin structures into soft membership vectors suitable for association analysis. This function handles basin multiplicity by assigning normalized membership weights to each basin containing a vertex.

Usage

gfassoc.membership(basins, support.stage = NULL)

Arguments

basins: Canonical trajectory complex (see gfcor()) or object of class "basins_of_attraction" from a compatible saved analysis. Its constructor is retired. Canonical inputs require an explicit support stage and both trajectory directions.
support.stage: Explicit canonical support choice; see gfcor().

Value

An object of class "gfassoc_membership" containing:

max_basin_indices: List of integer vectors. Element v contains 0-based indices of maximum basins containing vertex v.
min_basin_indices: List of integer vectors. Element v contains 0-based indices of minimum basins containing vertex v.
max_membership: List of numeric vectors. Element v contains normalized membership weights for maximum basins.
min_membership: List of numeric vectors. Element v contains normalized membership weights for minimum basins.
max_vertices: Integer vector of extremum vertex indices (1-based).
min_vertices: Integer vector of extremum vertex indices (1-based).
max_values: Numeric vector of function values at maxima.
min_values: Numeric vector of function values at minima.
n_max_basins: Number of maximum basins.
n_min_basins: Number of minimum basins.
cell_indices: List of 2-column matrices. Element v contains (max_idx, min_idx) pairs for cells containing vertex v (0-based indices).
cell_membership: List of numeric vectors. Element v contains normalized cell membership weights.

Details

In discrete Morse theory on graphs, a vertex may belong to multiple basins simultaneously. This occurs when the vertex has multiple neighbors with lower (for descending basins) or higher (for ascending basins) function values, leading to non-unique gradient trajectories.

The membership vectors normalize this multiplicity. If vertex v belongs to basins B_1, ..., B_k, the membership weight for each basin is 1/k (uniform weighting). This soft assignment allows downstream computations to properly account for ambiguity in basin boundaries.

Cell membership is computed as the product of basin memberships. A Morse-Smale cell \(C_{ij}\) is the intersection of maximum basin \(B_i^+\) and minimum basin \(B_j^-\). The cell membership \(\gamma_{ij}(v)\) is normalized so that \(\sum_{i,j}\gamma_{ij}(v)=1\).

Examples

if (FALSE) { # \dontrun{
## Compute basins
# basins must be a compatible saved basins_of_attraction object for y.

## Extract membership structure
membership <- gfassoc.membership(basins)

## Check multiplicity for a specific vertex
v <- 100
n.max.basins <- length(membership$max_basin_indices[[v]])
n.cells <- nrow(membership$cell_indices[[v]])
} # }