MapCharacters: Map Changes in Ancestral Character States
In DECIPHER: Tools for curating, analyzing, and manipulating biological sequences

Description Usage Arguments Details Value Author(s) See Also Examples

Maps character changes on a phylogenetic tree containing reconstructed ancestral states.

MapCharacters(x,
              refPositions = seq_len(nchar(attr(x, "state")[1])),
              labelEdges = FALSE,
              type = "dendrogram",
              ignoreAmbiguity = TRUE,
              ignoreIndels = TRUE)

`x`	An object of class `dendrogram` with `"state"` attributes for each node.
`refPositions`	Numeric vector of reference positions in the original sequence alignment. Only changes at `refPositions` are reported, and state changes are labeled according to their position in `refPositions`.
`labelEdges`	Logical determining whether to label edges with the number of changes along each edge.
`type`	Character string indicating the type of output desired. This should be (an abbreviation of) one of `"dendrogram"`, `"table"`, or `"both"`. (See value section below.)
`ignoreAmbiguity`	Logical specifying whether to report changes involving ambiguities. If `TRUE` (the default), changes involving `"N"` and other ambiguity codes are ignored.
`ignoreIndels`	Logical specifying whether to report insertions and deletions (indels). If `TRUE` (the default), only substitutions of one state with another are reported.

Ancestral state reconstruction affords the ability to identify character changes that occurred along edges of a rooted phylogenetic tree. Character changes are reported according to their index in refPositions. If ignoreIndels is FALSE, adjacent insertions and deletions are merged into single changes occurring at their first position. The table of changes can be used to identify parallel, convergent, and divergent mutations.

If type is "dendrogram" (the default) then the original dendrogram x is returned with the addition of "change" attributes on every edge except the root. If type is "table" then a sorted table of character changes is returned with the most frequent parallel changes at the beginning. If type is "both" then a list of length 2 is provided containing both the dendrogram and table.

Erik Wright eswright@pitt.edu

IdClusters

fas <- system.file("extdata", "Bacteria_175seqs.fas", package="DECIPHER")
dna <- readDNAStringSet(fas)

# align the sequences
rna <- RNAStringSet(RemoveGaps(dna))
rna <- AlignSeqs(rna)
rna # input alignment

d <- DistanceMatrix(rna, type="dist", correction="JC")
tree <- IdClusters(d,
                   method="NJ",
                   type="dendrogram",
                   myXStringSet=rna,
                   reconstruct=TRUE)

out <- MapCharacters(tree, labelEdges=TRUE, type="both")

# plot the tree with defaults
tree <- out[[1]]
plot(tree, horiz=TRUE) # edges show number of changes

# color edges by number of changes
maxC <- 200 # changes at maximum of color spectrum
colors <- colorRampPalette(c("black", "darkgreen", "green"))(maxC)
colorEdges <- function(x) {
   num <- attr(x, "edgetext") + 1
   if (length(num)==0)
       return(x)
   if (num > maxC)
       num <- maxC
   attr(x, "edgePar") <- list(col=colors[num])
   attr(x, "edgetext") <- NULL
   return(x)
}
colorfulTree <- dendrapply(tree, colorEdges)
plot(colorfulTree, horiz=TRUE, leaflab="none")

# look at parallel changes (X->Y)
parallel <- out[[2]]
head(parallel) # parallel changes

# look at convergent changes (*->Y)
convergent <- gsub(".*?([0-9]+.*)", "\\1", names(parallel))
convergent <- tapply(parallel, convergent, sum)
convergent <- sort(convergent, decreasing=TRUE)
head(convergent)

# look at divergent changes (X->*)
divergent <- gsub("(.*[0-9]+).*", "\\1", names(parallel))
divergent <- tapply(parallel, divergent, sum)
divergent <- sort(divergent, decreasing=TRUE)
head(divergent)

# plot number of changes by position
changes <- gsub(".*?([0-9]+).*", "\\1", names(parallel))
changes <- tapply(parallel, changes, sum)
plot(as.numeric(names(changes)),
     changes,
     xlab="Position",
     ylab="Total independent changes")

# count cases of potential compensatory mutations
compensatory <- dendrapply(tree,
    function(x) {
        change <- attr(x, "change")
        pos <- as.numeric(gsub(".*?([0-9]+).*", "\\1", change))
        e <- expand.grid(seq_along(pos), seq_along(pos))
        e <- e[pos[e[, 1]] < pos[e[, 2]],]
        list(paste(change[e[, 1]], change[e[, 2]], sep=" & "))
    })
compensatory <- unlist(compensatory)
u <- unique(compensatory)
m <- match(compensatory, u)
m <- tabulate(m, length(u))
compensatory <- sort(setNames(m, u), decreasing=TRUE)
head(compensatory) # ranked list of concurrent mutations