X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=man%2Face.Rd;h=aab1b64dc5979d771dfa4d491ac96d9344f227cf;hb=c488b74490ee3d9d200de0e471881f002a18fe4f;hp=edcab533e32c4a87d6fde5f498318a666cf74787;hpb=c827059eeafc8cbe41c812b26979543ab287803e;p=ape.git diff --git a/man/ace.Rd b/man/ace.Rd index edcab53..aab1b64 100644 --- a/man/ace.Rd +++ b/man/ace.Rd @@ -1,27 +1,48 @@ \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 @@ -37,38 +58,45 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE, 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). In the latter case, the specification of \code{phy} and + 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 specified through a numeric matrix with integer values taken as @@ -83,11 +111,19 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE, 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.} @@ -108,6 +144,14 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE, \item{call}{the function call.} } \references{ + Cunningham, C. W., Omland, K. E. and Oakley, T. H. (1998) + Reconstructing ancestral character states: a critical + 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. @@ -125,8 +169,7 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE, 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}},