/phylogenetics-builder

name: phylogenetics-builder
description: End-to-end ML phylogenetic tree inference — MSA, trimming, ModelFinder, IQ-TREE2/RAxML-NG.
license: MIT
metadata:
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🌳
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: conda
      package: bioconda::iqtree
    - kind: conda
      package: bioconda::raxml-ng
    - kind: conda
      package: bioconda::mafft
    - kind: conda
      package: bioconda::muscle
    - kind: conda
      package: bioconda::trimal
    trigger_keywords:
    - phylogeny
    - phylogenetic tree
    - iqtree
    - raxml
    - maximum likelihood tree
    - mafft alignment
    - build tree from sequences
    - model selection
    - ModelFinder
    - bootstrap support
    - evolutionary tree
    - molecular phylogeny
  author: ClawBio
  version: 0.3.0
  demo_data:
  - path: demo_alignment.fasta
    description: "Synthetic 12-taxon primate alignment (500 bp, pre-aligned)"
  dependencies:
    python: '>=3.10'
    packages:
    - pandas>=2.0
    - biopython>=1.80
    - matplotlib>=3.5
    optional:
    - ete3>=3.1  # midpoint rooting
  domain: genomics
  endpoints:
    cli: python skills/phylogenetics-builder/phylogenetics_builder.py --input {input_file} --output {output_dir}
  inputs:
  - name: input_file
    type: file
    format:
    - fasta
    - fa
    - aln
    description: DNA or protein sequences (unaligned for full pipeline, aligned with --aligned flag)
    required: true
  outputs:
  - name: report
    type: file
    format:
    - md
    description: Full analysis report with pipeline summary and branch table
  - name: result
    type: file
    format:
    - json
    description: Machine-readable results (ClawBio output contract)
  - name: phylo_tree
    type: file
    format:
    - nwk
    description: Newick format tree with bootstrap support values
  - name: alignment
    type: file
    format:
    - fasta
    description: Alignments produced by this run, alignment/aligned.fasta after the MSA
      stage and alignment/trimmed.fasta after trimAl; omitted for a stage that did not
      run, and for a destination the run is reading as its own input (reported in
      contract_alerts)

🌳 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, `--outgro