X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=man%2Face.Rd;h=1fc5d0147f791682af8aca4605888caeee006db0;hb=21426f51c5940cb37f3198a7853ef59743729b85;hp=1e711fdaece40483ea439729a76dc2022026ea73;hpb=21eb56120c84786502f24ff9c27b39d5badfe1f7;p=ape.git

diff --git a/man/ace.Rd b/man/ace.Rd
index 1e711fd..1fc5d01 100644
--- a/man/ace.Rd
+++ b/man/ace.Rd
@@ -1,5 +1,6 @@
 \name{ace}
 \alias{ace}
+\alias{print.ace}
 \alias{logLik.ace}
 \alias{deviance.ace}
 \alias{AIC.ace}
@@ -9,19 +10,21 @@
 ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
     model = if (type == "continuous") "BM" else "ER",
     scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1)
+\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,6 +40,7 @@ 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{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
@@ -67,7 +71,26 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
   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}.
+  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.
+
+  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.
 
   For discrete characters (\code{type = "discrete"}), only maximum
   likelihood estimation is available (Pagel 1994). The model is