viewing tree with ggtree

ggtree extend ggplot to support viewing phylogenetic tree. It implements geom_tree layer for displaying phylogenetic trees, as shown below:

nwk <- system.file("extdata", "sample.nwk", package="ggtree")
x <- readLines(nwk)
cat(substring(x, 1, 56), "\n", substring(x, 57), "\n")

## (((((((A:4,B:4):6,C:5):8,D:6):3,E:21):10,((F:4,G:12):14, 
##  H:8):13):13,((I:5,J:2):30,(K:11,L:11):2):17):4,M:56);

library("ggplot2")
library("ggtree")

tree <- read.tree(nwk)
ggplot(tree, aes(x, y)) + geom_tree() + theme_tree() + xlab("") + ylab("")

This example tree was obtained from Chapter 34 of Inferring Phylogenies³. The function, ggtree, was implemented as a short cut to visualize a tree, and it works exactly the same as shown above.

ggtree takes all the advantages of ggplot2. For example, we can change the color, size and type of the lines as we do with ggplot2.

ggtree(tree, color="steelblue", size=0.5, linetype="dotted")

By default, the tree is viewing in ladderize form, user can set the parameter ladderize = FALSE to disable it.

ggtree(tree, ladderize=FALSE)

The branch.length is used to scale the edge, user can set the parameter branch.length = "none" to only viewing the tree topology (cladogram) or other numerical variable to scale the tree (e.g. dN/dS).

ggtree(tree, branch.length="none")

support multiple phylogenetic classes

ggtree defined several S4 classes to store phylogenetic object and its associated annotation, including:

• beast
• codeml_mlc
• codeml
• hyphy
• jplace
• paml_rst
• raxml
• r8s

In addition, it also supports phylo (defined by ape⁴), and phylo4 (defined by phylobase)

User can use ggtree(object) command to view the phylogenetic tree directly, and annotation data stored in these objects can be added as demonstrated in Tree annotation with output from evolution software session.

layout

Currently, ggtree supports several layout, including:

• rectangular (by default)
• slanted
• fan or circular

for Phylogram (by default) and Cladogram if user explicitly setting branch.length='none'.

And unrooted layout.

Unrooted layout was implemented by the equal-angle algorithm that described in Inferring Phylogenies³.

library("gridExtra")
grid.arrange(ggtree(tree) + ggtitle("(Phylogram) rectangular layout"),
             ggtree(tree, branch.length='none') + ggtitle("(Cladogram) rectangular layout"),
         ggtree(tree, layout="slanted") + ggtitle("(Phylogram) slanted layout"),
             ggtree(tree, layout="slanted", branch.length='none') + ggtitle("(Cladogram) slanted layout"),
         ggtree(tree, layout="circular") + ggtitle("(Phylogram) circular layout"),
             ggtree(tree, layout="circular", branch.length="none") + ggtitle("(Cladogram) circular layout"),
         ggtree(tree, layout="unrooted") + ggtitle("unrooted layout"),
         ncol=2)

tree2d <- read.beast(system.file("extdata", "twoD.tree", package="ggtree"))
ggtree(tree2d, mrsd = "2014-05-01",
       yscale="NGS", yscale_mapping=c(N2=2, N3=3, N4=4, N5=5, N6=6, N7=7)) +
           theme_classic() + 
               theme(panel.grid.major=element_line(color="grey20", linetype="dotted", size=.3),
                     panel.grid.major.y=element_blank()) +
                         scale_y_continuous(labels=paste0("N", 2:7))

display evolution distance

To show evolution distance, user can use add_legend function.

ggtree(tree) %>% add_legend()

We can also use theme_tree2() or ggtree(showDistance=TRUE)

ggtree(tree) + theme_tree2()

display nodes/tips

Show all the internal nodes and tips in the tree can be done by adding a layer of points using geom_nodepoint, geom_tippoint or geom_point.

ggtree(tree)+geom_point(aes(shape=isTip, color=isTip), size=3)

p <- ggtree(tree) + geom_nodepoint(color="#b5e521", alpha=1/4, size=10)
p + geom_tippoint(color="#FDAC4F", shape=8, size=3)

display labels

Users can use geom_text to display the node/tip labels:

p + geom_text(aes(label=label), size=3, color="purple", hjust=-0.3)

For circular and unrooted layout, ggtree supports rotating node labels according to the angles of the branches.

ggtree(tree, layout="circular") + geom_text(aes(label=label, angle=angle), size=3, color="purple", vjust=-0.3)

By default, the positions are based on the node positions, we can change them to based on the middle of the branch/edge.

p + geom_text(aes(x=branch, label=label), size=3, color="purple", vjust=-0.3)

Based on the middle of branches is very useful when annotating transition from parent node to child node.

theme

theme_tree() defined a totally blank canvas, while theme_tree2() add phylogenetic distance legend. These two themes all accept a parameter of bgcolor that defined the background color.

grid.arrange(
    ggtree(rtree(30), color="red") + theme_tree("steelblue"),
    ggtree(rtree(20), color="white") + theme_tree("black"),
    ncol=2)

update tree viewing with a new tree

In the display nodes/tips section, we have a p object that stored the tree viewing of 13 tips and internal nodes highlighted with specific colored big dots. If you want to applied this pattern (we can imaging a more complex one) to a new tree, you don’t need to build the tree step by step. ggtree provides an operator, %<%, for applying the visualization pattern to a new tree.

For example, the pattern in the p object will be applied to a new tree with 50 tips as shown below:

p %<% rtree(50)

Another example can be found in CODEML session.

zoom on a portion of tree

ggtree provides gzoom function that similar to zoom function provided in ape. This function plots simultaneously a whole phylogenetic tree and a portion of it. It aims at exploring very large trees.

library("ape")
data(chiroptera)
library("ggtree")
gzoom(chiroptera, grep("Plecotus", chiroptera$tip.label))

color tree

In ggtree, coloring phylogenetic tree is easy, by using aes(color=VAR) to map the color of tree based on a specific variable (numeric and category are both supported).

ggtree(tree, aes(color=branch.length)) +
    scale_color_continuous(low="green", high="red") +
        theme(legend.position="bottom")

User can use any feature, including clade posterior and dN/dS etc., to scale the color of the tree.

annotate clade

ggtree implements annotation_clade and annotation_clade2 functions to annotate a selected clade with a bar indicating that clade with a corresponding label.

The annotation_clade function accepts a selected internal node number and annotates that selected clade, while annotation_clade2 functions accepts two tip labels (upper one and lower one) to annotate the clade.

User can use geom_text to display all the node numbers, and select interesting clade to annotate.

ggtree(tree) + geom_text(aes(label=node))

p <- ggtree(tree) + geom_tiplab()
annotation_clade(p, node=17, "selected clade", offset.text=2)

annotation_clade2(p, "B", "E", "Clade X", offset.text=2) %>%
    annotation_clade2("G", "H", "Clade Y", bar.size=4, font.size=8, offset=5, offset.text=4, color="steelblue")

The parameter bar.size is used to control the width of the bar and the font.size parameter is to control the font size of the clade lable. The parameter offset is used to control the distance from the annotation to the tree, while offset.text to control the distance from clade label to bar.

highlight clades

ggtree implements hilight function, that accepts tree view and internal node number and add a layer of rectangle to highlight the selected clade.

ggtree(tree) %>% hilight(node=21, fill="steelblue", alpha=.6) %>%
    hilight(node=17, fill="darkgreen", alpha=.6)

ggtree(tree, layout="fan") %>% hilight(node=21, fill="steelblue", alpha=.6) %>%
     hilight(node=23, fill="darkgreen", alpha=.6)

Another way to highlight selected clades is setting the clades with different colors and/or line types as demonstrated in group clades section.

collapse clade

With collapse function, user can collapse a selected clade.

cp <- ggtree(tree) %>% collapse(node=21)
cp + geom_point(subset=.(node == 21), size=5, shape=23, fill="steelblue")

expand collapsed clade

The collapsed clade can be expanded via expand function.

cp %>% expand(node=21)

flip clades

The positions of two selected branches can be flip over using flip function.

set.seed(2015-06-30)
p1 <- ggtree(rtree(30)) + geom_text(aes(label=node))
p2 <- flip(p1, node1=45, node2=33)
p3 <- flip(p2, 32, 58)
grid.arrange(p1, p2, p3, ncol=3)

rotate clade

A selected clade can be rotated by 180 degree using rotate function.

set.seed(2015-07-01)
p1 <- ggtree(rtree(30)) + geom_text(aes(label=node))
p1 <- hilight(p1, 33)
p2 <- rotate(p1, 33)
grid.arrange(p1, p2, ncol=2)

group OTUs

ggtree provides groupOTU function to group tips and all their related ancestors.

tree <- groupOTU(tree, focus=c("A", "B", "C", "D", "E"))

ggtree(tree, aes(color=group)) + geom_tiplab()

groupOTU can also input a list of tip groups.

cls <- list(c1=c("A", "B", "C", "D", "E"),
            c2=c("F", "G", "H"),
            c3=c("L", "K", "I", "J"),
            c4="M")

tree <- groupOTU(tree, cls)
library("colorspace")
ggtree(tree, aes(color=group, linetype=group)) + geom_text(aes(label=label),  hjust=-.25) +
     scale_color_manual(values=c("black", rainbow_hcl(4))) + theme(legend.position="right")

groupOTU also work with tree view (ggplot2 object).

p <- ggtree(tree)
groupOTU(p, LETTERS[1:5]) + aes(color=group) + geom_tiplab() + scale_color_manual(values=c("black", "firebrick"))

data(iris)
rn <- paste0(iris[,5], "_", 1:150)
rownames(iris) <- rn
d_iris <- dist(iris[,-5], method="man")

tree_iris <- bionj(d_iris)
tree_iris <- groupOTU(tree_iris, list(setosa    = rn[1:50],
                versicolor    = rn[51:100],
                virginica_145 = rn[101:150]))
cols <- rainbow_hcl(4)
ggtree(tree_iris, aes(color=group)) +
    geom_text(aes(label=label), hjust=-.1) +
        scale_color_manual(values=cols, breaks=1:3,
                           labels=c("Setosa", "Versicolor", "Virginica")) +
                               theme(legend.position="right")

group clades

As demonstrated above, groupOTU is used for clustering related OTUs. Related OTUs are not necessarily within a clade, they can be distantly related as demonstrated in iris example. groupOTU works fine for monophyletic (clade), polyphyletic and paraphyletic. If user wants to hilight a specific clade, we provides a more friendly function groupClade that accept an internal node or a vector of internal nodes to cluster clade/clades that works similar to groupOTU. User can also use hilight function demonstrated in hilight clades section for highlighting selected clades.

tree <- groupClade(tree, node=21)
ggtree(tree, aes(color=group, linetype=group))

tree <- groupClade(tree, node=c(21, 17))
ggtree(tree, aes(color=group, linetype=group))

It also works with tree view, just like groupOTU.

With groupOTU and groupClade, it’s easy to highlight selected taxa and easy to selecte taxa to display related feature.

ggtree(tree, aes(color=group, linetype=group)) +
    geom_text(aes(label=label), subset=.(group==2), hjust = -.5) +
        geom_text(aes(label=label), subset=.(group==1), hjust = -.5, color="blue")

scale clade

In collapse clade, we have illustrated how to collapse selected clades. Another approach is to zoom out clade to a small scale.

grid.arrange(ggtree(tree) %>% hilight(21, "steelblue"),
             ggtree(tree) %>% scaleClade(21, scale=0.3) %>% hilight(21, "steelblue"),
             ncol=2)

Of course, scaleClade can accept scale larger than 1 and zoom in the selected portion.

grid.arrange(ggtree(tree) %>% hilight(17, fill="steelblue") %>%
                 hilight(21, fill="darkgreen"),
             ggtree(tree) %>% scaleClade(17, scale=2) %>% scaleClade(21, scale=0.3) %>%
                 hilight(17, "steelblue") %>% hilight(21, fill="darkgreen"),
             ncol=2)

annotating tree with BEAST output

file <- system.file("extdata/BEAST", "beast_mcc.tree", package="ggtree")
beast <- read.beast(file)
beast

## 'beast' S4 object that stored information of
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/BEAST/beast_mcc.tree'.
## 
## ...@ tree: 
## Phylogenetic tree with 15 tips and 14 internal nodes.
## 
## Tip labels:
##  A_1995, B_1996, C_1995, D_1987, E_1996, F_1997, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features available:
##   'height',  'height_0.95_HPD',  'height_median',    'height_range', 'length',
##   'length_0.95_HPD', 'length_median',    'length_range', 'posterior',    'rate',
##   'rate_0.95_HPD',   'rate_median',  'rate_range'.

Since % is not a valid character in names, all the feature names that contain x% will convert to 0.x. For example, length_95%_HPD will be changed to length_0.95_HPD.

plot(beast, annotation="length_0.95_HPD", branch.length="none") + theme_tree()

User can round the digits by setting the parameter ndigits. The default value is 2.

plot(beast, annotation="height", ndigits=3, annotation.color="red")

annotating tree with PAML output

rstfile <- system.file("extdata/PAML_Baseml", "rst", package="ggtree")
rst <- read.paml_rst(rstfile)
rst

## 'paml_rst' S4 object that stored information of
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/PAML_Baseml/rst'.
## 
## ...@ tree:
## Phylogenetic tree with 15 tips and 13 internal nodes.
## 
## Tip labels:
##  A, B, C, D, E, F, ...
## Node labels:
##  16, 17, 18, 19, 20, 21, ...
## 
## Unrooted; includes branch lengths.
## 
## with the following features available:
##   'marginal_subs',   'joint_subs',   'marginal_AA_subs', 'joint_AA_subs'.

p <- plot(rst, annotation="marginal_AA_subs", annotation.color="steelblue")
print(p)

rstfile <- system.file("extdata/PAML_Codeml", "rst", package="ggtree")
rst <- read.paml_rst(rstfile)
p %<% rst

mlcfile <- system.file("extdata/PAML_Codeml", "mlc", package="ggtree")
mlc <- read.codeml_mlc(mlcfile)
mlc

## 'codeml_mlc' S4 object that stored information of
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/PAML_Codeml/mlc'. 
## 
## ...@ tree:
## Phylogenetic tree with 15 tips and 13 internal nodes.
## 
## Tip labels:
##  A, B, C, D, E, F, ...
## Node labels:
##  16, 17, 18, 19, 20, 21, ...
## 
## Unrooted; includes branch lengths.
## 
## with the following features available:
##   't',   'N',    'S',    'dN_vs_dS', 'dN',   'dS',   'N_x_dN',   'S_x_dS'.

plot(mlc, branch.length="branch.length", annotation="dN_vs_dS", annotation.color="blue", ndigits=3)

get.fields(mlc)

## [1] "t"        "N"        "S"        "dN_vs_dS" "dN"       "dS"      
## [7] "N_x_dN"   "S_x_dS"

plot(mlc, branch.length="dN_vs_dS", annotation="dN_vs_dS", ndigits=3)

ml <- read.codeml(rstfile, mlcfile)
ml

## 'codeml' S4 object that stored information of
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/PAML_Codeml/rst' and 
##  '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/PAML_Codeml/mlc'. 
## 
## ...@ tree:
## Phylogenetic tree with 15 tips and 13 internal nodes.
## 
## Tip labels:
##  A, B, C, D, E, F, ...
## Node labels:
##  16, 17, 18, 19, 20, 21, ...
## 
## Unrooted; includes branch lengths.
## 
## with the following features available:
##   'marginal_subs',   'joint_subs',   'marginal_AA_subs', 'joint_AA_subs',
##   't',   'N',    'S',    'dN_vs_dS',
##   'dN',  'dS',   'N_x_dN',   'S_x_dS',
## .

plot(ml, branch.length="rst.branch.length", annotation="dN_vs_dS")

plot(ml, branch.length="mlc.branch.length", annotation="marginal_AA_subs")

plot(ml, branch.length="dN", annotation="joint_AA_subs", annotation.color="darkgreen")

annotating tree with HYPHY output

nwk <- system.file("extdata/HYPHY", "labelledtree.tree", package="ggtree")
ancseq <- system.file("extdata/HYPHY", "ancseq.nex", package="ggtree")
tipfas <- system.file("extdata", "pa.fas", package="ggtree")
hy <- read.hyphy(nwk, ancseq, tipfas)
hy

## 'hyphy' S4 object that stored information of 
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/HYPHY/labelledtree.tree', 
##  '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/HYPHY/ancseq.nex' and 
##  '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/pa.fas'. 
## 
## ...@ tree:
## Phylogenetic tree with 15 tips and 13 internal nodes.
## 
## Tip labels:
##  K, N, D, L, J, G, ...
## Node labels:
##  Node1, Node2, Node3, Node4, Node5, Node12, ...
## 
## Unrooted; includes branch lengths.
## 
## with the following features available:
##   'subs',    'AA_subs'.

plot(hy, annotation="AA_subs")

annotating tree with RAxML bootstraping analysis

raxml_file <- system.file("extdata/RAxML", "RAxML_bipartitionsBranchLabels.H3", package="ggtree")
raxml <- read.raxml(raxml_file)
plot(raxml)

annotating tree with r8s output

r8s output contains 3 trees, namely TREE, RATO and PHYLO for time tree, rate tree and absolute substitution tree respectively.

r8s <- read.r8s(system.file("extdata/r8s", "H3_r8s_output.log", package="ggtree"))
ggtree(r8s, branch.length="TREE", mrsd="2014-01-01") + theme_tree2()

branch.length should be one of TREE, RATO or PHYLO for selecting the corresponding tree.

User can also view 3 trees simultaneously.

ggtree(get.tree(r8s)) + facet_wrap(~.id, scales="free_x") + theme_tree2()

annotating tree with EPA and PPLACER output

EPA⁷ and PPLACER⁸ have common output file format, jplace.

jpf <- system.file("extdata/sample.jplace",  package="ggtree")
jp <- read.jplace(jpf)
print(jp)

## 'jplace' S4 object that stored information of
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/sample.jplace'. 
## 
## ...@ tree: 
## Phylogenetic tree with 13 tips and 12 internal nodes.
## 
## Tip labels:
##  A, B, C, D, E, F, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features availables:
##   'edge_num',    'likelihood',   'like_weight_ratio',    'distal_length',    'pendant_length'.

In ggtree, we provide get.placements method to access the placement.

## get only best hit
get.placements(jp, by="best")

##   name edge_num likelihood like_weight_ratio distal_length pendant_length
## 1   AA       24  -61371.30          0.333344         3e-06       0.003887
## 2   BB        1  -61312.21          0.333335         1e-06       0.000003
## 3   BB        1  -61312.21          0.333335         1e-06       0.000003
## 4   BB        2  -61312.21          0.333322         3e-06       0.000003
## 5   CC        8  -61312.23          0.200011         1e-06       0.000003
## 6   CC        8  -61312.23          0.200011         1e-06       0.000003
## 7   CC        9  -61312.23          0.200000         3e-06       0.000003

## get all placement
get.placements(jp, by="all")

##   name edge_num likelihood like_weight_ratio distal_length pendant_length
## 1   AA       24  -61371.30          0.333344      0.000003       0.003887
## 2   BB        1  -61312.21          0.333335      0.000001       0.000003
## 3   BB        2  -61312.21          0.333322      0.000003       0.000003
## 4   BB      550  -61312.21          0.333322      0.000961       0.000003
## 5   CC        8  -61312.23          0.200011      0.000001       0.000003
## 6   CC        9  -61312.23          0.200000      0.000003       0.000003
## 7   CC       10  -61312.23          0.199992      0.000003       0.000003

This is only a tiny sample file. In reality, EPA and PPLACER may place thousands of short reads on a reference tree.

We may, for example, count the number of placement and annotate this information in the tree. We do not provide a plot method for jplace object, since we use this file format as a standard annotation format in ggtree package and have no assumption of information it may stored. Please refer to jplace file format session.

mergine tree objects

In ggtree, objects can be merged and evidences inferred from different phylogenetic analyses can be combined or compared and visualized.

User can use the command like:

tree <- merge_tree(tree_object_1, tree_object_2)
## it's chainable, and serveral tree objects can be merged into one tree object
tree <- merge_tree(tree_object_1, tree_object_2) %>% merge_tree(tree_object_3) %>% merge_tree(tree_object_4)

Here we use a tree analyzed by BEAST and CodeML and merge them into one.

beast_file <- system.file("examples/MCC_FluA_H3.tree", package="ggtree")
beast_tree <- read.beast(beast_file)

rst_file <- system.file("examples/rst", package="ggtree")
mlc_file <- system.file("examples/mlc", package="ggtree")
codeml_tree <- read.codeml(rst_file, mlc_file)

merged_tree <- merge_tree(beast_tree, codeml_tree)

merged_tree

## 'beast' S4 object that stored information of
##   '/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/examples/MCC_FluA_H3.tree'.
## 
## ...@ tree: 
## Phylogenetic tree with 76 tips and 75 internal nodes.
## 
## Tip labels:
##  A/Hokkaido/30-1-a/2013, A/New_York/334/2004, A/New_York/463/2005, A/New_York/452/1999, A/New_York/238/2005, A/New_York/523/1998, ...
## 
## Rooted; includes branch lengths.
## 
## with the following features available:
##   'height',  'height_0.95_HPD',  'height_median',    'height_range', 'length',
##   'length_0.95_HPD', 'length_median',    'length_range', 'posterior',    'rate',
##   'rate_0.95_HPD',   'rate_median',  'rate_range',   't',    'N',
##   'S',   'dN_vs_dS', 'dN',   'dS',   'N_x_dN',
##   'S_x_dS',  'marginal_subs',    'joint_subs',   'marginal_AA_subs', 'joint_AA_subs',
## .

After merging, all evidences inferred from different tools can be used to annotate the tree simultaneously. In this example, we used ‘dN’ inferred by CodeML to color the tree and annotate the tree with ‘posterior’ inferred by BEAST.

ggtree(merged_tree, aes(color=dN), mrsd="2013-01-01", ndigits = 3) +
    geom_text(aes(label=posterior), vjust=.1, hjust=-.1, size=5) + theme_tree2() +
        scale_color_continuous(low="green", high="red") + theme(legend.position="right")

annotating tree using ggplot2 layers

We implemented several plot methods for easily viewing annotation data. Users are not restricted to plot methods provided. They can use geom_text to add annotation layer. All annotation data are visible to ggplot2.

In the following example, we use the codeml object to visualize the \(\omega\) (dN/dS) tree, and annotate the tree with dN and dS.

ggtree(ml, branch.length="dN_vs_dS") + 
    geom_text(aes(x=branch, label=dN), 
              size=3, vjust=-0.5, color="red") +
                  geom_text(aes(x=branch, label=dS),
                            size=3, vjust=1.2, color="darkgreen")

the %<+% operator

We provides several functions to parse and store information from common software output, and corresponding plot methods for visualizing annotation in the tree.

Here, we would like to demonstrate how to inject user specific annotation data in a tree.

Suppose we have the following data that associated with the tree and would like to attach the data in the tree.

nwk <- system.file("extdata", "sample.nwk", package="ggtree")
tree <- read.tree(nwk)
p <- ggtree(tree)

dd <- data.frame(taxa  = LETTERS[1:13], 
             place = c(rep("GZ", 5), rep("HK", 3), rep("CZ", 4), NA),
                 value = round(abs(rnorm(13, mean=70, sd=10)), digits=1))
## you don't need to order the data
## data was reshuffled just for demonstration
dd <- dd[sample(1:13, 13), ]
row.names(dd) <- NULL

print(dd)

We can imaging that the place column is the place we isolated the species and value column stored numerical values for example bootstrap values.

We have shown using the operator, %<%, to update a tree view with a new tree. Here, we will introduce another operator, %<+%, that attaches annotation data to a tree view. The only requirement of the input data is that its first column should be matched with the node/tip labels of the tree.

After attaching the annotation data to the tree by %<+%, all the columns in the data are visible to ggplot2. As an example, here we attach the above annotation data to the tree view, p, and add a layer that showing the tip labels and colored them by the isolation site stored in place column.

p <- p %<+% dd + geom_text(aes(color=place, label=label), hjust=-0.5) + 
       geom_tippoint(aes(size=value, shape=place, color=place), alpha=0.25)
p+theme(legend.position="right")

Once the data was attached, it is always attached. So we can add another layer to display the isolation sites easily.

p <- p + geom_text(aes(color=place, label=place), hjust=1, vjust=-0.4, size=3)
print(p)

And another layer showing numerical values:

p <- p + geom_text(aes(color=place, label=value), hjust=1, vjust=1.4, size=3)
print(p)

jplace file format

The jplace file format was defined by Masten¹⁰ for phylogenetic placements. We employed this file format to store phylogenetic tree and user specific annotation data. Suppose we have a tree, and the associated data as shown below:

tree <- system.file("extdata", "pa.nwk", package="ggtree")
data <- read.csv(system.file("extdata", "pa_subs.csv", package="ggtree"), stringsAsFactor=FALSE)
print(tree)

## [1] "/private/tmp/Rtmpvl5aqI/Rinst10e0f432cd693/ggtree/extdata/pa.nwk"

head(data)

##   label                          subs    gc
## 1     A                   R262K/K603R 0.444
## 2     B                         R262K 0.442
## 3     C                   N272S/I354T 0.439
## 4     D K104R/F105L/E382D/F480S/I596T 0.449
## 5     E             T208S/V379I/K609R 0.443
## 6     F                   S277P/L549I 0.444

The data contains amino acid substitutions from parent node to child node and GC contents of each node. We can annotate the tree as demonstrated in user specific annotation session.

ggtree provides a function, write.jplace, to combine a tree and an associated data and store them to a single jplace file.

outfile <- tempfile()
write.jplace(tree, data, outfile)

Then read.jplace function was designed to read the jplace file and store the information to a jplace object.

jp <- read.jplace(outfile)
print(jp)

## 'jplace' S4 object that stored information of
##   '/tmp/RtmphEO8RD/file110a49751363'. 
## 
## ...@ tree: 
## Phylogenetic tree with 15 tips and 13 internal nodes.
## 
## Tip labels:
##  K, N, D, L, J, G, ...
## 
## Unrooted; includes branch lengths.
## 
## with the following features availables:
##   'label',   'subs', 'gc'.

Now we know the jp object stored the tree and the associated amino acid substitution and GC content information, we can view the tree and display the associated annotation data on it directly by ggtree.

ggtree(jp, showDistance=TRUE) + 
       geom_text(aes(x=branch, label=subs), color="purple", vjust=-1, size=3) + 
       geom_text(aes(label=gc), color="steelblue", hjust=-.6, size=3) +
       geom_text(aes(label=label), hjust=-.5)

visualize tree with associated matrix

At first we implemented gplot function to visualize tree with heatmap but it has an issue that it can’t always guarantee the heatmap aligning to the tree properly, since the line up is between two figures and it’s currently not supported internally by ggplot2. I have implemented another function gheatmap that can do the line up properly by creating a new layer above the tree.

In the following example, we visualized a tree of H3 influenza viruses with their associated genotype.

genotype_file <- system.file("examples/Genotype.txt", package="ggtree")
genotype <- read.table(genotype_file, sep="\t", stringsAsFactor=F)
p <- ggtree(beast_tree, mrsd="2013-01-01") %>% add_legend(x=2008, y=5)
p <- p + geom_tiplab(size=3)
gheatmap(p, genotype, offset = 2, width=0.5)

The width parameter is to control the width of the heatmap. It supports another parameter offset for controling the distance between the tree and the heatmap, for instance left space for tip labels.

For time scaled tree, as in this example, it’s more often to use x axis by using theme_tree2. But with this solution, the heatmap is just another layer and will change the x axis. To overcome this issue, we implemented scale_x_ggtree to set the x axis more reasonable. User can also use gplot and tweak the positions of two plot to align properly.

p <- ggtree(beast_tree,  mrsd="2013-01-01") + geom_tiplab(size=3, align=TRUE) + theme_tree2()

## Warning: The plyr::rename operation has created duplicates for the
## following name(s): (`size`)

pp <- (p + scale_y_continuous(expand=c(0, 0.3))) %>%
    gheatmap(genotype, offset=4, width=0.5, colnames=FALSE) %>%
        scale_x_ggtree()
pp + theme(legend.position="right")

visualize tree with multiple sequence alignment

With msaplot function, user can visualizes multiple sequence alignment with phylogenetic tree, as demonstrated below:

fasta <- system.file("examples/FluA_H3_AA.fas", package="ggtree")
msaplot(ggtree(beast_tree), fasta) 

A specific slice of the alignment can also be displayed by specific window parameter.