Skip to contents

Extract Regime Shift Transitions

Source: R/shift-distributions.R
shift_transitions.Rd

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.

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.

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.

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)
)
#>   node node_label parent_node parent_state parent_rate child_node child_state
#> 1    5          5          NA         <NA>          NA          5           0
#> 2    6          6           5            0           1          6           1
#> 3    7          7           6            1           4          7           2
#>   child_rate height age edge_length rate_delta percentage_change  log_ratio
#> 1          1      0   3          NA         NA                NA         NA
#> 2          4      1   2           1          3               300  1.3862944
#> 3          2      2   1           1         -2               -50 -0.6931472
#>   rate_change
#> 1        root
#> 2    increase
#> 3    decrease