3 ## Ancestral Character Estimation
5 ## Copyright 2005-2012 Emmanuel Paradis and Ben Bolker
7 ## This file is part of the R-package `ape'.
8 ## See the file ../COPYING for licensing issues.
10 .getSEs <- function(out)
13 if (any(diag(h) == 0)) {
14 warning("The likelihood gradient seems flat in at least one dimension (gradient null):\ncannot compute the standard-errors of the transition rates.\n")
15 se <- rep(NaN, nrow(h))
17 se <- sqrt(diag(solve(h)))
22 ace <- function(x, phy, type = "continuous", method = "ML", CI = TRUE,
23 model = if (type == "continuous") "BM" else "ER",
24 scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1)
26 if (!inherits(phy, "phylo"))
27 stop('object "phy" is not of class "phylo"')
28 if (is.null(phy$edge.length))
29 stop("tree has no branch lengths")
30 type <- match.arg(type, c("continuous", "discrete"))
31 nb.tip <- length(phy$tip.label)
33 if (nb.node != nb.tip - 1)
34 stop('"phy" is not rooted AND fully dichotomous.')
35 if (length(x) != nb.tip)
36 stop("length of phenotypic and of phylogenetic data do not match.")
37 if (!is.null(names(x))) {
38 if(all(names(x) %in% phy$tip.label))
40 else warning("the names of 'x' and the tip labels of the tree do not match: the former were ignored in the analysis.")
43 if (kappa != 1) phy$edge.length <- phy$edge.length^kappa
44 if (type == "continuous") {
45 switch(method, "REML" = {
46 minusLogLik <- function(sig2) {
47 if (sig2 < 0) return(1e100)
49 ## next three lines borrowed from dmvnorm() in 'mvtnorm'
50 distval <- stats::mahalanobis(x, center = mu, cov = V)
51 logdet <- sum(log(eigen(V, symmetric = TRUE, only.values = TRUE)$values))
52 (nb.tip * log(2 * pi) + logdet + distval)/2
54 mu <- rep(ace(x, phy, method="pic")$ace[1], nb.tip)
55 out <- nlm(minusLogLik, 1, hessian = TRUE)
56 sigma2 <- out$estimate
57 se_sgi2 <- sqrt(1/out$hessian)
58 tip <- phy$edge[, 2] <= nb.tip
59 minus.REML.BM <- function(p) {
60 x1 <- p[phy$edge[, 1] - nb.tip]
61 x2 <- numeric(length(x1))
62 x2[tip] <- x[phy$edge[tip, 2]]
63 x2[!tip] <- p[phy$edge[!tip, 2] - nb.tip]
64 -(-sum((x1 - x2)^2/phy$edge.length)/(2 * sigma2) -
65 nb.node * log(sigma2))
67 out <- nlm(function(p) minus.REML.BM(p),
68 p = rep(mu[1], nb.node), hessian = TRUE)
69 obj$resloglik <- -out$minimum
70 obj$ace <- out$estimate
71 names(obj$ace) <- nb.tip + 1:nb.node
72 obj$sigma2 <- c(sigma2, se_sgi2)
75 tmp <- se * qt(0.025, nb.node)
76 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
80 stop('the "pic" method can be used only with model = "BM".')
81 ## See pic.R for some annotations.
82 phy <- reorder(phy, "pruningwise")
83 phenotype <- numeric(nb.tip + nb.node)
84 phenotype[1:nb.tip] <- if (is.null(names(x))) x else x[phy$tip.label]
85 contr <- var.con <- numeric(nb.node)
86 ans <- .C("pic", as.integer(nb.tip), as.integer(nb.node),
87 as.integer(phy$edge[, 1]), as.integer(phy$edge[, 2]),
88 as.double(phy$edge.length), as.double(phenotype),
89 as.double(contr), as.double(var.con),
90 as.integer(CI), as.integer(scaled),
92 obj$ace <- ans[[6]][-(1:nb.tip)]
93 names(obj$ace) <- nb.tip + 1:nb.node
96 tmp <- se * qnorm(0.025)
97 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
101 tip <- phy$edge[, 2] <= nb.tip
102 dev.BM <- function(p) {
103 if (p[1] < 0) return(1e100) # in case sigma² is negative
104 x1 <- p[-1][phy$edge[, 1] - nb.tip]
105 x2 <- numeric(length(x1))
106 x2[tip] <- x[phy$edge[tip, 2]]
107 x2[!tip] <- p[-1][phy$edge[!tip, 2] - nb.tip]
108 -2 * (-sum((x1 - x2)^2/phy$edge.length)/(2*p[1]) -
111 out <- nlm(function(p) dev.BM(p),
112 p = c(1, rep(mean(x), nb.node)), hessian = TRUE)
113 obj$loglik <- -out$minimum / 2
114 obj$ace <- out$estimate[-1]
115 names(obj$ace) <- (nb.tip + 1):(nb.tip + nb.node)
117 obj$sigma2 <- c(out$estimate[1], se[1])
119 tmp <- se[-1] * qt(0.025, nb.node)
120 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
124 if (is.null(corStruct))
125 stop('you must give a correlation structure if method = "GLS".')
126 if (class(corStruct)[1] == "corMartins")
127 M <- corStruct[1] * dist.nodes(phy)
128 if (class(corStruct)[1] == "corGrafen")
129 phy <- compute.brlen(attr(corStruct, "tree"),
131 power = exp(corStruct[1]))
132 if (class(corStruct)[1] %in% c("corBrownian", "corGrafen")) {
133 dis <- dist.nodes(attr(corStruct, "tree"))
134 MRCA <- mrca(attr(corStruct, "tree"), full = TRUE)
135 M <- dis[as.character(nb.tip + 1), MRCA]
136 dim(M) <- rep(sqrt(length(M)), 2)
138 varAY <- M[-(1:nb.tip), 1:nb.tip]
139 varA <- M[-(1:nb.tip), -(1:nb.tip)]
140 V <- corMatrix(Initialize(corStruct, data.frame(x)),
143 o <- gls(x ~ 1, data.frame(x), correlation = corStruct)
145 obj$ace <- drop(varAY %*% invV %*% (x - GM) + GM)
146 names(obj$ace) <- (nb.tip + 1):(nb.tip + nb.node)
148 se <- sqrt((varA - varAY %*% invV %*% t(varAY))[cbind(1:nb.node, 1:nb.node)])
149 tmp <- se * qnorm(0.025)
150 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
153 } else { # type == "discrete"
155 stop("only ML estimation is possible for discrete characters.")
156 if (!is.factor(x)) x <- factor(x)
160 if (is.character(model)) {
161 rate <- matrix(NA, nl, nl)
162 if (model == "ER") np <- rate[] <- 1
163 if (model == "ARD") {
165 rate[col(rate) != row(rate)] <- 1:np
167 if (model == "SYM") {
168 np <- nl * (nl - 1)/2
169 sel <- col(rate) < row(rate)
175 if (ncol(model) != nrow(model))
176 stop("the matrix given as 'model' is not square")
177 if (ncol(model) != nl)
178 stop("the matrix 'model' must have as many rows as the number of categories in 'x'")
183 tmp <- cbind(1:nl, 1:nl)
184 index.matrix[tmp] <- NA
186 rate[rate == 0] <- np + 1 # to avoid 0's since we will use this as numeric indexing
188 liks <- matrix(0, nb.tip + nb.node, nl)
190 liks[cbind(TIPS, x)] <- 1
191 phy <- reorder(phy, "pruningwise")
193 Q <- matrix(0, nl, nl)
194 dev <- function(p, output.liks = FALSE) {
195 if (any(is.nan(p)) || any(is.infinite(p))) return(1e50)
196 ## from Rich FitzJohn:
197 comp <- numeric(nb.tip + nb.node) # Storage...
199 diag(Q) <- -rowSums(Q)
200 for (i in seq(from = 1, by = 2, length.out = nb.node)) {
202 anc <- phy$edge[i, 1]
203 des1 <- phy$edge[i, 2]
204 des2 <- phy$edge[j, 2]
205 v.l <- matexpo(Q * phy$edge.length[i]) %*% liks[des1, ]
206 v.r <- matexpo(Q * phy$edge.length[j]) %*% liks[des2, ]
209 liks[anc, ] <- v/comp[anc]
211 if (output.liks) return(liks[-TIPS, ])
212 dev <- -2 * sum(log(comp[-TIPS]))
213 if (is.na(dev)) Inf else dev
215 out <- nlminb(rep(ip, length.out = np), function(p) dev(p),
216 lower = rep(0, np), upper = rep(1e50, np))
217 obj$loglik <- -out$objective/2
219 oldwarn <- options("warn")
221 out.nlm <- nlm(function(p) dev(p), p = obj$rates, iterlim = 1,
222 stepmax = 0, hessian = TRUE)
224 obj$se <- .getSEs(out.nlm)
225 obj$index.matrix <- index.matrix
227 obj$lik.anc <- dev(obj$rates, TRUE)
228 colnames(obj$lik.anc) <- lvls
231 obj$call <- match.call()
236 logLik.ace <- function(object, ...) object$loglik
238 deviance.ace <- function(object, ...) -2*object$loglik
240 AIC.ace <- function(object, ..., k = 2)
242 if (is.null(object$loglik)) return(NULL)
243 ## Trivial test of "type"; may need to be improved
244 ## if other models are included in ace(type = "c")
245 np <- if (!is.null(object$sigma2)) 1 else length(object$rates)
246 -2*object$loglik + np*k
250 anova.ace <- function(object, ...)
252 X <- c(list(object), list(...))
253 df <- sapply(lapply(X, "[[", "rates"), length)
254 ll <- sapply(X, "[[", "loglik")
255 ## check if models are in correct order?
256 dev <- c(NA, 2*diff(ll))
257 ddf <- c(NA, diff(df))
258 table <- data.frame(ll, df, ddf, dev,
259 pchisq(dev, ddf, lower.tail = FALSE))
260 dimnames(table) <- list(1:length(X), c("Log lik.", "Df",
261 "Df change", "Resid. Dev",
263 structure(table, heading = "Likelihood Ratio Test Table",
264 class = c("anova", "data.frame"))
267 print.ace <- function(x, digits = 4, ...)
269 cat("\n Ancestral Character Estimation\n\n")
273 if (!is.null(x$loglik))
274 cat(" Log-likelihood:", x$loglik, "\n\n")
275 if (!is.null(x$resloglik))
276 cat(" Residual log-likelihood:", x$resloglik, "\n\n")
277 ratemat <- x$index.matrix
278 if (is.null(ratemat)) { # to be improved
280 x$resloglik <- x$loglik <- x$call <- NULL
283 dimnames(ratemat)[1:2] <- dimnames(x$lik.anc)[2]
284 cat("Rate index matrix:\n")
285 print(ratemat, na.print = ".")
287 npar <- length(x$rates)
288 estim <- data.frame(1:npar, round(x$rates, digits), round(x$se, digits))
289 cat("Parameter estimates:\n")
290 names(estim) <- c("rate index", "estimate", "std-err")
291 print(estim, row.names = FALSE)
292 cat("\nScaled likelihoods at the root (type '...$lik.anc' to get them for all nodes):\n")
293 print(x$lik.anc[1, ])