addBAMMshifts: Add `BAMM`-inferred rate shifts to a phylogeny plot

Description

Adds symbols to a plotted tree to mark the location(s) where there is a shift in the macroevolutionary dynamics of diversification or trait evolution.

Usage

addBAMMshifts(
  ephy,
  index = 1,
  method = "phylogram",
  cex = 1,
  pch = 21,
  col = 1,
  bg = 2,
  msp = NULL,
  shiftnodes = NULL,
  par.reset = TRUE,
  ...
)

Arguments

ephy: An object of class bammdata.
index: An integer indicating which posterior sample to use for adding shifts to the plotted tree.
method: A character string indicating the method used in plotting. Must be "polar" or "phylogram".
cex: A numeric indicating the character expansion ("size") of the plotted points.
pch: An integer indicating the choice of plotting symbol.
col: An integer or character string indicating the border color of the plotting symbol.
bg: An integer or character string indicating the background color of the plotting symbol.
msp: If not NULL, an object of class phylo where each branch length is equal to the marginal probability of a shift occurring on that branch. Plotted points corresponding to shifts will be sized by these probabilities.
shiftnodes: An optional vector of node numbers indicating the locations of shifts to plot.
par.reset: A logical indicating whether to reset the graphical parameters before exiting.
...: additional arguments to be passed to points.

Author

Mike Grundler

Details

Any given sample from the posterior distribution sampled using BAMM contains a potentially unique configuration of rate shifts and associated parameters. There is no single "best" rate shift, but rather a set of shift configurations (and associated parameters) - along with their relative probabilities - sampled with MCMC. This function enables the user to plot the locations of shifts sampled with BAMM for a given sample from the posterior.

If the bammdata object contains just a single sample, these shifts will be plotted regardless of the value of index.

Examples

Run this code

data(whales, events.whales)
ed <- getEventData(whales, events.whales, burnin=0.25, nsamples = 500)

# adding shifts to tree for specific posterior samples
plot(ed, method="polar")
addBAMMshifts(ed, index=5, "polar")

# multi-panel plotting and adding shifts
par(mfrow=c(2,3),mar=c(5,1,1,1))
samples = sample(1:length(ed$eventData), 6)
for (i in 1:6) {
  sed <- subsetEventData(ed, samples[i])
  plot(sed, par.reset=FALSE)
  addBAMMshifts(sed,index=1,method="phylogram",par.reset=FALSE)	
}