/etetoolkit

name: etetoolkit
description: "Phylogenetic tree toolkit (ETE). Tree manipulation (Newick/NHX), evolutionary event detection, orthology/paralogy, NCBI taxonomy, visualization (PDF/SVG), for phylogenomics."

ETE Toolkit Skill

Overview

ETE (Environment for Tree Exploration) is a toolkit for phylogenetic and hierarchical tree analysis. Manipulate trees, analyze evolutionary events, visualize results, and integrate with biological databases for phylogenomic research and clustering analysis.

Core Capabilities

1. Tree Manipulation and Analysis

Load, manipulate, and analyze hierarchical tree structures with support for:

• **Tree I/O**: Read and write Newick, NHX, PhyloXML, and NeXML formats
• **Tree traversal**: Navigate trees using preorder, postorder, or levelorder strategies
• **Topology modification**: Prune, root, collapse nodes, resolve polytomies
• **Distance calculations**: Compute branch lengths and topological distances between nodes
• **Tree comparison**: Calculate Robinson-Foulds distances and identify topological differences

**Common patterns:**

from ete3 import Tree

# Load tree from file
tree = Tree("tree.nw", format=1)

# Basic statistics
print(f"Leaves: {len(tree)}")
print(f"Total nodes: {len(list(tree.traverse()))}")

# Prune to taxa of interest
taxa_to_keep = ["species1", "species2", "species3"]
tree.prune(taxa_to_keep, preserve_branch_length=True)

# Midpoint root
midpoint = tree.get_midpoint_outgroup()
tree.set_outgroup(midpoint)

# Save modified tree
tree.write(outfile="rooted_tree.nw")

Use `scripts/tree_operations.py` for command-line tree manipulation:

# Display tree statistics
python scripts/tree_operations.py stats tree.nw

# Convert format
python scripts/tree_operations.py convert tree.nw output.nw --in-format 0 --out-format 1

# Reroot tree
python scripts/tree_operations.py reroot tree.nw rooted.nw --midpoint

# Prune to specific taxa
python scripts/tree_operations.py prune tree.nw pruned.nw --keep-taxa "sp1,sp2,sp3"

# Show ASCII visualization
python scripts/tree_operations.py ascii tree.nw

2. Phylogenetic Analysis

Analyze gene trees with evolutionary event detection:

• **Sequence alignment integration**: Link trees to multiple sequence alignments (FASTA, Phylip)
• **Species naming**: Automatic or custom species extraction from gene names
• **Evolutionary events**: Detect duplication and speciation events using Species Overlap or tree reconciliation
• **Orthology detection**: Identify orthologs and paralogs based on evolutionary events
• **Gene family analysis**: Split trees by duplications, collapse lineage-specific expansions

**Workflow for gene tree analysis:**

from ete3 import PhyloTree

# Load gene tree with alignment
tree = PhyloTree("gene_tree.nw", alignment="alignment.fasta")

# Set species naming function
def get_species(gene_name):
    return gene_name.split("_")[0]

tree.set_species_naming_function(get_species)

# Detect evolutionary events
events = tree.get_descendant_evol_events()

# Analyze events
for node in tree.traverse():
    if hasattr(node, "evoltype"):
        if node.evoltype == "D":
            print(f"Duplication at {node.name}")
        elif node.evoltype == "S":
            print(f"Speciation at {node.name}")

# Extract ortholog groups
ortho_groups = tree.get_speciation_trees()
for i, ortho_tree in enumerate(ortho_groups):
    ortho_tree.write(outfile=f"ortholog_group_{i}.nw")

**Finding orthologs and paralogs:**

# Find orthologs to query gene
query = tree & "species1_gene1"

orthologs = []
paralogs = []

for event in events:
    if query in event.in_seqs:
        if event.etype == "S":
            orthologs.extend([s for s in event.out_seqs if s != query])
        elif event.etype == "D":
            paralogs.extend([s for s in event.out_seqs if s != query])

3. NCBI Taxonomy Integration

Integrate taxonomic information from NCBI Taxonomy database:

• **Database access**: Automatic download and local caching of NCBI taxonomy (~300MB)
• **Taxid/name translation**: Convert between taxonomic IDs and scientific names
• **Lineage retrieval**: Get complete evolutionary lineages
• **Taxonomy trees**: Build species trees connecting specified taxa
• **Tree annotation**: Automatically annotate trees with taxonomic information

**Building taxonomy-based trees:**

from ete3 import NCBITaxa

ncbi = NCBITaxa()

# Build tree from species names
species = ["Homo sapiens", "Pan troglodytes", "Mus musculus"]
name2taxid = ncbi.get_name_translator(species)
taxids = [name2taxid[sp][0] for sp in species]

# Get minimal tree connecting taxa
tree = ncbi.get_topology(taxids)

# Annotate nodes with taxonomy info
for node in tree.traverse():
    if hasattr(node, "sci_name"):
        print(f"{node.sci_name} - Rank: {node.rank} - TaxID: {node.taxid}")

**Annotating existing trees:**

# Get taxonomy info for tree leaves
for leaf in tree:
    species = extract_species_from_name(leaf.name)
    taxid = ncbi.get_name_translator([species])[species][0]

    # Get lineage
    lineage = ncbi.get_lineage(taxid)
    ranks = ncbi.get_rank(lineage)
    names = ncbi.get_taxid_translator(lineage)

    # Add to node
    leaf.add_feature("taxid", taxid)
    leaf.add_feature("lineage", [names[t] for t in lineage])

4. Tree Visualization

Create publication-quality tree visualizations:

• **Output formats**: PNG (raster), PDF, and SVG (vector) for publications
• **Layout modes**: Rectangular and circular tree layouts
• **Interactive GUI**: Explore trees interactively with zoom, pan, and search
• **Custom styling**: NodeStyle for node appearance (colors, shapes, sizes)
• **Faces**: Add graphical elements (text, images, charts, heatmaps) to nodes
• **Layout functions**: Dynamic styling based on node properties

**Basic visualization workflow:**

from ete3 import Tree, TreeStyle, NodeStyle

tree = Tree("tree.nw")

# Configure tree style
ts = TreeStyle()