Skip to contents

Merge Basins in a Trajectory-First Gradient Flow Complex (gfc.flow)

Source: R/gfc_flow.R
merge.gfc.flow.basins.Rd

Merges (absorbs) a set of "loser" extrema basins into corresponding "winner" extrema basins by modifying trajectories: each trajectory that ends at a loser extremum is extended by a connector path from the loser to the winner.

The connector is computed on the domain graph. Initially, only the weighted shortest-path connector is implemented (via igraph). The public API is designed so that "high.saddle" and "high.saddle.shortest" can be added later without refactoring.

Usage

# S3 method for class 'gfc.flow.basins'
merge(
  x,
  y = NULL,
  adj.list = y,
  weight.list,
  merge.map = NULL,
  losers = NULL,
  winners = NULL,
  type = c("max", "min"),
  connector.method = c("closest", "shortest", "high.saddle", "high.saddle.shortest"),
  mark.loser.spurious = TRUE,
  merge.filter.stage = "MERGE",
  verbose = TRUE,
  ...
)

Arguments

x

A gfc.flow object from compute.gfc() trajectory modes (or compute.gfc.trajectory() / deprecated compute.gfc.flow()).

y

Optional alias for adj.list. Present for S3 signature compatibility.

adj.list

Adjacency list of the domain graph (1-based vertex indices).

weight.list

Parallel list of edge weights; weight.list[[i]] must align with adj.list[[i]].

merge.map

Named character/integer vector specifying merges. Names are losers, values are winners. Each element can be a label (e.g., "M4") or a vertex index (e.g., 1814).

losers

Optional vector of losers (labels or vertex indices). Used if merge.map is not supplied.

winners

Optional vector of winners (labels or vertex indices). If length 1 and losers has length > 1, the winner is recycled.

type

Extremum type to merge: "max" or "min".

connector.method

Connector policy. Currently only "closest" and "shortest" methods are implemented. "high.saddle" and "high.saddle.shortest" are reserved for future implementations.

mark.loser.spurious

Logical. If TRUE, marks loser extrema as spurious and sets merged.into to the winner label in summaries and basin records.

merge.filter.stage

Character string to write to filter.stage for merged losers (only used when mark.loser.spurious=TRUE).

verbose

Logical.

...

Additional arguments (currently ignored).

Value

A modified gfc.flow object with updated trajectories and derived basin/membership/summary fields.

Details

For each merge pair \(lM \to wM\) (or \(lm \to wm\) for minima), and for each trajectory \(T=(u_0,\ldots,u_m=lM)\) ending at the loser, the function replaces it with \(T'=(u_0,\ldots,u_m=lM,\ldots,wM)\) by appending a connector path \(P(lM,wM)\) (excluding the first vertex to avoid duplication).

After trajectory rewrites, the function rebuilds:

  • max.membership.all, min.membership.all from trajectories

  • max.basins.all, min.basins.all vertices and hop distances

  • basin.size in min.summaries.all / max.summaries.all

  • summary.all and summary via .postprocess.gfc.flow()

Note: fields such as max.overlap.dist / min.overlap.dist are not recomputed here and should be treated as stale after merging.