Simulates discrete character evolution on a phylogenetic tree.
sim.history(tree, Q, anc=NULL, nsim=1,
direction=c("column_to_row","row_to_column"), ...)
sim.Mk(tree, Q, anc=NULL, nsim=1, ...)
sim.multiMk(tree, Q, anc=NULL, nsim=1, ...)sim.history returns an object of class "simmap" (a tree with a mapped discrete character) or "multiSimmap" for nsim greater than one.
sim.Mk and sim.multiMk return a factor with the states of our discrete character at the tips of the tree only.
a phylogenetic tree as an object of class "phylo". For the case of sim.multiMk tree should be an object of class "simmap" in which the regimes for simulation have been mapped onto the tree.
a matrix containing the instantaneous transition rates between states. Note that for sim.history by default (i.e., when direction="column_to_row", see below) 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). For sim.Mk and sim.multiMk this matrix has the same conformation as in fitContinuous and make.simmap. For sim.multiMk Q should be a list of transition matrices with names that correspond to the states mapped onto the tree.
an optional value for the state at the root node; if NULL, a random state will be assigned. anc can be a vector of states, in which one of the states will be chosen randomly for each simulation. For sim.history anc can be a vector of probabilities with names, in which case a state will be chosen in proportion to the given probabilities.
number of simulations.
row/column direction of the input transition matrix, Q. "column_to_row" indicates that the transition rate from i -> j should be given by Q[j,i], while "row_to_column" indicates the converse.
other optional arguments. Currently only internal, a logical value indicating whether or not to return internal node states (defaults to internal=FALSE; and message, a logical indicating whether or not to turn on informational messages (defaults to message=TRUE).
Liam Revell liam.revell@umb.edu
The function sim.history 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.
The function sim.Mk simulates the states for a discrete character at the tips of the tree only.
Finally, the function sim.multiMk is the same as sim.Mk except that it permits the user to simulate under different values of Q in different parts of the tree.
Revell, L. J. (2024) phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505.
fitMk, fitmultiMk, make.simmap, read.simmap, plotSimmap, sim.rates