GVClass assigns taxonomy to giant virus genomes and metagenome-assembled genomes by phylogenetic placement against a comprehensive reference genome database. It covers Nucleocytoviricota (NCLDV), Mirusviricota, and Preplasmiviricota (PPV). It predicts taxonomy from domain down to genus and species level, assigning a nearest-reference label. Each genome returns a majority-vote taxonomy with a confidence flag, plus completeness and contamination metrics tuned for giant viruses.
GVClass calls genes across nine genetic codes, detects conserved markers with HMM panels, and places each marker protein in its own reference tree. Nearest neighbors across the trees cast a majority vote that sets taxonomy and confidence, and the marker evidence feeds completeness and contamination models tuned for giant viruses. How GVClass works explains each stage.
Full documentation: https://NeLLi-team.github.io/gvclass/
- Tutorials — learn GVClass on the bundled example.
- How-to guides — bins, contigs, HPC, species trees, speed/accuracy, quality.
- Reference — every CLI flag, config key, output column, and marker panel.
- Explanation — how placement, taxonomy, and the quality models work.
Pixi (local):
git clone https://github.com/NeLLi-team/gvclass.git
cd gvclass
pixi install
pixi run setup-db
pixi run exampleApptainer (HPC):
wget https://raw.githubusercontent.com/NeLLi-team/gvclass/main/gvclass-a
chmod +x gvclass-a
./gvclass-a QUERY_DIR RESULTS_DIR -t 32The Apptainer image bundles the database and dependencies. See Getting started for the full walkthrough.
The wrapper pulls the library://nelligroup-jgi/gvclass/gvclass:2.0.3 SIF
from the public Sylabs library. The image embeds the compact v2.0.0 database
and writes its Parquet materialization cache to a host directory under
~/.cache/gvclass/resource-cache/v2.0.0.
GVClass works best on bins after metagenomic binning: a directory of one or more FASTA files (.fna or .faa), one file per putative genome. For giant virus discovery, filter contigs to >=30 kb (>=50 kb preferred). Use --min-length to adjust the MAG/bin nucleotide floor and --contigs with --contigs-min-length to classify each contig in a multi-contig .fna independently. Details are in the how-to guides.
Pitot et al. (2024): Conservative taxonomy and quality assessment of giant virus genomes with GVClass. npj Viruses. https://www.nature.com/articles/s44298-024-00069-7
The trained contamination model is shipped in the runtime resource bundle at
resources/contamination/model.joblib.
The v2.0.0 runtime resource bundle is archived on Zenodo: https://doi.org/10.5281/zenodo.21225457
The GVClass runtime resources include genomes and models derived from:
Medvedeva S, Guyet U, Pelletier E, et al. (2026): Widespread and intron-rich mirusviruses are predicted to reproduce in nuclei of unicellular eukaryotes. Nature Microbiology 11:228-239. https://doi.org/10.1038/s41564-025-01906-2
Roux S, Fischer MG, Hackl T, Katz LA, Schulz F, Yutin N (2023): Updated Virophage Taxonomy and Distinction from Polinton-like Viruses. Biomolecules 13(2):204. https://doi.org/10.3390/biom13020204
Fiamenghi MB, Camargo AP, Chasapi IN, et al. (2025): Meta-virus resource (MetaVR): expanding the frontiers of viral diversity with 24 million uncultivated virus genomes. Nucleic Acids Research gkaf1283. https://doi.org/10.1093/nar/gkaf1283
Vasquez YM, Nardi T, Terasaki GM, et al. (2025): Genome-resolved expansion of Nucleocytoviricota and Mirusviricota reveals new diversity, functional potential, and biotechnological applications. bioRxiv 2025.09.26.678796. https://doi.org/10.1101/2025.09.26.678796
Bellas CM, Sommaruga R (2026): A framework for Polinton-like virus diversity across aquatic microbiomes reveals links to multiple viral classes and Nucleocytoviricota. bioRxiv 2026.06.19.733378. https://doi.org/10.64898/2026.06.19.733378
Non-commercial use only (see LICENCE). Report issues at https://github.com/NeLLi-team/gvclass/issues or contact fschulz@lbl.gov.