rateMapControl: Control Advanced 'rateMap()' Options

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

Control Advanced rateMap() Options

Description

Build a control object for less common rateMap() settings. These options are useful for interval maps, same-topology tree samples, custom fit object shapes, invalid-fit handling, and future-based parallel scheduling.

Usage

rateMapControl(
  res = 100,
  check = TRUE,
  target = c("first", "mcc"),
  tree_fun = NULL,
  param_fun = NULL,
  na_action = c("error", "omit"),
  rate_flags = rateMapRateFlags(),
  quantile_probs = c(0.025, 0.975),
  highest_density_interval_prob = 0.95,
  future_strategy = c("multisession", "multicore"),
  future_seed = FALSE,
  future_scheduling = 1,
  future_chunk_size = NULL
)

Arguments

res	Integer resolution of the global depth grid used to subdivide target-tree branches when summary = "interval". Ignored by summary = "branch".
check	Logical or character check mode. TRUE or "full" verifies that extracted trees and the target tree match in topology and branch lengths. "topology" verifies matching topology/tip labels while allowing branch lengths to differ. FALSE or "none" skips the upfront ape::all.equal.phylo() check, but target branches still must be matchable by descendant-tip sets.
target	Character target-tree selection when target_tree = NULL in rateMap(). "first" uses the first retained input tree. "mcc" chooses the retained input tree with the highest sum of log clade credibilities.
tree_fun	Optional function used to extract a mapped tree from each element of fits. If NULL, common bifrost and mvgls shapes are auto-detected. For "bifrost_search" objects, the default uses tree_no_uncertainty_untransformed to preserve the original branch-length scale; supply tree_fun explicitly to map a different tree field.
param_fun	Optional function used to extract a named numeric vector of state-specific fitted rates from each element of fits. If NULL, common bifrost and mvgls shapes are auto-detected.
na_action	What to do when a run has invalid parameters. "error" stops immediately. "omit" drops invalid runs before aggregation.
rate_flags	A "rateMap_rate_flags" object from rateMapRateFlags(), or a named list of rate-flagging options. Use NULL to disable rate diagnostics.
quantile_probs	Numeric length-2 vector of quantile probabilities to report when uncertainty = TRUE.
highest_density_interval_prob	Numeric scalar giving the highest-density interval mass to report when uncertainty = TRUE.
future_strategy	Future backend used only when workers is supplied to rateMap(). Must be one of "multisession" or "multicore".
future_seed	Seed control passed to future.apply::future_lapply().
future_scheduling	Scheduling control passed to future.apply::future_lapply().
future_chunk_size	Chunk size passed to future.apply::future_lapply().

Value

A "rateMap_control" object for the control argument of rateMap().

Examples

ctrl <- rateMapControl(
  res = 200,
  check = "topology",
  na_action = "omit",
  rate_flags = rateMapRateFlags(zero_floor = 1e-8)
)
ctrl[c("res", "check", "na_action")]
ctrl$rate_flags[c("method", "zero_floor")]

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