R: Simulate pure-birth or birth-death stochastic tree or trees

pbtree {phytools}

R Documentation

Simulate pure-birth or birth-death stochastic tree or trees

Description

This function simulates stochastic birth-death trees. Simulation can be performed conditioning on n, on t, or on both simultaneously. If the both, then (for optional argument method="rejection") rejection sampling is performed whereby trees are simulated given b and t until a tree containing n taxa is found. The giving-up point can be set using the optional argument max.count. Simulations can also be performed in continuous time (the default) or discrete time; the difference being that wait times in the continous-time simulation come from the exponential distribution; whereas waiting times in discrete-time simulations come from the geometric distribution. In addition, discrete-time simulations allow for the possibility that multiple speciation events can occur at (exactly) the same time, so long as they are on separate branches. Finally, sometimes for stopping criterion n in discrete-time there will be a number of tips different from n. This indicates that the last event contained more than one speciation event, and a warning is printed.

method="direct" is presently experimental. It does not really perform direct sampling; however waiting times & birth or death events are sampled first - with only wait-times consistent with n and t being retained. This rejection sampling occurs one layer earlier than for method="rejection". This results in a significant (several-fold) speed-up of the code and enables sampling conditioned on n and t simultaneously for much higher b and d. At the present time, extant.only=TRUE does not work for this mode, nor does type="discrete".

Note that if ape=FALSE, then the function will run faster, and the tree is theoretically compatible with the ape "phylo" standard; however some downstream errors with functions such as bind.tree have been observed.

Usage

pbtree(b=1, d=0, n=NULL, t=NULL, scale=NULL, nsim=1,
	type=c("continuous","discrete"), ...)

Arguments

`b`	birth rate or speciation rate for `type="continuous"`; the probability of speciating per time-step for `type="discrete"`.
`d`	death rate or extinction rate for `type="continuous"`; the probability of going extinct per time-step for `type="discrete"`.
`n`	desired number of species (i.e., taxa-stop criterion).
`t`	total time for simulation (i.e., time-stop criterion).
`scale`	if set, rescales tree to have total length `scale`.
`nsim`	number of simulated trees to return.
`type`	string to indicate whether to simulate trees in continuous or discrete time. If the former, then wait times between speciation events are drawn from an exponential distribution; whereas if the latter then wait times comes from a geometric distribution.
`...`	optional arguments including `ape`, a logical value indicating whether to return nodes in a 'ape' compatible ordering (default is `TRUE`); `extant.only` a logical value indicating whether or not to return only extant species (defaults to `FALSE`); `max.count` a numeric value indicating the maximum number of iterations to run is sampling conditioned on both `n` and `t` (defaults to `1e5`); `method` gives the method used for simultaneously conditioning on `n` and `t` - options are `"rejection"` and `"direct"`; `tip.label`, a vector of tip labels (only works for `n!=NULL`); and, finally, `quiet`, a logical value indicating whether or not to suppress certain message (defaults to `FALSE`).

Value

A tree or list of trees as an object of class "phylo" or "multiPhylo", respectively.

Author(s)

Liam Revell liam.revell@umb.edu

References

Revell, L. J. (2012) phytools: An R package for phylogenetic comparative biology (and other things). Methods Ecol. Evol., 3, 217-223.

Examples

# simulate a pure-birth tree with 1000 tips, scaled to a length of 1.0
tree<-pbtree(n=1000,scale=1)
# simulate a pure-birth tree conditioning on n & t
tt<-log(50)-log(2)
tree<-pbtree(n=50,t=tt)

[Package phytools version 0.4-60 Index]