rateMapView: Create a Display View of a 'rateMap' Object

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

Create a Display View of a rateMap Object

Description

Recompute the display mapping for a computed "rateMap" object without drawing it. This is optional in the usual rateMap() then plot() workflow; use it when you want to save or inspect category tables, color bins, or an uncertainty-valued map object and then reuse the same display mapping in one or more plots. The numeric branch or interval summaries computed by rateMap() are not recomputed.

Usage

rateMapView(
  x,
  value = "value",
  palette = NULL,
  reverse_palette = NULL,
  color_mode = NULL,
  n_categories = NULL,
  category_bin_method = NULL,
  category_breaks = NULL,
  category_labels = NULL,
  ncolors = NULL,
  legend_title = NULL
)

Arguments

x	An object of class "rateMap" returned by rateMap().
value	Name of the numeric column in x$intervals to map to colors. The default, "value", uses the central summary computed by rateMap().
palette	Optional palette override. This can be an hcl.colors() palette name, a vector of colors, or a palette function.
reverse_palette	Optional logical override for palette reversal.
color_mode	Optional color-mode override. Use "category" for discrete ordered bins or "continuous" for a continuous ramp.
n_categories	Optional target category count for color_mode = "category".
category_bin_method	Optional automatic category-binning method: "pretty" or "equal".
category_breaks	Optional strictly increasing category boundaries. Category legends draw valid numeric interval breaks with proportional segment widths.
category_labels	Optional labels for displayed categories.
ncolors	Optional number of colors for continuous ramps. If omitted, the stored x$ncolors value is used, falling back to 256 for older objects.
legend_title	Optional legend title stored on the returned object.

Value

A "rateMap" object with updated tree maps, color palette, intervals$value, rate_categories, and legend title. For branch-summary category views, rate_categories includes bin-level summaries of the plotted branch values and is recomputed whenever the view changes. For branch-summary maps with active rate diagnostics, diagnostic flags are recomputed for rate-valued views ("value", "mean", or "median") and preserved as metadata for non-rate views such as "sd". When preserved for a non-rate view, rate_flag_source identifies the rate-valued column that the flags classify; the flags do not classify the displayed uncertainty value. The selected value column must contain finite values for every plotted interval; uncertainty columns such as "sd" may be all NA for single-fit objects and are rejected with a clear error.

Examples

toy_tree <- ape::read.tree(text = "((a:1,b:1):1,c:2);")
toy_tree <- phytools::paintSubTree(
  toy_tree,
  node = ape::Ntip(toy_tree) + 1L,
  state = "0"
)
toy_tree <- phytools::paintSubTree(
  toy_tree,
  node = ape::Ntip(toy_tree) + 2L,
  state = "1"
)
toy_fit <- list(
  variables = list(tree = toy_tree),
  param = c("0" = 0.1, "1" = 0.5)
)
rm_obj <- rateMap(toy_fit, log = FALSE, progress = FALSE)
display_obj <- rateMapView(
  rm_obj,
  palette = "Viridis",
  n_categories = 3,
  legend_title = "Fitted rate"
)
display_obj[c("color_mode", "category_labels", "title")]

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