Claude Skill

alterlab-phylogenetics

Build phylogenetic trees end-to-end from raw sequences — MAFFT multiple sequence alignment, optional TrimAl trimming, IQ-TREE 3 maximum-likelihood inference with model selection and bootstraps, FastTree for large datasets, then visualize with ETE3 or FigTree. Use when reconstruct

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download AlterLab-IEU-AlterLab-Academic-Skills-skills_bioinformatics_alterlab-phylogenetics-3ab6d03.zip · 14 KB

Install

skills CLI npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-phylogenetics
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
Git git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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:

  1. MAFFT — Multiple sequence alignment
  2. IQ-TREE 3 — Maximum likelihood tree inference with model selection
  3. FastTree — Fast approximate maximum likelihood (for large datasets)
  4. 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.

# CLI binaries — bioconda (cross-platform) ...
conda install -c bioconda mafft iqtree fasttree trimal   # iqtree is now IQ-TREE 3
# ... or Homebrew on macOS (Apple Silicon): IQ-TREE/TrimAl live in the brewsci/bio tap
brew install mafft fasttree
brew tap brewsci/bio && brew install brewsci/bio/iqtree brewsci/bio/trimal

# Python visualization layer
uv pip install "ete3==3.1.3"   # also needs numpy<2 and PyQt5 for rendering

Binary name: bioconda's iqtree package is now IQ-TREE 3 (3.1.x) and installs the executables iqtree and iqtree3 — there is no iqtree2 in it. Call iqtree, which works on both the 2.x and 3.x packages; only reach for a versioned name when two releases coexist on PATH. IQ-TREE 3 adds MixtureFinder, multi-tree mixture models (MAST), gene/site concordance factors, and CMAPLE for very large pathogen datasets; the options below are unchanged from 2.x.

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

Does NOT Trigger

Scenario Use Instead
Manipulating or comparing an existing Newick tree (prune, root, Robinson-Foulds, duplication/speciation) alterlab-etetoolkit
Plain sequence parsing, translation, or format conversion alterlab-biopython
Homology search to find the sequences before aligning them alterlab-blast
Diversity/ordination on a community feature table (UniFrac, PCoA, PERMANOVA) alterlab-scikit-bio
Running the 16S amplicon pipeline that produces the ASVs and tree alterlab-qiime2-amplicon

Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-etetoolkit) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

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]

    with open(output_fasta, 'w') as out:
        result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)

    if result.returncode != 0:
        raise RuntimeError(f"MAFFT failed:\n{result.stderr}")

    # Count aligned sequences
    with open(output_fasta) as f:
        n_seqs = sum(1 for line in f if line.startswith('>'))
    print(f"MAFFT: aligned {n_seqs} sequences → {output_fasta}")

    return output_fasta

# MAFFT method selection guide:
# Few sequences (<200), accurate: linsi or einsi
# Many sequences (<1000), moderate: fftnsi
# Large datasets (>1000): fftns or auto
# Ultra-fast (>10000): mafft --retree 1

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}")
        # Fall back to using the untrimmed alignment
        import shutil
        shutil.copy(aligned_fasta, output_fasta)
    return output_fasta

3. IQ-TREE 3 — 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 3.

    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 = [
        "iqtree",
        "-s", aligned_fasta,
        "--prefix", output_prefix,
        "-m", model,
        "-B", str(bootstrap),   # Ultrafast bootstrap
        "-T", str(n_threads),
        "--redo"                # Overwrite existing results
    ]

    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}")

    # Print model selection result
    log_file = f"{output_prefix}.log"
    if os.path.exists(log_file):
        with open(log_file) as f:
            for line in f:
                if "Best-fit model" in line:
                    print(f"IQ-TREE: {line.strip()}")

    output_files = {
        "tree": f"{output_prefix}.treefile",
        "log": f"{output_prefix}.log",
        "iqtree": f"{output_prefix}.iqtree",  # Full report
        "model": f"{output_prefix}.model.gz",
    }

    print(f"IQ-TREE: Tree saved to {output_files['tree']}")
    return output_files

# Model selection: ModelFinder Plus (-m MFP) is the DEFAULT — omitting -m runs it.
# -m TEST is the narrower jModelTest/ProtTest-style search (no FreeRate models);
# use it only when you need to match those tools.
# Typical winners — DNA: GTR+F+I+G4, HKY+F+G4; Protein: LG+F+G4, Q.pfam+G4;
# Codon: MG+F3X4.

# For temporal (molecular clock) analysis, add:
# extra_args = ["--date", "dates.txt", "--clock-test", "--date-CI", "95"]

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)/len(distances) if distances else 0,
    }
    return stats

def find_mrca(t: Tree, leaf_names: list) -> Tree:
    """Find the most recent common ancestor of a set of leaves."""
    return t.get_common_ancestor(*leaf_names)

def visualize_tree(t: Tree, output_file: str = "tree.png",
                    show_branch_support: bool = True,
                    color_groups: dict = None,
                    width: int = 800) -> None:
    """
    Render phylogenetic tree to image.

    Args:
        t: ETE3 Tree object
        color_groups: Dict mapping leaf_name → color (for coloring taxa)
        show_branch_support: Show bootstrap values
    """
    ts = TreeStyle()
    ts.show_leaf_name = True
    ts.show_branch_support = show_branch_support
    ts.mode = "r"  # 'r' = rectangular, 'c' = circular

    if color_groups:
        for node in t.traverse():
            if node.is_leaf() and node.name in color_groups:
                nstyle = NodeStyle()
                nstyle["fgcolor"] = color_groups[node.name]
                nstyle["size"] = 8
                node.set_style(nstyle)

    t.render(output_file, tree_style=ts, w=width, units="px")
    print(f"Tree saved to: {output_file}")

def midpoint_root(t: Tree) -> Tree:
    """Root tree at midpoint (use when outgroup unknown)."""
    t.set_outgroup(t.get_midpoint_outgroup())
    return t

def prune_tree(t: Tree, keep_leaves: list) -> Tree:
    """Prune tree to keep only specified leaves."""
    t.prune(keep_leaves, preserve_branch_length=True)
    return 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:
        # -m TEST auto-detects the alphabet (nt vs aa) and selects the best model.
        iqtree_files = run_iqtree(
            aligned, prefix,
            model="TEST",
            bootstrap=bootstrap,
            n_threads=n_threads
        )
        tree_file = iqtree_files["tree"]

    print("\nStep 3: Tree Analysis")
    t = Tree(tree_file)
    t = midpoint_root(t)

    stats = basic_tree_stats(t)
    print(f"Tree statistics: {stats}")

    print("\nStep 4: Visualization")
    visualize_tree(t, f"{prefix}_tree.png", show_branch_support=True)

    # Save rooted tree
    rooted_tree_file = f"{prefix}_rooted.nwk"
    t.write(format=1, outfile=rooted_tree_file)

    results = {
        "aligned_fasta": aligned,
        "tree_file": tree_file,
        "rooted_tree": rooted_tree_file,
        "visualization": f"{prefix}_tree.png",
        "stats": stats
    }

    print("\n" + "=" * 50)
    print("Phylogenetic analysis complete!")
    print(f"Results in: {output_dir}/")
    return 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: IQ-TREE selects the model automatically by default (-m MFP); pass an explicit model only when you need to fix it.

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: ModelFinder Plus is IQ-TREE's default — just omit -m (or pass -m MFP). -m TEST restricts the search to jModelTest/ProtTest-style models, so use it only to match those tools
  • 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

Files (alterlab-academic-skills)
  • evals
    • evals.json 4.7 KB
      Loading…
  • references
    • iqtree_inference.md 5.5 KB
      Loading…
  • scripts
    • phylogenetic_analysis.py 9.9 KB
      Loading…
  • SKILL.md 17.1 KB
    ---
    name: alterlab-phylogenetics
    description: Build phylogenetic trees end-to-end from raw sequences — MAFFT multiple sequence alignment, optional TrimAl trimming, IQ-TREE 3 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 3, 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.1.0"
        last_updated: "2026-09-23"
    ---
    
    # 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:
    
    1. **MAFFT** — Multiple sequence alignment
    2. **IQ-TREE 3** — Maximum likelihood tree inference with model selection
    3. **FastTree** — Fast approximate maximum likelihood (for large datasets)
    4. **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.
    ```bash
    # CLI binaries — bioconda (cross-platform) ...
    conda install -c bioconda mafft iqtree fasttree trimal   # iqtree is now IQ-TREE 3
    # ... or Homebrew on macOS (Apple Silicon): IQ-TREE/TrimAl live in the brewsci/bio tap
    brew install mafft fasttree
    brew tap brewsci/bio && brew install brewsci/bio/iqtree brewsci/bio/trimal
    
    # Python visualization layer
    uv pip install "ete3==3.1.3"   # also needs numpy<2 and PyQt5 for rendering
    ```
    > **Binary name:** bioconda's `iqtree` package is now **IQ-TREE 3** (3.1.x) and installs the
    > executables `iqtree` and `iqtree3` — there is **no `iqtree2`** in it. Call `iqtree`, which
    > works on both the 2.x and 3.x packages; only reach for a versioned name when two releases
    > coexist on PATH. IQ-TREE 3 adds MixtureFinder, multi-tree mixture models (MAST), gene/site
    > concordance factors, and CMAPLE for very large pathogen datasets; the options below are
    > unchanged from 2.x.
    >
    > 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
    
    ### Does NOT Trigger
    
    | Scenario | Use Instead |
    |----------|-------------|
    | Manipulating or comparing an **existing** Newick tree (prune, root, Robinson-Foulds, duplication/speciation) | `alterlab-etetoolkit` |
    | Plain sequence parsing, translation, or format conversion | `alterlab-biopython` |
    | Homology search to *find* the sequences before aligning them | `alterlab-blast` |
    | Diversity/ordination on a community feature table (UniFrac, PCoA, PERMANOVA) | `alterlab-scikit-bio` |
    | Running the 16S amplicon pipeline that produces the ASVs and tree | `alterlab-qiime2-amplicon` |
    
    **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-etetoolkit`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
    
    ## Standard Workflow
    
    ### 1. Multiple Sequence Alignment with MAFFT
    
    ```python
    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]
    
        with open(output_fasta, 'w') as out:
            result = subprocess.run(cmd, stdout=out, stderr=subprocess.PIPE, text=True)
    
        if result.returncode != 0:
            raise RuntimeError(f"MAFFT failed:\n{result.stderr}")
    
        # Count aligned sequences
        with open(output_fasta) as f:
            n_seqs = sum(1 for line in f if line.startswith('>'))
        print(f"MAFFT: aligned {n_seqs} sequences → {output_fasta}")
    
        return output_fasta
    
    # MAFFT method selection guide:
    # Few sequences (<200), accurate: linsi or einsi
    # Many sequences (<1000), moderate: fftnsi
    # Large datasets (>1000): fftns or auto
    # Ultra-fast (>10000): mafft --retree 1
    ```
    
    ### 2. Trim Alignment (Optional but Recommended)
    
    ```python
    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}")
            # Fall back to using the untrimmed alignment
            import shutil
            shutil.copy(aligned_fasta, output_fasta)
        return output_fasta
    ```
    
    ### 3. IQ-TREE 3 — Maximum Likelihood Tree
    
    ```python
    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 3.
    
        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 = [
            "iqtree",
            "-s", aligned_fasta,
            "--prefix", output_prefix,
            "-m", model,
            "-B", str(bootstrap),   # Ultrafast bootstrap
            "-T", str(n_threads),
            "--redo"                # Overwrite existing results
        ]
    
        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}")
    
        # Print model selection result
        log_file = f"{output_prefix}.log"
        if os.path.exists(log_file):
            with open(log_file) as f:
                for line in f:
                    if "Best-fit model" in line:
                        print(f"IQ-TREE: {line.strip()}")
    
        output_files = {
            "tree": f"{output_prefix}.treefile",
            "log": f"{output_prefix}.log",
            "iqtree": f"{output_prefix}.iqtree",  # Full report
            "model": f"{output_prefix}.model.gz",
        }
    
        print(f"IQ-TREE: Tree saved to {output_files['tree']}")
        return output_files
    
    # Model selection: ModelFinder Plus (-m MFP) is the DEFAULT — omitting -m runs it.
    # -m TEST is the narrower jModelTest/ProtTest-style search (no FreeRate models);
    # use it only when you need to match those tools.
    # Typical winners — DNA: GTR+F+I+G4, HKY+F+G4; Protein: LG+F+G4, Q.pfam+G4;
    # Codon: MG+F3X4.
    
    # For temporal (molecular clock) analysis, add:
    # extra_args = ["--date", "dates.txt", "--clock-test", "--date-CI", "95"]
    ```
    
    ### 4. FastTree — Fast Approximate ML
    
    For large datasets (>1000 sequences) where IQ-TREE is too slow:
    
    ```python
    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
    
    ```python
    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)/len(distances) if distances else 0,
        }
        return stats
    
    def find_mrca(t: Tree, leaf_names: list) -> Tree:
        """Find the most recent common ancestor of a set of leaves."""
        return t.get_common_ancestor(*leaf_names)
    
    def visualize_tree(t: Tree, output_file: str = "tree.png",
                        show_branch_support: bool = True,
                        color_groups: dict = None,
                        width: int = 800) -> None:
        """
        Render phylogenetic tree to image.
    
        Args:
            t: ETE3 Tree object
            color_groups: Dict mapping leaf_name → color (for coloring taxa)
            show_branch_support: Show bootstrap values
        """
        ts = TreeStyle()
        ts.show_leaf_name = True
        ts.show_branch_support = show_branch_support
        ts.mode = "r"  # 'r' = rectangular, 'c' = circular
    
        if color_groups:
            for node in t.traverse():
                if node.is_leaf() and node.name in color_groups:
                    nstyle = NodeStyle()
                    nstyle["fgcolor"] = color_groups[node.name]
                    nstyle["size"] = 8
                    node.set_style(nstyle)
    
        t.render(output_file, tree_style=ts, w=width, units="px")
        print(f"Tree saved to: {output_file}")
    
    def midpoint_root(t: Tree) -> Tree:
        """Root tree at midpoint (use when outgroup unknown)."""
        t.set_outgroup(t.get_midpoint_outgroup())
        return t
    
    def prune_tree(t: Tree, keep_leaves: list) -> Tree:
        """Prune tree to keep only specified leaves."""
        t.prune(keep_leaves, preserve_branch_length=True)
        return t
    ```
    
    ### 6. Complete Analysis Script
    
    ```python
    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:
            # -m TEST auto-detects the alphabet (nt vs aa) and selects the best model.
            iqtree_files = run_iqtree(
                aligned, prefix,
                model="TEST",
                bootstrap=bootstrap,
                n_threads=n_threads
            )
            tree_file = iqtree_files["tree"]
    
        print("\nStep 3: Tree Analysis")
        t = Tree(tree_file)
        t = midpoint_root(t)
    
        stats = basic_tree_stats(t)
        print(f"Tree statistics: {stats}")
    
        print("\nStep 4: Visualization")
        visualize_tree(t, f"{prefix}_tree.png", show_branch_support=True)
    
        # Save rooted tree
        rooted_tree_file = f"{prefix}_rooted.nwk"
        t.write(format=1, outfile=rooted_tree_file)
    
        results = {
            "aligned_fasta": aligned,
            "tree_file": tree_file,
            "rooted_tree": rooted_tree_file,
            "visualization": f"{prefix}_tree.png",
            "stats": stats
        }
    
        print("\n" + "=" * 50)
        print("Phylogenetic analysis complete!")
        print(f"Results in: {output_dir}/")
        return 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:** IQ-TREE selects the model automatically by default (`-m MFP`); pass an explicit model
    only when you need to fix it.
    
    ## 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**: ModelFinder Plus is IQ-TREE's default — just omit `-m` (or pass `-m MFP`).
      `-m TEST` restricts the search to jModelTest/ProtTest-style models, so use it only to match
      those tools
    - **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
    
    - **MAFFT**: https://mafft.cbrc.jp/alignment/software/
    - **IQ-TREE 3**: http://www.iqtree.org/ | Tutorial: https://www.iqtree.org/workshop/molevol2022
    - **FastTree**: http://www.microbesonline.org/fasttree/
    - **ETE3**: http://etetoolkit.org/
    - **FigTree** (GUI visualization): https://tree.bio.ed.ac.uk/software/figtree/
    - **iTOL** (web visualization): https://itol.embl.de/
    - **MUSCLE** (alternative aligner): https://www.drive5.com/muscle/
    - **TrimAl** (alignment trimming): https://vicfero.github.io/trimal/
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.