shift_transitions: Extract Regime Shift Transitions

In bifrost: Branch-Level Inference Framework for Recognizing Optimal Shifts in Traits

Extract Regime Shift Transitions

Description

Extract node-state transitions from a mapped SIMMAP tree and annotate them with state-associated numeric values. For bifrost_search objects, the values are the fitted BMM regime rates in x$model_no_uncertainty$param. bifrost_search inputs are accepted only for multi-regime BMM fits, because other model families do not expose the mapped heterogeneous-rate history summarized here. For generic inputs, supply a SIMMAP tree and a named numeric state_values vector.

Usage

shift_transitions(
  x = NULL,
  tree = NULL,
  state_values = NULL,
  include_root = TRUE
)

Arguments

x	A bifrost_search object, a compatible list with tree_no_uncertainty_untransformed and model_no_uncertainty, a SIMMAP-style phylo tree when state_values is supplied, or NULL when using the tree argument.
tree	Optional SIMMAP-style phylo tree for generic input mode.
state_values	Named numeric vector mapping SIMMAP state labels to state-associated values for generic input mode.
include_root	Logical; include a synthetic root row describing the root state and value.

Details

shift_transitions() implements the manuscript's node-based shift definition. Each positive-length edge map must therefore contain only one state. SIMMAP histories with state transitions inside an edge are rejected because assigning such a transition to the child node would give it the wrong time and branch location.

Value

A shift_transitions data frame with one row per detected parent-child node-state transition, plus the optional root row. Columns include node identity, node height and age, parent and child states, parent and child values, rate delta, percentage change, log rate ratio, and the classified rate_change. The result carries tree, state_values, and settings attributes that record the mapped tree, resolved state-value vector, and input options used to create the table.

Examples

toy_tree <- ape::read.tree(text = "(((a:1,b:1):1,c:2):1,d:3);")
toy_tree <- phytools::paintSubTree(
  tree = toy_tree,
  node = ape::Ntip(toy_tree) + 1L,
  state = "0"
)
toy_tree <- phytools::paintSubTree(
  tree = toy_tree,
  node = ape::Ntip(toy_tree) + 2L,
  state = "1"
)
toy_tree <- phytools::paintSubTree(
  tree = toy_tree,
  node = ape::Ntip(toy_tree) + 3L,
  state = "2"
)
shift_transitions(
  tree = toy_tree,
  state_values = c("0" = 1, "1" = 4, "2" = 2)
)

bifrost documentation built on Nov. 5, 2026, 9:07 a.m.