various fixes in C files

[ape.git] / man / ace.Rd

diff --git a/man/ace.Rd b/man/ace.Rd
index 85cfb210bbbea57af3f7f0786d6b4f4028ea8e89..96860220b2cef50008075f1abe6f72afff7ffac7 100644 (file)
--- a/man/ace.Rd
+++ b/man/ace.Rd
@@ -1,5 +1,6 @@
 \name{ace}
 \alias{ace}
 \name{ace}
 \alias{ace}

+\alias{print.ace}

 \alias{logLik.ace}
 \alias{deviance.ace}
 \alias{AIC.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)
 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{
 \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
   \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
   \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,11 +40,12 @@ 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).}
     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
     information criterion.}
   \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.}
+  \item{\dots}{further arguments passed to or from other methods.}

 }
 \description{
   This function estimates ancestral character states, and the associated
 }
 \description{
   This function estimates ancestral character states, and the associated


@@ -52,7 +56,7 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
   Akaike information criterion of a tree. If no such values are
   available, \code{NULL} is returned.
 
   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
+  \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
   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


@@ -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
   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
 
   For discrete characters (\code{type = "discrete"}), only maximum
   likelihood estimation is available (Pagel 1994). The model is


@@ -130,8 +153,7 @@ ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
   Likelihood of ancestor states in adaptive radiation. \emph{Evolution},
   \bold{51}, 1699--1711.
 }
   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 \email{bolker@zoo.ufl.edu}}

 \seealso{
   \code{\link{corBrownian}}, \code{\link{corGrafen}},
   \code{\link{corMartins}}, \code{\link{compar.ou}},
 \seealso{
   \code{\link{corBrownian}}, \code{\link{corGrafen}},
   \code{\link{corMartins}}, \code{\link{compar.ou}},