Plot a Crossing-Free Basin Merge Tree and Persistence Barcode

Draws an exact graph level-set merge tree, its extremum-to-saddle persistence barcode, or both. Tree topology and scalar-field heights come from the canonical merge tree. An hclust-compatible representation determines only a deterministic crossing-free leaf order. The rendered tree is directed: every elder basin remains a continuous vertical trunk, and each dying branch terminates horizontally on the trunk that survives its saddle.

Usage

# S3 method for class 'basin.merge.tree'
plot(
  x,
  direction = "max",
  component = NULL,
  type = c("tree_and_barcode", "tree", "barcode"),
  label = c("basin.id", "extremum.id", "extremum.vertex"),
  labels = NULL,
  mass.measure = "primary.support.mass",
  support.measure = "primary.support.size",
  show.mass = TRUE,
  show.support = TRUE,
  show.leaf.labels = TRUE,
  show.barcode.guides = TRUE,
  show.barcode.birth.labels = FALSE,
  show.barcode.parent.labels = FALSE,
  height = NULL,
  branch.col = NULL,
  main.tree = "Crossing-free elder-rule merge tree",
  main.barcode = "Extremum-to-saddle persistence barcode",
  field.label = "Scalar-field value",
  annotation.cex = 0.6,
  basin.ids = NULL,
  close.ancestors = FALSE,
  ...
)

Arguments

x: A basin.merge.tree, or a compatible basin_complex.
direction: Tree orientation, "max" or "min".
component: Graph-component number. It may be omitted when the selected direction has exactly one graph component.
type: Panels to draw.
label: Canonical basin-table field used for branch labels.
labels: Optional custom labels. A named vector is matched by basin id; an unnamed vector follows deterministic basin-table order.
mass.measure: Numeric canonical basin-table column shown as mass.
support.measure: Numeric canonical basin-table column shown as support.
show.mass, show.support: Show the aligned top-margin annotation rows.
show.leaf.labels: Label extrema in the tree panel.
show.barcode.guides: Draw a gray dotted guide for every barcode row.
show.barcode.birth.labels: Add basin labels beside filled birth endpoints.
show.barcode.parent.labels: Add "dies into <parent>" beside each open death endpoint, where <parent> is the elder basin that survives the merge. Root endpoints are labeled "root".
height: Optional exact scalar-field cut shown in both panels.
branch.col: Optional branch colors. A named vector is matched by basin id; an unnamed vector must have one color per displayed basin.
main.tree, main.barcode: Panel titles.
field.label: Scalar-field axis label.
annotation.cex: Character expansion for mass and support annotations.
basin.ids: Optional canonical basin ids to display. The selection must be ancestor-closed unless close.ancestors = TRUE.
close.ancestors: Add and report missing canonical ancestors of basin.ids.
...: Reserved for S3 compatibility.

Value

Invisibly, a list containing the tree, selected branch table, crossing-free layout, and plotting coordinates.

Details

The optional top-margin rows report one mass and support quantity for each branch. Defaults use the non-overlapping primary assignment. Raw support measures are hierarchical and can overlap across ancestor and descendant branches. In the barcode, dotted guides, labels beside extremum births, and labels identifying the elder basin into which each branch dies can be controlled independently.