man/dbd.Rd

   1 \name{dbd}
   2 \alias{dyule}
   3 \alias{dbd}
   4 \alias{dbdTime}
   5 \title{Probability Density Under Birth--Death Models}
   6 \description{
   7   These functions compute the probability density under some
   8   birth--death models, that is the probability of obtaining \emph{x}
   9   species after a time \emph{t} giving how speciation and extinction
  10   probabilities vary through time (these may be constant, or even equal
  11   to zero for extinction).
  12 }
  13 \usage{
  14 dyule(x, lambda = 0.1, t = 1, log = FALSE)
  15 dbd(x, lambda, mu, t, conditional = FALSE, log = FALSE)
  16 dbdTime(x, birth, death, t, conditional = FALSE,
  17         BIRTH = NULL, DEATH = NULL, fast = FALSE)
  18 }
  19 \arguments{
  20   \item{x}{a numeric vector of species numbers (see Details).}
  21   \item{lambda}{a numerical value giving the probability of speciation;
  22     can be a vector with several values for \code{dyule}.}
  23   \item{mu}{id. for extinction.}
  24   \item{t}{id. for the time(s).}
  25   \item{log}{a logical value specifying whether the probabilities should
  26     be returned log-transformed; the default is \code{FALSE}.}
  27   \item{conditional}{a logical specifying whether the probabilities
  28     should be computed conditional under the assumption of no extinction
  29     after time \code{t}.}
  30   \item{birth, death}{a (vectorized) function specifying how the
  31     speciation or extinction probability changes through time (see
  32     \code{\link{yule.time}} and below).}
  33   \item{BIRTH, DEATH}{a (vectorized) function giving the primitive
  34     of \code{birth} or \code{death}.}
  35   \item{fast}{a logical value specifying whether to use faster
  36     integration (see \code{\link{bd.time}}).}
  37 }
  38 \details{
  39   These three functions compute the probabilities to observe \code{x}
  40   species starting from a single one after time \code{t} (assumed to be
  41   continuous). The first function is a short-cut for the second one with
  42   \code{mu = 0} and with default values for the two other arguments.
  43   \code{dbdTime} is for time-varying \code{lambda} and \code{mu}
  44   specified as \R functions.
  45
  46   \code{dyule} is vectorized simultaneously on its three arguments
  47   \code{x}, \code{lambda}, and \code{t}, according to \R's rules of
  48   recycling arguments. \code{dbd} is vectorized simultaneously \code{x}
  49   and \code{t} (to make likelihood calculations easy), and
  50   \code{dbdTime} is vectorized only on \code{x}; the other arguments are
  51   eventually shortened with a warning if necessary.
  52
  53   The returned value is, logically, zero for values of \code{x} out of
  54   range, i.e., negative or zero for \code{dyule} or if \code{conditional
  55   = TRUE}. However, it is not checked if the values of \code{x} are
  56   positive non-integers and the probabilities are computed and returned.
  57
  58   The details on the form of the arguments \code{birth}, \code{death},
  59   \code{BIRTH}, \code{DEATH}, and \code{fast} can be found in the links
  60   below.
  61 }
  62 \note{
  63   If you use these functions to calculate a likelihood function, it is
  64   strongly recommended to compute the log-likelihood with, for instance
  65   in the case of a Yule process, \code{sum(dyule( , log = TRUE))} (see
  66   examples).
  67 }
  68 \value{
  69   a numeric vector.
  70 }
  71 \references{
  72   Kendall, D. G. (1948) On the generalized ``birth-and-death''
  73   process. \emph{Annals of Mathematical Statistics}, \bold{19}, 1--15.
  74 }
  75 \author{Emmanuel Paradis}
  76 \seealso{
  77   \code{\link{bd.time}},  \code{\link{yule.time}}
  78 }
  79 \examples{
  80 x <- 0:10
  81 plot(x, dyule(x), type = "h", main = "Density of the Yule process")
  82 text(7, 0.85, expression(list(lambda == 0.1, t == 1)))
  83
  84 y <- dbd(x, 0.1, 0.05, 10)
  85 z <- dbd(x, 0.1, 0.05, 10, conditional = TRUE)
  86 d <- rbind(y, z)
  87 colnames(d) <- x
  88 barplot(d, beside = TRUE, ylab = "Density", xlab = "Number of species",
  89         legend = c("unconditional", "conditional on\nno extinction"),
  90         args.legend = list(bty = "n"))
  91 title("Density of the birth-death process")
  92 text(17, 0.4, expression(list(lambda == 0.1, mu == 0.05, t == 10)))
  93
  94 \dontrun{
  95 ### generate 1000 values from a Yule process with lambda = 0.05
  96 x <- replicate(1e3, Ntip(rlineage(0.05, 0)))
  97
  98 ### the correct way to calculate the log-likelihood...:
  99 sum(dyule(x, 0.05, 50, log = TRUE))
 100
 101 ### ... and the wrong way:
 102 log(prod(dyule(x, 0.05, 50)))
 103
 104 ### a third, less preferred, way:
 105 sum(log(dyule(x, 0.05, 50)))
 106 }}
 107 \keyword{utilities}