Filter Basins by Relative Value Threshold

Filters basins of attraction by removing extrema whose relative function values fall below specified thresholds. This operation proves essential when analyzing biological or physical data where only extrema of sufficient magnitude represent meaningful features rather than noise or artifacts.

Usage

filter.basins.by.relvalue(
  basins.obj,
  min.rel.value.max = NULL,
  max.rel.value.min = NULL
)

Arguments

basins.obj

An object of class "basins_of_attraction" returned by compute.basins.of.attraction containing the complete basin structure before filtering.

min.rel.value.max

Numeric value specifying the minimum relative value threshold for local maxima. Only maxima with relative values (value divided by mean of y) greater than or equal to this threshold will be retained. Default is NULL, meaning no filtering is applied to maxima. Set to 1.0 to retain only maxima above the mean, or higher values for more stringent filtering.

max.rel.value.min

Numeric value specifying the maximum relative value threshold for local minima. Only minima with relative values less than or equal to this threshold will be retained. Default is NULL, meaning no filtering is applied to minima. Set to 1.0 to retain only minima below the mean, or lower values for more stringent filtering.

Value

An object of class "basins_of_attraction" with the same structure as the input but containing only basins for extrema that satisfy the relative value criteria. The object contains:

lmin_basins

List of basin structures for retained local minima, with each basin preserving its complete vertex set, hop distances, and boundary information.

lmax_basins

List of basin structures for retained local maxima, similarly preserving all basin properties.

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:

min.rel.value.max

Threshold used for maxima filtering, or NULL if not applied.

max.rel.value.min

Threshold used for minima filtering, or NULL if not applied.

n.lmax.original

Number of maxima before filtering.

n.lmax.retained

Number of maxima after filtering.

n.lmin.original

Number of minima before filtering.

n.lmin.retained

Number of minima after filtering.

removed.lmax.vertices

Vertex indices of removed maxima.

removed.lmin.vertices

Vertex indices of removed minima.

Details

Consider the problem of identifying biologically significant features in a function landscape. Many local extrema emerge from measurement noise, minor perturbations, or fine-scale variations that, while mathematically valid as critical points, lack substantive meaning for downstream interpretation. The relative value of an extremum, computed as its function value divided by the mean across all vertices, provides a natural scale-invariant measure of prominence.

We begin by examining which extrema satisfy the threshold criteria. For local maxima, we retain only those whose relative values exceed a specified minimum, typically chosen to represent peaks that rise substantially above the average landscape level. For local minima, we retain those falling below a maximum relative value, capturing valleys that descend significantly beneath the mean. These criteria filter the topological structure to emphasize features of genuine interest.

The filtering operation must preserve the integrity of the basin structure. Simply removing extrema from the extrema list would leave orphaned basins in the basin lists, creating inconsistencies that corrupt downstream analyses. Therefore, we simultaneously filter both the extrema vertices and their corresponding basin structures, ensuring that every basin in the output corresponds to a retained extremum and vice versa.

After filtering, the basin indices no longer match the original vertex indices. The function reconstructs the complete basin structure with consistent indexing, preserving all basin information (vertex sets, hop distances, boundary vertices) for the retained extrema. This filtered structure integrates seamlessly with clustering and merging operations, as the subsequent analyses depend only on the relative relationships between basins rather than their absolute positions in the original extrema list.

The operation proves particularly valuable in biological applications where the signal-to-noise ratio varies across features. Microbiome data, for instance, often exhibits numerous small local maxima in composition space that reflect sampling variation rather than distinct ecological states. Filtering by relative value focuses the analysis on robust features that represent stable configurations worthy of biological interpretation.

See also

compute.basins.of.attraction for computing basins, summary.basins_of_attraction for computing relative values, cluster.local.extrema for clustering filtered basins, merge.clustered.basins for merging clustered basins

Examples

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

# Generate summary to examine relative values
edgelen.list <- compute.edge.lengths(adj.list, weight.list)
basin.summary <- summary(basins, edgelen.list)

# Examine distribution of relative values
max.basins <- basin.summary[basin.summary$type == "max", ]
cat("Maxima relative values:\n")
print(sort(max.basins$rel.value, decreasing = TRUE))

# Filter to retain only biologically significant maxima (rel.value >= 1.0)
filtered.basins <- filter.basins.by.relvalue(basins,
                                             min.rel.value.max = 1.0)

cat("Original maxima:", length(basins$lmax_basins), "\n")
cat("Retained maxima:", length(filtered.basins$lmax_basins), "\n")

# Examine what was removed
print(filtered.basins$filter.info)

# Filter both maxima and minima
filtered.both <- filter.basins.by.relvalue(basins,
                                          min.rel.value.max = 1.2,
                                          max.rel.value.min = 0.8)

# Now cluster only the retained extrema
max.clusters <- cluster.local.extrema(filtered.basins,
                                      edgelen.list,
                                      extrema.type = "max",
                                      overlap.threshold = 0.15)

# Continue with merging
merged.max <- merge.clustered.basins(filtered.basins,
                                    max.clusters,
                                    extrema.type = "max")
} # }