ggtree-py 0.1.0__tar.gz

ggtree_py-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*$py.class
+build/
+dist/
+*.egg-info/
+.venv/
+.pytest_cache/
+examples/output/
+.DS_Store
+.env

ggtree_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026-11-14)
+
+Initial Python release (`ggtree-py`, imported as `ggtree`), ported from Bioconductor `ggtree` (`4.3.2`).
+
+### Highlights
+- **Tree parsers & structures (`ggtree.tree`)**: Newick (`read_tree`), BEAST NEXUS (`read_beast`), NHX (`read_nhx`), jplace (`read_jplace`), FASTA (`read_fasta`), `Phylo`, `TreeData`, `MultiPhylo`, `TreeDataList`, `Hclust`/`hclust`, and bundled sample datasets (`system_file`).
+- **Tidy tree operations (`ggtree.tidytree`)**: `MRCA`, `groupOTU`, `groupClade`, `offspring`, `ancestor`, `parent`, `child`, `sibling`, `nodeid`, `nodelab`, `tree_subset`, `td_filter`, `td_mutate`, and `td_unnest`.
+- **12+ tree layouts (`ggtree.layout`)**: `rectangular`, `slanted`, `circular`, `fan`, `inward_circular`, `dendrogram`, `equal_angle`, `daylight` (`unrooted`), `tidy`, `ellipse`, `roundrect`, `radial`, `ape`, and `tree_and_leaf`, plus time-scaled MRSD coordinates (`Date2decimal`, `decimal2Date`).
+- **Grammar-of-graphics geoms & scales (`ggtree.aes`, `ggtree.geoms`, `ggtree.themes_scales`)**: Symbolic expressions (`aes`, `isTip`, `parent`), `geom_tree`, `geom_tiplab`, `geom_tiplab2`, `geom_nodelab`, `geom_point2`, `geom_tippoint`, `geom_nodepoint`, `geom_rootpoint`, `geom_rootedge`, `geom_aline`, `geom_hilight`, `geom_balance`, `geom_cladelab`, `geom_strip`, `geom_taxalink`, `geom_tanglelink`, `geom_range`, `geom_treescale`, `new_scale_fill`, `new_scale_color`, Viridis/Magma/Plasma/Inferno/Cividis/Brewer/gradient scales, and `theme_tree`, `theme_tree2`, `theme_dendrogram`.
+- **Manipulation & composite plots (`ggtree.manipulate`, `ggtree.compose`)**: `collapse`, `expand`, `rotate`, `flip`, `scaleClade`, `viewClade`, `zoomClade`, `open_tree`, `rotate_tree`, `gheatmap`, `msaplot`, `geom_facet`/`facet_plot`, `nodepie`/`nodebar`/`inset`, `ggdensitree`, `as_tanglegram`/`ggdoubletree`, `multiplot`, `plot_list`, and `|`/`/` patchwork composition.
+- **Zero-external-dependency SVG & PNG renderer (`ggtree.plot`)**: Direct vector SVG rendering and PNG export via `ggsave()`, `to_svg()`, and `to_png()` (using `rsvg-convert` when present, with pure-NumPy RGBA fallback).
+- **Verified**: All 49 tests pass (`tests/test_examples.py` + `tests/test_ggtree.py`).

ggtree_py-0.1.0/CONDUCT.md

@@ -0,0 +1,24 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or
+imagery, derogatory comments or personal attacks, trolling, public or private harassment,
+insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments,
+commits, code, wiki edits, issues, and other contributions that are not aligned to this
+Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed
+from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by
+opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the Contributor Covenant
+(http://contributor-covenant.org), version 1.0.0.

ggtree_py-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to `ggtree-py`
+
+Thank you for considering contributing to `ggtree-py`!
+
+## Development Setup
+
+```bash
+git clone <repo-url>
+cd ggtree.py
+python3 -m pip install -e ".[dev]"
+```
+
+Only `numpy>=1.22` is required at runtime (Python `>= 3.10`). Installing `rsvg-convert` (from `librsvg`) on your `PATH` enables high-resolution vector-to-PNG rasterization in `ggsave("out.png")`; without it, `ggtree` falls back to its built-in pure-NumPy PNG rasterizer.
+
+## Running Tests and Examples
+
+Run the full unit test suite (all 49 tests covering ported R manual examples and `testthat` suites):
+
+```bash
+python3 -s -m unittest discover -s tests -v
+```
+
+Generate all 14 composite example figures (SVG + PNG) in `examples/output/`:
+
+```bash
+python3 -s examples/run_all_examples.py
+```
+
+## Building Distributions
+
+```bash
+uv build
+```
+
+## Submitting Pull Requests
+
+- Keep core runtime dependencies restricted to the Python standard library and `numpy`.
+- Add or update tests in `tests/test_ggtree.py` or `tests/test_examples.py`.
+- Update the relevant documentation under `docs/` when adding or modifying public APIs.
+- Follow the [Contributor Code of Conduct](CONDUCT.md).

ggtree_py-0.1.0/LICENSE

@@ -0,0 +1,164 @@
+The Artistic License 2.0
+
+Copyright (c) 2014-2026 Guangchuang Yu (upstream R/Bioconductor ggtree authors)
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+Preamble
+
+This license establishes the terms under which a given free software
+Package may be copied, modified, distributed, and/or redistributed.
+The intent is that the Copyright Holder maintains some artistic
+control over the development of that Package while still keeping the
+Package available as open source and free software.
+
+You are always permitted to make arrangements wholly outside of this
+license directly with the Copyright Holder of a given Package.  If the
+terms of this license do not permit the full use that you propose to
+make of the Package, you should contact the Copyright Holder and seek
+a different licensing arrangement.
+
+Definitions
+
+    "Copyright Holder" means the individual(s) or organization(s)
+    named in the copyright notice for the entire Package.
+
+    "Contributor" means any party that has contributed code or other
+    material to the Package, in accordance with the Copyright Holder's
+    procedures.
+
+    "You" and "your" means any person who would like to copy,
+    distribute, or modify the Package.
+
+    "Package" means the collection of files distributed by the
+    Copyright Holder, and derivatives of that collection and/or
+    of those files. A given Package may consist of either the Standard
+    Version, or a Modified Version.
+
+    "Distribute" means providing a copy of the Package or making it
+    accessible to anyone else, or in the case of a company or
+    organization, to others outside of your company or organization.
+
+    "Distributor Fee" means any fee that you charge for Distributing
+    this Package or providing support for this Package to another
+    party.  It does not mean branding.
+
+    "Standard Version" refers to the Package if it has not been
+    modified, or has been modified only in ways explicitly requested
+    by the Copyright Holder.
+
+    "Modified Version" means the Package, when it has been changed,
+    and such changes were not explicitly requested by the Copyright
+    Holder.
+
+    "Original License" means this Artistic License as Distributed with
+    the Standard Version of the Package, in its current version or as
+    it may be modified by The Perl Foundation in the future.
+
+    "Source" form means the source code, documentation source, and
+    configuration files for the Package.
+
+    "Compiled" form means the compiled binary or object code or
+    executable, including generated binary files, generated
+    computer code, or translated or converted binary files.
+
+    "Application" means the problem solving program, application, or
+    other business function or application to which the Package is
+    linked.
+
+    "Aggregation" means a compilation of a number of separate
+    independent programs, not based on the Package, which are
+    not specifically written for the purpose of combining the Package
+    with the independent programs.
+
+    "Distribution" means the collection of files that constitute the
+    Package as it is distributed by you.
+
+    "Derivative Work" means any work derived from the Package,
+    either through copyright or contract.
+
+Permission for Use and Modification Without Distribution
+
+(1)  You are permitted to use the Standard Version and create and use
+Modified Versions for any purpose without restriction, provided that
+you do not Distribute the Modified Version.
+
+Permissions for Redistribution of the Standard Version
+
+(2)  You may Distribute verbatim copies of the Source form of the
+Standard Version of this Package in any medium without restriction,
+either gratis or for a Distributor Fee, provided that you duplicate
+all of the original copyright notices and associated disclaimers.  At
+your discretion, such binary files may be included under the conditions
+that you may Distribute them as provided in (3).
+
+Permissions for Redistribution of Modified Versions of the Source
+Form as a Standard Version
+
+(3)  You may Distribute any Modified Version in Source form under the
+conditions of section (2) above, provided that you include prominent
+notices stating how and when you changed the Package, and provided that
+the Modified Version is clearly distinguished from the Standard Version
+in one of the following ways:
+
+    (a)  make the Modified Version available as the Standard Version,
+         with the Modified Version clearly named, so that the User
+         can easily find the source of the Modified Version, and the
+         Package name and version number are clearly present.
+
+    (b)  make sure that the Modified Version has a different package
+         name than the Standard Version.
+
+    (c)  make sure that any non-Standard Version clearly carries a
+         different version number or name from the Standard Version.
+
+Permissions for Redistribution of Modified Versions of the Source
+Form as a Non-Standard Version
+
+(4)  You may Distribute any Modified Version in Source form without
+distinguishing it from the Standard Version as required by section (3)
+above, if you distribute the Modified Version exclusively in your own
+organization or company, and do not distribute it to anyone outside your
+organization or company.
+
+Permissions for Redistribution of Non-Source Forms of Modified Versions
+
+(5)  You may Distribute Non-Source Forms of a Modified Version
+provided that you do the following with each Non-Source Form:
+
+    (a)  do at least one of the following:
+
+         (i)   make the Source form of the Modified Version available
+               under the Original License, and include instructions on
+               how to acquire the Source form from the Copyright Holder;
+
+         (ii)  ensure that the Source form of the Modified Version is
+               made available under the Original License as provided
+               by the Copyright Holder;
+
+         (iii) make the Source form available from the same place
+               as the Non-Source Form;
+
+    (b)  keep intact all copyright notices and disclaimers;
+
+    (c)  clearly distinguish the Modified Version from the Standard
+         Version.
+
+Permissions for Aggregation
+
+(6)  You may Aggregate the Package with other independent programs
+and distribute the Aggregation provided that you do not state or imply
+that the Package is your own, or that the Aggregation is your own.
+
+Permissions for Linking
+
+(7)  You may link the Package with other files to produce an
+Application, and distribute the Application without restriction under
+the terms of this license.
+
+Disclaimer of Warranty
+
+(8)  THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+IMPLIED WARRANTIES.  INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

ggtree_py-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: ggtree-py
+Version: 0.1.0
+Summary: Grammar of Graphics for Phylogenetic Trees in Python — an R-compatible port of Bioconductor ggtree.
+Project-URL: Homepage, https://yulab-smu.top/treedata-book/
+Project-URL: Upstream, https://github.com/YuLab-SMU/ggtree
+Author: Guangchuang Yu, Tommy Tsan-Yuk Lam, Shuangbin Xu
+License-Expression: Artistic-2.0
+License-File: LICENSE
+Keywords: beast,bioinformatics,evolution,ggplot2,ggtree,newick,phylogenetics,phylogeny,tree-visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ggtree-py
+
+**Grammar of Graphics for Phylogenetic Trees in Python** — an R-compatible Python port of the Bioconductor [`ggtree`](https://github.com/YuLab-SMU/ggtree) ecosystem (`treeio`, `tidytree`, `treelayout`, `ggtree`).
+
+`ggtree-py` provides the `ggtree` Python package (`import ggtree`) with layered `+` plot composition, symbolic `aes(...)` expressions, 12+ phylogenetic tree layouts, evolutionary time-scale mapping (`mrsd`, `revts()`), clade manipulation, heatmaps (`gheatmap`), multiple sequence alignments (`msaplot`), multi-panel facets (`geom_facet`), node pie/bar insets (`nodepie`, `nodebar`, `inset`), tanglegrams (`ggdoubletree`), and built-in vector SVG and PNG rendering with **only `numpy` required at runtime**.
+
+---
+
+## Installation
+
+```bash
+pip install ggtree-py
+```
+
+### Requirements
+
+- **Python** `>= 3.10`
+- **Runtime dependency**: `numpy >= 1.22`
+- **Optional external rasterizer**: [`rsvg-convert`](https://wiki.gnome.org/Projects/LibRsvg) (`librsvg`) on `PATH` for high-resolution rasterization when calling `ggsave("plot.png")` or `plot.to_png()` (falls back automatically to a built-in pure-NumPy RGBA PNG rasterizer when `rsvg-convert` is not installed).
+
+### Local Development Install
+
+```bash
+git clone <repo-url>
+cd ggtree.py
+pip install -e ".[dev]"
+python3 -s -m unittest discover -s tests -v
+python3 -s examples/run_all_examples.py
+```
+
+---
+
+## Quickstart
+
+### 1. Annotated Tree (`+` Layers & Clade Highlights)
+
+```python
+import ggtree as gg
+
+tree = gg.read_tree(gg.system_file("extdata", "sample.nwk", package="treeio"))
+mrca_il = gg.MRCA(tree, "I", "L")
+
+p = (
+    gg.ggtree(tree)
+    + gg.geom_tippoint(color="steelblue", size=2)
+    + gg.geom_nodepoint(gg.aes(subset=~gg.isTip), color="orange", size=2)
+    + gg.geom_text2(gg.aes(subset=~gg.isTip, label=gg.node), hjust=-0.3, size=2.5)
+    + gg.geom_tiplab(align=True, linetype="dotted", offset=0.2)
+    + gg.geom_hilight(node=mrca_il, fill="steelblue", alpha=0.35, to_bottom=True)
+    + gg.geom_cladelab(node=mrca_il, label="italic('Clade IL')", parse=True, offset=2.0)
+    + gg.geom_strip("A", "C", label="Strip AC", offset=2.0, angle="auto")
+    + gg.geom_taxalink("A", "E", color="firebrick")
+    + gg.geom_treescale()
+    + gg.theme_tree2()
+    + gg.ggtitle("Annotated Sample Tree")
+)
+
+gg.ggsave("annotated_tree.svg", plot=p, width=9.5, height=6.5)
+gg.ggsave("annotated_tree.png", plot=p, width=9.5, height=6.5, dpi=100)
+```
+
+### 2. Time-Scaled BEAST Tree + HPD Intervals + Genotype Heatmap
+
+```python
+from ggtree import *
+
+beast_tree = read_beast(system_file("extdata/MCC_FluA_H3.tree", package="ggtree"))
+genotype = read_table(system_file("extdata/Genotype.txt", package="ggtree"), sep="\t")
+
+p_beast = (
+    ggtree(beast_tree, mrsd="2013-01-01")
+    + geom_range("height_0.95_HPD", color="red", size=1.5, alpha=0.5)
+    + geom_tiplab(size=2)
+    + theme_tree2()
+)
+
+p_hm = (
+    gheatmap(p_beast, genotype, offset=5, width=0.5, font_size=3, colnames_angle=-45, hjust=0)
+    + ggtitle("FluA H3 BEAST Tree + Genotype Heatmap")
+)
+ggsave("beast_gheatmap.png", plot=p_hm, width=11, height=11, dpi=100)
+```
+
+### 3. Multi-Scale Circular Heatmaps (`new_scale_fill`)
+
+```python
+from ggtree import *
+
+set_seed(2026)
+tr = read_tree(system_file("extdata", "sample.nwk", package="treeio"))
+df1 = DataFrame(
+    {
+        "first": ["a", "b", "a", "c", "d", "d", "a", "b", "e", "e", "f", "c", "f"],
+        "second": ["z", "z", "z", "z", "y", "y", "y", "y", "x", "x", "x", "a", "a"],
+    },
+    rownames=tr.tip_label,
+)
+df2 = DataFrame({"M1": rnorm(13).tolist(), "M2": rnorm(13).tolist()}, rownames=tr.tip_label)
+
+p1 = gheatmap(ggtree(tr, layout="circular"), df1, offset=0.8, width=0.2) + scale_fill_viridis_d(option="D") + new_scale_fill()
+p2 = gheatmap(p1, df2, offset=12.8, width=0.3) + scale_fill_viridis_c(option="A")
+ggsave("circular_stacked_heatmap.svg", plot=p2, width=9, height=8.5)
+```
+
+### 4. Composite Plots, MSA, Facets, and Tanglegrams
+
+```python
+from ggtree import *
+
+# Patchwork composition with | and /
+p_patch = (
+    (ggtree(tr) + geom_tiplab(size=2.5) + ggtitle("Rectangular"))
+    | (ggtree(tr, layout="fan", open_angle=120) + ggtitle("Fan"))
+) / (ggtree(tr, layout="tidy") + geom_tiplab(size=2.5) + ggtitle("Tidy"))
+
+# Multiple sequence alignment
+pa_tree = read_tree(system_file("extdata/pa.nwk", package="ggtree"))
+p_msa = msaplot(ggtree(pa_tree) + geom_tiplab(size=2.5), fasta=system_file("extdata/pa.fas", package="ggtree"), window=(1, 60))
+
+# Phylogeny + trait panel facet_plot / geom_facet
+trait_df = DataFrame({"id": tr.tip_label, "value": rnorm(len(tr.tip_label)).tolist()})
+p_facet = ggtree(tr) + geom_tiplab() + geom_facet(panel="Trait", data=trait_df, geom=geom_point, mapping=aes(x="value"))
+
+# Crossing-minimized tanglegram
+t1 = read_tree(text="(((a:1,b:1):1,c:2):1,(d:1.5,e:1.5):1.5);")
+t2 = read_tree(text="((e:1.5,d:1.5):1.5,(c:2,(b:1,a:1):1):1);")
+p_tangle = ggdoubletree(ggtree(t1) + geom_tiplab(), ggtree(t2) + geom_tiplab(), optimize=True, optimize_side="both")
+```
+
+---
+
+## R ↔ Python Operator & Syntax Cheatsheet
+
+| R `ggtree` | Python `ggtree` | Notes |
+| --- | --- | --- |
+| `p + layer` | `p + layer` | Immutable copy returning updated `GGTree` |
+| `p %<+% df` | `p % df` (also `<<`, `@`) | Left-joins external `DataFrame` onto tree node data |
+| `p %<% new_tree` | `p % new_tree` (also `<<`, `@`) | Replaces the underlying tree while preserving layers/themes |
+| `aes(subset = !isTip)` | `aes(subset=~isTip)` | Bitwise `~` negates symbolic expressions (`~isTip`, `"!isTip"`) |
+| `read.tree(...)`, `read.beast(...)` | `read_tree(...)`, `read_beast(...)`, or `read.tree(...)`, `read.beast(...)` | Dot-call proxies (`read`, `write`, `system`, `data`, `set_`, `as_`, `is_`) supported |
+| `p1 \| p2`, `p1 / p2` | `p1 \| p2`, `p1 / p2` | Nested patchwork composition returning `PlotList` |
+| `TRUE`, `FALSE`, `NA`, `NULL` | `True`/`TRUE`, `False`/`FALSE`, `None`/`NA`/`NULL` | R constants exported from `ggtree` |
+
+---
+
+## Documentation
+
+Full guides and reference pages live in [`docs/`](docs/index.md):
+
+- [Documentation Index](docs/index.md)
+- [Getting Started & Tree Data I/O](docs/getting_started.md)
+- [Layouts & Tree Manipulation](docs/layouts_and_manipulation.md)
+- [Annotations, Heatmaps, Facets & Multi-Tree Compositions](docs/annotations_and_compositions.md)
+- [API Reference](docs/api_reference.md)
+- [R-to-Python Migration Guide](docs/r_to_python_migration.md)
+
+---
+
+## Citation & Upstream Credit
+
+This library is a Python port of **Bioconductor `ggtree`** (`v4.3.2`) originally created by **Guangchuang Yu**, **Tommy Tsan-Yuk Lam**, **Shuangbin Xu**, and contributors ([YuLab-SMU/ggtree](https://github.com/YuLab-SMU/ggtree)).
+
+If you use `ggtree` in published research, please cite the original papers:
+
+1. S Xu, L Li, X Luo, M Chen, W Tang, L Zhan, Z Dai, TT Lam, Y Guan, **G Yu**. Ggtree: A serialized data object for visualization of a phylogenetic tree and annotation data. ***iMeta***, 2022, 1(4):e56. doi: [10.1002/imt2.56](https://doi.org/10.1002/imt2.56)
+2. **G Yu**. *Data Integration, Manipulation and Visualization of Phylogenetic Trees* (1st edition). ***Chapman and Hall/CRC***, 2022. doi: [10.1201/9781003279242](https://doi.org/10.1201/9781003279242)
+3. **G Yu**. Using ggtree to visualize data on tree-like structures. ***Current Protocols in Bioinformatics***, 2020, 69:e96. doi: [10.1002/cpbi.96](https://doi.org/10.1002/cpbi.96)
+4. **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(12):3041–3043. doi: [10.1093/molbev/msy194](https://doi.org/10.1093/molbev/msy194)
+5. **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](https://doi.org/10.1111/2041-210X.12628)
+
+## License
+
+Artistic License 2.0 — see [LICENSE](LICENSE).

ggtree_py-0.1.0/README.md

@@ -0,0 +1,173 @@
+# ggtree-py
+
+**Grammar of Graphics for Phylogenetic Trees in Python** — an R-compatible Python port of the Bioconductor [`ggtree`](https://github.com/YuLab-SMU/ggtree) ecosystem (`treeio`, `tidytree`, `treelayout`, `ggtree`).
+
+`ggtree-py` provides the `ggtree` Python package (`import ggtree`) with layered `+` plot composition, symbolic `aes(...)` expressions, 12+ phylogenetic tree layouts, evolutionary time-scale mapping (`mrsd`, `revts()`), clade manipulation, heatmaps (`gheatmap`), multiple sequence alignments (`msaplot`), multi-panel facets (`geom_facet`), node pie/bar insets (`nodepie`, `nodebar`, `inset`), tanglegrams (`ggdoubletree`), and built-in vector SVG and PNG rendering with **only `numpy` required at runtime**.
+
+---
+
+## Installation
+
+```bash
+pip install ggtree-py
+```
+
+### Requirements
+
+- **Python** `>= 3.10`
+- **Runtime dependency**: `numpy >= 1.22`
+- **Optional external rasterizer**: [`rsvg-convert`](https://wiki.gnome.org/Projects/LibRsvg) (`librsvg`) on `PATH` for high-resolution rasterization when calling `ggsave("plot.png")` or `plot.to_png()` (falls back automatically to a built-in pure-NumPy RGBA PNG rasterizer when `rsvg-convert` is not installed).
+
+### Local Development Install
+
+```bash
+git clone <repo-url>
+cd ggtree.py
+pip install -e ".[dev]"
+python3 -s -m unittest discover -s tests -v
+python3 -s examples/run_all_examples.py
+```
+
+---
+
+## Quickstart
+
+### 1. Annotated Tree (`+` Layers & Clade Highlights)
+
+```python
+import ggtree as gg
+
+tree = gg.read_tree(gg.system_file("extdata", "sample.nwk", package="treeio"))
+mrca_il = gg.MRCA(tree, "I", "L")
+
+p = (
+    gg.ggtree(tree)
+    + gg.geom_tippoint(color="steelblue", size=2)
+    + gg.geom_nodepoint(gg.aes(subset=~gg.isTip), color="orange", size=2)
+    + gg.geom_text2(gg.aes(subset=~gg.isTip, label=gg.node), hjust=-0.3, size=2.5)
+    + gg.geom_tiplab(align=True, linetype="dotted", offset=0.2)
+    + gg.geom_hilight(node=mrca_il, fill="steelblue", alpha=0.35, to_bottom=True)
+    + gg.geom_cladelab(node=mrca_il, label="italic('Clade IL')", parse=True, offset=2.0)
+    + gg.geom_strip("A", "C", label="Strip AC", offset=2.0, angle="auto")
+    + gg.geom_taxalink("A", "E", color="firebrick")
+    + gg.geom_treescale()
+    + gg.theme_tree2()
+    + gg.ggtitle("Annotated Sample Tree")
+)
+
+gg.ggsave("annotated_tree.svg", plot=p, width=9.5, height=6.5)
+gg.ggsave("annotated_tree.png", plot=p, width=9.5, height=6.5, dpi=100)
+```
+
+### 2. Time-Scaled BEAST Tree + HPD Intervals + Genotype Heatmap
+
+```python
+from ggtree import *
+
+beast_tree = read_beast(system_file("extdata/MCC_FluA_H3.tree", package="ggtree"))
+genotype = read_table(system_file("extdata/Genotype.txt", package="ggtree"), sep="\t")
+
+p_beast = (
+    ggtree(beast_tree, mrsd="2013-01-01")
+    + geom_range("height_0.95_HPD", color="red", size=1.5, alpha=0.5)
+    + geom_tiplab(size=2)
+    + theme_tree2()
+)
+
+p_hm = (
+    gheatmap(p_beast, genotype, offset=5, width=0.5, font_size=3, colnames_angle=-45, hjust=0)
+    + ggtitle("FluA H3 BEAST Tree + Genotype Heatmap")
+)
+ggsave("beast_gheatmap.png", plot=p_hm, width=11, height=11, dpi=100)
+```
+
+### 3. Multi-Scale Circular Heatmaps (`new_scale_fill`)
+
+```python
+from ggtree import *
+
+set_seed(2026)
+tr = read_tree(system_file("extdata", "sample.nwk", package="treeio"))
+df1 = DataFrame(
+    {
+        "first": ["a", "b", "a", "c", "d", "d", "a", "b", "e", "e", "f", "c", "f"],
+        "second": ["z", "z", "z", "z", "y", "y", "y", "y", "x", "x", "x", "a", "a"],
+    },
+    rownames=tr.tip_label,
+)
+df2 = DataFrame({"M1": rnorm(13).tolist(), "M2": rnorm(13).tolist()}, rownames=tr.tip_label)
+
+p1 = gheatmap(ggtree(tr, layout="circular"), df1, offset=0.8, width=0.2) + scale_fill_viridis_d(option="D") + new_scale_fill()
+p2 = gheatmap(p1, df2, offset=12.8, width=0.3) + scale_fill_viridis_c(option="A")
+ggsave("circular_stacked_heatmap.svg", plot=p2, width=9, height=8.5)
+```
+
+### 4. Composite Plots, MSA, Facets, and Tanglegrams
+
+```python
+from ggtree import *
+
+# Patchwork composition with | and /
+p_patch = (
+    (ggtree(tr) + geom_tiplab(size=2.5) + ggtitle("Rectangular"))
+    | (ggtree(tr, layout="fan", open_angle=120) + ggtitle("Fan"))
+) / (ggtree(tr, layout="tidy") + geom_tiplab(size=2.5) + ggtitle("Tidy"))
+
+# Multiple sequence alignment
+pa_tree = read_tree(system_file("extdata/pa.nwk", package="ggtree"))
+p_msa = msaplot(ggtree(pa_tree) + geom_tiplab(size=2.5), fasta=system_file("extdata/pa.fas", package="ggtree"), window=(1, 60))
+
+# Phylogeny + trait panel facet_plot / geom_facet
+trait_df = DataFrame({"id": tr.tip_label, "value": rnorm(len(tr.tip_label)).tolist()})
+p_facet = ggtree(tr) + geom_tiplab() + geom_facet(panel="Trait", data=trait_df, geom=geom_point, mapping=aes(x="value"))
+
+# Crossing-minimized tanglegram
+t1 = read_tree(text="(((a:1,b:1):1,c:2):1,(d:1.5,e:1.5):1.5);")
+t2 = read_tree(text="((e:1.5,d:1.5):1.5,(c:2,(b:1,a:1):1):1);")
+p_tangle = ggdoubletree(ggtree(t1) + geom_tiplab(), ggtree(t2) + geom_tiplab(), optimize=True, optimize_side="both")
+```
+
+---
+
+## R ↔ Python Operator & Syntax Cheatsheet
+
+| R `ggtree` | Python `ggtree` | Notes |
+| --- | --- | --- |
+| `p + layer` | `p + layer` | Immutable copy returning updated `GGTree` |
+| `p %<+% df` | `p % df` (also `<<`, `@`) | Left-joins external `DataFrame` onto tree node data |
+| `p %<% new_tree` | `p % new_tree` (also `<<`, `@`) | Replaces the underlying tree while preserving layers/themes |
+| `aes(subset = !isTip)` | `aes(subset=~isTip)` | Bitwise `~` negates symbolic expressions (`~isTip`, `"!isTip"`) |
+| `read.tree(...)`, `read.beast(...)` | `read_tree(...)`, `read_beast(...)`, or `read.tree(...)`, `read.beast(...)` | Dot-call proxies (`read`, `write`, `system`, `data`, `set_`, `as_`, `is_`) supported |
+| `p1 \| p2`, `p1 / p2` | `p1 \| p2`, `p1 / p2` | Nested patchwork composition returning `PlotList` |
+| `TRUE`, `FALSE`, `NA`, `NULL` | `True`/`TRUE`, `False`/`FALSE`, `None`/`NA`/`NULL` | R constants exported from `ggtree` |
+
+---
+
+## Documentation
+
+Full guides and reference pages live in [`docs/`](docs/index.md):
+
+- [Documentation Index](docs/index.md)
+- [Getting Started & Tree Data I/O](docs/getting_started.md)
+- [Layouts & Tree Manipulation](docs/layouts_and_manipulation.md)
+- [Annotations, Heatmaps, Facets & Multi-Tree Compositions](docs/annotations_and_compositions.md)
+- [API Reference](docs/api_reference.md)
+- [R-to-Python Migration Guide](docs/r_to_python_migration.md)
+
+---
+
+## Citation & Upstream Credit
+
+This library is a Python port of **Bioconductor `ggtree`** (`v4.3.2`) originally created by **Guangchuang Yu**, **Tommy Tsan-Yuk Lam**, **Shuangbin Xu**, and contributors ([YuLab-SMU/ggtree](https://github.com/YuLab-SMU/ggtree)).
+
+If you use `ggtree` in published research, please cite the original papers:
+
+1. S Xu, L Li, X Luo, M Chen, W Tang, L Zhan, Z Dai, TT Lam, Y Guan, **G Yu**. Ggtree: A serialized data object for visualization of a phylogenetic tree and annotation data. ***iMeta***, 2022, 1(4):e56. doi: [10.1002/imt2.56](https://doi.org/10.1002/imt2.56)
+2. **G Yu**. *Data Integration, Manipulation and Visualization of Phylogenetic Trees* (1st edition). ***Chapman and Hall/CRC***, 2022. doi: [10.1201/9781003279242](https://doi.org/10.1201/9781003279242)
+3. **G Yu**. Using ggtree to visualize data on tree-like structures. ***Current Protocols in Bioinformatics***, 2020, 69:e96. doi: [10.1002/cpbi.96](https://doi.org/10.1002/cpbi.96)
+4. **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(12):3041–3043. doi: [10.1093/molbev/msy194](https://doi.org/10.1093/molbev/msy194)
+5. **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](https://doi.org/10.1111/2041-210X.12628)
+
+## License
+
+Artistic License 2.0 — see [LICENSE](LICENSE).