Phylogenetics Builder

🌳 Phylogenetics Builder

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, alignment/aligned.fasta and alignment/trimmed.fasta when those stages ran and the destination is not this run's own input, 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
├── alignment/                  # aligned.fasta (MSA) and trimmed.fasta (trimAl), when produced
├── 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