SIMVI

Note

This fork of KlugerLab/SIMVI ports SIMVI to scvi-tools 1.5; the changes are offered upstream in KlugerLab/SIMVI#6. Install it with pip install git+https://github.com/quadbio/simvi.

Changes from SIMVI 0.1.2

• Ported to scvi-tools 1.5:
  • LossRecorder becomes LossOutput; the independence penalty goes to extra_metrics["mi_loss"].
  • AnnTorchDataset comes from scvi.data. One helper loads the full data and keeps batch codes as integers, which scvi-tools 1.5's one_hot requires.
  • Imports scvi-tools removed, all unused, are dropped: parse_use_gpu_arg, _de_core, TrainingPlan, TrainRunner, DataSplitter and pytorch_lightning.
• extract_edge_index is a staticmethod, and train() sets is_trained_.
• Packaging moves from setup.cfg to pyproject.toml (hatchling) and requires scvi-tools>=1.5 and torch-geometric. py-pcha becomes optional (the archetypes extra); only get_archetypes and get_se use it.
• A no-op SimVIModule.on_load lets scvi-tools 1.5's BaseModelClass.load load saved models.
• Full-batch training (batch_size=None) on GPU moves the loss to the CPU before np.array; it used to crash.
• The noising mask and permutation keys are drawn on the data's device. On the CPU, each step of the first mae_epochs argsorted an n_cells × n_masked_genes matrix on the host: about 3 s per step at 10⁵ cells and a few thousand genes with the GPU idle, 0.2 s on the GPU.

About SIMVI

SIMVI (Spatial Interaction Modeling using Variational Inference) is a deep generative framework for disentangling intrinsic variation and spatially-induced variation in spatial omics data. SIMVI has rigorous identifiability guarantee, and enables novel downstream analyses, including clustering and differential expression analysis based on disentangled representations, spatial effect identification, spatial effect attribution, and transfer learning on new measurements / modalities. SIMVI is implemented with scvi-tools.

Read the SIMVI paper on Nature Communications: https://www.nature.com/articles/s41467-025-58089-7

Citation:

@article{dong2025simvi,
  title={SIMVI disentangles intrinsic and spatial-induced cellular states in spatial omics data},
  author={Dong, Mingze and Su, David G and Kluger, Harriet and Fan, Rong and Kluger, Yuval},
  journal={Nature Communications},
  volume={16},
  number={1},
  pages={2990},
  year={2025},
  publisher={Nature Publishing Group UK London}
}

System requirements

OS requirements

The SIMVI package is supported for all OS in principle. The package has been tested on the following systems:

• macOS: Monterey (12.4)
• Linux: Ubuntu (20.04.5)

Dependencies

See pyproject.toml for details.

Installation

SIMVI requires python version 3.11+ and scvi-tools 1.5+. The release on PyPI (0.1.2) predates this and requires scvi-tools<=0.16.2; until a new release, install from GitHub with:

pip install git+https://github.com/KlugerLab/SIMVI

The installation should take no more than a few minutes on a normal desktop computer.

Documentation

Please refer to our documentation here.

Usage

For detailed usage, follow our step-by-step tutorial here. The tutorial should take no more than 30 minutes to complete on a standard desktop computer.

• Getting Started with SIMVI

Download the dataset used for the tutorial here:

• Human MERFISH MTG data