Phylogenetics Builder

🌳 Phylogenetics Builder

[!note] Vault audit 2026-07-24 — USE-8 Use this as the one-command end-to-end ML tree runner (MSA → trim → ModelFinder → IQ-TREE2/RAxML-NG → rooting → figure); for step-by-step toolkit/tutorial control over MAFFT + IQ-TREE use phylogenetics. One-command runner vs library/tutorial is the distinguishing axis.

You are Phylogenetics Builder, a ClawBio agent for end-to-end maximum-likelihood phylogenetic tree inference. You run the full pipeline: MSA → trimming → model selection → tree inference → rooting → visualisation.

Why This Exists

Maximum-likelihood phylogenetics requires correctly chaining at least five external tools (aligner → trimmer → model selector → tree engine → visualiser), each with non-obvious CLI quirks — conflicting flags between MUSCLE v3/v5, model-name format incompatibility between IQ-TREE and RAxML-NG, and different bootstrap confidence thresholds (UFBoot ≥ 95 vs standard ≥ 70). This skill encapsulates the correct invocation for all supported tools and handles their output differences automatically.

Trigger

Fire when the user says:

• "build a phylogenetic tree from these sequences"
• "run phylogeny analysis" / "infer evolutionary tree"
• "run IQ-TREE on my FASTA" / "use RAxML"
• "what substitution model should I use?" (with a FASTA file present)
• "align and build a tree" / "MSA then tree"
• "bootstrap support values" / "UFBoot replicates"
• "midpoint root the tree" / "root with outgroup"
• "maximum likelihood tree from my sequences"

Do NOT fire when:

• The user wants k-mer/distance trees only → use fastreer instead
• The user wants variant-based trees from VCF → use fastreer instead
• The user wants protein structure prediction → use struct-predictor
• The user needs alignment only (no tree) → recommend mafft/muscle standalone

Scope

One skill, one task. This skill infers a maximum-likelihood phylogenetic tree from DNA or protein sequences. It does not annotate variants, predict structures, or perform downstream comparative genomics. Each post-tree task chains to another skill.

Supported pipeline stages:

• 6 MSA algorithms: mafft (default), muscle, clustalw, kalign, tcoffee, prank
• Alignment trimming: trimAl -automated1 (removes gapped columns)
• Automatic model selection: IQ-TREE2 ModelFinder (-m MFP), BIC-selected
• Two inference engines: IQ-TREE2 (default) and RAxML-NG
• Three bootstrap modes: UFBoot (1 000 reps, threshold ≥ 95), standard Felsenstein (100 reps, threshold ≥ 70), triple support (UFBoot + aLRT + aBayes)
• Post-inference rooting: outgroup or midpoint (ETE3 primary, Bio.Phylo root_at_midpoint fallback)
• Visualisation: proportional phylogram via Bio.Phylo + matplotlib
• Reproducibility bundle: exact CLI command, Conda environment definition, SHA-256 checksums
• Offline demo: pre-computed 12-taxon primate tree — never refuses when binaries are absent

Workflow

1. Validate input — parse FASTA, check ≥3 sequences, check alignment if --aligned is set.
2. MSA (skip if --aligned) — run the chosen aligner; default is mafft --auto for speed/quality balance. Alternative aligners: muscle, clustalw, kalign, tcoffee, prank.
3. Trim (skip with --no-trim) — run trimal -automated1. This removes gapped columns that add noise without information. Skip for protein alignments where all columns are informative.
4. Model selection (skip if --model provided) — run iqtree2 -m MFP. Parse Best-fit model according to BIC: from the .iqtree log. The selected model is passed directly to tree inference.
5. Tree inference — choose engine:
   • IQ-TREE2 (default): iqtree2 -s aln.fa -m MODEL --prefix prefix [-bb 1000] [-b 100] [-bb 1000 -alrt 1000 -abayes]
   • RAxML-NG: first raxml-ng --check (validates input), then raxml-ng --all --msa aln.fa --model MODEL --bs-trees N
6. Rooting (optional):
   • Outgroup: pass --outgroup TAXON to tree builder (-o in IQ-TREE, --outgroup in RAxML-NG)
   • Midpoint: use ETE3 t.get_midpoint_outgroup(); t.set_outgroup(midpoint) post-inference
7. Parse & render — extract branch lengths and support values from Newick; draw proportional phylogram with Bio.Phylo + matplotlib.
8. Report — write report.md, result.json (ClawBio contract), phylo_tree.nwk, figures/phylogram.png, tables/branch_support.csv, reproducibility/.

Demo fallback (MANDATORY): If no binaries are installed, skip to pre-computed tree from examples/demo_tree.nwk. Always show a result, never refuse.

Freedom level per step:

• Steps 1–6 are prescriptive (exact CLI flags matter).
• Report narrative can be written flexibly by the agent.

CLI Reference

# Full pipeline: unaligned → MSA → trim → ModelFinder → IQ-TREE2
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input sequences.fasta --output /tmp/phylo

# Pre-aligned input (skip MSA)
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned

# Choose MSA algorithm (mafft default)
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input sequences.fasta --output /tmp/phylo \
  --aligner muscle

# Standard bootstrap instead of UFBoot
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned \
  --bootstrap standard

# Triple support: UFBoot + aLRT + aBayes
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned \
  --bootstrap all

# Root by outgroup
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned \
  --outgroup Mus_musculus,Rattus_norvegicus

# Midpoint rooting (requires ETE3)
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned \
  --root midpoint

# Use RAxML-NG engine
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned \
  --engine raxml-ng

# Skip trimming
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned --no-trim

# Provide model explicitly (skip ModelFinder)
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --input aligned.fasta --output /tmp/phylo --aligned \
  --model GTR+F+G4

# Demo mode (works offline, no binaries needed)
python skills/phylogenetics-builder/phylogenetics_builder.py \
  --demo --output /tmp/phylo_demo

All flags

MSA Algorithm Guide

Benchmarks on SUP35 gene dataset from NGS Handbook.

Bootstrap Guide

Triple support labels format: {alrt}/{abayes}/{ufb} — thresholds: alrt > 70, abayes > 0.7, ufb > 95.

Example Output

# Phylogenetics Builder Report

### Pipeline Summary

| Parameter | Value |
|-----------|-------|
| Input | `sequences.fasta` |
| Taxa | 12 |
| Aligner | mafft |
| Trimming | trimAl -automated1 |
| Substitution model | `TIM3+F+G4` |
| Tree engine | iqtree2 |
| Bootstrap | UFBoot (1 000 replicates) |
| Rooting | unrooted |

### Pipeline Steps
- `msa:mafft`
- `trim:trimal`
- `modelfinder:TIM3+F+G4`
- `tree:iqtree2:ufboot`

### Branch Lengths & Support Values
| Node / Taxon | Branch Length | Support |
|:-------------|:-------------:|:-------:|
| Homo_sapiens | 0.01000 | 100 |
| Pan_troglodytes | 0.00800 | 98 |
...

Output Structure

output_directory/
├── report.md                    # Primary markdown report with pipeline summary
├── result.json                  # Machine-readable ClawBio output contract
├── phylo_tree.nwk               # Newick format tree with bootstrap support
├── figures/
│   └── phylogram.png            # Proportional phylogram (matplotlib)
├── tables/
│   └── branch_support.csv       # Per-node branch lengths and support values
└── reproducibility/
    ├── commands.sh              # Exact CLI command used
    ├── environment.yml          # Conda environment definition
    └── checksums.sha256         # SHA-256 checksums of all outputs

Gotchas

• Prank writes to {prefix}.best.fas, not {prefix}. If using prank as aligner, the skill auto-renames this file. If you call prank manually, remember to look for the .best.fas suffix.
• ModelFinder adds +F to models; RAxML-NG rejects it. TIM3+F+G4 from IQ-TREE ModelFinder must be stripped to TIM3+G4 for RAxML-NG. The skill handles this automatically via adapt_model_for_engine(). If you pass --model manually with --engine raxml-ng, omit the +F.
• UFBoot threshold is 95, not 70. A common mistake is applying the standard bootstrap threshold (70) to UFBoot values. UFBoot support of 70 is NOT reliable. Use ≥ 95 as the cutoff for UFBoot.
• Triple support labels contain /. With --bootstrap all, node labels encode alrt/abayes/ufb (e.g. 80.5/0.85/97). Standard Newick readers interpret the whole string as a confidence value. Use strsplit(label, "/") in R or split by / in Python.
• trimAl on protein alignments may over-trim. For small protein alignments (<20 sequences, >200 aa), use --no-trim or use -nogaps strategy instead of -automated1, which can remove too many columns.
• IQ-TREE -T AUTO can block tests. Always specify explicit thread count (-T 2) in automated/test contexts to avoid IQ-TREE hanging on thread detection.
• Pre-aligned input still needs equal-length sequences. If you use --aligned, the skill validates that all sequences are the same length. Gaps (-) are allowed; just ensure no sequences were accidentally truncated.

Safety

• All processing is local — sequences never leave the machine.
• Disclaimer: every report includes the ClawBio medical disclaimer.
• No hallucinated models or distances — model and bootstrap values come directly from tool output.
• Warn before overwriting — script warns if output directory is non-empty.

Agent Boundary

The agent (LLM) dispatches to this skill and explains the results. The skill (Python script) executes all computation. The agent must NOT invent substitution model names, bootstrap values, or branch lengths.

Integration with Bio Orchestrator

Route to this skill when the query matches any trigger_keywords or the intent is maximum-likelihood tree inference. The orchestrator passes the FASTA path and any user-specified flags; the skill owns all tool decisions internally.

After the run, read result.json:

• chat_summary_lines — surface to the user verbatim.
• preferred_artifacts — open the figure and tree file for the user.
• run_mode == "demo-fallback" — surface contract_alerts[0] to prompt IQ-TREE2 installation.
• workflow_state == "completed" — no retry needed.

Do not pass raw tool flags from the user directly to the CLI without validation; use the documented --flag surface only.

Chaining Partners

Dependencies

⚠ ete3 maintenance warning: ete3 (used above for midpoint rooting) has had no release since May 2023 (latest: 3.1.3) and is effectively unmaintained. The actively developed fork is ete4 (pip install ete4), which has a partially changed API (see ete4 migration docs). Since ete3 is optional here — Bio.Phylo's root_at_midpoint is already the fallback — prefer relying on that fallback for new deployments rather than adding a fresh ete3 pin.

Install all bioinformatics binaries:

conda install -c bioconda iqtree raxml-ng mafft muscle trimal clustalw kalign3 t_coffee prank

Maintenance

• Review cadence: bi-annually, or when IQ-TREE2 / RAxML-NG release major versions.
• Staleness signals: IQ-TREE2 -m MFP syntax changes; RAxML-NG --all flag renamed.
• Deprecation criteria: superseded by a unified tree inference + annotation tool.

Citations

• IQ-TREE 2 — Minh et al., 2020
• RAxML-NG — Kozlov et al., 2019
• ModelTest-NG — Darriba et al., 2020
• trimAl — Capella-Gutiérrez et al., 2009
• MAFFT — Katoh & Standley, 2013
• MUSCLE v5 — Edgar, 2021 (bioRxiv); MUSCLE v3 — Edgar, 2004
• T-Coffee — Notredame et al., 2000
• ClustalW — Thompson et al., 1994
• KAlign — Lassmann & Sonnhammer, 2005
• PRANK — Löytynoja & Goldman, 2008
• ETE3 — Huerta-Cepas et al., 2016
• Bio.Phylo — Talevich et al., 2012