\name{ace}
\alias{ace}
+\alias{print.ace}
\alias{logLik.ace}
\alias{deviance.ace}
\alias{AIC.ace}
\alias{anova.ace}
\title{Ancestral Character Estimation}
+\description{
+ This function estimates ancestral character states, and the associated
+ uncertainty, for continuous and discrete characters.
+
+ \code{logLik}, \code{deviance}, and \code{AIC} are generic functions
+ used to extract the log-likelihood, the deviance, or the Akaike
+ information criterion of a fitted object. If no such values are
+ available, \code{NULL} is returned.
+
+ \code{anova} is another generic function which is used to compare
+ nested models: the significance of the additional parameter(s) is
+ tested with likelihood ratio tests. You must ensure that the models
+ are effectively nested (if they are not, the results will be
+ meaningless). It is better to list the models from the smallest to the
+ largest.
+}
\usage{
-ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
+ace(x, phy, type = "continuous", method = if (type == "continuous")
+ "REML" else "ML", CI = TRUE,
model = if (type == "continuous") "BM" else "ER",
- scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1)
+ scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1,
+ use.expm = FALSE)
+\method{print}{ace}(x, digits = 4, ...)
\method{logLik}{ace}(object, ...)
\method{deviance}{ace}(object, ...)
\method{AIC}{ace}(object, ..., k = 2)
\method{anova}{ace}(object, ...)
}
\arguments{
- \item{x}{a vector or a factor.}
+ \item{x}{a vector or a factor; an object of class \code{"ace"} in the
+ case of \code{print}.}
\item{phy}{an object of class \code{"phylo"}.}
\item{type}{the variable type; either \code{"continuous"} or
\code{"discrete"} (or an abbreviation of these).}
\item{method}{a character specifying the method used for
- estimation. Three choices are possible: \code{"ML"}, \code{"pic"},
- or \code{"GLS"}.}
+ estimation. Four choices are possible: \code{"ML"}, \code{"REML"},
+ \code{"pic"}, or \code{"GLS"}.}
\item{CI}{a logical specifying whether to return the 95\% confidence
intervals of the ancestral state estimates (for continuous
characters) or the likelihood of the different states (for discrete
structure to be used (this also gives the assumed model).}
\item{ip}{the initial value(s) used for the ML estimation procedure
when \code{type == "discrete"} (possibly recycled).}
+ \item{use.expm}{a logical specifying whether to use the package
+ \pkg{expm} to compute the matrix exponential (relevant only if
+ \code{type = "d"}). The default is to use the function
+ \code{matexpo} from \pkg{ape} (see details).}
+ \item{digits}{the number of digits to be printed.}
\item{object}{an object of class \code{"ace"}.}
\item{k}{a numeric value giving the penalty per estimated parameter;
the default is \code{k = 2} which is the classical Akaike
information criterion.}
- \item{...}{further arguments passed to or from other methods.}
-}
-\description{
- This function estimates ancestral character states, and the associated
- uncertainty, for continuous and discrete characters.
-
- \code{logLik}, \code{deviance}, and \code{AIC} are generic functions
- used to extract the log-likelihood, the deviance (-2*logLik), or the
- Akaike information criterion of a tree. If no such values are
- available, \code{NULL} is returned.
-
- \code{anova} is another generic function that is used to compare
- nested models: the significance of the additional parameter(s) is
- tested with likelihood ratio tests. You must ensure that the models
- are effectively nested (if they are not, the results will be
- meaningless). It is better to list the models from the smallest to the
- largest.
+ \item{\dots}{further arguments passed to or from other methods.}
}
\details{
If \code{type = "continuous"}, the default model is Brownian motion
where characters evolve randomly following a random walk. This model
- can be fitted by maximum likelihood (the default, Schluter et
- al. 1997), least squares (\code{method = "pic"}, Felsenstein 1985), or
- generalized least squares (\code{method = "GLS"}, Martins and Hansen
- 1997, Cunningham et al. 1998). In the latter case, the specification
- of \code{phy} and \code{model} are actually ignored: it is instead
- given through a correlation structure with the option \code{corStruct}.
+ can be fitted by residual maximum likelihood (the default), maximum
+ likelihood (Felsenstein 1973, Schluter et al. 1997), least squares
+ (\code{method = "pic"}, Felsenstein 1985), or generalized least
+ squares (\code{method = "GLS"}, Martins and Hansen 1997, Cunningham et
+ al. 1998). In the last case, the specification of \code{phy} and
+ \code{model} are actually ignored: it is instead given through a
+ correlation structure with the option \code{corStruct}.
+
+ In the setting \code{method = "ML"} and \code{model = "BM"} (this used
+ to be the default until \pkg{ape} 3.0-7) the maximum likelihood
+ estimation is done simultaneously on the ancestral values and the
+ variance of the Brownian motion process; these estimates are then used
+ to compute the confidence intervals in the standard way. The REML
+ method first estimates the ancestral value at the root (aka, the
+ phylogenetic mean), then the variance of the Brownian motion process
+ is estimated by optimizing the residual log-likelihood. The ancestral
+ values are finally inferred from the likelihood function giving these
+ two parameters. If \code{method = "pic"} or \code{"GLS"}, the
+ confidence intervals are computed using the expected variances under
+ the model, so they depend only on the tree.
+
+ It could be shown that, with a continous character, REML results in
+ unbiased estimates of the variance of the Brownian motion process
+ while ML gives a downward bias. Therefore the former is recommanded.
For discrete characters (\code{type = "discrete"}), only maximum
likelihood estimation is available (Pagel 1994). The model is
an equal-rates model (e.g., the first and third examples above),
\code{"ARD"} is an all-rates-different model (the second example), and
\code{"SYM"} is a symmetrical model (e.g., \code{matrix(c(0, 1, 2, 1,
- 0, 3, 2, 3, 0), 3)}). If a short-cut is used, the number of states
- is determined from the data.
+ 0, 3, 2, 3, 0), 3)}). If a short-cut is used, the number of states is
+ determined from the data.
+
+ With discrete characters it is necessary to compute the exponential of
+ the rate matrix. By default (and the only possible choice until
+ \pkg{ape} 3.0-7) the function \code{\link{matexpo}} in \pkg{ape} is
+ used. If \code{use.expm = TRUE}, the function
+ \code{\link[expm]{expm}}, in the package of the same name, is
+ used. \code{matexpo} is faster but quite inaccurate for large and/or
+ asymmetric matrices. In case of doubt, use the latter.
}
\value{
- a list with the following elements:
+ an object of class \code{"ace"} with the following elements:
\item{ace}{if \code{type = "continuous"}, the estimates of the
ancestral character values.}
reappraisal. \emph{Trends in Ecology & Evolution}, \bold{13},
361--366.
+ Felsenstein, J. (1973) Maximum likelihood estimation
+ of evolutionary trees from continuous characters. \emph{American Journal of Human Genetics}, \bold{25}, 471--492.
+
Felsenstein, J. (1985) Phylogenies and the comparative
method. \emph{American Naturalist}, \bold{125}, 1--15.
Likelihood of ancestor states in adaptive radiation. \emph{Evolution},
\bold{51}, 1699--1711.
}
-\author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}, Ben Bolker
-\email{bolker@zoo.ufl.edu}}
+\author{Emmanuel Paradis, Ben Bolker}
\seealso{
\code{\link{corBrownian}}, \code{\link{corGrafen}},
\code{\link{corMartins}}, \code{\link{compar.ou}},
projects / ape.git / blobdiff