man/compar.ou.Rd

   1 \name{compar.ou}
   2 \alias{compar.ou}
   3 \title{Ornstein--Uhlenbeck Model for Continuous Characters}
   4 \usage{
   5 compar.ou(x, phy, node = NULL, alpha = NULL)
   6 }
   7 \arguments{
   8   \item{x}{a numeric vector giving the values of a continuous
   9     character.}
  10   \item{phy}{an object of class \code{"phylo"}.}
  11   \item{node}{a vector giving the number(s) of the node(s) where the
  12     parameter `theta' (the character optimum) is assumed to change. By
  13     default there is no change (same optimum thoughout lineages).}
  14   \item{alpha}{the value of \eqn{\alpha}{alpha} to be used when fitting
  15     the model. By default, this parameter is estimated (see details).}
  16 }
  17 \description{
  18   This function fits an Ornstein--Uhlenbeck model giving a phylogenetic
  19   tree, and a continuous character. The user specifies the node(s) where
  20   the optimum changes. The parameters are estimated by maximum
  21   likelihood; their standard-errors are computed assuming normality of
  22   these estimates.
  23 }
  24 \details{
  25   The Ornstein--Uhlenbeck (OU) process can be seen as a generalization
  26   of the Brownian motion process. In the latter, characters are assumed
  27   to evolve randomly under a random walk, that is change is equally
  28   likely in any direction. In the OU model, change is more likely
  29   towards the direction of an optimum (denoted \eqn{\theta}{theta}) with
  30   a strength controlled by a parameter denoted \eqn{\alpha}{alpha}.
  31
  32   The present function fits a model where the optimum parameter
  33   \eqn{\theta}{theta}, is allowed to vary throughout the tree. This is
  34   specified with the argument \code{node}: \eqn{\theta}{theta} changes
  35   after each node whose number is given there. Note that the optimum
  36   changes \emph{only} for the lineages which are descendants of this
  37   node.
  38
  39   Hansen (1997) recommends to not estimate \eqn{\alpha}{alpha} together
  40   with the other parameters. The present function allows this by giving
  41   a numeric value to the argument \code{alpha}. By default, this
  42   parameter is estimated, but this seems to yield very large
  43   standard-errors, thus validating Hansen's recommendation. In practice,
  44   a ``poor man estimation'' of \eqn{\alpha}{alpha} can be done by
  45   repeating the function call with different values of \code{alpha}, and
  46   selecting the one that minimizes the deviance (see Hansen 1997 for an
  47   example).
  48
  49   If \code{x} has names, its values are matched to the tip labels of
  50   \code{phy}, otherwise its values are taken to be in the same order
  51   than the tip labels of \code{phy}.
  52
  53   The user must be careful here since the function requires that both
  54   series of names perfectly match, so this operation may fail if there
  55   is a typing or syntax error. If both series of names do not match, the
  56   values in the \code{x} are taken to be in the same order than the tip
  57   labels of \code{phy}, and a warning message is issued.
  58 }
  59 \note{
  60   The inversion of the variance-covariance matrix in the likelihood
  61   function appeared as somehow problematic. The present implementation
  62   uses a Cholevski decomposition with the function
  63   \code{\link[base]{chol2inv}} instead of the usual function
  64   \code{\link[base]{solve}}.
  65 }
  66 \value{
  67   an object of class \code{"compar.ou"} which is list with the following
  68   components:
  69
  70   \item{deviance}{the deviance (= -2 * loglik).}
  71   \item{para}{a data frame with the maximum likelihood estimates and
  72     their standard-errors.}
  73   \item{call}{the function call.}
  74 }
  75 \references{
  76   Hansen, T. F. (1997) Stabilizing selection and the comparative
  77   analysis of adaptation. \emph{Evolution}, \bold{51}, 1341--1351.
  78 }
  79 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
  80 \seealso{
  81   \code{\link{ace}}, \code{\link{compar.lynch}},
  82   \code{\link{corBrownian}}, \code{\link{corMartins}}, \code{\link{pic}}
  83 }
  84 \examples{
  85 \dontrun{
  86 data(bird.orders)
  87 ### This is likely to give you estimates close to 0, 1, and 0
  88 ### for alpha, sigma^2, and theta, respectively:
  89 compar.ou(rnorm(23), bird.orders)
  90 ### Much better with a fixed alpha:
  91 compar.ou(rnorm(23), bird.orders, alpha = 0.1)
  92 ### Let us 'mimick' the effect of different optima
  93 ### for the two clades of birds...
  94 x <- c(rnorm(5, 0), rnorm(18, 5))
  95 ### ... the model with two optima:
  96 compar.ou(x, bird.orders, node = -2, alpha = .1)
  97 ### ... and the model with a single optimum:
  98 compar.ou(x, bird.orders, node = NULL, alpha = .1)
  99 ### => Compare both models with the difference in deviances
 100 ##     with follows a chi^2 with df = 1.
 101 }
 102 }
 103 \keyword{models}