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.
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:
edge See documentation for class phylo in package ape.
Nnode See documentation for class phylo in package
ape.
tip.label See documentation for class phylo in package
ape.
edge.length See documentation for class phylo in
package ape.
begin The beginning time of each branch in absolute time (the
root is set to time zero)
end The ending time of each branch in absolute time.
numberEvents An 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.
eventData A 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'.
eventVectors A 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.
eventBranchSegs A 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.
tipStates A 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.
tipLambda A 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.
tipMu A 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.
meanTipLambda For 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.
meanTipMu For 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.
type A character string. Either "diversification" or "trait"
depending on your BAMM analysis.
downseq An integer vector holding the nodes of phy. The
order corresponds to the order in which nodes are visited by a
pre-order tree traversal.
lastvisit An 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]).
Note
Currently the function does not check for duplicate tip labels in
phy, which may cause the function to choke.
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)
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(BAMMtools)
Loading required package: ape
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/BAMMtools/getEventData.Rd_%03d_medium.png", width=480, height=480)
> ### Name: getEventData
> ### Title: Create 'bammdata' object from MCMC output
> ### Aliases: getEventData
> ### Keywords: models
>
> ### ** Examples
>
> data(primates, events.primates)
> xx <- getEventData(primates, events.primates, burnin=0.25, nsamples=500,
+ type = 'trait')
Processing event data from data.frame
Discarded as burnin: GENERATIONS < 4990000
Analyzing 500 samples from posterior
Setting recursive sequence on tree...
Done with recursive sequence
>
> # compute mean phenotypic rate for primate body size evolution:
> brates <- getCladeRates(xx)
> mean(brates$beta)
[1] 0.03754413
>
> # Plot rates:
> plot(xx)
>
>
>
>
>
> dev.off()
null device
1
>