R: Evolve Birth-Death Trees

simulate {diversitree}

R Documentation

Evolve Birth-Death Trees

Description

Evolves one or more trees under the BiSSE (Binary State Speciation and Extinction), MuSSE (Multi-State Speciation and Extinction), BiSSE-ness (BiSSE-node enhanced state shift), ClaSSE (Cladogenetic State change Speciation and Extinction), or GeoSSE (Geographic State Speciation and Extinction) model, or a simple character independent birth-death model. For the SSE models, it simultaneously evolves a character that affects speciation and/or extinction, and the tree itself.

Usage

trees(pars, type=c("bisse", "bisseness", "bd", "classe", "geosse",
      "musse", "quasse", "yule"), n=1, max.taxa=Inf, max.t=Inf,
      include.extinct=FALSE, ...)

tree.bisse(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE,
           x0=NA)
tree.musse(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE,
           x0=NA)
tree.musse.multitrait(pars, n.trait, depth, max.taxa=Inf, max.t=Inf,
                      include.extinct=FALSE, x0=NA)

tree.quasse(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE, x0=NA,
            single.lineage=TRUE, verbose=FALSE)

tree.bisseness(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE,
               x0=NA)

tree.classe(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE,
           x0=NA)

tree.geosse(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE,
           x0=NA)

tree.bd(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE)
tree.yule(pars, max.taxa=Inf, max.t=Inf, include.extinct=FALSE)

prune(phy, to.drop=NULL)

Arguments

`pars`	Vector of parameters. The parameters must be in the same order as an unconstrained likelihood function returned by `make.x`, for tree type x. The MuSSE simulator automatically detects the appropriate number of states, given a parameter vector.
`type`	Type of tree to generate: May be "bisse" or "bd".
`n`	How many trees to generate?
`max.taxa`	Maximum number of taxa to include in the tree. If `Inf`, then the tree will be evolved until `max.t` time has passed.
`max.t`	Maximum length to evolve the phylogeny over. If `Inf` (the default), then the tree will evolve until `max.taxa` extant taxa are present.
`include.extinct`	Logical: should extinct taxa be included in the final phylogeny? And should extinct trees be returned by `trees`?
`x0`	Initial character state at the root (state 0 or 1). A value of `NA` will randomly choose a state from the model's equilibrium distribution for a BiSSE, ClaSSE, or GeoSSE model, but a non-NA value must be specified for MuSSE and QuaSSE.
`n.trait, depth`	For `tree.musse.multitrait` only, these specify the number of binary traits and the style of parameters (with the same meaning as in `make.musse.multitrait`). The `pars` argument then needs to be in the same order as a likelihood function created by `make.musse.multitrait` with these arguments (this interface may be improved in future – email me if you find this annoying).
`single.lineage`	(`tree.quasse` only): Start simulation with a single lineage? If `FALSE`, then the simulation starts with two lineages in state `x0` (i.e., immediately following a speciation event).
`verbose`	(`tree.quasse` only): print verbose details about tree simuations. This can be reassuring for really large trees.
`...`	Additional arguments
`phy`	A phylogeny, possibly with extinct species, produced by one of the tree evolving functions.
`to.drop`	Optional vector with the species names to drop.

Details

The phylogeny will begin from a single lineage in state x0, but the final phylogeny will include only branches above the first split.

tree.bisse may return an extinct phylogeny, and trees might return extinct phylogenies if include.extinct is TRUE.

Value

A phylo phylogenetic tree (ape format), or for bisse.trees, a list of phylo trees.

The trees will have an element tip.state that contains the binary state information.

Note

There are some logic problems around the creation of zero and one species trees; this will cause occasional errors when running the above functions. Things will change to fix this soon. All these functions may change in the near future.

Author(s)

Richard G. FitzJohn

Examples

pars <- c(0.1, 0.2, 0.03, 0.03, 0.01, 0.01)
set.seed(3)
phy <- tree.bisse(pars, max.taxa = 30, x0 = 0)
phy$tip.state

##  sp7  sp8 sp10 sp11 sp12 sp13 sp14 sp16 sp17 sp18 sp19 sp20 sp21 sp22 sp24 
##    0    0    0    0    1    1    0    1    1    1    1    1    0    0    1 
## sp25 sp26 sp27 sp28 sp29 sp30 sp31 sp32 sp33 sp34 sp35 sp36 sp37 sp38 sp39 
##    1    1    1    1    1    1    1    1    1    1    1    1    1    1    1


h <- history.from.sim.discrete(phy, 0:1)
plot(h, phy)

plot of chunk unnamed-chunk-1

Retain extinct species:

set.seed(3)
phy2 <- tree.bisse(pars, max.taxa = 30, x0 = 0, include.extinct = TRUE)
h2 <- history.from.sim.discrete(phy2, 0:1)
plot(h2, phy2)

plot of chunk unnamed-chunk-2

Two states

pars <- c(0.1, 0.2, 0.03, 0.04, 0.05, 0.1)
set.seed(2)
phy <- tree.musse(pars, 20, x0 = 1)

h <- history.from.sim.discrete(phy, 1:2)
plot(h, phy)

plot of chunk unnamed-chunk-3

A 3-state example where movement is only allowed between neighbouring states (1 <-> 2 <-> 3), and where speciation and extinction rates increase moving from 1 -> 2 -> 3:

pars <- c(.1,  .15,  .2,  # lambda 1, 2, 3
          .03, .045, .06, # mu 1, 2, 3
          .05, 0,         # q12, q13
          .05, .05,       # q21, q23
          0,   .05)       # q31, q32

set.seed(2)
phy <- tree.musse(pars, 30, x0=1, include.extinct=TRUE)

h <- history.from.sim.discrete(phy, 1:3)
plot(h, phy, cex=.7)

plot of chunk unnamed-chunk-4

And with extinct taxa pruned:

phy2 <- prune(phy)
h2 <- history.from.sim.discrete(phy2, 1:3)
plot(h2, phy2, cex = 0.7)

plot of chunk unnamed-chunk-5

This can all be done in one step (and is by default):

set.seed(2)
phy <- tree.musse(pars, 30, x0 = 1)
h <- history.from.sim.discrete(phy, 1:3)
plot(h, phy, cex = 0.7)

plot of chunk unnamed-chunk-6

[Package diversitree version 0.9-4 ]