etetoolkit
Analyze, manipulate, compare, annotate, and visualize phylogenetic or other hierarchical trees with ETE 4. Use for Newick/Nexus tree I/O, topology edits and pattern matching, Robinson-Foulds comparisons, gene-tree evolutionary events and reconciliation, NCBI/GTDB taxonomy, SmartView exploration, and publication rendering. Do not use it to infer trees from raw sequences; align sequences and infer a tree first.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill etetoolkituvx research-agent-skills install etetoolkitDocumentation & Instructions
ETE Toolkit 4
Scope
Use ETE 4 to work with an existing tree:
- Read Newick/Nexus, then inspect, annotate, transform, root, prune, and write Newick trees
- Compare topologies and calculate phylogenetic distances
- Find repeated subtree topologies with
TreePattern - Analyze gene trees with
PhyloTree - Query local NCBI or GTDB taxonomy databases
- Explore large trees interactively with SmartView
- Render PNG with SmartView or PNG/PDF/SVG with the optional Qt treeview
ETE does not replace sequence alignment or phylogenetic inference software. For raw sequences, first use MAFFT or another aligner and IQ-TREE 2, FastTree, or another inference tool; then load the resulting tree into ETE.
Current Target
This skill targets ETE 4.4.0, released September 3, 2025 and verified as the current PyPI release on July 23, 2026.
Use https://etetoolkit.github.io/ete/ for ETE 4 documentation. The
etetoolkit.org/docs/latest pages are legacy ETE 3 documentation despite the
URL name.
Do not silently translate these examples back to ETE 3:
- Package and import:
ete4, notete3 - File input: pass an open file object; use strings for Newick text and do not rely on path-string heuristics retained in ETE 4.4.0
- Newick selection:
parser=, notformat= - Node metadata:
props,add_prop(), andadd_props() - Iteration:
leaves(),descendants(), and related methods return iterators - Predicates:
node.is_leafandnode.is_rootare properties, not methods - Node lookup:
tree["name"], nottree & "name"
For porting older code, load
references/migration-ete3-to-ete4.md.
Installation
Install the pinned base package:
uv pip install "ete4==4.4.0"
Add only the visualization extra required by the workflow:
# SmartView static PNG screenshots
uv pip install "ete4[render-sm]==4.4.0"
# Legacy Qt renderer for PNG, PDF, and SVG
uv pip install "ete4[treeview]==4.4.0"
Confirm the active environment:
uv run --with "ete4==4.4.0" python -c "import ete4; print(ete4.__version__)"
No credentials are required. NCBI and GTDB workflows download public taxonomy
data and can consume substantial disk space; see
references/taxonomy.md before the first update.
Quick Start
from pathlib import Path
from ete4 import Tree
# Use an open file object for files; reserve strings for Newick text.
with Path("tree.nw").open(encoding="utf-8") as handle:
tree = Tree(handle, parser=1) # parser 1: internal node names
print(tree.to_str(props=["name", "dist"], compact=True))
print("Leaves:", list(tree.leaf_names()))
# Search and annotate.
focal = tree["species1"]
focal.add_props(host="human", status="focal")
# Keep selected tips while preserving pairwise branch-length distances.
tree.prune(
["species1", "species2", "species3"],
preserve_branch_length=True,
)
# Root and serialize explicitly.
tree.set_midpoint_outgroup()
tree.write(
outfile="processed.nw",
parser=1,
props=["host", "status"],
)
Choose the parser deliberately. A parser mismatch is the most common cause of
NewickError, lost internal labels, or support values being read as names.
See references/api_reference.md.
Core Workflows
Inspect and transform a tree
from ete4 import Tree
tree = Tree("((A:1,B:1)CladeAB:0.4,C:2)Root;", parser=1)
for node in tree.traverse("preorder"):
label = node.name if node.name is not None else node.id
print(label, node.level, node.is_leaf, node.dist)
tree["A"].add_prop("group", "case")
tree["B"].add_prop("group", "control")
mrca = tree.common_ancestor("A", "B")
print(mrca.name)
tree.write(
outfile="annotated.nhx",
parser=1,
props=["group"],
format_root_node=True,
)
Node names need not be unique. tree["A"] returns the first match; use
list(tree.search_nodes(name="A")) and validate the count when duplicates are
possible.
Compare two topologies
from ete4 import Tree
tree_a = Tree("((A,B),(C,D));")
tree_b = Tree("((A,C),(B,D));")
(
rf,
max_rf,
common_leaves,
edges_a,
edges_b,
discarded_a,
discarded_b,
) = tree_a.robinson_foulds(tree_b)
normalized_rf = rf / max_rf if max_rf else 0.0
print(rf, max_rf, normalized_rf, sorted(common_leaves))
RF comparison uses shared leaf labels and requires meaningful, preferably unique names. Decide explicitly whether rooted or unrooted comparison is scientifically appropriate.
Detect duplication and speciation events
from ete4 import PhyloTree
gene_tree = PhyloTree(
"((Hsa|g1,Ptr|g1),(Hsa|g2,Mmu|g1));",
sp_naming_function=lambda name: name.split("|", 1)[0],
)
for event in gene_tree.get_descendant_evol_events(sos_thr=0.0):
relationship = "speciation/orthology" if event.etype == "S" else "duplication/paralogy"
print(relationship, sorted(event.in_seqs), sorted(event.out_seqs))
Species-overlap calls are inferences from the supplied topology and naming
function, not independent evidence of orthology. Pass the naming function
explicitly, and use a rooted, fully bifurcating gene tree. For strict
reconciliation, use a curated species tree and
gene_tree.reconcile(species_tree).
Query taxonomy
from ete4 import NCBITaxa
ncbi = NCBITaxa()
names = ["Homo sapiens", "Pan troglodytes", "Mus musculus"]
name_to_taxids = ncbi.get_name_translator(names)
missing = [name for name in names if name not in name_to_taxids]
if missing:
raise ValueError(f"Names not resolved by NCBI taxonomy: {missing}")
taxids = [name_to_taxids[name][0] for name in names]
taxonomy_tree = ncbi.get_topology(taxids)
print(taxonomy_tree.to_str(props=["sci_name", "rank"]))
ETE 4 also provides GTDBTaxa for genome-centric bacterial and archaeal
taxonomy. Do not mix NCBI numeric TaxIDs and GTDB string identifiers.
Visualize
Interactive SmartView:
from ete4 import Tree
tree = Tree("((A:1,B:1)90:0.2,C:1);", parser="support")
tree.explore()
Static SmartView screenshot:
tree.render_sm("tree.png", w=1200, h=800)
render_sm() produces PNG screenshot data; use the Qt treeview renderer when
the deliverable must be vector PDF or SVG. Load
references/visualization.md for layouts,
faces, remote exploration, and renderer selection.
Bundled Scripts
Run from this skill directory. The commands below use a pinned, isolated ETE 4
runtime through uv run --with.
Tree operations
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
stats tree.nw --parser 1
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
ascii tree.nw --parser 1 --props name,dist
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
convert tree.nw output.nw \
--input-parser 1 --output-parser 1
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
reroot tree.nw rooted.nw \
--parser 1 --midpoint
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
prune tree.nw pruned.nw \
--parser 1 --keep species1 species2 species3
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
compare tree_a.nw tree_b.nw
Use --keep-file taxa.txt instead of --keep ... for one taxon per line.
The script refuses ambiguous or missing requested names rather than silently
producing a partial tree.
Visualization
# Interactive SmartView
uv run --with "ete4==4.4.0" python scripts/quick_visualize.py \
tree.nw --parser 1
# SmartView PNG (requires ete4[render-sm])
uv run --with "ete4[render-sm]==4.4.0" python scripts/quick_visualize.py \
tree.nw tree.png \
--parser support --mode circular --show-support --color-by-support
# Vector output via Qt treeview (requires ete4[treeview])
uv run --with "ete4[treeview]==4.4.0" python scripts/quick_visualize.py \
tree.nw tree.svg \
--parser 1 --engine treeview --title "Species phylogeny"
Quality and Interpretation Checks
Before reporting a result:
- Confirm the parser preserves the intended internal names, support, and branch lengths.
- Check for empty and duplicate leaf names before name-based lookup or RF comparison.
- State whether the tree is treated as rooted or unrooted.
- Preserve branch lengths when pruning only if retained pairwise distances should remain unchanged.
- Treat arbitrary polytomy resolution as a display/algorithmic convenience, not evolutionary evidence.
- Record ETE version, parser, rooting method, pruning set, and taxonomy database snapshot in reproducible analyses.
- Prefer iterators for large trees and
get_cached_content()for repeated descendant-content queries.
Reference Map
Load only the reference needed for the task:
references/api_reference.md— ETE 4 core classes, parsers, properties, traversal, I/O, topology, and comparisonreferences/workflows.md— complete analysis patterns, validation, reconciliation, batching, and large-tree workreferences/visualization.md— SmartView, layouts/faces, PNG screenshots, and Qt vector renderingreferences/taxonomy.md— NCBI and GTDB setup, translation, topology, annotation, and reproducibilityreferences/migration-ete3-to-ete4.md— breaking API changes and porting checklist
Authoritative Upstream Sources
- Documentation: https://etetoolkit.github.io/ete/
- ETE 3 to ETE 4 migration: https://etetoolkit.github.io/ete/3to4.html
- Releases: https://github.com/etetoolkit/ete/releases
- PyPI: https://pypi.org/project/ete4/
- Source: https://github.com/etetoolkit/ete
- Visualization gallery: https://github.com/etetoolkit/ete-gallery
Agent operating procedure
- Check the environment. Confirm tool versions, the reference genome/annotation build and the input formats (FASTQ, BAM, VCF, h5ad).
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Run the pipeline on a small subset (one sample, one chromosome, a few thousand cells) first.
- Execute the full task using the instructions and references above.
- Validate the result. Check QC metrics, sample identities, genome build consistency and batch effects before interpreting results.
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| Genome builds or identifiers do not match between inputs | Stop and harmonize (liftover, ID mapping) before continuing. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Do not interpret biological significance beyond what the statistics support; report multiple-testing correction.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Related skills
biopython: Provides Biopython (Bio.Seq, Bio.SeqIO, Bio.Align, Bio.Entrez, Bio.Blast, Bio.PDB, Bio.Phylo, Bio.motifs, Bio.SeqUtils, Bio.Restriction) fo…scikit-bio: Python library scikit-bio for biological sequence and community-ecology analysis: DNA/RNA/protein sequences, pair_align alignment, phylogen…
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects etetoolkit for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“How do I load a Newick file in ete4 and prune it down to just 12 taxa?”
expects Uses ete4 (not ete3) with an open file object or a Newick string and an explicit parser= choice. Prunes via the tree's prune method with a validated list of leaf names, and says whether branch lengths are preserved. Checks that the names exist and are unique.
- should trigger
“I'm porting my lab's old ete3 script to ete4 and it now fails with 'NewickError' on gene_tree.nwk, which has bootstrap support on internal nodes. The old code used Tree('gene_tree.nwk', format=1) and `t & 'Hsap_1'`, then called node.is_leaf() and t.get_leaves(). Fix it and then label each internal node as duplication or speciation, where leaf names look like SPECIES_geneID.”
expects Explains the ETE 4 changes: import from ete4, parser= instead of format=, pass an open file object or Newick text rather than a path string, tree['Hsap_1'] for lookup, is_leaf as a property, and leaves() returning an iterator. Picks a parser that keeps support values rather than reading them as names. Uses PhyloTree with an explicit species-naming function, requires a rooted bifurcating tree, and notes that species-overlap calls are inferences. Suggests a curated species tree with reconcile() for strict reconciliation.
- should trigger
“I have two published trees for the same 40 bird species, one from mitochondrial genomes and one from nuclear loci. I want a number that tells me how different their branching patterns are, and I'd also like to know which splits they disagree on.”
expects Recommends a Robinson-Foulds comparison on the shared leaf labels using ETE. Checks that leaf names are unique and match across the two trees, and decides explicitly between rooted and unrooted comparison. Reports normalized RF along with the specific differing splits, and states the ETE version and parser used.
Near misses (2)
- near miss
“I have 16S rRNA FASTA sequences for 60 bacterial isolates. Align them and build a maximum-likelihood tree with bootstrap support.”
expects Recognizes that inferring a tree from raw sequences is outside this skill's scope. Recommends aligning with MAFFT and inferring the tree with IQ-TREE 2 or FastTree. ETE would only be used afterward to load, inspect or render the resulting tree.
- near miss
“Compute Faith's phylogenetic diversity and weighted UniFrac distances across my 30 soil microbiome samples from an OTU table and a tree, then run PERMANOVA on the treatment groups.”
expects Identifies this as community-ecology diversity analysis, so it should use scikit-bio and not ETE. Computes Faith's PD and weighted UniFrac from the OTU table and tree, then runs PERMANOVA on the resulting distance matrix.