1 added, 1 removed. Audit A to A.
---
name: tracking-taxonomy-updates
description: Track taxonomy changes and triage sequence assignments across NCBI, GTDB, ICTV, and eukaryotic frameworks. Use when comparing releases, resolving renamed taxa, or routing genomes, bins, and contigs by domain.
---
# Tracking Taxonomy Updates
Use authoritative sources to report taxonomy changes with explicit versions, dates, and provenance.
## Instructions
1. Determine scope (domain, timeframe, output type).
2. Pull authoritative updates and release notes.
3. Extract versioned changes and impacts.
4. If assigning taxonomy for any assembly, MAG, SAG, isolate genome, bin set, or contig FASTA, start with a QuickClade first-pass domain screen through the BBTools container. Save both per-input and `percontig` results before choosing downstream tools.
5. Route from the QuickClade domain screen:
- Bacteria or Archaea -> run GTDB-Tk for genome taxonomy. If the GTDB-Tk reference package is missing, set up/download it under the project/reference DB root, set `GTDBTK_DATA_PATH`, and record the release before running classification.
- Viral or virus-like -> route to `/bio-viromics`; use vConTACT3 for phage/prokaryotic-virus gene-sharing taxonomy and GVClass for giant-virus/Nucleocytoviricota candidates.
- Eukaryota -> run EukCC for eukaryotic MAG/genome QC and taxonomy context.
- Mixed, low-confidence, or conflicting domains -> split or flag contigs for manual review before domain-specific classification.
6. Normalize IDs and taxonomy strings across tools.
Convert QuickClade machine output with
`scripts/quickclade_to_routing.py` so every downstream decision uses the
documented `domain_routing.tsv` schema.
7. Deliver a versioned report with conflicts flagged.
8. Submit GTDB-Tk, EukCC, vConTACT3, and GVClass work through
`scripts/submit_taxonomy.sh`; do not run these compute-heavy commands on a
login node.
## Quick Reference
| Task | Action |
|------|--------|
| Sources | See `reference/sources.md` |
| Tools | See `reference/tools.md` |
| IDs/ranks | See `reference/ranks-and-identifiers.md` |
| Report template | See `reference/report-template.md` |
| QA checklist | See `reference/qa-checklist.md` |
| Release snapshots at authoring time | See `reference/last-verified-snapshots.md` (examples only — re-check sources for "latest") |
| Environment | Use the project's pinned Pixi environment and record its lockfile |
- | Normalize QuickClade | `uv run --no-project python scripts/quickclade_to_routing.py quickclade.tsv --sample-id S1 --output domain_routing.tsv` |
+ | Normalize QuickClade | `uv run --script scripts/quickclade_to_routing.py quickclade.tsv --sample-id S1 --output domain_routing.tsv` |
| Submit downstream classification | `SLURM_ACCOUNT=... scripts/submit_taxonomy.sh gtdbtk bins results/taxonomy/gtdbtk` |
## Domain Triage Contract
QuickClade is the required first pass for sequence-to-taxonomy assignment unless the user explicitly supplies a trusted domain label and asks to skip triage. It is a router, not the final authority.
Persist:
- `results/taxonomy/quickclade_percontig.tsv`
- `results/taxonomy/domain_routing.tsv`
- downstream tool outputs under `results/taxonomy/{gtdbtk,eukcc,vcontact3,gvclass}/`
Minimum `domain_routing.tsv` columns:
- `sample_id`
- `query_id`
- `contig_id`
- `quickclade_domain`
- `quickclade_taxonomy`
- `quickclade_confidence`
- `route`
- `downstream_tool`
- `review_flag`
- `notes`
## Input Requirements
- Domain(s) and timeframe
- Source systems to compare (NCBI/GTDB/ICTV/etc.)
- Sequences or genomes (for assignment workflows)
## Output
- Versioned taxonomy update summary
- Conflict report across sources
- Standardized taxonomy assignment table (when applicable)
- QuickClade per-contig domain screen and routing table for sequence assignment workflows
## Quality Gates
- [ ] Every “latest” claim includes date, version, and authority
- [ ] Stable identifiers used for joins (taxids, GTDB IDs)
- [ ] Provenance captured (tool version, DB release, run date)
- [ ] QuickClade was run first for assembly/MAG/genome assignment workflows, with container tag and reference spectra recorded.
- [ ] Per-contig QuickClade results were persisted and used to choose downstream tools.
- [ ] Bacteria/Archaea routes include GTDB-Tk outputs and the GTDB reference release; missing GTDB-Tk databases were installed or explicitly reported as blockers.
- [ ] Viral routes distinguish phage/prokaryotic viruses from giant-virus/Nucleocytoviricota candidates before choosing vConTACT3 or GVClass.
- [ ] Eukaryotic routes use EukCC rather than prokaryotic QC/taxonomy tools.
- [ ] GTDB-Tk, EukCC, vConTACT3, and GVClass were submitted through the scheduler, with post-run non-empty output checks.
## Examples
### Example 1: Update scan scope
```text
Domains: Bacteria + Archaea
Timeframe: last 12 months
Output: summary table + pipeline impact notes
```
## Troubleshooting
**Issue**: Conflicting taxonomy between sources
**Solution**: Report both with explicit conflict flags and provenance.
**Issue**: Missing stable IDs
**Solution**: Resolve via TaxonKit and capture merged/deleted taxid warnings.