NetworkVI: Biologically Guided Variational Inference for Interpretable Multimodal Single-Cell Integration and Discovery

Getting started

NetworkVI is a sparse deep generative model designed for the paired, vertical (shared cells across measurements), horizontal (shared features across datasets) or mosaic integration and interpretation of multimodal single-cell data. The model learns a rich, batch-corrected low-dimensional representation of bi- and trimodal single-cell count datasets, estimating the representation using normalized input data. Please refer to the documentation. We also provide tutorials:

• Paired integration and query-to-reference mapping
• Mosaic integration
• Interpretability: Inference of GO importances and Gene-GO associations
• Interpretability: Infernce of GO term-specific covariate attention values

Installation

NetworkVI supports both standard pip installation and Pixi-based reproducible environments. We recommend Pixi for most users, as it automatically manages Python, CUDA, and PyTorch versions.

Recommended: Installation using Pixi (reproducible, CUDA-enabled)

Pixi is a modern environment manager that combines Conda and pip, making it easy to install GPU-enabled scientific software reproducibly.

1. Install Pixi

Follow the instructions at: https://pixi.sh

2. Clone the repository

git clone https://github.com/LArnoldt/networkvi.git
cd networkvi

3. Create and activate the environment

pixi install
pixi shell

Alternative: Installation using pip

If you prefer a standard pip-based installation (CPU or manually managed GPU):

1. Install the latest release of NetworkVI from PyPi:

pip install networkvi

2. (Optional, GPU) Install PyTorch and PyG dependencies manually

For CUDA 12.1:

pip install -U torch==2.2.0 --index-url https://download.pytorch.org/whl/cu121
pip install -U torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.2.0+cu121.html

Other CUDA versions are available at:

• https://pytorch.org
• https://pytorch-geometric.readthedocs.io

Optional dependencies

Additional functionality can be installed via extras:

pip install "networkvi[tutorials]"
pip install "networkvi[docs]"
pip install "networkvi[all]"

When using Pixi, extras can be enabled by adjusting pixi.toml.

API

Please find the API here.

Release notes

Please find the release notes here.

Contact

If you found a bug, please use the issue tracker. If you use NetworkVI in your research, please consider citing the preprint:

Arnoldt, L., Upmeier zu Belzen, J., Herrmann, L., Nguyen, K., Theis, F.J., Wild, B. , Eils, R., "Biologically Guided Variational Inference for Interpretable Multimodal Single-Cell Integration and Mechanistic Discovery", bioRxiv, June 2025.

Reproducibility

Code and notebooks to reproduce the results and figues from the paper are available here.