R: Simulate stochastic character history under some model

sim.history {phytools}

R Documentation

Simulate stochastic character history under some model

Description

This function simulates a stochastic character history for a discretely valued character trait on the tree. The resultant tree is stored as a modified "phylo" object in stochastic character map (e.g., make.simmap) format.

Usage

sim.history(tree, Q, anc=NULL, nsim=1, ...)

Arguments

`tree`	a phylogenetic tree as an object of class `"phylo"`.
`Q`	a matrix containing the instantaneous transition rates between states. Note that normally this is the transpose of the matrix produced by `fitDiscrete` in the geiger package or `make.simmap` in phytools; that is to say the transition rate from `i -> j` should be given by `Q[j,i]`. However, if your matrix is properly conformed (i.e., rows or columns sum to 0), then `sim.history` will attempt to transpose your matrix correctly & will return an informative message (if `message=TRUE`, see below).
`anc`	an optional value for the state at the root node; if `NULL`, a random state will be assigned.
`nsim`	number of simulations.
`...`	other optional arguments. Currently only `message`, a logical value indicating whether or not to turn on informational messages (defaults to `message=TRUE`).

Value

A modified phylogenetic tree of class "phylo" (or a modified "multiPhylo" object, for nsim > 1) with the following additional elements:

`maps`	a list of named vectors containing the times spent in each state on each branch, in the order in which they occur.
`mapped.edge`	a matrix containing the total time spent in each state along each edge of the tree.
`states`	a vector containing the tip states.
`node.states`	a matrix containing the states at internal & terminal nodes (according to the dimensions of `edge`).

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.