Compare Rate-Shift Magnitudes — compare_shift

Compare the magnitude of fitted rate increases and decreases from a bifrost_search BMM result or a transition table returned by shift_transitions(). This is the package-level analogue of the Berv et al. (2026) workflow that summarized rate changes and tested whether increase and decrease magnitudes differed. When x is a bifrost_search object, it must be a multi-regime BMM fit; use a transition table or tree plus state_values for generic mapped-tree inputs.

Usage

compare_shift_magnitudes(
  x = NULL,
  tree = NULL,
  state_values = NULL,
  measure = c("rate_delta", "percentage_change", "log_ratio"),
  transform = c("log_absolute", "absolute", "signed"),
  tests = "ks",
  alternative = c("two.sided", "less", "greater"),
  ks_simulate_p_value = TRUE,
  ks_B = 10000L,
  bootstrap_p_value = FALSE,
  bootstrap_R = 100L,
  ks_reps = NULL,
  bootstrap_reps = NULL,
  seed = NULL
)

Arguments

x: A bifrost_search object, compatible list, SIMMAP tree, data frame with rate_change and the selected measure, a list of transition tables or BMM bifrost_search objects to pool before testing, a shift_magnitude_groups object to compare each named group separately, or NULL when using the tree argument. Fitted bifrost_search inputs are accepted only for multi-regime BMM fits.
tree: Optional SIMMAP-style phylo tree for generic input mode.
state_values: Named numeric state-value vector for generic input mode.
measure: Which transition column to compare. rate_delta compares fitted child-minus-parent rate differences, percentage_change compares percent changes relative to the parent rate, and log_ratio compares log child/parent rate ratios.
transform: How to transform the selected measure before testing. "absolute" compares magnitudes, "log_absolute" compares log magnitudes, and "signed" compares signed values.
tests: Character vector of tests to run. Supported values are "t" for a Welch t-test, "wilcox" for an unpaired Wilcoxon rank-sum test, and "ks" for a two-sample Kolmogorov-Smirnov test. Use "all" for all three. The default reproduces the Berv et al. (2026) rate-delta magnitude comparison: a KS test on log(abs(rate_delta)).
alternative: Alternative hypothesis passed to the tests.
ks_simulate_p_value: Logical; passed to stats::ks.test() when "ks" is requested. The default matches the Berv et al. (2026) utility.
ks_B: Integer number of replicates for the simulated KS p-value.
bootstrap_p_value: Logical; estimate the mean p-value from stratified bootstrap resampling within the increase and decrease groups. This reproduces the bootstrap p-value annotation used in the Berv et al. (2026) magnitude-density panels when "ks" is requested.
bootstrap_R: Integer number of bootstrap replicates when bootstrap_p_value = TRUE.
ks_reps: Optional clearer alias for ks_B.
bootstrap_reps: Optional clearer alias for bootstrap_R.
seed: Optional random seed for stochastic KS simulation and bootstrap p-value resampling. The Berv et al. (2026) defaults are unchanged; when a seed is supplied, the previous global RNG state is restored before returning.

Value

A list of class shift_magnitude_comparison with the transformed values used for testing, group summaries, modal summaries, test results, and settings. When x is a shift_magnitude_groups object, a named shift_magnitude_comparison_set is returned instead.

Details

Plain lists of transition tables or BMM search objects are pooled into one comparison before testing. Use shift_magnitude_groups() when list elements are analysis groups that should be compared separately. If a group is already a shift_magnitude_comparison, its measure, transform, tests, alternative, KS settings, and bootstrap settings must exactly match the grouped call; otherwise, recompute that group from raw transitions or call compare_shift_magnitudes() with matching settings.

Examples

transitions <- data.frame(
  rate_change = c("increase", "increase", "decrease", "decrease"),
  rate_delta = c(2, 3, -1, -1.5)
)
compare_shift_magnitudes(transitions, ks_reps = 99)
#> $values
#>   rate_change raw_value     value
#> 1    increase       2.0 0.6931472
#> 2    increase       3.0 1.0986123
#> 3    decrease      -1.0 0.0000000
#> 4    decrease      -1.5 0.4054651
#> 
#> $summary
#>   rate_change n      mean    median        sd       min       max
#> 1    increase 2 0.8958797 0.8958797 0.2867071 0.6931472 1.0986123
#> 2    decrease 2 0.2027326 0.2027326 0.2867071 0.0000000 0.4054651
#>   mean_signed_raw mean_abs_raw median_abs_raw
#> 1            2.50         2.50           2.50
#> 2           -1.25         1.25           1.25
#> 
#> $modal
#>   mode_increase mode_decrease mode_difference linear_ratio
#> 1      1.095835   0.002777444        1.093057     2.983382
#> 
#> $tests
#>   test statistic parameter p_value mean_increase mean_decrease mean_difference
#> 1   ks         1        NA    0.42     0.8958797     0.2027326       0.6931472
#>   median_increase median_decrease median_difference conf_low conf_high
#> 1       0.8958797       0.2027326         0.6931472       NA        NA
#>                                           method bootstrap_mean_p bootstrap_R
#> 1 Monte-Carlo two-sample Kolmogorov-Smirnov test               NA          NA
#> 
#> $settings
#> $settings$measure
#> [1] "rate_delta"
#> 
#> $settings$transform
#> [1] "log_absolute"
#> 
#> $settings$tests
#> [1] "ks"
#> 
#> $settings$alternative
#> [1] "two.sided"
#> 
#> $settings$ks_simulate_p_value
#> [1] TRUE
#> 
#> $settings$ks_B
#> [1] 99
#> 
#> $settings$bootstrap_p_value
#> [1] FALSE
#> 
#> $settings$bootstrap_R
#> [1] 100
#> 
#> $settings$seed
#> NULL
#> 
#> 
#> attr(,"class")
#> [1] "shift_magnitude_comparison" "list"                      
groups <- shift_magnitude_groups(A = transitions, B = transitions)
compare_shift_magnitudes(groups, ks_reps = 99)
#> $A
#> $values
#>   rate_change raw_value     value
#> 1    increase       2.0 0.6931472
#> 2    increase       3.0 1.0986123
#> 3    decrease      -1.0 0.0000000
#> 4    decrease      -1.5 0.4054651
#> 
#> $summary
#>   rate_change n      mean    median        sd       min       max
#> 1    increase 2 0.8958797 0.8958797 0.2867071 0.6931472 1.0986123
#> 2    decrease 2 0.2027326 0.2027326 0.2867071 0.0000000 0.4054651
#>   mean_signed_raw mean_abs_raw median_abs_raw
#> 1            2.50         2.50           2.50
#> 2           -1.25         1.25           1.25
#> 
#> $modal
#>   mode_increase mode_decrease mode_difference linear_ratio
#> 1      1.095835   0.002777444        1.093057     2.983382
#> 
#> $tests
#>   test statistic parameter p_value mean_increase mean_decrease mean_difference
#> 1   ks         1        NA    0.35     0.8958797     0.2027326       0.6931472
#>   median_increase median_decrease median_difference conf_low conf_high
#> 1       0.8958797       0.2027326         0.6931472       NA        NA
#>                                           method bootstrap_mean_p bootstrap_R
#> 1 Monte-Carlo two-sample Kolmogorov-Smirnov test               NA          NA
#> 
#> $settings
#> $settings$measure
#> [1] "rate_delta"
#> 
#> $settings$transform
#> [1] "log_absolute"
#> 
#> $settings$tests
#> [1] "ks"
#> 
#> $settings$alternative
#> [1] "two.sided"
#> 
#> $settings$ks_simulate_p_value
#> [1] TRUE
#> 
#> $settings$ks_B
#> [1] 99
#> 
#> $settings$bootstrap_p_value
#> [1] FALSE
#> 
#> $settings$bootstrap_R
#> [1] 100
#> 
#> $settings$seed
#> NULL
#> 
#> 
#> attr(,"class")
#> [1] "shift_magnitude_comparison" "list"                      
#> 
#> $B
#> $values
#>   rate_change raw_value     value
#> 1    increase       2.0 0.6931472
#> 2    increase       3.0 1.0986123
#> 3    decrease      -1.0 0.0000000
#> 4    decrease      -1.5 0.4054651
#> 
#> $summary
#>   rate_change n      mean    median        sd       min       max
#> 1    increase 2 0.8958797 0.8958797 0.2867071 0.6931472 1.0986123
#> 2    decrease 2 0.2027326 0.2027326 0.2867071 0.0000000 0.4054651
#>   mean_signed_raw mean_abs_raw median_abs_raw
#> 1            2.50         2.50           2.50
#> 2           -1.25         1.25           1.25
#> 
#> $modal
#>   mode_increase mode_decrease mode_difference linear_ratio
#> 1      1.095835   0.002777444        1.093057     2.983382
#> 
#> $tests
#>   test statistic parameter p_value mean_increase mean_decrease mean_difference
#> 1   ks         1        NA    0.35     0.8958797     0.2027326       0.6931472
#>   median_increase median_decrease median_difference conf_low conf_high
#> 1       0.8958797       0.2027326         0.6931472       NA        NA
#>                                           method bootstrap_mean_p bootstrap_R
#> 1 Monte-Carlo two-sample Kolmogorov-Smirnov test               NA          NA
#> 
#> $settings
#> $settings$measure
#> [1] "rate_delta"
#> 
#> $settings$transform
#> [1] "log_absolute"
#> 
#> $settings$tests
#> [1] "ks"
#> 
#> $settings$alternative
#> [1] "two.sided"
#> 
#> $settings$ks_simulate_p_value
#> [1] TRUE
#> 
#> $settings$ks_B
#> [1] 99
#> 
#> $settings$bootstrap_p_value
#> [1] FALSE
#> 
#> $settings$bootstrap_R
#> [1] 100
#> 
#> $settings$seed
#> NULL
#> 
#> 
#> attr(,"class")
#> [1] "shift_magnitude_comparison" "list"                      
#> 
#> attr(,"settings")
#> attr(,"settings")$measure
#> [1] "rate_delta"
#> 
#> attr(,"settings")$transform
#> [1] "log_absolute"
#> 
#> attr(,"settings")$tests
#> [1] "ks"
#> 
#> attr(,"settings")$alternative
#> [1] "two.sided"
#> 
#> attr(,"settings")$ks_simulate_p_value
#> [1] TRUE
#> 
#> attr(,"settings")$ks_B
#> [1] 99
#> 
#> attr(,"settings")$bootstrap_p_value
#> [1] FALSE
#> 
#> attr(,"settings")$bootstrap_R
#> [1] 100
#> 
#> attr(,"settings")$seed
#> NULL
#> 
#> attr(,"class")
#> [1] "shift_magnitude_comparison_set" "list"