getRateThroughTimeMatrix: Generate rate-through-time matrix from `bammdata` object

Description

Computes a matrix of macroevolutionary rates at specified timepoints from a bammdata object. These rates can be used for plotting speciation rates (and other rates) through time.

Usage

getRateThroughTimeMatrix(
  ephy,
  start.time = NULL,
  end.time = NULL,
  nslices = 100,
  node = NULL,
  nodetype = "include"
)

Value

An object of class bamm-ratematrix with the following components:

lambda: A nsamples x nslices matrix of speciation rates, where nsamples is the number of posterior samples in the bammdata object.
mu: A nsamples x nslices matrix of extinction rates.
beta: A nsamples x nslices matrix of phenotypic rates (if applicable).
times: A vector of timepoints where rates were computed.
times: A vector of timepoints where rates were computed (see Examples).
type: Either "diversification" or "trait", depending on the input data.

Arguments

ephy: An object of class bammdata.
start.time: The start time (in units before present) for the time. sequence over which rates should be computed. If NULL, starts at the root.
end.time: The end time (in units before present) for the time sequence over which rates should be computed. If NULL, ends in the present.
nslices: The number of time points at which to compute rate estimates (between start.time and end.time).
node: Allows user to extract rate-through-time information for the subtree descended from a specific node. Alternatively, a specified subtree can be excluded from the rate matrix calculations.
nodetype: Two options: "include" and "exclude". If "include", computes rate matrix only for the descendants of subtree defined by node. If "exclude", computes rate matrix for all background lineages in tree after excluding the subtree defined by node. Ignored if node = NULL.

Author

Dan Rabosky

Details

Computes evolutionary rates for each sample in the posterior included as part of the bammdata object. Rates are computed by draping an imaginary grid over the phylogeny, where the grid begins at start.time and ends at end.time, with nslices vertical lines through the phylogeny. The mean rate at each point in time (for a given sample from the posterior) is simply the mean rate at that time for all branches that are intersected by the grid (see the grid plot in the examples section).

This function is used by plotRateThroughTime, but the user can work directly with the bamm-ratematrix object for greater control in plotting rate-through-time trajectories for individual clades. See examples for an example of how this can be used to plot confidence intervals on a rate trajectory using shaded polygons.