---
title: "Tree Visualization"
author: "Guangchuang Yu and Tommy Tsan-Yuk Lam\\
School of Public Health, The University of Hong Kong"
date: "`r Sys.Date()`"
bibliography: ggtree.bib
csl: nature.csl
output:
prettydoc::html_pretty:
toc: true
theme: cayman
highlight: github
pdf_document:
toc: true
vignette: >
%\VignetteIndexEntry{02 Tree Visualization}
%\VignetteEngine{knitr::rmarkdown}
%\usepackage[utf8]{inputenc}
---
```{r style, echo=FALSE, results="asis", message=FALSE}
knitr::opts_chunk$set(tidy = FALSE,
message = FALSE)
```
```{r echo=FALSE, results="hide", message=FALSE}
library("ape")
library("ggplot2")
library("ggtree")
```
To view a phylogenetic tree, we first need to parse the tree file into `R`. The `ggtree` package supports many file formats including output files of commonly used software packages in evolutionary biology. For more details, plase refer to the [Tree Data Import](treeImport.html) vignette.
```{r}
library("ggtree")
nwk <- system.file("extdata", "sample.nwk", package="treeio")
tree <- read.tree(nwk)
```
# Viewing a phylogenetic tree with `ggtree`
The `ggtree` package extends _`ggplot2`_ package to support viewing phylogenetic tree.
It implements _`geom_tree`_ layer for displaying phylogenetic tree, as shown below:
```{r fig.width=3, fig.height=3, fig.align="center"}
ggplot(tree, aes(x, y)) + geom_tree() + theme_tree()
```
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`_.
```{r fig.width=3, fig.height=3, fig.align="center"}
ggtree(tree, color="firebrick", size=1, linetype="dotted")
```
By default, the tree is viewed in ladderize form, user can set the parameter _`ladderize = FALSE`_ to disable it.
```{r fig.width=3, fig.height=3, fig.align="center"}
ggtree(tree, ladderize=FALSE)
```
The _`branch.length`_ is used to scale the edge, user can set the parameter _`branch.length = "none"`_ to only view the tree topology (cladogram) or other numerical variable to scale the tree (e.g. _dN/dS_, see also in [Tree Annotation](treeAnnotation.html) vignette).
```{r fig.width=3, fig.height=3, fig.align="center"}
ggtree(tree, branch.length="none")
```
# Layout
Currently, _`ggtree`_ supports several layouts, including:
+ `rectangular` (by default)
+ `slanted`
+ `circular`
+ `fan`
for `Phylogram` (by default) and `Cladogram` if user explicitly setting `branch.length='none'`.
`ggtree` also supports `unrooted` layout.
## Phylogram
__`rectangular`__
```{r fig.height=4, fig.width=4, fig.align="center"}
ggtree(tree) + ggtitle("(Phylogram) rectangular layout")
```
__`slanted`__
```{r fig.height=4, fig.width=4, fig.align="center"}
ggtree(tree, layout="slanted") + ggtitle("(Phylogram) slanted layout")
```
__`circular`__
```{r fig.height=5, fig.width=5, fig.align="center"}
ggtree(tree, layout="circular") + ggtitle("(Phylogram) circular layout")
```
__`fan`__
```{r fig.height=5, fig.width=5, fig.align="center"}
ggtree(tree, layout="fan", open.angle=180) + ggtitle("(Phylogram) fan layout")
```
## Cladogram
__`rectangular`__
```{r fig.height=4, fig.width=4, fig.align="center"}
ggtree(tree, branch.length='none') + ggtitle("(Cladogram) rectangular layout")
```
__`slanted`__
```{r fig.height=4, fig.width=4, fig.align="center"}
ggtree(tree, layout="slanted", branch.length='none') + ggtitle("(Cladogram) slanted layout")
```
__`circular`__
```{r fig.height=5, fig.width=5, fig.align="center"}
ggtree(tree, layout="circular", branch.length="none") + ggtitle("(Cladogram) circular layout")
```
__`fan`__
```{r fig.height=5, fig.width=5, fig.align="center"}
ggtree(tree, layout="fan", open.angle=180, branch.length="none") + ggtitle("(Cladogram) circular layout")
```
## Unrooted
Unrooted layout was implemented by the _`equal-angle algorithm`_ that described in _Inferring Phylogenies_[@felsenstein_inferring_2003 pp.578-580].
```{r fig.height=4, fig.width=4, fig.align="center"}
ggtree(tree, layout="unrooted") + ggtitle("unrooted layout")
```
## Time-scaled tree
A phylogenetic tree can be scaled by time (time-scaled tree) by specifying the parameter, `mrsd` (most recent sampling date).
```{r fig.width=9, fig.height=9, fig.align="center"}
tree2d <- read.beast(system.file("extdata", "twoD.tree", package="treeio"))
ggtree(tree2d, mrsd = "2014-05-01") + theme_tree2()
```
## Two dimensional tree
`ggtree` implemented two dimensional tree. It accepts parameter _`yscale`_ to scale the y-axis based on the selected tree attribute. The attribute should be numerical variable. If it is *character*/*category* variable, user should provides a name vector of mapping the variable to numeric by passing it to parameter _`yscale_mapping`_.
```{r fig.width=9, fig.height=4, fig.align="center"}
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(axis.line.x=element_line(), axis.line.y=element_line()) +
theme(panel.grid.major.x=element_line(color="grey20", linetype="dotted", size=.3),
panel.grid.major.y=element_blank()) +
scale_y_continuous(labels=paste0("N", 2:7))
```
In this example, the figure demonstrates the quantity of __*y*__ increase along the trunk. User can highlight the trunk with different line size or color using the functions described in [Tree Manipulation](treeManipulation.html) vignette.
# Displaying tree scale (evolution distance)
To show tree scale, user can use `geom_treescale()` layer.
```{r fig.width=4, fig.height=4, fig.align="center"}
ggtree(tree) + geom_treescale()
```
`geom_treescale()` supports the following parameters:
+ `x` and `y` for tree scale position
+ `width` for the length of the tree scale
+ `fontsize` for the size of the text
+ `linesize` for the size of the line
+ `offset` for relative position of the line and the text
+ `color` for color of the tree scale
```{r fig.width=4, fig.height=4, fig.align="center"}
ggtree(tree)+geom_treescale(x=0, y=12, width=6, color='red')
```
```{r fig.width=4, fig.height=4, fig.align="center"}
ggtree(tree)+geom_treescale(fontsize=8, linesize=2, offset=-1)
```
We can also use `theme_tree2()` to display the tree scale by adding `x axis`.
```{r fig.width=3, fig.height=3, fig.align="center"}
ggtree(tree) + theme_tree2()
```
Tree scale is not restricted to evolution distance, `ggtree` can re-scale the tree with other numerical variable. More details can be found in the [Tree Annotation](treeAnnotation.html) vignette.
# Displaying nodes/tips
Showing 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`_.
```{r fig.width=3, fig.height=3, fig.align="center"}
ggtree(tree)+geom_point(aes(shape=isTip, color=isTip), size=3)
```
```{r fig.width=3, fig.height=3, fig.align="center"}
p <- ggtree(tree) + geom_nodepoint(color="#b5e521", alpha=1/4, size=10)
p + geom_tippoint(color="#FDAC4F", shape=8, size=3)
```
## Displaying labels
Users can use _`geom_text`_ to display the node (if available) and tip labels simultaneously or `geom_tiplab` to only display tip labels:
```{r fig.width=3, fig.height=3, warning=FALSE, fig.align="center"}
p + geom_tiplab(size=3, color="purple")
```
For _`circular`_ and _`unrooted`_ layout, `ggtree` supports rotating node labels according to the angles of the branches.
```{r fig.width=6, fig.height=6, warning=FALSE, fig.align="center"}
ggtree(tree, layout="circular") + geom_tiplab(aes(angle=angle), color='blue')
```
To make it more readable for human eye, `ggtree` provides a `geom_tiplab2` for `circular` layout (see post [1](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/bioc-ggtree/o35PV3iHO-0) and [2](https://groups.google.com/forum/#!topic/bioc-ggtree/p42R5l8J-14)).
```{r fig.width=6, fig.height=6, warning=FALSE, fig.align="center"}
ggtree(tree, layout="circular") + geom_tiplab2(color='blue')
```
By default, the positions are based on the node positions, we can change them to based on the middle of the branch/edge.
```{r fig.width=4, fig.height=3, warning=FALSE, fig.align="center"}
p + geom_tiplab(aes(x=branch), size=3, color="purple", vjust=-0.3)
```
Based on the middle of branch is very useful when annotating transition from parent node to child node.
# update tree view with a new tree
In previous example, we have a _`p`_ object that stored the tree viewing of 13 tips and internal nodes highlighted with specific colored big dots. If users want to apply 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:
```{r fig.width=3, fig.height=3, fig.align="center"}
p %<% rtree(50)
```
Another example can be found in the [Tree Data Import](treeImport.html#rst-file) vignette.
# theme
`theme_tree()` defined a totally blank canvas, while _`theme_tree2()`_ adds phylogenetic distance (via x-axis). These two themes all accept a parameter of _`bgcolor`_ that defined the background color.
```{r fig.width=6, fig.height=3, fig.align="center"}
multiplot(
ggtree(rtree(30), color="red") + theme_tree("steelblue"),
ggtree(rtree(20), color="white") + theme_tree("black"),
ncol=2)
```
# Visualize a list of trees
`ggtree` supports `multiPhylo` object and a list of trees can be viewed simultaneously.
```{r fig.width=12, fig.height=4}
trees <- lapply(c(10, 20, 40), rtree)
class(trees) <- "multiPhylo"
ggtree(trees) + facet_wrap(~.id, scale="free") + geom_tiplab()
```
One hundred bootstrap trees can also be view simultaneously.
```{r fig.width=20, fig.height=20}
btrees <- read.tree(system.file("extdata/RAxML", "RAxML_bootstrap.H3", package="treeio"))
ggtree(btrees) + facet_wrap(~.id, ncol=10)
```
Another way to view the bootstrap trees is to merge them together to form a density tree. We can add a layer of the best tree on the top of the density tree.
```{r}
p <- ggtree(btrees, layout="rectangular", color="lightblue", alpha=.3)
best_tree <- read.tree(system.file("extdata/RAxML", "RAxML_bipartitionsBranchLabels.H3", package="treeio"))
df <- fortify(best_tree, branch.length = 'none')
p+geom_tree(data=df, color='firebrick')
```
# References
