8 \title{Ancestral Character Estimation}
10 ace(x, phy, type = "continuous", method = "ML", CI = TRUE,
11 model = if (type == "continuous") "BM" else "ER",
12 scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1)
13 \method{print}{ace}(x, digits = 4, ...)
14 \method{logLik}{ace}(object, ...)
15 \method{deviance}{ace}(object, ...)
16 \method{AIC}{ace}(object, ..., k = 2)
17 \method{anova}{ace}(object, ...)
20 \item{x}{a vector or a factor; an object of class \code{"ace"} in the
21 case of \code{print}.}
22 \item{phy}{an object of class \code{"phylo"}.}
23 \item{type}{the variable type; either \code{"continuous"} or
24 \code{"discrete"} (or an abbreviation of these).}
25 \item{method}{a character specifying the method used for
26 estimation. Three choices are possible: \code{"ML"}, \code{"pic"},
28 \item{CI}{a logical specifying whether to return the 95\% confidence
29 intervals of the ancestral state estimates (for continuous
30 characters) or the likelihood of the different states (for discrete
32 \item{model}{a character specifying the model (ignored if \code{method
33 = "GLS"}), or a numeric matrix if \code{type = "discrete"} (see
35 \item{scaled}{a logical specifying whether to scale the contrast
36 estimate (used only if \code{method = "pic"}).}
37 \item{kappa}{a positive value giving the exponent transformation of
38 the branch lengths (see details).}
39 \item{corStruct}{if \code{method = "GLS"}, specifies the correlation
40 structure to be used (this also gives the assumed model).}
41 \item{ip}{the initial value(s) used for the ML estimation procedure
42 when \code{type == "discrete"} (possibly recycled).}
43 \item{digits}{the number of digits to be printed.}
44 \item{object}{an object of class \code{"ace"}.}
45 \item{k}{a numeric value giving the penalty per estimated parameter;
46 the default is \code{k = 2} which is the classical Akaike
47 information criterion.}
48 \item{\dots}{further arguments passed to or from other methods.}
51 This function estimates ancestral character states, and the associated
52 uncertainty, for continuous and discrete characters.
54 \code{logLik}, \code{deviance}, and \code{AIC} are generic functions
55 used to extract the log-likelihood, the deviance (-2*logLik), or the
56 Akaike information criterion of a tree. If no such values are
57 available, \code{NULL} is returned.
59 \code{anova} is another generic function that is used to compare
60 nested models: the significance of the additional parameter(s) is
61 tested with likelihood ratio tests. You must ensure that the models
62 are effectively nested (if they are not, the results will be
63 meaningless). It is better to list the models from the smallest to the
67 If \code{type = "continuous"}, the default model is Brownian motion
68 where characters evolve randomly following a random walk. This model
69 can be fitted by maximum likelihood (the default, Schluter et
70 al. 1997), least squares (\code{method = "pic"}, Felsenstein 1985), or
71 generalized least squares (\code{method = "GLS"}, Martins and Hansen
72 1997, Cunningham et al. 1998). In the latter case, the specification
73 of \code{phy} and \code{model} are actually ignored: it is instead
74 given through a correlation structure with the option
77 In the default setting (i.e., \code{method = "ML"} and \code{model =
78 "BM"}) the maximum likelihood estimation is done simultaneously on
79 the ancestral values and the variance of the Brownian motion process;
80 these estimates are then used to compute the confidence intervals in
81 the standard way (see the package \pkg{geiger} for a different
82 implementation). If \code{method = "pic"} or \code{"GLS"}, the
83 confidence intervals are computed using the expected variances under
84 the model, so they depend only on the tree.
86 For discrete characters (\code{type = "discrete"}), only maximum
87 likelihood estimation is available (Pagel 1994). The model is
88 specified through a numeric matrix with integer values taken as
89 indices of the parameters. The numbers of rows and of columns of this
90 matrix must be equal, and are taken to give the number of states of
91 the character. For instance, \code{matrix(c(0, 1, 1, 0), 2)} will
92 represent a model with two character states and equal rates of
93 transition, \code{matrix(c(0, 1, 2, 0), 2)} a model with unequal
94 rates, \code{matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3)} a model with
95 three states and equal rates of transition (the diagonal is always
96 ignored). There are short-cuts to specify these models: \code{"ER"} is
97 an equal-rates model (e.g., the first and third examples above),
98 \code{"ARD"} is an all-rates-different model (the second example), and
99 \code{"SYM"} is a symmetrical model (e.g., \code{matrix(c(0, 1, 2, 1,
100 0, 3, 2, 3, 0), 3)}). If a short-cut is used, the number of states
101 is determined from the data.
104 a list with the following elements:
106 \item{ace}{if \code{type = "continuous"}, the estimates of the
107 ancestral character values.}
108 \item{CI95}{if \code{type = "continuous"}, the estimated 95\%
109 confidence intervals.}
110 \item{sigma2}{if \code{type = "continuous"}, \code{model = "BM"}, and
111 \code{method = "ML"}, the maximum likelihood estimate of the
113 \item{rates}{if \code{type = "discrete"}, the maximum likelihood
114 estimates of the transition rates.}
115 \item{se}{if \code{type = "discrete"}, the standard-errors of
117 \item{index.matrix}{if \code{type = "discrete"}, gives the indices of
118 the \code{rates} in the rate matrix.}
119 \item{loglik}{if \code{method = "ML"}, the maximum log-likelihood.}
120 \item{lik.anc}{if \code{type = "discrete"}, the scaled likelihoods of
121 each ancestral state.}
122 \item{call}{the function call.}
125 Cunningham, C. W., Omland, K. E. and Oakley, T. H. (1998)
126 Reconstructing ancestral character states: a critical
127 reappraisal. \emph{Trends in Ecology & Evolution}, \bold{13},
130 Felsenstein, J. (1985) Phylogenies and the comparative
131 method. \emph{American Naturalist}, \bold{125}, 1--15.
133 Martins, E. P. and Hansen, T. F. (1997) Phylogenies and the
134 comparative method: a general approach to incorporating phylogenetic
135 information into the analysis of interspecific data. \emph{American
136 Naturalist}, \bold{149}, 646--667.
138 Pagel, M. (1994) Detecting correlated evolution on phylogenies: a
139 general method for the comparative analysis of discrete
140 characters. \emph{Proceedings of the Royal Society of London. Series
141 B. Biological Sciences}, \bold{255}, 37--45.
143 Schluter, D., Price, T., Mooers, A. O. and Ludwig, D. (1997)
144 Likelihood of ancestor states in adaptive radiation. \emph{Evolution},
145 \bold{51}, 1699--1711.
147 \author{Emmanuel Paradis, Ben Bolker \email{bolker@zoo.ufl.edu}}
149 \code{\link{corBrownian}}, \code{\link{corGrafen}},
150 \code{\link{corMartins}}, \code{\link{compar.ou}},
151 \code{\link[stats]{anova}}
154 ### Just some random data...
157 ### Compare the three methods for continuous characters:
159 ace(x, bird.orders, method = "pic")
160 ace(x, bird.orders, method = "GLS",
161 corStruct = corBrownian(1, bird.orders))
162 ### For discrete characters:
163 x <- factor(c(rep(0, 5), rep(1, 18)))
164 ans <- ace(x, bird.orders, type = "d")
165 #### Showing the likelihoods on each node:
166 plot(bird.orders, type = "c", FALSE, label.offset = 1)
167 co <- c("blue", "yellow")
168 tiplabels(pch = 22, bg = co[as.numeric(x)], cex = 2, adj = 1)
169 nodelabels(thermo = ans$lik.anc, piecol = co, cex = 0.75)
170 ### An example of the use of the argument `ip':
172 tr[1] <- "((((t10:5.03,t2:5.03):2.74,(t9:4.17,"
173 tr[2] <- "t5:4.17):3.60):2.80,(t3:4.05,t7:"
174 tr[3] <- "4.05):6.53):2.32,((t6:4.38,t1:4.38):"
175 tr[4] <- "2.18,(t8:2.17,t4:2.17):4.39):6.33);"
176 tr <- read.tree(text = paste(tr, collapse = ""))
177 y <- c(rep(1, 6), rep(2, 4))
178 ### The default `ip = 0.1' makes ace fails:
179 ace(y, tr, type = "d")
180 ace(y, tr, type = "d", ip = 0.01)
181 ### Surprisingly, using an initial value farther to the
182 ### MLE than the default one works:
183 ace(y, tr, type = "d", ip = 0.3)