8000 GitHub - holab-hku/vOMIX-MEGA: An ultra-fast & modular end-to-end pipeline for terabyte-scale viral metagenomics analysis. · GitHub
[go: up one dir, main page]

Skip to content

About

An ultra-fast & modular end-to-end pipeline for terabyte-scale viral metagenomics analysis.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Documentation Status License: GPL v3 Python 3.12.13 Apptainer

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


⚡ Key Features

  • ⚡ 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 / Singularity containers 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.

🏗️ Pipeline Overview & Modules

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

📦 Installation

vOMIX-MEGA can be installed via Conda / Mamba or run using an Apptainer / Singularity container.

Option 1: Conda or Mamba (Latest Stable Release)

conda env create -f environment.yml   # Or: mamba env create -f environment.yml
conda activate vomix

# 4. Verify installation
vomix -h

Option 2: Conda or Mamba (Latest Release)

# 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-lock file:

conda-lock install --name vomix conda-lock.yml
conda activate vomix
pip install .

Option 2: Apptainer / Singularity Container

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

🚀 Quick Start Tutorial

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

📚 Complete Documentation

Detailed guides, advanced cluster submission options (SLURM / PBS / SGE), parameter specifications, and troubleshooting tips are available at our official documentation site:

👉 vOMIX-MEGA ReadTheDocs


📄 Citation

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


🐛 Bug Reports & Community Support

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.

About

An ultra-fast & modular end-to-end pipeline for terabyte-scale viral metagenomics analysis.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0