bio-viromics · diff
git:20260905.3e49039 to git:20261001.bf5afd6
61 added, 59 removed. Audit A to A.
---
name: bio-viromics
- description: Detect, quality-control, and classify viral contigs. Use when identifying viruses in assemblies, checking viral completeness and contamination, or assigning viral taxonomy.
+ description: Detect, QC, and classify viral contigs with geNomad, CheckV, vConTACT3, and GVClass. Use when finding viruses in assemblies, grading viral genomes, or assigning phage or giant-virus taxonomy.
---
# Bio Viromics
- Detect, classify, and QC viral contigs.
+ Detect, quality-check, and classify viral contigs, then compare each viral genome against a literature-derived reference set.
## Instructions
- Tool guides and versions: [docs/README.md](docs/README.md).
+ Tool guides, versions, and verified flags: [docs/README.md](docs/README.md).
- 1. Validate the pinned resource manifest and assemble the complete comparative evidence and reasoning bundle:
+ Run geNomad, CheckV, GVClass, and vConTACT3 on a workstation or compute node, never on a login node. Pass an explicit thread count to each tool (`-t`). Without it, geNomad and CheckV use every CPU available to the process, and vConTACT3 uses every CPU on the host, even inside a smaller Slurm allocation. On HPC, submit through `sbatch` with CPUs matched to that thread count and follow the site's account and partition rules.
- ```bash
- uv run --script skills/bio-viromics/scripts/build_viromics_evidence.py \
- viral_metrics.tsv --resources resources.json --hypotheses hypotheses.tsv \
- --reflections reflections.tsv --comparative-dir comparison/ \
- --out results/bio-viromics
- ```
+ 1. Start from `/tracking-taxonomy-updates` QuickClade domain routing when assemblies, MAGs, genomes, or contigs have not been screened. Viral, virus-like, mixed, or low-confidence contigs enter this skill; bacterial, archaeal, and eukaryotic rows stay on their domain routes unless later evidence contradicts the triage.
+ 2. Detect viruses with geNomad v1.12.0 (database v1.9) as the primary virus and plasmid classifier: `genomad end-to-end -t <n> contigs.fna out/ genomad_db`. For prokaryotic-virus discovery, VirSorter2 v2.2.4 is a complementary detector; combine either detector with CheckV QC to remove false positives.
+ 3. Run CheckV v1.1.1 with database v1.5 for completeness, contamination, and host-region trimming: `checkv end_to_end viral.fna out/ -d checkv-db-v1.5 -t <n>`.
+ 4. Infer the likely viral group from QuickClade, geNomad taxonomy, genome statistics, and marker or similarity evidence.
+ 5. Search the literature for that group (`/polars-dovmed`) and write `analysis_playbook.md`: typical reference sets, markers, comparative analyses, genome features, plots, and outlier signals used by people who study the group.
+ 6. Choose taxonomy, clustering, phylogenetic, and comparative methods from the playbook:
+ - Bacteriophages and other prokaryotic viruses: vConTACT3 gene-sharing networks for genus-to-order assignment. vConTACT3 replaces vConTACT2. The upstream source tag is 3.2.4; bioconda ships 3.1.6. Record the version you ran.
+ - Nucleocytoviricota, Mirusviricota, and Preplasmiviricota: GVClass v2.0.3 with resource bundle v2.0.0, plus marker-gene phylogenies of core genes through `/bio-phylogenomics`.
+ - RNA viruses, ssDNA viruses, and other groups that vConTACT3 does not cover well: group-specific markers, phylogenomics, and protein-family methods from the playbook. Do not force a phage-oriented workflow on them.
+ 7. For each viral genome or high-quality viral contig, call genes and annotate proteins when needed (`/bio-gene-calling`, `/bio-annotation`), then inspect the annotation set according to the playbook rather than a fixed feature list.
+ 8. Compare each query to the literature-supported reference set on the comparative axes in the repository AGENTS.md: marker census, per-family copy number, conserved neighborhoods, and ncRNA census. Write `marker_census.tsv`, `family_copy_number_comparison.tsv`, `conserved_neighborhoods.tsv`, and `ncRNA_census.tsv` to one comparison directory. Report what matches expectations, what is missing, expanded, or query-specific, and which patterns are likely artifacts.
+ 9. Genome-size frontier: place each query's genome size and gene count in the distribution of close relatives and the literature-reported extremes for the group. State the percentile, the distance from the group median, and whether the query exceeds the known record size, and cite the paper that defines the record. A mid-distribution placement is still a result.
+ 10. Assemble the evidence bundle. The driver checksum-verifies the geNomad, CheckV, GVClass, and vConTACT3 database resources, checks the hypothesis register and reflections, copies the four comparative tables, and computes `genome_size_frontier.tsv`:
- The driver checksum-verifies geNomad, CheckV, GVClass, and vConTACT3 database resources; requires at least five hypotheses including a technical/null explanation; requires initial, intermediate, and final reflections; and persists marker, family-copy, synteny, ncRNA, and genome-frontier evidence under `schemas/evidence-bundle.schema.json`. Database resources may be files or directories. Set `kind` to `directory` and record the deterministic tree SHA-256 for installed database directories.
- 2. Start from `/tracking-taxonomy-updates` QuickClade domain routing when assemblies, MAGs, genomes, or contigs have not already been screened. Viral, virus-like, mixed, or low-confidence contigs enter this skill; bacterial/archaeal and eukaryotic rows stay on their domain-specific routes unless later evidence contradicts the triage.
- 3. Run virus detection with geNomad v1.8+ (use as primary plasmid-and-virus classifier).
- 4. Run CheckV v1.1.1 with database v1.5 for completeness, contamination, and host-removal QC.
- 5. Infer the likely viral group from QuickClade, detection output, taxonomy hints, genome statistics, and marker/similarity evidence.
- 6. Search the literature for that viral group and write a short analysis playbook: typical reference sets, markers, comparative analyses, genome features, plots, and outlier signals used by scientists studying that group.
- 7. Choose taxonomy, clustering, phylogenetic, and comparative methods from the playbook:
- - For bacteriophage and prokaryotic-virus gene-sharing taxonomy: vConTACT3 v3.2.4 (hierarchical genus-to-order assignment, >95% ICTV agreement; supersedes vConTACT2).
- - For Nucleocytoviricota / giant viruses: gvclass v1.6.0 with resources v1.5.0 for genus-level classification combined with marker-gene phylogenies of NCLDV core genes.
- - For RNA viruses, ssDNA viruses, or other groups not well-served by vConTACT3: use group-specific markers, phylogenomics, and protein-family approaches from the literature playbook rather than forcing a phage-oriented workflow.
- 8. For prokaryotic-virus discovery, VirSorter2 v2.2.4 is a complementary detector to geNomad; combine with CheckV QC to remove false positives.
- 9. For each viral genome or high-quality viral contig, call genes and annotate proteins when needed, then inspect the annotation set according to the playbook rather than a fixed global feature list.
- 10. Compare each query viral genome to the literature-supported reference set. Report what matches expectations, what is missing, what is expanded, what is query-specific, and which patterns are likely artifacts.
- 11. **Genome-size frontier** — for each query, compute where the genome size and gene count sit within the distribution of close relatives AND the literature-reported extremes for the inferred viral group. State percentile, distance from the group median, and whether the query approaches or exceeds known record-class sizes (cite the paper that defines that record). This applies even when the query is mid-distribution — the placement itself is the finding.
- 12. Produce an interesting-findings table and order it deterministically from `genome_size_frontier.tsv`. Sort by `record_class` in the order `above_literature_max`, `within_known_range`; then by `distance_from_median` descending, with blank or non-numeric values last; then by `genome` ascending. If no strong discovery candidates are found, state that explicitly and list the literature-derived checks performed.
+ ```bash
+ uv run --script skills/bio-viromics/scripts/build_viromics_evidence.py \
+ viral_metrics.tsv --resources resources.json --hypotheses hypotheses.tsv \
+ --reflections reflections.tsv --comparative-dir comparison/ \
+ --out results/bio-viromics/evidence
+ ```
+ Input contracts (tab-separated, exact column order; fixtures under `fixtures/`):
+ - `viral_metrics.tsv`: `genome role group genome_size gene_count literature_min literature_max literature_doi`; `role` is `query` or `reference`, and each query needs at least two references of the same `group`.
+ - `hypotheses.tsv`: `hypothesis_id hypothesis type status evidence revision_stage`; at least five distinct IDs and at least one row of `type` `technical` or `null`.
+ - `reflections.tsv`: `stage observed qc_status hypotheses_gained hypotheses_lost alternatives next_check literature_id`; the first stage is `initial`, a `final` stage is present, at least four stages in total, and `qc_status` is `passed`, `failed`, or `conditional`.
+ - `resources.json`: schema `1.0` with exactly `genomad`, `checkv`, `gvclass`, `vcontact3` and their `_db` entries, each with `version` and `sha256`. Database entries also carry `path` and `kind` (`file`, or `directory` with the deterministic tree SHA-256 the driver computes).
+
+ The driver computes the frontier from genome size only and sets `record_class` to `above_literature_max` or `within_known_range`. Add gene-count placement in the report.
+ 11. Write the interesting-findings table ordered from `genome_size_frontier.tsv`: `record_class` in the order `above_literature_max`, `within_known_range`; then `distance_from_median` descending, with blank or non-numeric values last; then `genome` ascending. If no strong discovery candidate is found, state that and list the literature-derived checks performed.
+
## Input Requirements
Prerequisites:
- - Tools declared in the project's pinned Pixi environment. See `docs/README.md` for expected tools.
- - Reference DB root: set `BIO_DB_ROOT` to the project or site-local database directory.
- - Input contigs are available.
+ - Tools pinned in the project's Pixi environment; see [docs/README.md](docs/README.md).
+ - `BIO_DB_ROOT` set to the project or site database directory that holds the geNomad, CheckV, GVClass, and vConTACT3 databases.
+
Inputs:
- - contigs.fasta
- - results/taxonomy/domain_routing.tsv when available
+ - `contigs.fasta` (non-empty)
+ - `results/taxonomy/domain_routing.tsv` when available
## Output
- - results/bio-viromics/viral_contigs.fasta
- - results/bio-viromics/domain_routing_review.tsv
- - results/bio-viromics/checkv_results/
- - results/bio-viromics/group_comparison_results/
- - results/bio-viromics/analysis_playbook.md
- - results/bio-viromics/viral_taxonomy.tsv
- - results/bio-viromics/comparison_baseline.tsv
- - results/bio-viromics/closest_relatives.tsv
- - results/bio-viromics/viral_discovery_candidates.tsv
- - results/bio-viromics/viral_feature_inventory.tsv
- - results/bio-viromics/genome_size_frontier.tsv
- - results/bio-viromics/viromics_report.md
- - results/bio-viromics/logs/
+ Driver outputs under `results/bio-viromics/evidence/`:
+ - `marker_census.tsv`, `family_copy_number_comparison.tsv`, `conserved_neighborhoods.tsv`, `ncRNA_census.tsv`
+ - `hypothesis_register.tsv`, `intermediate_reflections.tsv`
+ - `genome_size_frontier.tsv`
+ - `run_manifest.json`, validated against [schemas/evidence-bundle.schema.json](schemas/evidence-bundle.schema.json)
- stdout: the last line is one JSON envelope `{ok, skill, out, manifest, warnings}` (driver stdout contract in AGENTS.md)
- - Artifact contract: [schemas/evidence-bundle.schema.json](schemas/evidence-bundle.schema.json)
+ Workflow outputs under `results/bio-viromics/`, written by the agent:
+ - (agent-authored) `viral_contigs.fasta`, `checkv_results/`, `viral_taxonomy.tsv`
+ - (agent-authored) `domain_routing_review.tsv`, `analysis_playbook.md`
+ - (agent-authored) `comparison_baseline.tsv`, `closest_relatives.tsv`, `group_comparison_results/`
+ - (agent-authored) `viral_feature_inventory.tsv`, `viral_discovery_candidates.tsv`
+ - (agent-authored) `viromics_report.md`, `logs/`
+
## Quality Gates
- - [ ] CheckV quality thresholds meet project standards.
+ - [ ] `contigs.fasta` is non-empty and the viral databases exist under `BIO_DB_ROOT`.
+ - [ ] QuickClade domain routing was reviewed for assembly, MAG, or genome inputs, or the missing screen was run before final classification.
- [ ] Resource versions and database checksums are recorded and verified before classification.
- - [ ] Marker, family-copy, synteny, and ncRNA artifacts refer to the same query/reference set and are linked to explicit hypothesis revisions.
- - [ ] Contamination flags are below 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 contigs.fasta is non-empty.
- - [ ] QuickClade domain-routing evidence was reviewed for assembly/MAG/genome inputs, or the absence of a prior screen is corrected before final classification.
- - [ ] Verify viral reference DBs exist under the reference root.
- - [ ] Literature-derived analysis playbook names the inferred viral group, cited sources, standard analyses, and chosen/skipped methods.
- - [ ] Chosen comparison method is appropriate for the inferred viral group; phage-oriented tools are not used for non-phage groups without literature support.
- - [ ] Discovery scan covers the feature classes and outlier dimensions identified in the playbook.
- - [ ] Closest-relative or reference-set context is reported for every high-quality viral genome where references are available.
- - [ ] `genome_size_frontier.tsv` places each query in the size/gene-count distribution of close relatives and the literature-defined group extremes, with cited references.
- - [ ] Report includes candidate discoveries with evidence, confidence, relative comparison, and follow-up checks, or a credible negative finding.
+ - [ ] CheckV quality tiers and contamination meet the project thresholds; unmet thresholds are reported as results.
+ - [ ] The playbook names the inferred viral group, cited sources, standard analyses, and chosen and skipped methods.
+ - [ ] The comparison method fits the inferred group; phage-oriented tools are not used for other groups without literature support.
+ - [ ] Marker, family-copy, neighborhood, and ncRNA tables use the same query and reference set and are linked to hypothesis revisions.
+ - [ ] Every high-quality viral genome with available references has closest-relative or reference-set context.
+ - [ ] `genome_size_frontier.tsv` places each query against close relatives and cited literature extremes.
+ - [ ] The report lists candidate discoveries with evidence, confidence, comparison baseline, and follow-up checks, or a credible negative finding.
+ - [ ] On execution failure, logs are kept and the failed command is reported; a retry follows a diagnosis and records the changed parameters. Parameters are never tuned only to pass a gate.
## Non-Goals
- No host assignment beyond the evidence the run produced. Without host-linked signal from the chosen tools, the host stays unassigned.
- - No completeness or contamination claims without CheckV; detector output alone does not grade a viral genome.
+ - No completeness or contamination claims without CheckV (or GVClass for giant viruses); detector output alone does not grade a viral genome.
- No lifecycle calls (lytic, lysogenic, chronic) from sequence alone.
- - No phage-oriented taxonomy for groups the literature playbook does not support, and no classification while database checksums are unverified.
+ - No phage-oriented taxonomy for groups the playbook does not support, and no classification while database checksums are unverified.