vOMIX-MEGA is a highly scalable, fast, and reproducible viral metagenomic pipeline designed for large-scale bulk-metagenomic and viromic data analysis. Built on top of a Snakemake backend with automated Conda and Apptainer/Singularity container support, vOMIX-MEGA resolves performance bottlenecks in current state-of-the-art tools to achieve dramatic speedups without sacrificing accuracy.
📖 Full Documentation: vomix-mega.readthedocs.io
- ⚡ Unmatched Speed: Operates 10–1000× faster than traditional unoptimized pipelines by fine-tuning underlying software dependencies and optimizing parallel job scheduling.
- 🧠 Predictable & Low Memory Footprint: Standard viral end-to-end analysis requires a maximum of 24 GB RAM (further tuneable down to 8 GB for resource-constrained systems).
- 🧩 Modular Architecture: Run standalone sub-workflows (
preprocess,viral-identify,viral-host,prok-binning, etc.) or execute full end-to-end analysis. - 🔬 Extensively Benchmarked: Evaluated across mock and experimental datasets to ensure top-tier sensitivity and precision.
- 📦 Reproducible & Containerized: Full support for
Apptainer/Singularitycontainers combined with per-rule Conda environments ensures 100% computational reproducibility. - 📥 Seamless SRA Input: Simply feed SRA accessions to download, preprocess, assemble, and analyze viral communities automatically.
vOMIX-MEGA structures complex viral and prokaryotic metagenomic workflows into dedicated, easy-to-use modules:
| Category | Module | Description |
|---|---|---|
| Core Viral Workflow | viral-identify |
High-throughput identification of viral contigs and proviruses |
viral-taxonomy |
Taxonomic classification of identified viral contigs (vOTUs) | |
viral-host |
Host prediction using CRISPR spacers and tRNA/sequence matching | |
viral-annotate |
Functional annotation of viral genes and genomes | |
viral-community |
Relative abundance estimation and community profiling | |
viral-end-to-end |
Full pipeline execution from raw reads to community profiling | |
| Benchmarking & Utils | viral-benchmark |
Compare 6 viral identification tools (geNomad, DeepVirFinder, Phamer, VirSorter2, VirFinder, VIBRANT) |
cluster-fast |
High-speed sequence clustering for vOTU definition | |
checkv-pyhmmer |
Ultra-fast CheckV quality assessment powered by PyHMMER | |
setup-database |
Automated setup and verification of required reference databases | |
| Prokaryotic Modules | prok-binning |
Metagenomic binning for prokaryotic genomes (MAGs) |
prok-annotate |
Functional annotation of bacterial/archaeal contigs and MAGs | |
prok-community |
Taxonomic and functional profiling of prokaryotic communities | |
| Upstream Processing | preprocess |
Quality filtering, adapter trimming, and host decontam |
assembly |
De novo metagenomic assembly optimized for viral discovery |
vOMIX-MEGA can be installed via Conda / Mamba or run using an Apptainer / Singularity container.
conda env create -f environment.yml # Or: mamba env create -f environment.yml
conda activate vomix
# 4. Verify installation
vomix -h
# 1. Clone the repository
git clone https://github.com/holab-hku/vOMIX-MEGA.git
cd vOMIX-MEGA
# 2. Create and activate the conda environment
conda env create -f environment.yml # Or: mamba env create -f environment.yml
conda activate vomix
# 3. Install the vOMIX CLI package
pip install .
# 4. Verify installation
vomix -h
Note on Conda Lock: If dependency resolution fails on your environment, use our pinned
conda-lockfile:conda-lock install --name vomix conda-lock.yml conda activate vomix pip install .
For HPC clusters or environments where Conda environments are restricted:
cd vOMIX-MEGA
# 1. Clone the repository
git clone https://github.com/holab-hku/vOMIX-MEGA.git
cd vOMIX-MEGA
# 2. Create and activate the conda environment
conda env create -f environment.yml # Or: mamba env create -f environment.yml
conda activate vomix
# 3. Install the vOMIX CLI package
pip install .
# 4. Pull the official Apptainer container (~9.5 GB)
VOMIX_VERSION="v0.1.0-beta.1"
apptainer pull --name workflow/apptainer/vomix_${VOMIX_VERSION}.sif oras://ghcr.io/erfanshekarriz/vomix:${VOMIX_VERSION}
# 5. Test installation with a dry-run
vomix -h
vomix viral-identify --sdm apptainer --fasta sample/contigs/contigs_simulated_viral_nonviral.fasta --outdir quick-run/results -j 64 --latency-wait 20 -n
Identify viral contigs in a sample FASTA dataset containing mixed viral and non-viral sequences using viral-identify.
# Activate your environment
conda activate vomix
# 1. Test run (Dry-run to verify workflow execution steps)
vomix viral-identify \
--sdm conda \
--fasta sample/contigs/contigs_simulated_viral_nonviral.fasta \
--outdir quick-run/results \
--contig-splits 0 \
--checkv-splits 0 \
-j 64 \
--latency-wait 20 \
-n
# 2. Run high-performance mode (~22 GB RAM, fast execution ~10 mins)
vomix viral-identify \
--sdm conda \
--fasta sample/contigs/contigs_simulated_viral_nonviral.fasta \
--outdir quick-run/results \
--contig-splits 0 \
--checkv-splits 0 \
-j 64 \
--latency-wait 20
# 3. Run low-memory mode (~8 GB RAM for smaller machines)
vomix viral-identify \
--sdm conda \
--fasta sample/contigs/contigs_simulated_viral_nonviral.fasta \
--outdir quick-run/results \
--contig-splits 7 \
--checkv-splits 7 \
-j 64 \
--latency-wait 20
# 4. View identification summary output
head -n 20 quick-run/results/identify/viral/output/classification_summary_vOTUs.csv
Detailed guides, advanced cluster submission options (SLURM / PBS / SGE), parameter specifications, and troubleshooting tips are available at our official documentation site:
- 🛠️ Installation Details & Troubleshooting
- ⚡ Quick Start Guide
- 📖 Module Specifications & Parameters
- 🔧 Troubleshooting Guide
If you use vOMIX-MEGA in your research, please cite our pre-print:
vOMIX-MEGA: A critical speed enhancement for end-to-end viral metagenomics Erfan Shekarriz, Elsa Vijendran, Joshua WK Ho bioRxiv (2026). DOI: https://doi.org/10.64898/2026.07.28.741255
Found a bug or have a feature request? Please open an issue on our GitHub Issues Page.
Copyright © 2026 Ho Lab, The University of Hong Kong (HKU). Distributed under the MIT License.