bio-phylogenomics

Bio Phylogenomics

Build marker-gene alignments and maximum-likelihood trees, identify closest relatives, and fetch the relative genomes that downstream comparisons need.

Instructions

Tool guides, versions, and verified flags: docs/README.md.

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

2. Extract marker genes or SSU rRNA sequences for the queries and references.

3. Validate the marker and reference manifests and write a checksum-gated, fixed-seed plan; inspect run_manifest.json, then rerun with --execute:

   uv run --script skills/bio-phylogenomics/scripts/run_phylogenomics.py \
     markers.tsv --references references.tsv --seed 1729 \
     --tree-tool veryfasttree --threads 4 --out results/bio-phylogenomics/trees
   

   • markers.tsv columns: marker_id fasta sequence_type (protein or nucleotide); each FASTA holds the unaligned marker sequences.
   • references.tsv columns: accession path sha256; every reference file must match its checksum before anything runs.
   • Per marker the plan runs mafft --auto, trimal -automated1, then the tree tool, and writes support.tsv. --tree-tool iqtree3 (default) runs -m MFP -B 1000 --alrt 1000; veryfasttree runs -boot 1000 and adds -nt for nucleotide markers. --threads sets the thread count for MAFFT and the tree tool.
   • A stage is reused only when its outputs are non-empty and its .done marker exists.
   • support.tsv holds every internal support value on a 0–1 scale. IQ-TREE SH-aLRT/UFBoot labels become separate sh_alrt and ufboot rows; mixed 0–1 and 0–100 values within one support type fail validation. --normalize-only TREE --out support.tsv normalizes an existing tree.

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

5. Choose the tree builder by objective first, then by leaf count:

   • Exploratory placement, reference-set screening, benchmark iterations, or any time-bounded run: VeryFastTree v4.0.5, at any size. VeryFastTree -boot 1000 -threads <n> alignment.faa > tree.nwk; add -nt for nucleotides.
   • Final or publication trees up to about 2,000 taxa: IQ-TREE v3.1.4 with ModelFinder (-m MFP), UFBoot and SH-aLRT, and a fixed --seed.
   • Above about 2,000 taxa, or when memory or runtime is uncertain: VeryFastTree, with -disk-computing for very large trees.
   • Use iqtree3 --fast only when VeryFastTree is unavailable or the project requires IQ-TREE output; record the fallback in the report.

6. Post-process trees with ETE v4 (ete4): root, prune, collapse weak nodes, compute distances, and attach taxonomy or trait annotations. ETE's default Newick parser rejects IQ-TREE SH-aLRT/UFBoot labels; load those trees with parser=1 as shown in docs/ete-toolkit.md.

7. Draw tree figures in greyscale by default. Use color only when it encodes information the reader must tell apart (for example the query versus references, or a small set of clades), choose a colorblind-safe palette, and pair color with a second encoding such as label text, shape, or line style.

8. Identify nearest neighbors and the closest named relatives for each query when the marker and reference set support that interpretation. Separate well-supported nearest relatives from weak placements.

9. Export closest_relatives.tsv with support values, distances, taxonomy, reference accessions, and uncertainty notes.

10. Fetch and persist the close-relative genomes and proteomes for downstream comparisons: results/bio-phylogenomics/relatives/{accession}/genome.fna and proteins.faa, plus relatives_manifest.tsv with accession, source database, taxonomy, genome size, gene count, and the reason for inclusion. Record each failed download with its reason. The comparative axes downstream cannot run without this table.

11. Pass the well-supported relatives, or a documented broader comparison set, to /bio-protein-clustering-pangenome and /bio-annotation.