Compute Waiting Times Between Regime Shifts — shift_waiting

Compute chronological whole-tree waiting times, between-shift intervals along root-to-tip lineages, and acceleration-focused increase-to-increase waiting times from a mapped SIMMAP tree or from the output of shift_transitions(). Lineage intervals exclude the censored root-to-first-shift and last-shift-to-tip boundaries. Fitted bifrost_search inputs are accepted only for multi-regime BMM fits; generic SIMMAP trees remain supported with tree and state_values. Tied or simultaneous transitions are preserved as zero-length waiting times in the descriptive tables.

Usage

shift_waiting_times(
  x = NULL,
  tree = NULL,
  state_values = NULL,
  scope = c("all", "global", "lineage", "acceleration")
)

Arguments

x: A BMM bifrost_search object, compatible list, SIMMAP tree, shift_transitions data frame, or NULL when using tree.
tree: Optional SIMMAP-style phylo tree for generic input mode, or the tree corresponding to a user-supplied transition table.
state_values: Named numeric state-value vector for generic input mode.
scope: Which components to compute. "all" computes global, lineage, and acceleration summaries.

Value

A list of class shift_waiting_times with transitions, global, lineage, lineage_by_tip, acceleration, and summaries components. Components outside the requested scope are returned as NULL.

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_waiting_times(
  tree = toy_tree,
  state_values = c("0" = 1, "1" = 4, "2" = 2)
)
#> $transitions
#>   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
#> 
#> $global
#>   PreviousNode NextNode PreviousState NextState PreviousShift NextShift
#> 1            5        6             0         1          root  increase
#> 2            6        7             1         2      increase  decrease
#>   TimeToNext             Category
#> 1          1                other
#> 2          1 increase_to_decrease
#> 
#> $lineage
#>   Lineage tip_label PreviousNode NextNode PreviousState NextState PreviousShift
#> 1       1         a            6        7             1         2      increase
#> 2       2         b            6        7             1         2      increase
#>   NextShift TimeToNext             Category
#> 1  decrease          1 increase_to_decrease
#> 2  decrease          1 increase_to_decrease
#> 
#> $lineage_by_tip
#> $lineage_by_tip$a
#>   Lineage tip_label PreviousNode NextNode PreviousState NextState PreviousShift
#> 1       1         a            6        7             1         2      increase
#>   NextShift TimeToNext             Category
#> 1  decrease          1 increase_to_decrease
#> 
#> $lineage_by_tip$b
#>   Lineage tip_label PreviousNode NextNode PreviousState NextState PreviousShift
#> 1       2         b            6        7             1         2      increase
#>   NextShift TimeToNext             Category
#> 1  decrease          1 increase_to_decrease
#> 
#> $lineage_by_tip$c
#>  [1] Lineage       tip_label     PreviousNode  NextNode      PreviousState
#>  [6] NextState     PreviousShift NextShift     TimeToNext    Category     
#> <0 rows> (or 0-length row.names)
#> 
#> $lineage_by_tip$d
#>  [1] Lineage       tip_label     PreviousNode  NextNode      PreviousState
#>  [6] NextState     PreviousShift NextShift     TimeToNext    Category     
#> <0 rows> (or 0-length row.names)
#> 
#> 
#> $acceleration
#> $acceleration$lineage_weighted
#> [1] Lineage      tip_label    older_node   younger_node gap         
#> <0 rows> (or 0-length row.names)
#> 
#> $acceleration$collapsed
#> [1] older_node   younger_node gap         
#> <0 rows> (or 0-length row.names)
#> 
#> $acceleration$summary
#>            summary n mean median sd
#> 1 lineage_weighted 0   NA     NA NA
#> 2        collapsed 0   NA     NA NA
#> 
#> 
#> $summaries
#> $summaries$global
#>               Category Mean Median Variance Count
#> 1                other    1      1       NA     1
#> 2 increase_to_decrease    1      1       NA     1
#> 
#> $summaries$lineage
#>               Category Mean Median Variance Count
#> 1 increase_to_decrease    1      1        0     2
#> 
#> $summaries$acceleration
#>            summary n mean median sd
#> 1 lineage_weighted 0   NA     NA NA
#> 2        collapsed 0   NA     NA NA
#> 
#> 
#> $scope
#> [1] "all"
#> 
#> attr(,"class")
#> [1] "shift_waiting_times" "list"