man/bd.time.Rd

   1 \name{bd.time}
   2 \alias{bd.time}
   3 \title{Time-Dependent Birth-Death Models}
   4 \description{
   5   This function fits a used-defined time-dependent birth-death
   6   model.
   7 }
   8 \usage{
   9 bd.time(phy, birth, death, BIRTH = NULL, DEATH = NULL,
  10         ip, lower, upper, fast = FALSE, boot = 0, trace = 0)
  11 }
  12 \arguments{
  13   \item{phy}{an object of class \code{"phylo"}.}
  14   \item{birth}{either a numeric (if speciation rate is assumed
  15     constant), or a (vectorized) function specifying how the birth
  16     (speciation) probability changes through time (see details).}
  17   \item{death}{id. for extinction probability.}
  18   \item{BIRTH}{(optional) a vectorized function giving the primitive
  19     of \code{birth}.}
  20   \item{DEATH}{id. for \code{death}.}
  21   \item{ip}{a numeric vector used as initial values for the estimation
  22     procedure. If missing, these values are guessed.}
  23   \item{lower, upper}{the lower and upper bounds of the parameters. If
  24     missing, these values are guessed too.}
  25   \item{fast}{a logical value specifying whether to use faster
  26     integration (see details).}
  27   \item{boot}{the number of bootstrap replicates to assess the
  28     confidence intervals of the parameters. Not run by default.}
  29   \item{trace}{an integer value. If non-zero, the fitting procedure is
  30     printed every \code{trace} steps. This can be helpful if convergence
  31     is particularly slow.}
  32 }
  33 \details{
  34   Details on how to specify the birth and death functions and their
  35   primitives can be found in the help page of \code{\link{yule.time}}.
  36
  37   The model is fitted by minimizing the least squares deviation between
  38   the observed and the predicted distributions of branching times. These
  39   computations rely heavily on numerical integrations. If \code{fast =
  40   FALSE}, integrations are done with R's \code{\link[stats]{integrate}}
  41   function. If \code{fast = TRUE}, a faster but less accurate function
  42   provided in \pkg{ape} is used. If fitting a complex model to a large
  43   phylogeny, a strategy might be to first use the latter option, and
  44   then to use the estimates as starting values with \code{fast = FALSE}.
  45 }
  46 \value{
  47   A list with the following components:
  48
  49 \itemize{
  50   \item{par}{a vector of estimates with names taken from the parameters
  51     in the specified functions.}
  52   \item{SS}{the minimized sum of squares.}
  53   \item{convergence}{output convergence criterion from
  54     \code{\link[stats]{nlminb}}.}
  55   \item{message}{id.}
  56   \item{iterations}{id.}
  57   \item{evaluations}{id.}
  58 }}
  59 \references{
  60   Paradis, E. (2011) Time-dependent speciation and extinction from
  61   phylogenies: a least squares approach. \emph{Evolution}, \bold{65},
  62   661--672.
  63 }
  64 \author{Emmanuel Paradis}
  65 \seealso{
  66   \code{\link{ltt.plot}}, \code{\link{birthdeath}},
  67   \code{\link{yule.time}}
  68 }
  69 \examples{
  70 set.seed(3)
  71 tr <- rbdtree(0.1, 0.02)
  72 bd.time(tr, 0, 0) # fits a simple BD model
  73 bd.time(tr, 0, 0, ip = c(.1, .01)) # 'ip' is useful here
  74 ## the classic logistic:
  75 birth.logis <- function(a, b) 1/(1 + exp(-a*t - b))
  76 \dontrun{
  77 bd.time(tr, birth.logis, 0, ip = c(0, -2, 0.01))
  78 ## slow to get:
  79 ## $par
  80 ##            a            b        death
  81 ## -0.003486961 -1.995983179  0.016496454
  82 ##
  83 ## $SS
  84 ## [1] 20.73023
  85 }
  86 }