getEventData: Create `bammdata` object from MCMC output

Description

getEventData reads shift configuration data (the "event data" output) from a BAMM analysis and creates a bammdata object. The bammdata object is fundamental for extracting information about macroevolutionary rate variation through time and among lineages.

Usage

getEventData(phy, eventdata, burnin = 0, nsamples = NULL, 
	verbose = FALSE, type = "diversification")

Arguments

phy

an object of class phylo - specifically, the time calibrated tree that was analyzed with BAMM. Alternatively, a character string specifying the path to a newick-formatted tree.

eventdata

a character string specifying the path to a BAMM event-data file. Alternatively, an object of class data.frame that includes the event data from a BAMM run.

burnin

a numeric indicating the fraction of posterior samples to discard as burn-in.

nsamples

an integer indicating the number of posterior samples to include in the bammdata object. May be NULL.

verbose

a logical. If TRUE progess is outputted to the console. Defaults to FALSE.

type

a character string. Either "diversification" or "trait" depending on your BAMM analysis.

Value

A list with many components:
edgeSee documentation for class phylo in package ape.
NnodeSee documentation for class phylo in package ape.
tip.labelSee documentation for class phylo in package ape.
edge.lengthSee documentation for class phylo in package ape.
beginThe beginning time of each branch in absolute time (the root is set to time zero)
endThe ending time of each branch in absolute time.
numberEventsAn integer vector with the number of events contained in phy for each posterior sample. The length of this vector is equal to the number of posterior samples in the bammdata object.
eventDataA list of dataframes. Each element is a single posterior sample. Each row in a dataframe holds the data for a single event. Data associated with an event are: node - a node number. This identifies the branch where the event originates. time - this is the absolute time on that branch where the event originates (with the root at time 0). lam1 - an initial rate of speciation or trait evolution. lam2 - a decay/growth parameter. mu1 - an initial rate of extinction. mu2 - a decay/growth parameter. index - a unique integer associated with the event. See 'Details'.
eventVectorsA list of integer vectors. Each element is a single posterior sample. For each branch in phy the index of the event that occurs along that branch. Branches are ordered increasing here and elsewhere.
eventBranchSegsA list of matrices. Each element is a single posterior sample. Each matrix has four columns: Column 1 identifies a node in phy. Column 2 identifies the beginning time of the branch or segment of the branch that subtends the node in Column 1. Column 3 identifies the ending time of the branch or segment of the branch that subtends the node in Column 1. Column 4 identifies the index of the event that occurs along the branch or segment of the branch that subtends the node in Column 1.
tipStatesA list of integer vectors. Each element is a single posterior sample. For each tip the index of the event that occurs along the branch subtending the tip. Tips are ordered increasing here and elsewhere.
tipLambdaA list of numeric vectors. Each element is a single posterior sample. For each tip the rate of speciation or trait evolution at the end of the terminal branch subtending that tip.
tipMuA list of numeric vectors. Each element is a single posterior sample. For each tip the rate of extinction at the end of the terminal branch subtending that tip. Meaningless if working with BAMM trait results.
meanTipLambdaFor each tip the mean of the marginal posterior density of the rate of speciation or trait evolution at the end of the terminal branch subtending that tip.
meanTipMuFor each tip the mean of the marginal posterior density of the rate of extinction at the end of the terminal branch subtending that tip. Meaningless if working with BAMM trait results.
typeA character string. Either "diversification" or "trait" depending on your BAMM analysis.
downseqAn integer vector holding the nodes of phy. The order corresponds to the order in which nodes are visited by a pre-order tree traversal.
lastvisitAn integer vector giving the index of the last node visited by the node in the corresponding position in downseq. downseq and lastvisit can be used to quickly retrieve the descendants of any node. e.g. the descendants of node 89 can be found by downseq[which(downseq==89):which(downseq==lastvisit[89]).

Details

In the BAMM framework, an "event" defines a macroevolutionary process of diversification or trait evolution. Every sample from the posterior includes at least one process, defined by such an "event". If a given sample includes just a single event, then the dynamics of diversification or trait evolution can be described entirely by a single time-constant or time-varying process that begins at the root of the tree. Any sample from the posterior distribution may include a complex mixture of distinct processes. To represent temporal heterogeneity in macroevolutionary rates, BAMM models a rate $R$, e.g. speciation, as a function that changes exponentially with time: $R(t) = R(0)*exp(b*t)$. Here $R(0)$ is the initial rate and $b$ is a parameter determining how quickly that rate grows or decays with time.

The eventdata file (or data frame) is a record of events and associated parameters that were sampled with BAMM during simulation of the posterior with reversible jump MCMC. This complex, information-rich file is processed into a bammdata object, which serves as the core data object for numerous downstream analyses. From a bammdata object, you can summarize rate variation through time, among clades, extract locations of rate shifts, summarize clade-specific rates of speciation and extinction, and more.

In general, the user does not need to be concerned with the details of a bammdata object. The object is used as input by a number of BAMMtools functions. The parameter nsamples can be used to reduce the total amount of data included in the raw eventdata output from a BAMM run. The final bammdata object will consist of all data for nsamples from the posterior. These nsamples are equally spaced after discarding some burnin fraction as "burn-in". If nsamples is set to NULL, the bammdata object will include all samples in the posterior after discarding the burnin fraction.

References

bamm-project.org

Rabosky, D. L. 2014. Automatic detection of key innovations, rate shifts, and diversity-dependence on phylogenetic trees. PLoS ONE 9:e89543

Rabosky, D. L., F. Santini, J. T. Eastman, S. A. Smith, B. L. Sidlauskas, J. Chang, and M. E. Alfaro. 2013. Rates of speciation and morphological evolution are correlated across the largest vertebrate radiation. Nature Communications DOI: 10.1038/ncomms2958

Examples

Run this code

data(primates, events.primates)
xx <- getEventData(primates, events.primates, burnin=0.25, nsamples=500, type = 'trait')

# compute mean phenotypic rate for primate body size evolution:
brates <- getCladeRates(xx)
mean(brates$beta)

# Plot rates:
plot.bammdata(xx)

Run the code above in your browser using DataLab