Control Advanced rateMap() Options

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

if (FALSE) { # \dontrun{
# Same-topology tree samples with differing branch lengths:
ctrl <- rateMapControl(check = "topology")
posterior_rates <- rateMap(
  posterior_fit_list,
  target_tree = summary_tree,
  uncertainty = TRUE,
  control = ctrl
)

# Interval maps with a finer depth grid:
interval_rates <- rateMap(
  fits,
  summary = "interval",
  control = rateMapControl(res = 200)
)
} # }