R: Evaluate evidence for temporal rate variation across tree
testTimeVariableBranches
R Documentation
Evaluate evidence for temporal rate variation across tree
Description
For each branch in a phylogenetic tree, evaluates the
evidence (posterior probability or Bayes factor) that
macroevolutionary rates have varied through time.
The prior probability that rate shifts lead to a new
time-varying rate process (versus a time-constant process).
return.type
Either "posterior" or "bayesfactor",
depending on which form of evidence you would like.
Details
In BAMM 2.0, rate shifts on trees can lead to time-varying
or constant-rate diversification processes. In other words, the model
will incorporate temporal variation in rates only if there is
sufficient evidence in the data to favor it. The function
testTimeVariableBranches enables the user to extract the
evidence in favor of time-varying rates on any branch of a
phylogenetic tree from a bammdata object.
The function returns a copy of the original phylogenetic tree, but
where branch lengths have been replaced by either the posterior
probability (return.type = "posterior") or the Bayes factor
evidence (return.type = "bayesfactor") that the
macroevolutionary rate regime governing each branch is time-variable.
Consider a particular branch X on a phylogenetic tree. If the length
of this branch is 0.97 and return.type = "posterior", this
implies that branch X was governed by a time-varying rate dynamic in
97% of all samples in the posterior. Alternatively, only 3% of
samples specified a constant rate dynamic on this branch.
The function also provides an alternative measure of support if
return.type = "bayesfactor". In this case, the Bayes factor
evidence for temporal rate variation is computed for each branch. We
simply imagine that diversification rates on each branch can be
explained by one of two models: either rates vary through time, or
they do not. In the above example (branch X), the Bayes factor would
be computed as follows, letting Prob_timevar and
Prior_timevar be the posterior and prior probabilities that a
particular branch is governed by a time-varying rate process:
The Bayes factor is not particularly useful under uniform prior odds
(e.g., prior_tv = 0.5), since this simply reduces to the ratio
of posterior probabilities. Note that the prior must correspond to
whatever you used to analyze your data in BAMM. By default,
time-variable and time-constant processes are assumed to have equal
prior odds.
This function can be used several ways, but this function allows the
user to quickly evaluate which portions of a phylogenetic tree have
"significant" evidence for rate variation through time (see Examples
below).
Value
An object of class phylo, but where branch lengths are
replaced with the desired evidence (posterior probability or Bayes
factor) that each branch is governed by a time-varying rate dynamic.
# Load whale data:
data(whales, events.whales)
ed <- getEventData(whales, events.whales, burnin=0.1, nsamples=200)
# compute the posterior probability of
# time-varying rates on each branch
tree.pp <- testTimeVariableBranches(ed)
# Plot tree, but color all branches where the posterior
# probability of time-varying rates exceeds 95%:
colvec <- rep("black", nrow(whales$edge))
colvec[tree.pp$edge.length >= 0.95] <- 'red'
plot.phylo(whales, edge.color=colvec, cex=0.5)
# now, compute Bayes factors for each branch:
tree.bf <- testTimeVariableBranches(ed, return.type = "bayesfactor")
# now, assume that our prior was heavily stacked in favor
# of a time-constant process:
tree.bf2 <- testTimeVariableBranches(ed, prior_tv = 0.1,
return.type = "bayesfactor")
# Plotting the branch-specific Bayes factors against each other:
plot.new()
par(mar=c(5,5,1,1))
plot.window(xlim=c(0, 260), ylim=c(0, 260))
points(tree.bf2$edge.length, tree.bf$edge.length, pch=21, bg='red',
cex=1.5)
axis(1)
axis(2, las=1)
mtext(side=1, text="Bayes factor: prior_tv = 0.1", line=3, cex=1.5)
mtext(side = 2, text = "Bayes factor: uniform prior odds", line=3,
cex=1.5)
# and you can see that if your prior favors CONSTANT RATE dynamics
# you will obtain much stronger Bayes factor support for time varying
# rates.
# IF the evidence is present in your data to support time variation.
# To be clear, the Bayes factors in this example were computed from the
# same posterior probabilities: it is only the prior odds that differed.
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/testTimeVariableBranches.Rd_%03d_medium.png", width=480, height=480)
> ### Name: testTimeVariableBranches
> ### Title: Evaluate evidence for temporal rate variation across tree
> ### Aliases: testTimeVariableBranches
>
> ### ** Examples
>
> # Load whale data:
> data(whales, events.whales)
> ed <- getEventData(whales, events.whales, burnin=0.1, nsamples=200)
Processing event data from data.frame
Discarded as burnin: GENERATIONS < 995000
Analyzing 200 samples from posterior
Setting recursive sequence on tree...
Done with recursive sequence
>
> # compute the posterior probability of
> # time-varying rates on each branch
> tree.pp <- testTimeVariableBranches(ed)
>
> # Plot tree, but color all branches where the posterior
> # probability of time-varying rates exceeds 95%:
>
> colvec <- rep("black", nrow(whales$edge))
> colvec[tree.pp$edge.length >= 0.95] <- 'red'
>
> plot.phylo(whales, edge.color=colvec, cex=0.5)
>
> # now, compute Bayes factors for each branch:
>
> tree.bf <- testTimeVariableBranches(ed, return.type = "bayesfactor")
>
> # now, assume that our prior was heavily stacked in favor
> # of a time-constant process:
> tree.bf2 <- testTimeVariableBranches(ed, prior_tv = 0.1,
+ return.type = "bayesfactor")
>
> # Plotting the branch-specific Bayes factors against each other:
>
> plot.new()
> par(mar=c(5,5,1,1))
> plot.window(xlim=c(0, 260), ylim=c(0, 260))
> points(tree.bf2$edge.length, tree.bf$edge.length, pch=21, bg='red',
+ cex=1.5)
> axis(1)
> axis(2, las=1)
> mtext(side=1, text="Bayes factor: prior_tv = 0.1", line=3, cex=1.5)
> mtext(side = 2, text = "Bayes factor: uniform prior odds", line=3,
+ cex=1.5)
>
> # and you can see that if your prior favors CONSTANT RATE dynamics
> # you will obtain much stronger Bayes factor support for time varying
> # rates.
> # IF the evidence is present in your data to support time variation.
> # To be clear, the Bayes factors in this example were computed from the
> # same posterior probabilities: it is only the prior odds that differed.
>
>
>
>
>
> dev.off()
null device
1
>