Bio Phylogenomics

Build marker gene alignments and phylogenetic trees.

Instructions

1. Extract marker genes or SSU rRNA sequences.
2. Align with MAFFT v7.5+ and trim with trimAl v1.4 (or ClipKIT when phylogenetically-informed trimming is preferred).
3. 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.

1. 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.

1. Use the literature-derived analysis playbook to choose markers, reference sampling, rooting, and placement strategy appropriate for the inferred group.
2. Identify nearest neighbors and closest named relatives for each query sequence/genome when the chosen marker/reference set supports that interpretation.
3. Export a closest-relatives table with support values, distances, taxonomy, reference accessions, and uncertainty notes.
4. 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.
5. 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

Input Requirements

Prerequisites:

• Tools available in the active environment (Pixi/conda/system). 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.
• [ ] 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.