shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

bio-phylogenomics

Build marker gene alignments and phylogenetic trees.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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