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.

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/
• stdout: the last line is one JSON envelope {ok, skill, out, manifest, warnings} (driver stdout contract in AGENTS.md)

Quality Gates

• Alignment length and missingness meet project thresholds.
• Every reference checksum matches before alignment, and the run manifest records a positive fixed seed.
• A stage is reused only when its declared outputs are non-empty and its .done marker exists.
• 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 execution failure, preserve logs and report the failed command; retry only after diagnosing the cause and recording the changed parameters. Report unmet biological thresholds as results; never tune parameters solely to pass a gate.
• 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).