Citation

If you use ggtree in published research, please cite the most appropriate paper(s) from this list:

1. G Yu, DK Smith, H Zhu, Y Guan, TTY Lam^*. ggtree: an R package for visualization and annotation of phylogenetic trees with their covariates and other associated data. Methods in Ecology and Evolution. 2017, 8(1):28-36. doi: 10.1111/2041-210X.12628.
2. G Yu^*, TTY Lam, H Zhu, Y Guan^*. Two methods for mapping and visualizing associated data on phylogeny using ggtree. Molecular Biology and Evolution, 2018, 35(2):3041-3043. doi: 10.1093/molbev/msy194.

Introduction

This project arose from our needs to annotate nucleotide substitutions in the phylogenetic tree, and we found that there is no tree visualization software can do this easily. Existing tree viewers are designed for displaying phylogenetic tree, but not annotating it. Although some tree viewers can displaying bootstrap values in the tree, it is hard/impossible to display other information in the tree. Our first solution for displaying nucleotide substituitions in the tree is to add this information in the node/tip names and use traditional tree viewer to show it. We displayed the information in the tree successfully, but we believe this indirect approach is inefficient.

Previously, phylogenetic trees were much smaller. Annotation of phylogenetic trees was not as necessary as nowadays much more data is becomming available. We want to associate our experimental data, for instance antigenic change, with the evolution relationship. Visualizing these associations in a phylogenetic tree can help us to identify evolution patterns. We believe we need a next generation tree viewer that should be programmable and extensible. It can view a phylogenetic tree easily as we did with classical software and support adding annotation data in a layer above the tree. This is the objective of developing the ggtree (Yu et al. 2017). Common tasks of annotating a phylogenetic tree should be easy and complicated tasks can be possible to achieve by adding multiple layers of annotation.

The ggtree is designed by extending the ggplot2 (Wickham 2009) package. It is based on the grammar of graphics and takes all the good parts of ggplot2. There are other R packages that implement tree viewer using ggplot2, including OutbreakTools, phyloseq (McMurdie and Holmes 2013) and ggphylo; they mostly create complex tree view functions for their specific needs. Internally, these packages interpret a phylogenetic as a collection of lines, which makes it hard to annotate diverse user input that are related to node (taxa). The ggtree is different to them by interpreting a tree as a collection of taxa and allowing general flexibilities of annotating phylogenetic tree with diverse types of user inputs.

Getting data into R

Most of the tree viewer software (including R packages) focus on Newick and Nexus file format, while there are file formats from different evolution analysis software that contain supporting evidences within the file that are ready for annotating a phylogenetic tree. The treeio package supports several file formats and software outputs. It brings analysis findings to R users for further analysis (e.g. summarization, visualization, comparison and test, etc.). It also allows external data to be mapped on the phylogeny. Please refer to the treeio vignette for more details.

Users can use the following command to open the vignette:

vignette("Importer", package="treeio")

All the data parsed/integrated by treeio package can be used to visualize or annotate phylogenetic tree in ggtree (Yu et al. 2017).

Tree Visualization and Annotation

Tree Visualization in ggtree is easy, with one line of command ggtree(tree_object). It supports several layouts, including rectangular, slanted, circular and fan for phylogram and cladogram, equal_angle and daylight for unrooted layout, time-scaled and two dimentional phylogenies. Tree Visualization vignette describes these feature in details.

We implement several functions to manipulate a phylogenetic tree visually, including viewing selected clade to explore large tree, taxa clustering, rotating clade or tree, zoom out or collapsing clades etc..

Details and examples can be found in Tree Manipulation vignette.

Most of the phylogenetic trees are scaled by evolutionary distance (substitution/site), in ggtree a phylogenetic tree can be re-scaled by any numerical variable inferred by evolutionary analysis ( e.g. species divergence time, d_N/d_S, etc). Numerical and category variable can be used to color a phylogenetic tree.

The ggtree package provides several layers to annotate a phylogenetic tree. These layers are building blocks that can be freely combined together to create complex tree visualization.

ggtree supports creating phylomoji using Emoji fonts, please refer to the Phylomoji vignette.

ggtree integrates phylopic database and silhouette images of organisms can be downloaded and used to annotate phylogenetic directly. ggtree also supports using local or remote images to annotate a phylogenetic tree. For details, please refer to the ggimage package vignette, which can be opened via the following command:

vignette("ggtree", package="ggimage")

Visualizing an annotated phylogenetic tree with numerical matrix (e.g. genotype table), multiple sequence alignment and subplots are also supported in ggtree. Examples of annotating phylogenetic trees can be found in the Tree Annotation vignette.

Vignette Entry

• Tree Data Import
• Tree Visualization
• Tree Manipulation
• Tree Annotation
• Phylomoji
• Annotating phylogenetic tree with images
• Annotate a phylogenetic tree with insets

ggtree homepage: https://guangchuangyu.github.io/software/ggtree (contains more information about the package, more documentation, a gallery of beautiful published images and links to related resources).

Need helps?

If you have questions/issues, please visit ggtree homepage first. Your problems are mostly documented. If you think you found a bug, please follow the guide and provide a reproducible example to be posted on github issue tracker. For questions, please post to google group. Users are highly recommended to subscribe to the mailing list.

Session info

Here is the output of sessionInfo() on the system on which this document was compiled:

## R version 3.5.2 (2018-12-20)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows Server 2012 R2 x64 (build 9600)
## 
## Matrix products: default
## 
## locale:
## [1] LC_COLLATE=C                          
## [2] LC_CTYPE=English_United States.1252   
## [3] LC_MONETARY=English_United States.1252
## [4] LC_NUMERIC=C                          
## [5] LC_TIME=English_United States.1252    
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## loaded via a namespace (and not attached):
##  [1] compiler_3.5.2  magrittr_1.5    htmltools_0.3.6 tools_3.5.2    
##  [5] prettydoc_0.2.1 yaml_2.2.0      Rcpp_1.0.0      stringi_1.2.4  
##  [9] rmarkdown_1.11  highr_0.7       knitr_1.21      stringr_1.3.1  
## [13] digest_0.6.18   xfun_0.4        evaluate_0.12