# Bioconductor Ggtree > 'ggtree' extends the 'ggplot2' plotting system which implemented the grammar of graphics. 'ggtree' is designed for visualization and annotation of phylogenetic trees and other tree-like structures with their annotation data. - Skill: `biomate-ai/bioconductor-ggtree` (Agent Skill) - Install (CLI): `npx skillmds@latest add biomate-ai/bioconductor-ggtree` - Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/bioconductor-ggtree/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: biomate-ai (https://skillmd.com/u/biomate-ai) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/biomate-ai/bioconductor-ggtree --- # ggtree `ggtree` extends the `ggplot2` plotting system to implement the grammar of graphics for phylogenetic trees. It is designed for the visualization, manipulation, and annotation of phylogenetic trees and other tree-like structures with their associated multi-omics and clinical metadata. ## Dependencies & Environment > Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment. - **Version:** 4.2.0 · **Bioconductor:** 3.23 · **R:** ≥ 4.6 - **Imports:** ape, aplot, cli, dplyr, ggfun, ggiraph, ggplot2, magrittr, purrr, rlang, scales, tidyr, tidytree, treeio, yulab.utils - **Install:** `BiocManager::install("ggtree")` ## When to Use - Visualizing complex phylogenetic trees (e.g., from RAxML, IQ-TREE, or BEAST) integrated with multi-omics metadata (such as microbiome abundance, genomic features, or clinical traits). - Annotating tree nodes, clades, and leaves with custom shapes, colors, images, or subplots (e.g., barplots, pie charts) using the grammar of graphics. - Displaying circular, radial, rectangular, or slanted tree layouts for large-scale evolutionary studies containing hundreds to thousands of taxa. ## When NOT to Use - For interactive, web-based tree exploration, use `phylocanvas` or `iTOL` instead because `ggtree` produces static vector graphics. - For simple, quick tree plotting without complex annotations, use `ape::plot.phylo` instead because it has zero overhead and requires no `ggplot2` syntax. - For highly customized interactive network visualizations that are not strictly hierarchical, use `ggnetwork` or `tidygraph` instead because `ggtree` is optimized specifically for tree topologies. ## Data Requirements - **Input format**: Tree objects of class `phylo` (from `ape`), `treedata` (from `treeio`), or standard R dendrograms. - **Metadata**: A data frame containing a column matching the tip labels of the tree. - **Scale**: Supports trees from 10 to 10,000+ tips, though rendering times scale with taxon count. ## Key Parameters - **layout** ("rectangular"): Layout of the tree; options include "circular", "slanted", "fan", "radial", "unrooted", "equal_angle", or "daylight". - **ladderize** (TRUE): Logical; whether to sort the branches to make the tree look more structured. - **branch.length** ("branch.length"): Variable to determine branch lengths; set to "none" for cladograms with equal branch lengths. - **as.Date** (FALSE): Logical; whether to parse the x-axis as dates for time-resolved (chronogram) trees. - **yscale** (NULL): Variable used to scale the y-axis, useful for custom vertical spacing. ## Best Practices - Use the `treeio` package to import trees from diverse software formats (e.g., BEAST, MrBayes, NHX) to preserve node-level annotations. - Attach external metadata using the `%<+%` operator to seamlessly map sample traits to tree tips or internal nodes. - For large trees, use `layout = "circular"` or `layout = "fan"` to maximize space efficiency and prevent text overlap. - Adjust label offsets and text sizes dynamically using `geom_tiplab(offset = ...)` to prevent labels from clipping outside the plot boundaries. ## Common Pitfalls - **Tip labels overlapping or cut off**: Occurs when tree margins are too small or labels are long; fix this by adding `hexpand()` or `xlim()` to extend the plot canvas. - **Metadata mapping failure**: Occurs when the ID column in the metadata does not match the tip labels exactly; fix this by ensuring `row.names` or a specific ID column matches `tree$tip.label`. - **Slow rendering of large trees**: Occurs when adding too many individual geom layers to a tree with >10,000 tips; fix this by collapsing clades using `collapse()` before plotting. ## Alternatives - `ape`: The foundational R phylogenetics package, faster for basic plotting but lacks `ggplot2` integration. - `ggtreeExtra`: An extension of `ggtree` designed specifically for presenting circular layouts with multiple rings of complex genomic data. - `phyloseq`: Excellent for microbiome-specific tree plotting, but less flexible for general phylogenetic annotations than `ggtree`. - `tanggle`: Specifically designed for visualizing phylogenetic networks rather than strict bifurcating trees. ## Citations - Yu, G., Smith, D. K., Zhu, H., Guan, Y., & Lam, T. T. Y. (2017). ggtree: an R package for visualization and annotation of phylogenetic trees with their covariates and other associated data. *Methods in Ecology and Evolution*, 8(1), 28-36. - Yu, G. (2022). *Integration, Manipulation and Visualization of Phylogenetic Trees* (1st ed.). Chapman and Hall/CRC. ## References - Homepage: https://bioconductor.org/packages/ggtree - Vignette: https://bioconductor.org/packages/release/bioc/vignettes/ggtree/inst/doc/ggtree.html --- ## Run this on BioMate This skill is the **knowledge layer** — when, why, and how to use `ggtree`. To **run this analysis on your own data** with managed compute, automated QC, and reproducible outputs, use **[BioMate](https://www.biomate.ai?ref=kb&pkg=ggtree)** — free to start. ▶ **[Open `ggtree` on BioMate →](https://www.biomate.ai?ref=kb&pkg=ggtree)**