Filter Basins by Retaining Only Specified Extrema

Filters a basin structure to retain only basins corresponding to a specified set of extrema vertices. This function proves essential when extrema have been filtered based on various criteria (such as isolation measures, basin size, or other quality metrics) and the basin structure must be updated to reflect only the retained features.

Usage

filter.basins(basins.obj, good.extrema)

Arguments

basins.obj: An object of class "basins_of_attraction" returned by compute.basins.of.attraction or merge.clustered.basins. This object contains the complete basin structure before filtering.
good.extrema: Integer vector of vertex indices (1-based) for extrema to retain. These are the extrema that survived external filtering based on quality metrics, isolation measures, or other criteria. The vector may contain only minima, only maxima, or both types mixed together. The function automatically determines which type each vertex represents by examining the basin structure.

Value

An object of class "basins_of_attraction" with the same structure as the input but containing only basins for extrema whose vertices appear in good.extrema. The object contains:

lmin_basins

List of basin structures for retained local minima, preserving all basin properties (vertex sets, hop distances, boundaries).

lmax_basins

List of basin structures for retained local maxima, similarly preserving complete basin information.

n_vertices

Total number of vertices in the graph (unchanged).

y

Copy of the input function values (unchanged).

filter.info

List documenting the filtering operation with components:

n.extrema.input: Total number of extrema in input (minima + maxima).
n.extrema.retained: Total number of extrema after filtering.
n.extrema.removed: Number of extrema removed by filtering.
n.lmin.original: Number of minima before filtering.
n.lmin.retained: Number of minima after filtering.
n.lmin.removed: Number of minima removed.
n.lmax.original: Number of maxima before filtering.
n.lmax.retained: Number of maxima after filtering.
n.lmax.removed: Number of maxima removed.
retained.lmin.vertices: Vertex indices of retained minima.
retained.lmax.vertices: Vertex indices of retained maxima.
removed.lmin.vertices: Vertex indices of removed minima.
removed.lmax.vertices: Vertex indices of removed maxima.

Details

The filtering problem arises naturally in topological data analysis when initial basin computation identifies numerous local extrema, many of which fail subsequent quality checks. We begin with a complete basin structure containing all detected extrema, then apply domain-specific filters to identify which extrema represent genuine features worthy of further analysis.

Consider the case of filtering isolated extrema using density-based measures. The p.mean.nbrs.dist statistic quantifies how densely surrounded an extremum is by other data points, with high values indicating isolation in sparse regions of the feature space. By examining the distribution of this statistic across extrema and identifying natural gaps, we can establish thresholds that separate well-supported features from artifacts of sparse sampling. However, this filtering operates at the summary level, leaving us with a vector of vertices corresponding to extrema that passed our criteria.

The function addresses the subsequent step of updating the basin structure itself. Simply discarding rows from a summary table proves insufficient because the basins object maintains complex nested structures linking extrema to their associated vertex sets, hop distances, and boundary information. Each basin in the lmin_basins and lmax_basins lists must be examined to determine whether its extremum vertex appears in the retention set, with only matching basins preserved in the output.

This approach offers maximum flexibility regarding filtering criteria. Whether extrema are selected based on isolation measures, basin sizes, relative values, spatial location, or any combination of quality metrics, the function operates uniformly on the resulting vertex set. The retention vector may contain only minima, only maxima, or a mixed set, with the function automatically determining the type of each extremum from the basin structure and filtering accordingly.

The filtering operation preserves complete basin information for retained extrema. All basin properties including vertex membership, hop distance maps, and boundary vertices carry forward unchanged. The function also records comprehensive metadata about the filtering operation, documenting which extrema were removed and providing counts by extremum type. This transparency proves essential for understanding how filtering decisions impact the subsequent analysis pipeline.

After filtering, the resulting basin structure integrates seamlessly with downstream operations. The filtered basins can proceed directly to gradient flow graph construction, or they can undergo additional clustering and merging if further consolidation seems warranted. The filtering step thus serves as a quality control gate, ensuring that only extrema meeting domain-specific criteria propagate through the analysis workflow.

Examples

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

# Cluster and merge extrema
max.clusters <- cluster.local.extrema(basins, edgelen.list,
                                      extrema.type = "max",
                                      overlap.threshold = 0.15)
merged.max <- merge.clustered.basins(basins, max.clusters, extrema.type = "max")

min.clusters <- cluster.local.extrema(merged.max, edgelen.list,
                                      extrema.type = "min",
                                      overlap.threshold = 0.15)
merged.basins <- merge.clustered.basins(merged.max, min.clusters,
                                       extrema.type = "min")

# Generate summary
merged.basin.df <- summary(merged.basins, edgelen.list)

# Filter maxima by isolation measure
max.basin.df <- merged.basin.df[merged.basin.df$type == "max", ]
max.basin.df <- max.basin.df[max.basin.df$p.mean.nbrs.dist < 0.8, ]
good.max.vertices <- max.basin.df$vertex

# Filter minima by isolation measure
min.basin.df <- merged.basin.df[merged.basin.df$type == "min", ]
min.basin.df <- min.basin.df[min.basin.df$p.mean.nbrs.dist < 0.75, ]
good.min.vertices <- min.basin.df$vertex

# Combine filtered extrema
good.extrema <- c(good.min.vertices, good.max.vertices)

# Filter basin structure
filtered.basins <- filter.basins(merged.basins, good.extrema)

cat("Original:", length(merged.basins$lmin_basins), "minima,",
    length(merged.basins$lmax_basins), "maxima\n")
cat("Filtered:", length(filtered.basins$lmin_basins), "minima,",
    length(filtered.basins$lmax_basins), "maxima\n")

# Examine filtering details
print(filtered.basins$filter.info)

# Continue with gradient flow graph construction
gflow.graph <- construct.gflow.graph(filtered.basins)
plot(gflow.graph)

# Alternative: Filter only maxima
filtered.max.only <- filter.basins(merged.basins, good.max.vertices)

# Alternative: Filter by basin size
large.basins <- merged.basin.df[merged.basin.df$basin.size >= 100, ]
filtered.by.size <- filter.basins(merged.basins, large.basins$vertex)
} # }