man/ace.Rd

   1 \name{ace}
   2 \alias{ace}
   3 \alias{print.ace}
   4 \alias{logLik.ace}
   5 \alias{deviance.ace}
   6 \alias{AIC.ace}
   7 \alias{anova.ace}
   8 \title{Ancestral Character Estimation}
   9 \usage{
  10 ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
  11     model = if (type == "continuous") "BM" else "ER",
  12     scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1)
  13 \method{print}{ace}(x, digits = 4, ...)
  14 \method{logLik}{ace}(object, ...)
  15 \method{deviance}{ace}(object, ...)
  16 \method{AIC}{ace}(object, ..., k = 2)
  17 \method{anova}{ace}(object, ...)
  18 }
  19 \arguments{
  20   \item{x}{a vector or a factor; an object of class \code{"ace"} in the
  21     case of \code{print}.}
  22   \item{phy}{an object of class \code{"phylo"}.}
  23   \item{type}{the variable type; either \code{"continuous"} or
  24     \code{"discrete"} (or an abbreviation of these).}
  25   \item{method}{a character specifying the method used for
  26     estimation. Three choices are possible: \code{"ML"}, \code{"pic"},
  27     or \code{"GLS"}.}
  28   \item{CI}{a logical specifying whether to return the 95\% confidence
  29     intervals of the ancestral state estimates (for continuous
  30     characters) or the likelihood of the different states (for discrete
  31     ones).}
  32   \item{model}{a character specifying the model (ignored if \code{method
  33       = "GLS"}), or a numeric matrix if \code{type = "discrete"} (see
  34     details).}
  35   \item{scaled}{a logical specifying whether to scale the contrast
  36     estimate (used only if \code{method = "pic"}).}
  37   \item{kappa}{a positive value giving the exponent transformation of
  38     the branch lengths (see details).}
  39   \item{corStruct}{if \code{method = "GLS"}, specifies the correlation
  40     structure to be used (this also gives the assumed model).}
  41   \item{ip}{the initial value(s) used for the ML estimation procedure
  42     when \code{type == "discrete"} (possibly recycled).}
  43   \item{digits}{the number of digits to be printed.}
  44   \item{object}{an object of class \code{"ace"}.}
  45   \item{k}{a numeric value giving the penalty per estimated parameter;
  46     the default is \code{k = 2} which is the classical Akaike
  47     information criterion.}
  48   \item{\dots}{further arguments passed to or from other methods.}
  49 }
  50 \description{
  51   This function estimates ancestral character states, and the associated
  52   uncertainty, for continuous and discrete characters.
  53
  54   \code{logLik}, \code{deviance}, and \code{AIC} are generic functions
  55   used to extract the log-likelihood, the deviance (-2*logLik), or the
  56   Akaike information criterion of a tree. If no such values are
  57   available, \code{NULL} is returned.
  58
  59   \code{anova} is another generic function that is used to compare
  60   nested models: the significance of the additional parameter(s) is
  61   tested with likelihood ratio tests. You must ensure that the models
  62   are effectively nested (if they are not, the results will be
  63   meaningless). It is better to list the models from the smallest to the
  64   largest.
  65 }
  66 \details{
  67   If \code{type = "continuous"}, the default model is Brownian motion
  68   where characters evolve randomly following a random walk. This model
  69   can be fitted by maximum likelihood (the default, Schluter et
  70   al. 1997), least squares (\code{method = "pic"}, Felsenstein 1985), or
  71   generalized least squares (\code{method = "GLS"}, Martins and Hansen
  72   1997, Cunningham et al. 1998). In the latter case, the specification
  73   of \code{phy} and \code{model} are actually ignored: it is instead
  74   given through a correlation structure with the option
  75   \code{corStruct}.
  76
  77   In the default setting (i.e., \code{method = "ML"} and \code{model =
  78   "BM"}) the maximum likelihood estimation is done simultaneously on
  79   the ancestral values and the variance of the Brownian motion process;
  80   these estimates are then used to compute the confidence intervals in
  81   the standard way (see the package \pkg{geiger} for a different
  82   implementation). If \code{method = "pic"} or \code{"GLS"}, the
  83   confidence intervals are computed using the expected variances under
  84   the model, so they depend only on the tree.
  85
  86   For discrete characters (\code{type = "discrete"}), only maximum
  87   likelihood estimation is available (Pagel 1994). The model is
  88   specified through a numeric matrix with integer values taken as
  89   indices of the parameters. The numbers of rows and of columns of this
  90   matrix must be equal, and are taken to give the number of states of
  91   the character. For instance, \code{matrix(c(0, 1, 1, 0), 2)} will
  92   represent a model with two character states and equal rates of
  93   transition, \code{matrix(c(0, 1, 2, 0), 2)} a model with unequal
  94   rates, \code{matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3)} a model with
  95   three states and equal rates of transition (the diagonal is always
  96   ignored). There are short-cuts to specify these models: \code{"ER"} is
  97   an equal-rates model (e.g., the first and third examples above),
  98   \code{"ARD"} is an all-rates-different model (the second example), and
  99   \code{"SYM"} is a symmetrical model (e.g., \code{matrix(c(0, 1, 2, 1,
 100     0, 3, 2, 3, 0), 3)}). If a short-cut is used, the number of states
 101   is determined from the data.
 102 }
 103 \value{
 104   a list with the following elements:
 105
 106   \item{ace}{if \code{type = "continuous"}, the estimates of the
 107     ancestral character values.}
 108   \item{CI95}{if \code{type = "continuous"}, the estimated 95\%
 109     confidence intervals.}
 110   \item{sigma2}{if \code{type = "continuous"}, \code{model = "BM"}, and
 111     \code{method = "ML"}, the maximum likelihood estimate of the
 112     Brownian parameter.}
 113   \item{rates}{if \code{type = "discrete"}, the maximum likelihood
 114     estimates of the transition rates.}
 115   \item{se}{if \code{type = "discrete"}, the standard-errors of
 116     estimated rates.}
 117   \item{index.matrix}{if \code{type = "discrete"}, gives the indices of
 118     the \code{rates} in the rate matrix.}
 119   \item{loglik}{if \code{method = "ML"}, the maximum log-likelihood.}
 120   \item{lik.anc}{if \code{type = "discrete"}, the scaled likelihoods of
 121     each ancestral state.}
 122   \item{call}{the function call.}
 123 }
 124 \references{
 125   Cunningham, C. W., Omland, K. E. and Oakley, T. H. (1998)
 126   Reconstructing ancestral character states: a critical
 127   reappraisal. \emph{Trends in Ecology & Evolution}, \bold{13},
 128   361--366.
 129
 130   Felsenstein, J. (1985) Phylogenies and the comparative
 131   method. \emph{American Naturalist}, \bold{125}, 1--15.
 132
 133   Martins, E. P. and Hansen, T. F. (1997) Phylogenies and the
 134   comparative method: a general approach to incorporating phylogenetic
 135   information into the analysis of interspecific data. \emph{American
 136     Naturalist}, \bold{149}, 646--667.
 137
 138   Pagel, M. (1994) Detecting correlated evolution on phylogenies: a
 139   general method for the comparative analysis of discrete
 140   characters. \emph{Proceedings of the Royal Society of London. Series
 141     B. Biological Sciences}, \bold{255}, 37--45.
 142
 143   Schluter, D., Price, T., Mooers, A. O. and Ludwig, D. (1997)
 144   Likelihood of ancestor states in adaptive radiation. \emph{Evolution},
 145   \bold{51}, 1699--1711.
 146 }
 147 \author{Emmanuel Paradis, Ben Bolker \email{bolker@zoo.ufl.edu}}
 148 \seealso{
 149   \code{\link{corBrownian}}, \code{\link{corGrafen}},
 150   \code{\link{corMartins}}, \code{\link{compar.ou}},
 151   \code{\link[stats]{anova}}
 152 }
 153 \examples{
 154 ### Just some random data...
 155 data(bird.orders)
 156 x <- rnorm(23)
 157 ### Compare the three methods for continuous characters:
 158 ace(x, bird.orders)
 159 ace(x, bird.orders, method = "pic")
 160 ace(x, bird.orders, method = "GLS",
 161     corStruct = corBrownian(1, bird.orders))
 162 ### For discrete characters:
 163 x <- factor(c(rep(0, 5), rep(1, 18)))
 164 ans <- ace(x, bird.orders, type = "d")
 165 #### Showing the likelihoods on each node:
 166 plot(bird.orders, type = "c", FALSE, label.offset = 1)
 167 co <- c("blue", "yellow")
 168 tiplabels(pch = 22, bg = co[as.numeric(x)], cex = 2, adj = 1)
 169 nodelabels(thermo = ans$lik.anc, piecol = co, cex = 0.75)
 170 ### An example of the use of the argument `ip':
 171 tr <- character(4)
 172 tr[1] <- "((((t10:5.03,t2:5.03):2.74,(t9:4.17,"
 173 tr[2] <- "t5:4.17):3.60):2.80,(t3:4.05,t7:"
 174 tr[3] <- "4.05):6.53):2.32,((t6:4.38,t1:4.38):"
 175 tr[4] <- "2.18,(t8:2.17,t4:2.17):4.39):6.33);"
 176 tr <- read.tree(text = paste(tr, collapse = ""))
 177 y <- c(rep(1, 6), rep(2, 4))
 178 ### The default `ip = 0.1' makes ace fails:
 179 ace(y, tr, type = "d")
 180 ace(y, tr, type = "d", ip = 0.01)
 181 ### Surprisingly, using an initial value farther to the
 182 ### MLE than the default one works:
 183 ace(y, tr, type = "d", ip = 0.3)
 184 }
 185 \keyword{models}