VirNest

Hierarchical virus clustering for metagenomic data — VirNest estimates Virus Clusters (vOTUs) and their taxonomic hierarchy from viral contigs using protein-similarity networks, UniFrac distances, and nested Stochastic Block Models (nSBM).

---

Table of Contents

• Overview
• Method
• Installation
• Quick Start
• Reproducing the Paper
• Data
• Citation
• References
• License

---

Overview

VirNest provides a principled, graph-based framework for clustering viral metagenomic contigs into Virus Operational Taxonomic Units (vOTUs) and inferring a multi-level taxonomic hierarchy. It was applied to three independent cohort studies:

Study	Disease	Samples
IBD	Inflammatory Bowel Disease	n = see paper
CRC	Colorectal Cancer	n = see paper
GvHD	Graft-versus-Host Disease	n = see paper

Two variants of the pipeline are provided:

Variant	Description
VirNest	Single unified hierarchy across all protein components
VirNestMG	Per-component multigraph — preserves component-level resolution

---

Method

Step-by-step pipeline

Viral contigs (FASTA) + Abundance matrix
          │
          ▼
  Step 0 ─ Gene prediction   (Prodigal)
          │
          ▼
  Step 0 ─ Protein similarity (MMseqs2) → Protein network
          │
          ▼
  Step 1 ─ nSBM per protein component → Protein Clusters (ProCs)
          │
          ▼
  Step 2 ─ ProC–contig overlap → Presence/Absence matrix
          │
          ▼
  Step 3 ─ UniFrac distance between contigs
          │
          ▼
  Step 4 ─ Threshold + nSBM per contig component → vOTUs
          │
          ▼
  Step 5 ─ Annotation via ViralRefSeq

VirNestMG variant

VirNestMG constructs a multigraph over protein components, running separate nSBM hierarchies per component before merging them into a unified vOTU table.

---

Installation

VirNest requires conda because two key dependencies (graph-tool, unifrac) are only available via conda-forge.

# 1. Clone the repository
git clone https://github.com/gnopuz83/virnest.git
cd virnest

# 2. Create and activate the conda environment (≈10–20 min first time)
conda env create -f environment.yml
conda activate virnest

# 3. Install the VirNest package in editable mode
pip install -e .

Running on Google Colab? Use the notebooks in notebooks/ — they bootstrap the conda environment automatically via condacolab.

---

Quick Start

Command-line interface

virnest run \
  --genome-file    path/to/contigs.fasta \
  --abundance-file path/to/abundance.tsv \
  --output-dir     path/to/output/ \
  --distance-type  unifrac_unweighted \
  --multigraph                          # omit for single-tree VirNest

Python API

from virnest.run_virnest import run_virnest

run_virnest(
    genome_file      = "contigs.fasta",
    abundance_matrix = "abundance.tsv",
    output_dir       = "output/",
    distance_type    = "unifrac_unweighted",
    multigraph       = True,          # False for VirNest single-tree
    use_reference    = True,
    threshold_values = [0.8],
    min_protein_component_size = 2,
    random_seed      = 42,
)

Key parameters

Parameter	Default	Description
multigraph	True	True = VirNestMG, False = VirNest
distance_type	unifrac_unweighted	Distance metric for contig–contig graph
threshold_values	[0.8]	UniFrac threshold(s) for graph construction
min_protein_component_size	2	Minimum proteins per component to process
use_reference	True	Annotate against ViralRefSeq
random_seed	42	Reproducibility seed

---

Reproducing the Paper

All analyses from the paper can be reproduced using the Colab notebooks in notebooks/. Each notebook mounts your Google Drive, installs the environment, and runs the full pipeline end-to-end.

Notebook	Study	Variant
IBD_VirNestMG.ipynb	IBD	VirNestMG
CRC_VirNestMG.ipynb	CRC	VirNestMG
GvHD_VirNestMG.ipynb	GvHD	VirNestMG
IBD_VirNest.ipynb	IBD	VirNest
CRC_VirNest.ipynb	CRC	VirNest
GvHD_VirNest.ipynb	GvHD	VirNest

To run:

1. Open any notebook in Google Colab.
2. Run Cell 0 once (bootstraps conda, triggers kernel restart).
3. Run Cells 1–5 top-to-bottom. The pipeline checkpoints each step — interrupted runs can be safely resumed.

The VirNest notebooks reuse Prodigal + MMseqs2 outputs from the corresponding VirNestMG run via symlink — run the MG variant first.

---

Data

All input data and processed outputs are deposited at Zenodo:

Zenodo record: 10.5281/zenodo.20717679

Expected Drive layout for the Colab notebooks:

MyDrive/Colab_Notebooks/Zenodo1/
  data/
    Virus/
      IBD/Contigs/{Sequence,Abundance}/
      CRC/Contigs/{Sequence,Abundance}/
      GvHD/Contigs/{Sequence,Abundance}/
    Bacteria/
      IBD/   (16S abundance table)
      CRC/
      GvHD/
  package/
    Virnest_package.zip

---

Citation

If you use VirNest in your research, please cite:

@article{virnest2025,
  title   = {VirNest: Hierarchical virus clustering for metagenomic data},
  author  = {Pugno, Daniele and others},
  journal = {TODO},
  year    = {2025},
  doi     = {TODO}
}

---

References

• Whole-Virome Analysis Sheds Light on Viral Dark Matter in Inflammatory Bowel Disease — DOI:10.1016/j.chom.2019.10.009
• vConTACT2: Virus clustering with network-based methods — DOI:10.1038/s41587-019-0100-8
• CAMISIM: Simulating metagenomes and microbial communities — DOI:10.1186/s40168-019-0633-6

---

License

This project is licensed under the MIT License.