phylogenetics-builder

Files (7)

• INTENTS.json
• SKILL.md
• api.py
• demo_alignment.fasta
• demo_tree.nwk · examples/
• phylogenetics_builder.py
• test_phylogenetics_builder.py · tests/

SKILL.md (first lines)

# 🌳 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

```bash
# 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

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio