| name | alterlab-phylogenetics |
| description | Build phylogenetic trees end-to-end from raw sequences — MAFFT multiple sequence alignment, optional TrimAl trimming, IQ-TREE 2 maximum-likelihood inference with model selection and bootstraps, FastTree for large datasets, then visualize with ETE3 or FigTree. Use when reconstructing trees from sequences (FASTA) for evolutionary analysis, microbial genomics, viral phylodynamics, protein-family studies, or molecular-clock dating. For manipulating/comparing an EXISTING Newick tree (prune, root, Robinson-Foulds, duplication/speciation events) use alterlab-etetoolkit; for plain sequence parsing/translation use alterlab-biopython. Part of the AlterLab Academic Skills suite. |
| license | MIT |
| allowed-tools | Read Write Edit Bash(python:*) Bash(uv:*) |
| compatibility | Needs external CLI tools (MAFFT, IQ-TREE 2, FastTree; optionally TrimAl) on PATH — install via bioconda or Homebrew, NOT pip/uv. Python parts (ETE3 for visualization) run under `uv run python`. No API key or account required. |
| metadata | {"skill-author":"AlterLab","version":"1.0.0"} |
Phylogenetics
Overview
Phylogenetic analysis reconstructs the evolutionary history of biological sequences (genes, proteins, genomes) by inferring the branching pattern of descent. This skill covers the standard pipeline:
- MAFFT — Multiple sequence alignment
- IQ-TREE 2 — Maximum likelihood tree inference with model selection
- FastTree — Fast approximate maximum likelihood (for large datasets)
- ETE3 — Python library for tree manipulation and visualization
Installation: The aligners and tree builders are compiled CLI tools (not on PyPI). Install the binaries via bioconda or Homebrew; install the Python visualization layer with uv.
conda install -c bioconda mafft iqtree fasttree trimal
brew install mafft fasttree
brew tap brewsci/bio && brew install brewsci/bio/iqtree brewsci/bio/trimal
uv pip install "ete3==3.1.3"
ETE3 (3.1.3) is the last ete3 release and can be fragile to install on Python ≥3.12 (pins old numpy/PyQt5). If t.render() fails, fall back to writing the Newick tree and viewing it in FigTree/iTOL, or use the maintained successor ete4 (note: ete4 changed the TreeStyle/render API, so the snippets below are ete3-specific).
When to Use This Skill
Use phylogenetics when:
- Evolutionary relationships: Which organism/gene is most closely related to my sequence?
- Viral phylodynamics: Trace outbreak spread and estimate transmission dates
- Protein family analysis: Infer evolutionary relationships within a gene family
- Horizontal gene transfer detection: Identify genes with discordant species/gene trees
- Ancestral sequence reconstruction: Infer ancestral protein sequences
- Molecular clock analysis: Estimate divergence dates using temporal sampling
- GWAS companion: Place variants in evolutionary context (e.g., SARS-CoV-2 variants)
- Microbiology: Species phylogeny from 16S rRNA or core genome phylogeny
Standard Workflow
1. Multiple Sequence Alignment with MAFFT
import subprocess
import os
def run_mafft(input_fasta: str, output_fasta: str, method: str = "auto",
n_threads: int = 4) -> str:
"""
Align sequences with MAFFT.
Args:
input_fasta: Path to unaligned FASTA file
output_fasta: Path for aligned output
method: 'auto' (auto-select), 'einsi' (accurate), 'linsi' (accurate, slow),
'fftnsi' (medium), 'fftns' (fast), 'retree2' (fast)
n_threads: Number of CPU threads
Returns:
Path to aligned FASTA file
"""
methods = {
"auto": ["mafft", "--auto"],
"einsi": ["mafft", "--genafpair", "--maxiterate", "1000"],
"linsi": ["mafft", "--localpair", "--maxiterate", "1000"],
"fftnsi": ["mafft", "--retree", "2", "--maxiterate", "2"],
"fftns": ["mafft", "--retree", "2", "--maxiterate", "0"],
"retree2": ["mafft", "--retree", "2"],
}
cmd = methods.get(method, methods["auto"])
cmd += ["--thread", str(n_threads), "--inputorder", input_fasta]
(output_fasta, ) out:
result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=)
result.returncode != :
RuntimeError()
(output_fasta) f:
n_seqs = ( line f line.startswith())
()
output_fasta
2. Trim Alignment (Optional but Recommended)
def trim_alignment_trimal(aligned_fasta: str, output_fasta: str,
method: str = "automated1") -> str:
"""
Trim poorly aligned columns with TrimAl.
Methods:
- 'automated1': Automatic heuristic (recommended)
- 'gappyout': Remove gappy columns
- 'strict': Strict gap threshold
"""
cmd = ["trimal", f"-{method}", "-in", aligned_fasta, "-out", output_fasta, "-fasta"]
result = subprocess.run(cmd, capture_output=True, text=True)
if result.returncode != 0:
print(f"TrimAl warning: {result.stderr}")
import shutil
shutil.copy(aligned_fasta, output_fasta)
return output_fasta
3. IQ-TREE 2 — Maximum Likelihood Tree
def run_iqtree(aligned_fasta: str, output_prefix: str,
model: str = "TEST", bootstrap: int = 1000,
n_threads: int = 4, extra_args: list = None) -> dict:
"""
Build a maximum likelihood tree with IQ-TREE 2.
Args:
aligned_fasta: Aligned FASTA file
output_prefix: Prefix for output files
model: 'TEST' for automatic model selection, or specify (e.g., 'GTR+G' for DNA,
'LG+G4' for proteins, 'JTT+G' for proteins)
bootstrap: Number of ultrafast bootstrap replicates (1000 recommended)
n_threads: Number of threads ('AUTO' to auto-detect)
extra_args: Additional IQ-TREE arguments
Returns:
Dict with paths to output files
"""
cmd = [
"iqtree2",
"-s", aligned_fasta,
"--prefix", output_prefix,
"-m", model,
"-B", str(bootstrap),
"-T", str(n_threads),
"--redo"
]
if extra_args:
cmd.extend(extra_args)
result = subprocess.run(cmd, capture_output=True, text=True)
if result.returncode != 0:
raise RuntimeError(f"IQ-TREE failed:\n{result.stderr}")
log_file = f"{output_prefix}.log"
if os.path.exists(log_file):
with (log_file) f:
line f:
line:
()
output_files = {
: ,
: ,
: ,
: ,
}
()
output_files
4. FastTree — Fast Approximate ML
For large datasets (>1000 sequences) where IQ-TREE is too slow:
def run_fasttree(aligned_fasta: str, output_tree: str,
sequence_type: str = "nt", model: str = "gtr",
n_threads: int = 4) -> str:
"""
Build a fast approximate ML tree with FastTree.
Args:
sequence_type: 'nt' for nucleotide or 'aa' for amino acid
model: For nt: 'gtr' (recommended) or 'jc'; for aa: 'lg', 'wag', 'jtt'
"""
if sequence_type == "nt":
cmd = ["FastTree", "-nt", "-gtr"]
else:
cmd = ["FastTree", f"-{model}"]
cmd += [aligned_fasta]
with open(output_tree, 'w') as out:
result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)
if result.returncode != 0:
raise RuntimeError(f"FastTree failed:\n{result.stderr}")
print(f"FastTree: Tree saved to {output_tree}")
return output_tree
5. Tree Analysis and Visualization with ETE3
from ete3 import Tree, TreeStyle, NodeStyle, TextFace, PhyloTree
import matplotlib.pyplot as plt
def load_tree(tree_file: str) -> Tree:
"""Load a Newick tree file."""
t = Tree(tree_file)
print(f"Tree: {len(t)} leaves, {len(list(t.traverse()))} nodes")
return t
def basic_tree_stats(t: Tree) -> dict:
"""Compute basic tree statistics."""
leaves = t.get_leaves()
distances = [t.get_distance(l1, l2) for l1 in leaves[:min(50, len(leaves))]
for l2 in leaves[:min(50, len(leaves))] if l1 != l2]
stats = {
"n_leaves": len(leaves),
"n_internal_nodes": len(t) - len(leaves),
"total_branch_length": sum(n.dist for n in t.traverse()),
"max_leaf_distance": max(distances) if distances else 0,
"mean_leaf_distance": sum(distances)/(distances) distances ,
}
stats
() -> Tree:
t.get_common_ancestor(*leaf_names)
() -> :
ts = TreeStyle()
ts.show_leaf_name =
ts.show_branch_support = show_branch_support
ts.mode =
color_groups:
node t.traverse():
node.is_leaf() node.name color_groups:
nstyle = NodeStyle()
nstyle[] = color_groups[node.name]
nstyle[] =
node.set_style(nstyle)
t.render(output_file, tree_style=ts, w=width, units=)
()
() -> Tree:
t.set_outgroup(t.get_midpoint_outgroup())
t
() -> Tree:
t.prune(keep_leaves, preserve_branch_length=)
t
6. Complete Analysis Script
import subprocess, os
from ete3 import Tree
def full_phylogenetic_analysis(
input_fasta: str,
output_dir: str = "phylo_results",
sequence_type: str = "nt",
n_threads: int = 4,
bootstrap: int = 1000,
use_fasttree: bool = False
) -> dict:
"""
Complete phylogenetic pipeline: align → trim → tree → visualize.
Args:
input_fasta: Unaligned FASTA
sequence_type: 'nt' (nucleotide) or 'aa' (amino acid/protein)
use_fasttree: Use FastTree instead of IQ-TREE (faster for large datasets)
"""
os.makedirs(output_dir, exist_ok=True)
prefix = os.path.join(output_dir, "phylo")
print("=" * 50)
print("Step 1: Multiple Sequence Alignment (MAFFT)")
aligned = run_mafft(input_fasta, f"{prefix}_aligned.fasta",
method="auto", n_threads=n_threads)
print("\nStep 2: Tree Inference")
if use_fasttree:
tree_file = run_fasttree(
aligned, f"{prefix}.tree",
sequence_type=sequence_type,
model="gtr" if sequence_type == "nt" else "lg"
)
else:
iqtree_files = run_iqtree(
aligned, prefix,
model=,
bootstrap=bootstrap,
n_threads=n_threads
)
tree_file = iqtree_files[]
()
t = Tree(tree_file)
t = midpoint_root(t)
stats = basic_tree_stats(t)
()
()
visualize_tree(t, , show_branch_support=)
rooted_tree_file =
t.write(=, outfile=rooted_tree_file)
results = {
: aligned,
: tree_file,
: rooted_tree_file,
: ,
: stats
}
( + * )
()
()
results
IQ-TREE Model Guide
DNA Models
| Model | Description | Use case |
|---|
GTR+G4 | General Time Reversible + Gamma | Most flexible DNA model |
HKY+G4 | Hasegawa-Kishino-Yano + Gamma | Two-rate model (common) |
TrN+G4 | Tamura-Nei | Unequal transitions |
JC | Jukes-Cantor | Simplest; all rates equal |
Protein Models
| Model | Description | Use case |
|---|
LG+G4 | Le-Gascuel + Gamma | Best average protein model |
WAG+G4 | Whelan-Goldman | Widely used |
JTT+G4 | Jones-Taylor-Thornton | Classical model |
Q.pfam+G4 | Pfam-trained (QMaker) | General protein families |
Q.bird+G4 | Bird clade-specific (QMaker) | Bird proteins; siblings: Q.mammal, Q.insect, Q.yeast, Q.plant |
Tip: Use -m TEST to let IQ-TREE automatically select the best model.
Best Practices
- Alignment quality first: Poor alignment → unreliable trees; check alignment manually
- Use
linsi for small (<200 seq), fftns or auto for large alignments
- Model selection: Always use
-m TEST for IQ-TREE unless you have a specific reason
- Bootstrap: Use ≥1000 ultrafast bootstraps (
-B 1000) for branch support
- Root the tree: Unrooted trees can be misleading; use outgroup or midpoint rooting
- FastTree for >5000 sequences: IQ-TREE becomes slow; FastTree is 10–100× faster
- Trim long alignments: TrimAl removes unreliable columns; improves tree accuracy
- Check for recombination in viral/bacterial sequences before building trees (
RDP4, GARD)
Additional Resources
