man/yule.cov.Rd

   1 \name{yule.cov}
   2 \alias{yule.cov}
   3 \title{Fits the Yule Model With Covariates}
   4 \usage{
   5 yule.cov(phy, formula, data = NULL)
   6 }
   7 \arguments{
   8   \item{phy}{an object of class \code{"phylo"}.}
   9   \item{formula}{a formula specifying the model to be fitted.}
  10   \item{data}{the name of the data frame where the variables in
  11     \code{formula} are to be found; by default, the variables are looked
  12     for in the global environment.}
  13 }
  14 \description{
  15   This function fits by maximum likelihood the Yule model with
  16   covariates, that is a birth-only model where speciation rate is
  17   determined by a generalized linear model.
  18 }
  19 \details{
  20   The model fitted is a generalization of the Yule model where the
  21   speciation rate is determined by:
  22
  23   \deqn{\ln\frac{\lambda_i}{1 - \lambda_i} = \beta_1 x_{i1} + \beta_2 x_{i2}
  24     + \dots + \alpha }{ln(li / (1 - li)) = b1 xi1 + b2 xi2 + ... a}
  25
  26   where \eqn{\lambda_i}{li} is the speciation rate for species i,
  27   \eqn{x_{i1}, x_{i2}, \dots}{xi1, xi2, ...} are species-specific
  28   variables, and \eqn{\beta_1, \beta_2, \dots, \alpha}{b1, b2, ..., a}
  29   are parameters to be estimated. The term on the left-hand side above
  30   is a logit function often used in generalized linear models for
  31   binomial data (see \code{\link[stats]{family}}). The above model can
  32   be written in matrix form:
  33
  34   \deqn{\mathrm{logit} \lambda_i = x_i' \beta}{logit li = xi' b}
  35
  36   The standard-errors of the parameters are computed with the second
  37   derivatives of the log-likelihood function. (See References for other
  38   details on the estimation procedure.)
  39
  40   The function needs three things:
  41
  42   \item a phylogenetic tree which may contain multichotomies;
  43
  44   \item a formula which specifies the predictors of the model described
  45   above: this is given as a standard R formula and has no response (no
  46   left-hand side term), for instance: \code{~ x + y}, it can include
  47   interactions (\code{~ x + a * b}) (see \code{\link[stats]{formula}}
  48   for details);
  49
  50   \item the predictors specified in the formula must be accessible to
  51   the function (either in the global space, or though the \code{data}
  52   option); they can be numeric vectors or factors. The length and the
  53   order of these data are important: the number of values (length) must
  54   be equal to the number of tips of the tree + the number of nodes. The
  55   order is the following: first the values for the tips in the same
  56   order than for the labels, then the values for the nodes sequentially
  57   from the root to the most terminal nodes (i.e. in the order given by
  58   \code{phy$edge}).
  59
  60   The user must obtain the values for the nodes separately.
  61
  62   Note that the method in its present implementation assumes that the
  63   change in a species trait is more or less continuous between two nodes
  64   or between a node and a tip. Thus reconstructing the ancestral values
  65   with a Brownian motion model may be consistent with the present
  66   method. This can be done with the function \code{\link{pic}} but
  67   currently needs some hacking!
  68 }
  69 \value{
  70   A NULL value is returned, the results are simply printed.
  71 }
  72 \references{
  73   Paradis, E. (2005) Statistical analysis of diversification with
  74   species traits. \emph{Evolution}, \bold{59}, 1--12.
  75 }
  76 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
  77 \seealso{
  78   \code{\link{branching.times}}, \code{\link{diversi.gof}},
  79   \code{\link{diversi.time}}, \code{\link{ltt.plot}},
  80   \code{\link{birthdeath}}, \code{\link{bd.ext}}, \code{\link{yule}}
  81 }
  82 \examples{
  83 ### a simple example with some random data
  84 data(bird.orders)
  85 x <- rnorm(45) # the tree has 23 tips and 22 nodes
  86 ### the standard-error for x should be as large as
  87 ### the estimated parameter
  88 yule.cov(bird.orders, ~ x)
  89 ### compare with the simple Yule model, eventually
  90 ### with a likelihood ratio test
  91 yule(bird.orders)
  92 ### another example with a tree that has a multichotomy
  93 ### but we cannot run yule() because of this!
  94 data(bird.families)
  95 y <- rnorm(272) # 137 tips + 135 nodes
  96 yule.cov(bird.families, ~ y)
  97 }
  98 \keyword{models}