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