some news for ape 3.0-8

[ape.git] / man / ace.Rd

diff --git a/man/ace.Rd b/man/ace.Rd
index 101aebf2c4bb61aa863c1bffe9d8fcc1aa4964bc..aab1b64dc5979d771dfa4d491ac96d9344f227cf 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 (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 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 \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,
-  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
@@ -111,8 +111,8 @@ 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
@@ -149,6 +149,9 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
   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.