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 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. (2010) Time-dependent speciation and extinction from
  61   phylogenies: a least squares approach. (under revision)
  62   %\emph{Evolution}, \bold{59}, 1--12.
  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 }