man/rTraitDisc.Rd

   1 \name{rTraitDisc}
   2 \alias{rTraitDisc}
   3 \title{Discrete Character Simulation}
   4 \usage{
   5 rTraitDisc(phy, model = "ER", k = if (is.matrix(model)) ncol(model) else 2,
   6            rate = 0.1, states = LETTERS[1:k], freq = rep(1/k, k),
   7            ancestor = FALSE, root.value = 1)
   8 }
   9 \arguments{
  10   \item{phy}{an object of class \code{"phylo"}.}
  11   \item{model}{a character, a square numeric matrix, or a function
  12     specifying the model (see details).}
  13   \item{k}{the number of states of the character.}
  14   \item{rate}{the rate of change used if \code{model} is a character; it
  15     is \emph{not} recycled if \code{model = "ARD"} of \code{model =
  16       "SYM"}.}
  17   \item{states}{the labels used for the states; by default ``A'', ``B'',
  18     \dots}
  19   \item{freq}{a numeric vector giving the equilibrium relative
  20     frequencies of each state; by default the frequencies are equal.}
  21   \item{ancestor}{a logical value specifying whether to return the
  22     values at the nodes as well (by default, only the values at the tips
  23     are returned).}
  24   \item{root.value}{an integer giving the value at the root (by default,
  25     it's the first state). To have a random value, use \code{root.value
  26       = sample(k)}.}
  27   \item{\dots}{further arguments passed to \code{model} if it is a
  28     function.}
  29 }
  30 \description{
  31   This function simulates the evolution of a discrete character along a
  32   phylogeny. If \code{model} is a character or a matrix, evolution is
  33   simulated with a Markovian model; the transition probabilities are
  34   calculated for each branch with \eqn{P = e^{Qt}} where \eqn{Q} is the
  35   rate matrix given by \code{model} and \eqn{t} is the branch length.
  36   The calculation is done recursively from the root. See Paradis (2006,
  37   p. 101) for a general introduction applied to evolution.
  38 }
  39 \details{
  40   There are three possibilities to specify \code{model}:
  41
  42 \itemize{
  43   \item{A matrix:}{it must be a numeric square matrix; the diagonal is
  44     always ignored. The arguments \code{k} and \code{rate} are ignored.}
  45
  46   \item{A character:}{these are the same short-cuts than in the function
  47   \code{\link{ace}}: \code{"ER"} is an equal-rates model, \code{"ARD"}
  48   is an all-rates-different model, and \code{"SYM"} is a symmetrical
  49   model. Note that the argument \code{rate} must be of the appropriate
  50   length, i.e., 1, \eqn{k(k - 1)}, or \eqn{k(k - 1)/2} for the three models,
  51   respectively. The rate matrix \eqn{Q} is then filled column-wise.}
  52
  53   \item{A function:}{it must be of the form \code{foo(x, l)} where
  54     \code{x} is the trait of the ancestor and \code{l} is the branch
  55     length. It must return the value of the descendant as an integer.}
  56 }}
  57 \value{
  58   A factor with names taken from the tip labels of \code{phy}. If
  59   \code{ancestor = TRUE}, the node labels are used if present,
  60   otherwise, ``Node1'', ``Node2'', etc.
  61 }
  62 \references{
  63   Paradis, E. (2006) \emph{Analyses of Phylogenetics and Evolution with
  64     R.} New York: Springer.
  65 }
  66 \author{Emmanuel Paradis}
  67 \seealso{
  68   \code{\link{rTraitCont}}, \code{\link{ace}}
  69 }
  70 \examples{
  71 data(bird.orders)
  72 ### the two followings are the same:
  73 rTraitDisc(bird.orders)
  74 rTraitDisc(bird.orders, model = matrix(c(0, 0.1, 0.1, 0), 2))
  75 ### two-state model with irreversibility:
  76 rTraitDisc(bird.orders, model = matrix(c(0, 0, 0.1, 0), 2))
  77 ### an imaginary model with stasis 0.5 time unit after a node, then
  78 ### random evolution:
  79 foo <- function(x, l) {
  80     if (l < 0.5) return(x)
  81     sample(2, size = 1)
  82 }
  83 tr <- rcoal(20, br = runif)
  84 x <- rTraitDisc(tr, foo, ancestor = TRUE)
  85 plot(tr, show.tip.label = FALSE)
  86 co <- c("blue", "yellow")
  87 cot <- c("white", "black")
  88 Y <- x[1:20]
  89 A <- x[-(1:20)]
  90 nodelabels(A, bg = co[A], col = cot[A])
  91 tiplabels(Y, bg = co[Y], col = cot[Y])
  92 }
  93 \keyword{datagen}