bio-phylogenomics

Bio Phylogenomics

Build marker gene alignments and phylogenetic trees.

Instructions

Tool guides and versions: docs/README.md.

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

   uv run --script 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 paired with a stage .done marker. It normalizes internal support values from either 0–1 or 0–100 notation to support.tsv on a 0–1 scale. IQ-TREE SH-aLRT/UFBoot labels are emitted as separate sh_alrt and ufboot rows; mixed scales within one support type fail validation.

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.