X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=man%2Face.Rd;h=ee66b0d3ef7fd6f8c951af74eafb545deda0286b;hb=646d8be3497d656d95331e2c7f6bef5d2ff86b2c;hp=96860220b2cef50008075f1abe6f72afff7ffac7;hpb=1df144a18356d9b329324324bc2f78cfdf1cea3d;p=ape.git

diff --git a/man/ace.Rd b/man/ace.Rd
index 9686022..ee66b0d 100644
--- a/man/ace.Rd
+++ b/man/ace.Rd
@@ -6,10 +6,28 @@
 \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, ...)
@@ -40,6 +58,10 @@ 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;
@@ -47,50 +69,33 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
     information criterion.}
   \item{\dots}{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 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.
-}
 \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 (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 default setting (i.e., \code{method = "ML"} and \code{model =
-  "BM"}) 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.
+  In the setting \code{method = "ML"} and \code{model = "BM"} (this used
+  to be the default until 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
-  over the latter, even though it is not the default.
+  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
@@ -108,9 +113,17 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
   \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.
+
+  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.}
@@ -153,7 +166,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, 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}},