Skip to contents

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

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

Reassigns extremum labels (e.g., M1, M2, sM1, m1, sm1) in a gfc.flow object so that numbering reflects the current basin ranking (by default, descending basin size). This is particularly useful after one or more rounds of basin merging with merge.gfc.flow.basins(), where some extrema may be absorbed and end up with basin.size == 0 and/or stale labels.

The function updates labels consistently across:

  • x$max.summaries.all, x$min.summaries.all

  • x$max.basins.all, x$min.basins.all

  • x$summary.all and x$summary (if present)

  • overlap matrices dimnames (x$max.overlap.dist, x$min.overlap.dist) (if present)

  • x$merge.report label columns (if present)

By default, any extremum with basin.size == 0 is treated as absorbed and forced to be spurious (to avoid retained labels like M8 having empty basins).

Usage

relabel.basins.gfc.flow(
  x,
  rank.by = c("basin.size"),
  tie.break = c("n.trajectories", "value", "vertex"),
  compute.n.trajectories = TRUE,
  enforce.absorbed.spurious = TRUE,
  absorbed.filter.stage = "absorbed",
  relabel.spurious = TRUE,
  store.label.map = TRUE,
  verbose = FALSE
)

Arguments

x

A gfc.flow object.

rank.by

Character string specifying ranking criterion for labeling. Currently supported: "basin.size" (default). (Reserved: "n.trajectories", "value".)

tie.break

Character vector specifying tie-break order. Supported values: "n.trajectories", "value", "vertex". Default is c("n.trajectories","value","vertex").

compute.n.trajectories

Logical. If TRUE and x$trajectories exists, computes number of trajectories per extremum and uses it as a tie-breaker (and stores it internally for mapping decisions; it does not add a new column to summaries).

enforce.absorbed.spurious

Logical. If TRUE (default), any extremum with basin.size == 0 is forced to is.spurious = TRUE. If filter.stage is present and empty/"none", it is set to absorbed.filter.stage.

absorbed.filter.stage

Character string used for filter.stage when forcing absorbed extrema to spurious. Default is "absorbed".

relabel.spurious

Logical. If TRUE (default), spurious extrema are relabeled sM1, sM2, ... / sm1, sm2, ... according to the chosen ranking. If FALSE, spurious labels are left unchanged but retained labels are still relabeled.

store.label.map

Logical. If TRUE (default), stores old->new label maps in x$label.map.history.

verbose

Logical.

Value

A modified gfc.flow object with relabeled basins/summaries.