bio-phylogenomics

name	bio-phylogenomics
description	Build and validate marker-gene alignments and phylogenetic trees. Use when inferring evolutionary relationships, choosing models, or checking tree support and contamination.

Bio Phylogenomics

Build marker gene alignments and phylogenetic trees.

Instructions

1. Validate marker/reference manifests and create a checksum-gated, fixed-seed execution plan:

   uv run --no-project python skills/bio-phylogenomics/scripts/run_phylogenomics.py \
     markers.tsv --references references.tsv --seed 1729 \
     --out results/bio-phylogenomics
   # Inspect run_manifest.json, then add --execute.
   

   The driver restarts only from non-empty stage outputs and normalizes internal support values from either 0–1 or 0–100 notation to support.tsv on a 0–1 scale.

2. Extract marker genes or SSU rRNA sequences.

3. Align with MAFFT v7.5+ and trim with trimAl v1.4 (or ClipKIT when phylogenetically-informed trimming is preferred).

4. Build ML trees with support values. Choose by objective first, then leaf count:

   • Exploratory placement, benchmark iterations, reference-set screening, or any time-bounded analysis: use VeryFastTree v4.0 first, even below ~2,000 taxa. Prefer VeryFastTree -boot 1000 -threads <n> < alignment.faa > tree.nw for proteins and add -nt for nucleotide alignments.
   • Final or publication-quality trees up to ~2,000 taxa: IQ-TREE v3 (v3.1.2+) for comprehensive model selection, MAST/GTRpmix, UFBoot/SH-aLRT, and defensible final inference.
   • Above ~2,000 taxa, or when memory/runtime is uncertain: VeryFastTree v4.0 (multi-threaded, SIMD, -disk-computing for very large trees).
   • Use iqtree3 -fast only when VeryFastTree is unavailable or a project explicitly requires IQ-TREE-compatible exploratory output; record that fallback in the report.

5. Post-process trees with ETE v4 (ete4):

   • Compute tree statistics (branch lengths, distances, topology metrics).
   • Root, prune, or collapse nodes as needed.
   • Filter by bootstrap support.
   • Add taxonomic or trait annotations.
   • Generate publication-quality visualizations.

6. Use the literature-derived analysis playbook to choose markers, reference sampling, rooting, and placement strategy appropriate for the inferred group.

7. Identify nearest neighbors and closest named relatives for each query sequence/genome when the chosen marker/reference set supports that interpretation.

8. Export a closest-relatives table with support values, distances, taxonomy, reference accessions, and uncertainty notes.

9. Fetch and persist the close-relative genomes and proteomes that downstream comparative analyses will use. Save under results/bio-phylogenomics/relatives/{accession}/genome.fna and proteins.faa, plus relatives_manifest.tsv recording accession, source DB, taxonomy, genome size, gene count, and the reason for inclusion. If a relative cannot be downloaded, record the failure explicitly. Without this artifact, the comparative axes downstream cannot run.

10. Use well-supported relatives or a documented broader comparison set to guide downstream comparative analysis with /bio-protein-clustering-pangenome and /bio-annotation.

Quick Reference

Task	Action
Run workflow	Follow the steps in this skill and capture outputs.
Validate inputs	Confirm required inputs and reference data exist.
Review outputs	Inspect reports and QC gates before proceeding.
Tool docs	See docs/README.md.

Input Requirements

Prerequisites:

• Tools declared in the project's pinned Pixi environment. See docs/README.md for expected tools.
• Marker gene set or alignments available. Inputs:
• markers.faa (marker genes) or alignments.fasta

Output

• results/bio-phylogenomics/alignments/
• results/bio-phylogenomics/trees/
• results/bio-phylogenomics/closest_relatives.tsv
• results/bio-phylogenomics/relatives/{accession}/genome.fna
• results/bio-phylogenomics/relatives/{accession}/proteins.faa
• results/bio-phylogenomics/relatives_manifest.tsv
• results/bio-phylogenomics/phylo_report.md
• results/bio-phylogenomics/logs/

Quality Gates

• Alignment length and missingness meet project thresholds.
• Every reference checksum matches before alignment, and the run manifest records a positive fixed seed.
• Internal supports are exported on a documented 0–1 scale without mixing raw IQ-TREE and VeryFastTree conventions.
• Bootstrap support summary meets project thresholds.
• On failure: retry with alternative parameters; if still failing, record in report and exit non-zero.
• Verify markers.faa is non-empty and aligned sequences are consistent.
• Marker and reference choices are justified against the literature-derived analysis playbook.
• Closest relatives are reported with support/distance metrics or uncertainty is stated.
• Tree interpretation distinguishes well-supported nearest relatives from weakly supported placements.
• relatives_manifest.tsv is populated and the matching genome/proteome files are present on disk (or each failure is recorded with a reason).

Examples

Example 1: Expected input layout

markers.faa (marker genes) or alignments.fasta

Troubleshooting

Issue: Missing inputs or reference databases Solution: Verify paths and permissions before running the workflow.

Issue: Low-quality results or failed QC gates Solution: Review reports, adjust parameters, and re-run the affected step.