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

sim.history {phytools}

R Documentation

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 liam.revell@umb.edu

References

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