Summarize Extrema from Riemannian Extremality Analysis

Creates a structured summary of local extrema detected via Riemannian extremality analysis. This function extracts and filters extremality scores, hop-extremality radii, and neighborhood sizes from a fitted model, producing a data frame suitable for reporting, visualization, and further analysis.

Usage

extremality.summary(dcx, extremality.quantile = 0.95, inv.d1.quantile = 0.1)

Arguments

dcx

A fitted riem.dcx object from gflowx::fit.rdgraph.regression() with compute.extremality = TRUE. Must contain the extremality component with scores, hop_extremality_radii, and hop_neighborhood_sizes.

extremality.quantile

Numeric in (0,1). Quantile threshold for extremality score filtering. Default 0.95 keeps vertices with |extremality| above the 95th percentile.

inv.d1.quantile

Numeric in \([0,1)\). Lower quantile threshold for inverse nearest neighbor distance filtering. Default 0.10 removes vertices in the bottom 10% of connectivity. Set to 0 to disable.

Value

A data frame with one row per detected extremum, containing:

vertex

Integer: vertex index (1-indexed)

value

Numeric: fitted value \(\hat{y}(v)\) at the vertex

rel.value

Numeric: relative value normalized by \(\bar{\hat{y}}\)

type

Character: "max" for local maxima, "min" for local minima

inv.1d

Numeric: inverse distance to nearest neighbor (1/d_min), measuring local density

extremality

Numeric in \([-1, 1]\): Riemannian extremality score. Positive for maxima, negative for minima. Magnitude indicates strength.

extremality.radius

Numeric: hop-extremality radius. Maximum hop distance maintaining |extremality| above threshold. Inf for global extrema, NA if not computed.

extremality.nbhd.size

Numeric: number of vertices in the hop-extremality neighborhood. Measures local support for the extremum. Inf for global extrema, NA if not computed.

label

Character: extremum label. Maxima labeled M1, M2, ... in descending order by value. Minima labeled m1, m2, ... in ascending order.

Details

This function provides a convenient interface for working with extremality analysis results computed during model fitting (when compute.extremality = TRUE). It applies filtering by extremality score magnitude and effective degree (inverse nearest neighbor distance), then organizes the results into a clean summary format.

Function Naming

The function is named extremality.summary() rather than compute.gextrema.nbhds() because:

• The extremality scores and hop radii are already computed during fitting

• This function only summarizes and filters pre-computed results

• The name better reflects its role as a post-processing summarization tool

• It distinguishes from compute.pextrema.nbhds() which performs its own computations

Three-Stage Filtering Pipeline

Stage 1 (Extremality Filtering): Select vertices with |extremality| above the specified quantile threshold. This identifies vertices exhibiting strong local maximum or minimum behavior according to the Riemannian metric.

Stage 2 (Connectivity Filtering): Remove poorly connected vertices (outliers) by filtering on inverse nearest neighbor distance (inv.1d). Vertices in sparse, isolated regions are likely less reliable as extrema.

Stage 3 (Organization): Separate maxima and minima, sort by function value, assign labels, and combine into a single summary data frame.

Comparison with compute.pextrema.nbhds()

extremality.summary():

• Uses Riemannian extremality scores from the coboundary operator

• Requires compute.extremality = TRUE during fitting

• Provides hop-extremality radii and neighborhood sizes

• Theoretically rigorous for final analysis

compute.pextrema.nbhds():

• Computes probabilistic maxp/minp scores on the fly

• Works with any fitted model

• Provides hop-extremp radii (probabilistic variant)

• Fast and approximate, suitable for exploration

See also

gflowx::fit.rdgraph.regression() for model fitting with extremality analysis, compute.pextrema.nbhds for probabilistic extrema detection

Examples

if (FALSE) { # \dontrun{
# Fit model with extremality analysis
fit <- gflowx::fit.rdgraph.regression(X, y, k = 50,
                              compute.extremality = TRUE,
                              p.threshold = 0.90,
                              max.hop = 20)

# Summarize extrema with default filtering
extrema <- extremality.summary(fit)
print(extrema)

# More stringent filtering
extrema_strict <- extremality.summary(fit,
                                      extremality.quantile = 0.99,
                                      inv.d1.quantile = 0.20)

# Examine persistent extrema with strong support
persistent <- subset(extrema,
                     extremality.radius >= 5 &
                     extremality.nbhd.size >= 100)

# Visualize extrema by neighborhood size
with(extrema, plot(value, extremality,
                   cex = sqrt(extremality.nbhd.size) / 10,
                   col = ifelse(type == "max", "red", "blue"),
                   main = "Extrema: size ~ neighborhood support"))
} # }