make.simmap: Simulate stochastic character maps on a phylogenetic tree or trees

Description

This function fits a continuous-time reversible Markov model for the evolution of x and then simulates stochastic character histories using that model and the tip states on the tree. This is the same procedure that is described in Bollback (2006), except that simulation is performed using a fixed value of Q instead of by sampling Q from a user-specified prior distribution.

Usage

make.simmap(tree, x, model="SYM", nsim=1, ...)

Arguments

tree

a phylogenetic tree as an object of class "phylo", or a list of trees as an object of class "multiPhylo".

a vector containing the tip states for a discretely valued character, or a matrix containing the prior probabilities of tip states in rows.

model

a character string containing the model - options as in ace.

nsim

number of simulations. If tree is an object of class "multiPhylo", then nsim simulations will be conducted per tree.

...

optional arguments. So far, pi gives the state frequencies - options are "equal", "estimated", or a vector with the frequencies. If pi="estimated" then the stationary distribution is estimated by numeric

Value

A modified phylogenetic tree of class "phylo" (or a modified "multiPhylo" object, for nsim > 1) with the following additional elements:
mapsa list of named vectors containing the times spent in each state on each branch, in the order in which they occur.
mapped.edgea matrix containing the total time spent in each state along each edge of the tree.

Details

Samples trees from the conditional posterior distribution - conditioning on the maximum likelihood transition matrix given our model. Uses code modified from ace by Paradis et al. As of phytools>=0.2-33 x can be a vector of states or a matrix containing the prior probabilities of tip states in rows. In this case the column names of x should contain the states, and the row names should contain the tip names. Note that there was a small (but potentially significant) bug in how node states were simulated by make.simmap in versions of phytools<=0.2-26. between="" phytools="" 0.2-26="" and="" 0.2-36="" there="" was="" also="" a="" bug="" for="" asymmetric="" models="" of="" character="" change="" (e.g.,="" model="ARD"). Finally, between phytools 0.2-33 and phytools 0.2-47 there was an error in use of the conditional likelihoods for the root node, which caused the root node of the tree to be sampled incorrectly. All of these issues should be fixed in the present version.

References

Paradis, E., J. Claude, and K. Strimmer. 2004. APE: Analyses of phylogenetics and evolution in R language. Bioinformatics, 20, 289--290. Huelsenbeck, J. P., R. Neilsen, and J. P. Bollback. 2003. Stochastic mapping of morphological characters. Systematic Biology, 52, 131-138. Bollback, J. P. 2006. Stochastic character mapping of discrete traits on phylogenies. BMC Bioinformatics, 7, 88.