R/ace.R

   1 ## ace.R (2013-03-18)
   2
   3 ##   Ancestral Character Estimation
   4
   5 ## Copyright 2005-2013 Emmanuel Paradis and Ben Bolker
   6
   7 ## This file is part of the R-package `ape'.
   8 ## See the file ../COPYING for licensing issues.
   9
  10 .getSEs <- function(out)
  11 {
  12     h <- out$hessian
  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))
  16     } else {
  17         se <- sqrt(diag(solve(h)))
  18     }
  19     se
  20 }
  21
  22 ace <-
  23   function(x, phy, type = "continuous",
  24            method = if (type == "continuous") "REML" else "ML",
  25            CI = TRUE, model = if (type == "continuous") "BM" else "ER",
  26            scaled = TRUE, kappa = 1, corStruct = NULL, ip = 0.1,
  27            use.expm = FALSE)
  28 {
  29     if (!inherits(phy, "phylo"))
  30         stop('object "phy" is not of class "phylo"')
  31     if (is.null(phy$edge.length))
  32         stop("tree has no branch lengths")
  33     type <- match.arg(type, c("continuous", "discrete"))
  34     nb.tip <- length(phy$tip.label)
  35     nb.node <- phy$Nnode
  36     if (nb.node != nb.tip - 1)
  37         stop('"phy" is not rooted AND fully dichotomous.')
  38     if (length(x) != nb.tip)
  39         stop("length of phenotypic and of phylogenetic data do not match.")
  40     if (!is.null(names(x))) {
  41         if(all(names(x) %in% phy$tip.label))
  42           x <- x[phy$tip.label]
  43         else warning("the names of 'x' and the tip labels of the tree do not match: the former were ignored in the analysis.")
  44     }
  45     obj <- list()
  46     if (kappa != 1) phy$edge.length <- phy$edge.length^kappa
  47     if (type == "continuous") {
  48         switch(method, "REML" = {
  49             minusLogLik <- function(sig2) {
  50                 if (sig2 < 0) return(1e100)
  51                 V <- sig2 * vcv(phy)
  52                 ## next three lines borrowed from dmvnorm() in 'mvtnorm'
  53                 distval <- stats::mahalanobis(x, center = mu, cov = V)
  54                 logdet <- sum(log(eigen(V, symmetric = TRUE, only.values = TRUE)$values))
  55                 (nb.tip * log(2 * pi) + logdet + distval)/2
  56             }
  57             mu <- rep(ace(x, phy, method="pic")$ace[1], nb.tip)
  58             out <- nlm(minusLogLik, 1, hessian = TRUE)
  59             sigma2 <- out$estimate
  60             se_sgi2 <- sqrt(1/out$hessian)
  61             tip <- phy$edge[, 2] <= nb.tip
  62             minus.REML.BM <- function(p) {
  63                 x1 <- p[phy$edge[, 1] - nb.tip]
  64                 x2 <- numeric(length(x1))
  65                 x2[tip] <- x[phy$edge[tip, 2]]
  66                 x2[!tip] <- p[phy$edge[!tip, 2] - nb.tip]
  67                 -(-sum((x1 - x2)^2/phy$edge.length)/(2 * sigma2) -
  68                   nb.node * log(sigma2))
  69             }
  70             out <- nlm(function(p) minus.REML.BM(p),
  71                        p = rep(mu[1], nb.node), hessian = TRUE)
  72             obj$resloglik <- -out$minimum
  73             obj$ace <- out$estimate
  74             names(obj$ace) <- nb.tip + 1:nb.node
  75             obj$sigma2 <- c(sigma2, se_sgi2)
  76             if (CI) {
  77                 se <- .getSEs(out)
  78                 tmp <- se * qt(0.025, nb.node)
  79                 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
  80             }
  81         }, "pic" = {
  82             if (model != "BM")
  83                 stop('the "pic" method can be used only with model = "BM".')
  84             ## See pic.R for some annotations.
  85             phy <- reorder(phy, "pruningwise")
  86             phenotype <- numeric(nb.tip + nb.node)
  87             phenotype[1:nb.tip] <- if (is.null(names(x))) x else x[phy$tip.label]
  88             contr <- var.con <- numeric(nb.node)
  89             ans <- .C("pic", as.integer(nb.tip), as.integer(nb.node),
  90                       as.integer(phy$edge[, 1]), as.integer(phy$edge[, 2]),
  91                       as.double(phy$edge.length), as.double(phenotype),
  92                       as.double(contr), as.double(var.con),
  93                       as.integer(CI), as.integer(scaled),
  94                       PACKAGE = "ape")
  95             obj$ace <- ans[[6]][-(1:nb.tip)]
  96             names(obj$ace) <- nb.tip + 1:nb.node
  97             if (CI) {
  98                 se <- sqrt(ans[[8]])
  99                 tmp <- se * qnorm(0.025)
 100                 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
 101             }
 102         }, "ML" = {
 103             if (model == "BM") {
 104                 tip <- phy$edge[, 2] <= nb.tip
 105                 dev.BM <- function(p) {
 106                     if (p[1] < 0) return(1e100) # in case sigma² is negative
 107                     x1 <- p[-1][phy$edge[, 1] - nb.tip]
 108                     x2 <- numeric(length(x1))
 109                     x2[tip] <- x[phy$edge[tip, 2]]
 110                     x2[!tip] <- p[-1][phy$edge[!tip, 2] - nb.tip]
 111                     -2 * (-sum((x1 - x2)^2/phy$edge.length)/(2*p[1]) -
 112                           nb.node * log(p[1]))
 113                 }
 114                 out <- nlm(function(p) dev.BM(p),
 115                            p = c(1, rep(mean(x), nb.node)), hessian = TRUE)
 116                 obj$loglik <- -out$minimum / 2
 117                 obj$ace <- out$estimate[-1]
 118                 names(obj$ace) <- (nb.tip + 1):(nb.tip + nb.node)
 119                 se <- .getSEs(out)
 120                 obj$sigma2 <- c(out$estimate[1], se[1])
 121                 if (CI) {
 122                     tmp <- se[-1] * qt(0.025, nb.node)
 123                     obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
 124                 }
 125             }
 126         }, "GLS" = {
 127             if (is.null(corStruct))
 128                 stop('you must give a correlation structure if method = "GLS".')
 129             if (class(corStruct)[1] == "corMartins")
 130                 M <- corStruct[1] * dist.nodes(phy)
 131             if (class(corStruct)[1] == "corGrafen")
 132                 phy <- compute.brlen(attr(corStruct, "tree"),
 133                                      method = "Grafen",
 134                                      power = exp(corStruct[1]))
 135             if (class(corStruct)[1] %in% c("corBrownian", "corGrafen")) {
 136                 dis <- dist.nodes(attr(corStruct, "tree"))
 137                 MRCA <- mrca(attr(corStruct, "tree"), full = TRUE)
 138                 M <- dis[as.character(nb.tip + 1), MRCA]
 139                 dim(M) <- rep(sqrt(length(M)), 2)
 140             }
 141             varAY <- M[-(1:nb.tip), 1:nb.tip]
 142             varA <- M[-(1:nb.tip), -(1:nb.tip)]
 143             V <- corMatrix(Initialize(corStruct, data.frame(x)),
 144                            corr = FALSE)
 145             invV <- solve(V)
 146             o <- gls(x ~ 1, data.frame(x), correlation = corStruct)
 147             GM <- o$coefficients
 148             obj$ace <- drop(varAY %*% invV %*% (x - GM) + GM)
 149             names(obj$ace) <- (nb.tip + 1):(nb.tip + nb.node)
 150             if (CI) {
 151                 se <- sqrt((varA - varAY %*% invV %*% t(varAY))[cbind(1:nb.node, 1:nb.node)])
 152                 tmp <- se * qnorm(0.025)
 153                 obj$CI95 <- cbind(obj$ace + tmp, obj$ace - tmp)
 154             }
 155         })
 156     } else { # type == "discrete"
 157         if (method != "ML")
 158             stop("only ML estimation is possible for discrete characters.")
 159         if (!is.factor(x)) x <- factor(x)
 160         nl <- nlevels(x)
 161         lvls <- levels(x)
 162         x <- as.integer(x)
 163         if (is.character(model)) {
 164             rate <- matrix(NA, nl, nl)
 165             if (model == "ER") np <- rate[] <- 1
 166             if (model == "ARD") {
 167                 np <- nl*(nl - 1)
 168                 rate[col(rate) != row(rate)] <- 1:np
 169             }
 170             if (model == "SYM") {
 171                 np <- nl * (nl - 1)/2
 172                 sel <- col(rate) < row(rate)
 173                 rate[sel] <- 1:np
 174                 rate <- t(rate)
 175                 rate[sel] <- 1:np
 176             }
 177         } else {
 178             if (ncol(model) != nrow(model))
 179               stop("the matrix given as 'model' is not square")
 180             if (ncol(model) != nl)
 181               stop("the matrix 'model' must have as many rows as the number of categories in 'x'")
 182             rate <- model
 183             np <- max(rate)
 184         }
 185         index.matrix <- rate
 186         tmp <- cbind(1:nl, 1:nl)
 187         index.matrix[tmp] <- NA
 188         rate[tmp] <- 0
 189         rate[rate == 0] <- np + 1 # to avoid 0's since we will use this as numeric indexing
 190
 191         liks <- matrix(0, nb.tip + nb.node, nl)
 192         TIPS <- 1:nb.tip
 193         liks[cbind(TIPS, x)] <- 1
 194         phy <- reorder(phy, "pruningwise")
 195
 196         ## E <- if (use.expm) expm::expm else ape::matexpo
 197         E <- if (use.expm) {
 198             library(expm)
 199             get("expm", "package:expm")
 200         } else ape::matexpo
 201
 202         Q <- matrix(0, nl, nl)
 203         dev <- function(p, output.liks = FALSE) {
 204             if (any(is.nan(p)) || any(is.infinite(p))) return(1e50)
 205             ## from Rich FitzJohn:
 206             comp <- numeric(nb.tip + nb.node) # Storage...
 207             Q[] <- c(p, 0)[rate]
 208             diag(Q) <- -rowSums(Q)
 209             for (i  in seq(from = 1, by = 2, length.out = nb.node)) {
 210                 j <- i + 1L
 211                 anc <- phy$edge[i, 1]
 212                 des1 <- phy$edge[i, 2]
 213                 des2 <- phy$edge[j, 2]
 214                 v.l <- E(Q * phy$edge.length[i]) %*% liks[des1, ]
 215                 v.r <- E(Q * phy$edge.length[j]) %*% liks[des2, ]
 216                 v <- v.l * v.r
 217                 comp[anc] <- sum(v)
 218                 liks[anc, ] <- v/comp[anc]
 219             }
 220             if (output.liks) return(liks[-TIPS, ])
 221             dev <- -2 * sum(log(comp[-TIPS]))
 222             if (is.na(dev)) Inf else dev
 223         }
 224         out <- nlminb(rep(ip, length.out = np), function(p) dev(p),
 225                       lower = rep(0, np), upper = rep(1e50, np))
 226         obj$loglik <- -out$objective/2
 227         obj$rates <- out$par
 228         oldwarn <- options("warn")
 229         options(warn = -1)
 230         out.nlm <- nlm(function(p) dev(p), p = obj$rates, iterlim = 1,
 231                        stepmax = 0, hessian = TRUE)
 232         options(oldwarn)
 233         obj$se <- .getSEs(out.nlm)
 234         obj$index.matrix <- index.matrix
 235         if (CI) {
 236             obj$lik.anc <- dev(obj$rates, TRUE)
 237             colnames(obj$lik.anc) <- lvls
 238         }
 239     }
 240     obj$call <- match.call()
 241     class(obj) <- "ace"
 242     obj
 243 }
 244
 245 logLik.ace <- function(object, ...) object$loglik
 246
 247 deviance.ace <- function(object, ...) -2*object$loglik
 248
 249 AIC.ace <- function(object, ..., k = 2)
 250 {
 251     if (is.null(object$loglik)) return(NULL)
 252     ## Trivial test of "type"; may need to be improved
 253     ## if other models are included in ace(type = "c")
 254     np <- if (!is.null(object$sigma2)) 1 else length(object$rates)
 255     -2*object$loglik + np*k
 256 }
 257
 258 ### by BB:
 259 anova.ace <- function(object, ...)
 260 {
 261     X <- c(list(object), list(...))
 262     df <- sapply(lapply(X, "[[", "rates"), length)
 263     ll <- sapply(X, "[[", "loglik")
 264     ## check if models are in correct order?
 265     dev <- c(NA, 2*diff(ll))
 266     ddf <- c(NA, diff(df))
 267     table <- data.frame(ll, df, ddf, dev,
 268                         pchisq(dev, ddf, lower.tail = FALSE))
 269     dimnames(table) <- list(1:length(X), c("Log lik.", "Df",
 270                                            "Df change", "Resid. Dev",
 271                                            "Pr(>|Chi|)"))
 272     structure(table, heading = "Likelihood Ratio Test Table",
 273               class = c("anova", "data.frame"))
 274 }
 275
 276 print.ace <- function(x, digits = 4, ...)
 277 {
 278     cat("\n    Ancestral Character Estimation\n\n")
 279     cat("Call: ")
 280     print(x$call)
 281     cat("\n")
 282     if (!is.null(x$loglik))
 283         cat("    Log-likelihood:", x$loglik, "\n\n")
 284     if (!is.null(x$resloglik))
 285         cat("    Residual log-likelihood:", x$resloglik, "\n\n")
 286     ratemat <- x$index.matrix
 287     if (is.null(ratemat)) { # to be improved
 288         class(x) <- NULL
 289         x$resloglik <- x$loglik <- x$call <- NULL
 290         print(x)
 291     } else {
 292         dimnames(ratemat)[1:2] <- dimnames(x$lik.anc)[2]
 293         cat("Rate index matrix:\n")
 294         print(ratemat, na.print = ".")
 295         cat("\n")
 296         npar <- length(x$rates)
 297         estim <- data.frame(1:npar, round(x$rates, digits), round(x$se, digits))
 298         cat("Parameter estimates:\n")
 299         names(estim) <- c("rate index", "estimate", "std-err")
 300         print(estim, row.names = FALSE)
 301         cat("\nScaled likelihoods at the root (type '...$lik.anc' to get them for all nodes):\n")
 302         print(x$lik.anc[1, ])
 303     }
 304 }