Identifies local minima and maxima of a scalar field on a graph and computes their basins via geodesic flow analysis.
Usage
find.gflow.basins(
adj.list,
weight.list,
y,
min.basin.size = 1L,
min.path.size = 2L,
q.edge.thld = 0.5
)Arguments
- adj.list
A list of integer vectors. Each vector contains indices of vertices adjacent to the corresponding vertex. Indices must be 1-based.
- weight.list
A list of numeric vectors. Each vector contains weights of edges corresponding to adjacencies in
adj.list. Must have the same structure asadj.list.- y
A numeric vector of length \(n\), the response values at each graph vertex.
- min.basin.size
An integer scalar, the minimum number of vertices a basin must contain to be considered significant. Default is 1.
- min.path.size
An integer scalar, the minimum number of vertices along a shortest path for which monotonicity is tested. Default is 2.
- q.edge.thld
A numeric scalar in \([0,1]\), the quantile threshold for maximum allowed edge weight along geodesics. Default is 0.5.
Value
An object of class "gflow_basins", which is a list with the following components:
- basins
A list with two elements:
- ascending
A list of local-minimum basins
- descending
A list of local-maximum basins
Each basin is a list with components:
- vertex
Integer, the 1-based vertex index of the extremum
- value
Numeric, the function value at the extremum
- basin
A matrix with columns "vertex" and "distance"
- label
Character, a unique label for the extremum
- local_extrema
A data frame summarizing all detected extrema with columns:
- vertex_index
Integer, 1-based vertex index
- is_maximum
Integer, 1 if maximum, 0 if minimum
- label
Character, unique label (e.g., "M1", "m1")
- fn_value
Numeric, function value at extremum
Examples
# Create a simple graph
adj.list <- list(c(2, 3), c(1, 3, 4), c(1, 2, 4), c(2, 3))
weight.list <- list(c(1, 1), c(1, 1, 1), c(1, 1, 1), c(1, 1))
y <- c(1, 0, 2, 1.5)
# \donttest{
# Find basins (requires compiled C++ backend)
result <- find.gflow.basins(adj.list, weight.list, y,
min.basin.size = 1,
min.path.size = 2,
q.edge.thld = 0.5)
summary(result)
# }