Plot rateMap Objects — plot.rateMap • bifrost

Render a computed "rateMap" object. The usual workflow is x <- rateMap(...) followed by plot(x, ...).

Usage

# S3 method for class 'rateMap'
plot(
  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,
  legend = NULL,
  fsize = NULL,
  tip_fsize = NULL,
  legend_fsize = NULL,
  ftype = NULL,
  show_tip_labels = TRUE,
  outline = FALSE,
  lwd = 3,
  type = c("phylogram", "fan", "arc"),
  mar = rep(0.3, 4),
  direction = "rightwards",
  offset = NULL,
  xlim = NULL,
  ylim = NULL,
  hold = TRUE,
  underscore = FALSE,
  arc_height = 2,
  legend_digits = NULL,
  ...
)

Arguments

x: An object of class "rateMap" returned by rateMap() or rateMapView().
value: Character column in the plotted summary table (x$intervals) to map to branch colors. The default "value" plots the central estimate chosen by rateMap(). When uncertainty = TRUE, useful alternatives include "mean", "median", "sd", "ci_width", "highest_density_interval_width", and "cv".
palette: Optional palette override used for this plot. This can be an hcl.colors() palette name, a vector of colors, or a palette function.
reverse_palette: Optional logical override for palette reversal used for this plot.
color_mode: Optional color-mode override. Use "continuous" for a numeric color ramp or "category" for ordered discrete rate categories. If NULL, the stored mode in x is used. Category mode draws one color per exact value or category bin; continuous mode draws a many-color ramp.
n_categories: Optional category-count override for color_mode = "category". This changes the target number of category bins, not the number of colors in continuous mode.
category_bin_method: Optional category-binning override for color_mode = "category". Use "pretty" for pretty breaks or "equal" for equal-width numeric intervals. Ignored when category_breaks is supplied.
category_breaks: Optional category-break override for color_mode = "category". Custom breaks override automatic bins.
category_labels: Optional category-label override for color_mode = "category".
ncolors: Optional number of colors to use when recoloring this plot with color_mode = "continuous". If omitted, the stored x$ncolors value is used, falling back to 256 for older objects.
legend_title: Optional legend title override for this plot.
legend: Legend length. If NULL or TRUE, a layout-specific default is used. Set legend = FALSE to suppress the legend. Continuous legends are drawn with phytools::add.color.bar(); category legends are drawn by rateMap so bin labels can reflect rate categories and diagnostics.
fsize: Numeric font-size vector. The first element is passed as the tip label fsize to phytools::plotSimmap() and, when outline = TRUE, to phytools::plotTree(). The second element is used by the legend.
tip_fsize: Optional override for the first fsize element passed to the underlying tree plot.
legend_fsize: Optional override for the legend font size.
ftype: Font type. The first element is passed as ftype to phytools::plotSimmap() and, when outline = TRUE, to phytools::plotTree(). The second element is reserved for legends.
show_tip_labels: Logical; if FALSE, rateMap sets the tree-plot ftype to "off" before calling the underlying phytools plotter.
outline: Logical; if TRUE, draw a branch outline beneath the rate map. The outline pass is drawn with phytools::plotTree() before the colored phytools::plotSimmap() pass.
lwd: Branch and legend line widths. The first element is passed to phytools::plotSimmap() and, with + 2, to phytools::plotTree() for outlines. The second element is used for the legend.
type: Plot type: "phylogram", "fan", or "arc". This is passed to phytools::plotSimmap() for fan and arc layouts and to phytools::plotTree() for outline passes.
mar: Plot margins passed to phytools::plotSimmap() and, when outline = TRUE, to phytools::plotTree().
direction: Plotting direction for type = "phylogram"; passed to phytools::plotSimmap() and phytools::plotTree().
offset: Tip-label offset passed to phytools::plotSimmap() and, when outline = TRUE, to phytools::plotTree().
xlim, ylim: Optional plot limits passed to phytools::plotSimmap() and, when outline = TRUE, to phytools::plotTree().
hold: Logical controlling rateMap's device hold/flush guard. rateMap passes hold = FALSE to the internal phytools calls so the two-pass outline/color drawing is controlled in one place.
underscore: Logical; if FALSE, underscores in tip labels may be shown as spaces by the underlying phytools::plotSimmap() and phytools::plotTree() calls.
arc_height: Arc height passed through to phytools::plotSimmap() and, for outlines, phytools::plotTree() when type = "arc".
legend_digits: Optional number of digits for legend endpoint labels. If omitted, small-magnitude values use enough digits to avoid zero-valued legend endpoints.
...: Additional arguments are rejected. Include all display choices as named plot() arguments.

Value

Invisibly returns the plotted "rateMap" object.

Details

The plot method uses phytools::plotSimmap() and draws either a continuous color-bar legend or a segmented rate-category color bar. The plotting controls intentionally mirror the phytools density-map plotting style for phylogram, fan, and arc layouts. In branch-summary category mode, near-zero or high-outlier rate diagnostics are drawn as special categories when rate-valued columns are plotted; these special categories do not consume positions in the ordered palette used for regular rate bins. When special categories are present, the category legend spans the full plotted value range and marks the diagnostic cutoff separating special and regular bins. When plotting non-rate columns such as "sd", diagnostic columns are preserved only as metadata with rate_flag_source provenance; special rate categories are not drawn for those non-rate values. 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.

The plot() method handles "phylogram", "fan", and "arc" layouts. legend controls the length of the color bar; set legend = FALSE to suppress it. legend_digits controls numeric endpoint labels and defaults to enough precision to avoid rounding small values to zero. Single fitted objects should be converted explicitly with rateMap() before plotting, for example plot(rateMap(search_a), ...).

Relationship to phytools plotting arguments. plot.rateMap() keeps the tree-layout argument names close to phytools: type, fsize, ftype, lwd, mar, direction, offset, xlim, ylim, underscore, and arc_height are forwarded to phytools::plotSimmap() or phytools::plotTree() as described above. rateMap fixes phytools::plotSimmap() options such as colors, pts, node.numbers, add, and hold internally, because those are determined by the computed "rateMap" object and by the optional outline pass. palette, color_mode, n_categories, category_breaks, category_labels, legend_title, legend_digits, and the rate-flag display behavior are rateMap controls, not phytools arguments.

References

Revell, L. J. (2013). Two new graphical methods for mapping trait evolution on phylogenies. Methods in Ecology and Evolution, 4, 754-759.

Revell, L. J. (2024). phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505. doi:10.7717/peerj.16505

Examples

if (FALSE) { # \dontrun{
rm_obj <- rateMap(fits, progress = FALSE)
plot(
  rm_obj,
  type = "arc",
  show_tip_labels = FALSE,
  legend_fsize = 0.8
)

# If rm_obj was built with uncertainty = TRUE, plot uncertainty directly:
plot(rm_obj, value = "sd", palette = "Inferno")

# Use a continuous ramp instead of the default ordered rate categories:
plot(rm_obj, color_mode = "continuous")

# Or keep category colors but change the binning:
plot(rm_obj, n_categories = 5, category_bin_method = "equal")
plot(rm_obj, category_breaks = c(-4, -2, 0, 2))
} # }

Plot `rateMap` Objects