man/yule.time.Rd

   1 \name{yule.time}
   2 \alias{yule.time}
   3 \title{Fits the Time-Dependent Yule Model}
   4 \usage{
   5 yule.time(phy, birth, BIRTH = NULL, root.time = 0, opti = "nlm", start = 0.01)
   6 }
   7 \arguments{
   8   \item{phy}{an object of class \code{"phylo"}.}
   9   \item{birth}{a (vectorized) function specifying how the birth
  10     (speciation) probability changes through time (see details).}
  11   \item{BIRTH}{a (vectorized) function giving the primitive of
  12     \code{birth}.}
  13   \item{root.time}{a numeric value giving the time of the root node
  14     (time is measured from the past towards the present).}
  15   \item{opti}{a character string giving the function used for
  16     optimisation of the likelihood function. Three choices are possible:
  17     \code{"nlm"}, \code{"nlminb"}, or \code{"optim"}, or any unambiguous
  18     abbreviation of these.}
  19   \item{start}{the initial values used in the optimisation.}
  20 }
  21 \description{
  22   This function fits by maximum likelihood the time-dependent Yule
  23   model. The time is measured from the past (\code{root.time}) to the
  24   present.
  25 }
  26 \details{
  27   The model fitted is a straightforward extension of the Yule model with
  28   covariates (see \code{\link{yule.cov}}). Rather than having
  29   heterogeneity among lineages, the speciation probability is the same
  30   for all lineages at a given time, but can change through time.
  31
  32   The function \code{birth} \emph{must} meet these two requirements: (i)
  33   the parameters to be estimated are the formal arguments; (ii) time is
  34   named \code{t} in the body of the function. However, this is the
  35   opposite for the primitive \code{BIRTH}: \code{t} is the formal
  36   argument, and the parameters are used in its body. See the examples.
  37
  38   It is recommended to use \code{BIRTH} if possible, and required if
  39   speciation probability is constant on some time interval. If this
  40   primitive cannot be provided, a numerical integration is done with
  41   \code{\link[stats]{integrate}}.
  42
  43   The standard-errors of the parameters are computed with the Hessian of
  44   the log-likelihood function.
  45 }
  46 \value{
  47   An object of class \code{"yule"} (see \code{\link{yule}}).
  48 }
  49 \author{Emmanuel Paradis}
  50 \references{
  51   Hubert, N., Paradis, E., Bruggemann, H. & Planes, S. (2011) Community
  52   assembly and diversification in Indo-Pacific coral reef
  53   fishes. \emph{Ecology and Evolution} (in press).
  54 }
  55 \seealso{
  56   \code{\link{branching.times}}, \code{\link{ltt.plot}},
  57   \code{\link{birthdeath}}, \code{\link{yule}}, \code{\link{yule.cov}},
  58   \code{\link{bd.time}}
  59 }
  60 \examples{
  61 ### define two models...
  62 birth.logis <- function(a, b) 1/(1 + exp(-a*t - b)) # logistic
  63 birth.step <- function(l1, l2, Tcl) { # 2 rates with one break-point
  64     ans <- rep(l1, length(t))
  65     ans[t > Tcl] <- l2
  66     ans
  67 }
  68 ### ... and their primitives:
  69 BIRTH.logis <- function(t) log(exp(-a*t) + exp(b))/a + t
  70 BIRTH.step <- function(t)
  71 {
  72     out <- numeric(length(t))
  73     sel <- t <= Tcl
  74     if (any(sel)) out[sel] <- t[sel] * l1
  75     if (any(!sel)) out[!sel] <- Tcl * l1 + (t[!sel] - Tcl) * l2
  76     out
  77 }
  78 data(bird.families)
  79 ### fit both models:
  80 yule.time(bird.families, birth.logis)
  81 yule.time(bird.families, birth.logis, BIRTH.logis) # same but faster
  82 \dontrun{yule.time(bird.families, birth.step)}  # fails
  83 yule.time(bird.families, birth.step, BIRTH.step,
  84           opti = "nlminb", start = c(.01, .01, 100))
  85 }
  86 \keyword{models}