modified ace( method = ...)

[ape.git] / man / ace.Rd

diff --git a/man/ace.Rd b/man/ace.Rd
index 101aebf2c4bb61aa863c1bffe9d8fcc1aa4964bc..ee66b0d3ef7fd6f8c951af74eafb545deda0286b 100644 (file)
--- a/man/ace.Rd
+++ b/man/ace.Rd
@@ -23,7 +23,8 @@
   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,
     use.expm = FALSE)
@@ -71,31 +72,30 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
 \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 (\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,
-  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