Creates the canonical schema used by all basin-construction methods in gflow. Each advertised construction method returns the same canonical schema while retaining method-specific merge-tree, trajectory, RTCB, or overlap-cell structures.
Usage
create.basin.complex(
adj.list,
edge.length.list,
field,
method = c("trajectory_flow", "superlevel_merge_tree", "geodesic_reachability", "rtcb",
"overlap_cell_complex"),
direction = "both",
vertex.mass = NULL,
vertex.density = NULL,
graph.params = list(edge.length.symmetry.tolerance = sqrt(.Machine$double.eps)),
method.params = list(),
simplify.params = list(),
verbose = FALSE,
vertex.id = seq_along(field),
vertex.mass.provenance = NULL
)Arguments
- adj.list
Undirected graph adjacency list using 1-based vertex ids.
- edge.length.list
Numeric edge-length vectors parallel to
adj.list.- field
Finite scalar field over graph vertices.
- method
Basin-construction family.
- direction
One of
"max","min", or"both".- vertex.mass
Optional finite nonnegative empirical or quadrature mass. The total must be positive. No uniform fallback is applied when omitted.
- vertex.density
Optional finite nonnegative vertex density used by density-modulated trajectory methods.
- graph.params
Named graph-validation parameters; see basin-parameters.
- method.params
Named method parameters. Defaults, applicability and consequential choices are listed in basin-parameters.
- simplify.params
Named refinement parameters; see basin-parameters.
- verbose
Logical scalar controlling backend progress output.
- vertex.id
Optional integer or character external vertex IDs in graph order. Factors, missing values, duplicates, empty strings, and invalid encodings are rejected. Existing canonical tables retain internal integer indices and add external-ID companion columns.
- vertex.mass.provenance
Optional typed provenance declarations and upstream attestations for
vertex.mass. The constructor recomputes only facts supported by its inputs and preserves external claims with their stated validation authority.
Value
A basin_complex. Successful construction returns status = "ok".
A recoverable backend failure returns status = "failed" with a
structured diagnostic.
Details
The five construction families are:
"trajectory_flow": directed flow trajectories terminating at field extrema;"superlevel_merge_tree": exact plateau-aware merge trees of graph level sets;"geodesic_reachability": basins defined by monotone geodesic reachability;"rtcb": relaxed trajectory-constrained basins; and"overlap_cell_complex": joint ascending/descending overlap cells.
direction = "max" follows the field toward maxima, "min" follows it
toward minima, and "both" computes both orientations. The overlap-cell
method requires "both".
vertex.mass and vertex.density have different meanings. Mass supplies
empirical or quadrature support weights used in basin summaries and
mass-based refinement. Density modifies trajectory edge scores only when
method.params$modulation is "DENSITY" or "DENSITY_EDGELEN". Neither is
inferred from the other.
Basin membership can overlap. get.basin.membership() is therefore the
authoritative many-to-many vertex-to-basin relation. get.basin.assignment()
is an optional, method-dependent single label for convenience; it must not
be interpreted as replacing membership.
Refinement is requested with simplify.params and is applied in the fixed
order recorded in provenance$refinement.stages: relative-value filtering,
extrema clustering, geometric filtering, support filtering, and expansion.
Unsupported refinement stages fail validation rather than being silently
ignored.
CLOSEST trajectory flow contracts each connected component of exactly equal
field values before selecting an improving edge. A flow-terminal plateau has
no adjacent plateau with a strictly higher field value for maximum flow or
a strictly lower field value for minimum flow; original graph degree is
irrelevant. The smallest original vertex is the representative.
Non-flow-terminal plateaus select a boundary edge by length, target vertex,
then source vertex. The resolved trajectory parameter
plateau.policy = "connected_exact" is mandatory for CLOSEST and recorded
in the returned provenance.
Retired constructors such as compute.gfc(),
compute.basins.of.attraction(), compute.gfc.trajectory(),
compute.gfc.flow(), and create.basin.cx() raise a lifecycle error.
Construct new objects here. Use as.basin.complex() only to convert a
compatible archived result while its original graph (and field when not
retained by the archive) is available.
See also
get.basin.table(), get.basin.membership(),
get.basin.assignment(), summary.basin_complex(), plot.basin_complex()
and vignette("basin_complex_workflow_vignette", package = "gflow") for
all five method families and their refinement controls.
Examples
# A path with a plateau peak at vertices 2--3 and a higher peak at 6.
adjacency <- list(2L, c(1L, 3L), c(2L, 4L), c(3L, 5L),
c(4L, 6L), c(5L, 7L), 6L)
lengths <- lapply(adjacency, function(v) rep(1, length(v)))
field <- c(0, 3, 3, 1, 2, 4, 0)
tree <- create.basin.complex(adjacency, lengths, field,
method = "superlevel_merge_tree", direction = "max")
summary(tree)
#> Canonical Basin Complex Summary
#> Method: superlevel_merge_tree
#> Direction: max
#> Status: ok
#> Vertices/components: 7/1
#> Basin rows: 2; membership rows: 9; assignment rows: 7
#>
#> Coverage (unique vertices; assignment rows may have no label):
#> direction retained.basins raw.vertices retained.vertices assigned.vertices
#> max 2 7 7 7
#> total.vertices
#> 7
#>
#> Maxima: 2 of 2 returned basins; ranked by primary.support.size
#> Number of vertices uniquely assigned to the basin.
#> rank extremum.vertex.id primary.support.size persistence retained
#> 1 6 5 4 TRUE
#> 2 2 2 2 TRUE
#>
#> Persistence is in field units; mass measures are normalized support fractions.
get.basin.table(tree)[, c("extremum.vertex", "persistence", "raw.support.size")]
#> extremum.vertex persistence raw.support.size
#> 1 6 4 7
#> 2 2 2 2
membership <- get.basin.membership(tree)
assignment <- get.basin.assignment(tree)
stopifnot(nrow(membership) > 0L, nrow(assignment) == length(field))
# At height 2 the plateau and the higher peak are separate components.
cut(get.basin.merge.tree(tree), height = 2)$components
#> component.id graph.component basin.id extremum.id
#> 1 component_max_0001 1 basin_max_v00000002 extremum_max_v00000002
#> 2 component_max_0002 1 basin_max_v00000006 extremum_max_v00000006
#> extremum.vertex extremum.value support.size support.mass vertices vertex.ids
#> 1 2 3 2 NA 2, 3 2, 3
#> 2 6 4 2 NA 5, 6 5, 6
plot(tree, view = "merge_tree", direction = "max", type = "tree",
label = "extremum.vertex", show.mass = FALSE, show.support = FALSE)
