sim.history: Simulate character history or a discrete character at the...

In phytools: Phylogenetic Tools for Comparative Biology (and Other Things)

Simulate character history or a discrete character at the tips of the tree under some model

Description

Simulates discrete character evolution on a phylogenetic tree.

Usage

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, ...)

Arguments

tree	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.
Q	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.
anc	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.
nsim	number of simulations.
direction	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).

Details

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.

Value

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.

Author(s)

Liam Revell [e-mail]

References

Revell, L. J. (2024) phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505.

See Also

fitMk, fitmultiMk, make.simmap, read.simmap, plotSimmap, sim.rates

phytools documentation built on Nov. 5, 2025, 5:11 p.m.