bio-viromics

Bio Viromics

Detect, quality-check, and classify viral contigs, then compare each viral genome against a literature-derived reference set.

Instructions

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

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.

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: