revise-svc 0.0.7

Spatial transcriptomics benchmarking and annotation toolkit.

REVISE

REVISE (REconstruction via Vision-integrated Spatial Estimation) is a unified framework for reconstructing Spatially-inferred Virtual Cells (SVCs) by integrating spatial transcriptomics (ST) data, histological imaging, and matched single-cell RNA-seq references.

Visit our documentation for installation, tutorials, examples and more. Download Sim2Real benchmark, generated results and Real application data in Zenodo. Put them into raw_data dir if you want to reproduce our results.

Motivation

Current ST technologies are limited by six key confounding factors (CFs) that hinder the reconstruction of biologically coherent single-cell units:

Current ST limitations

• Spatially heterogeneous CFs: image segmentation artifacts, bin-to-cell assignment errors
• Spatially homogeneous CFs: spot size, batch effects, gene panel limitations, gene dropout

REVISE addresses these limitations through a topology-aware hierarchical optimal transport (OT) framework, generating two complementary types of virtual cells:

• sp-SVC: leverages spatial priors to correct spatially heterogeneous CFs and preserve local tissue architecture
• sc-SVC: integrates scRNA-seq references to restore transcriptome-wide coverage and correct dropout

Overview of the REVISE framework

Highlights

• Unified Framework: Handles six CFs across three ST platforms (sST, iST, hST)
• Dual SVC Modes: sp-SVC for spatial refinement, sc-SVC for molecular completeness
• Benchmark Module: Reproducible evaluation pipelines for simulated or public datasets
• Application Module: Annotation, reconstruction, and downstream analyses for real ST data

SVC Applications

sp-SVC Applications

• Recovers spatially resolved gene and pathway signals from Visium HD data
• Identifies localized transcriptional programs (e.g., EMT at tumor leading edge)
• Enhances spatial autocorrelation and clustering coherence

sc-SVC Applications

• Reconstructs whole-transcriptome profiles for Xenium data
• Defines fine-grained immune subtypes (T cells, TAMs, CAFs)
• Reveals spatially organized cell-cell communication and clinical associations

Biological insights enabled by SVC reconstruction

Quick Start

Install the Python package via pip:

pip install revise-svc

If you want to use REVISE for a real ST application, please import these class:

# sp-SVC, usually for hST platforms (e.g., Visium HD)
from revise.application import SpSVC

# sc-SVC, usually for iST platforms (e.g., Xenium) and sST platforms (e.g., Visium)
from revise.application import ScSVC

If you want to use REVISE for benchmark (such as in our Sim2Real-ST benchmark setting), please import these class:

# For two spa-hetero CFs: segmentation error and bin2cell
from revise.benchmark import SpSVC

# For two spa-homo CFs: spot size and batch effect
from revise.benchmark import ScSVCSr

# For two spa-homo CFs: gene panel limitation and dropout
from revise.benchmark import ScSVCImpute

Example

Run benchmark settings (sp-SVC)

Please make sure that you have downloaded Sim2Real-ST benchmark datasets from Zenodo.

import anndata as ad
from revise.benchmark import SpSVC
from revise.conf.benchmark_seg_conf import BenchmarkSegConf

st = ad.read_h5ad("data/spatial.h5ad")
sc = ad.read_h5ad("data/single_cell_reference.h5ad")
gt_st = ad.read_h5ad("data/ground_truth_spatial.h5ad")

# Initialize the config class for sp-SVC, check the detailed API at https://revise-svc.readthedocs.io/en/latest/source/api/generated/revise.conf.application_sp_conf.ApplicationSpConf.html
config = BenchmarkSegConf(
    
)

svc = SpSVC(st, sc, config, gt_st, None)
svc.annotate()
svc.reconstruct()

Run application settings

import anndata as ad
from revise.application import SpSVC

st = ad.read_h5ad("data/spatial.h5ad")
sc = ad.read_h5ad("data/single_cell_reference.h5ad")
# Put your config file, check the files we upload in the ./revise/conf as a reference
config = ...

svc = SpSVC(st, sc, config=config, logger=None)
svc.annotate()
svc.reconstruct()

Reproducibility

If you want to reproduce our results based on the Sim2Real-ST benchmark setting, you can run single bash script as following:

cd ./reproduce/benchmark/

# for bin2cell
bash benchmark_bin2cell.sh

# for batch effect 
bash benchmark_batch_effect.sh

...

Or you can use our merged benchmark_main.sh script as following:

bash benchmark_main.sh

Repository Layout

• revise/application: SVC workflows for real datasets.
• revise/benchmark: SVC variants for benchmarking studies.
• revise/methods: Algorithm implementations and model components.
• revise/tools: Distance metrics, logging helpers, and general utilities.
• conf: Example configurations and experiment parameters.

License

REVISE is released under the MIT License (see LICENSE).