getEventData: Create 'bammdata' object from MCMC output

Description Usage Arguments Details Value Note Author(s) References See Also Examples

View source: R/getEventData.R

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

1
2
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.

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.

Value

A list with many components:

Note

Currently the function does not check for duplicate tip labels in phy, which may cause the function to choke.

Author(s)

Dan Rabosky, Mike Grundler

References

http://bamm-project.org/

See Also

summary.bammdata, plot.bammdata, dtRates.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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(xx)

BAMMtools documentation built on May 29, 2017, 5:47 p.m.