revise-svc 0.0.9

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.

You can also check out our podcast and watch our intro videos for a quick overview.

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 scanpy as sc
import revise.benchmark as benchmark
from revise.benchmark import SpSVC
from revise.conf import BenchmarkSegConf

# 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(
    sample_name=YOUR_OWN_SAMPLE_NAME,
    annotate_mode="pot",
    raw_data_path=YOUR_OWN_DATA_PATH,
    result_root_path=YOUR_OWN_RESULT_PATH,
    cell_type_col="Level1",
    confidence_col="Confidence",
    unknown_key="Unknown",
    st_file=YOUR_OWN_ST_FILE,
    gt_svc_file=YOUR_OWN_GT_SVC_FILE,
    sc_ref_file=YOUR_OWN_SC_REF_FILE,
    seg_method="seg_1",
)
adata_st = sc.read_h5ad(config.st_file_path)
adata_gt_svc = sc.read_h5ad(config.gt_svc_file_path)
adata_sc_ref = sc.read_h5ad(config.sc_ref_file_path)
svc = SpSVC(adata_st, adata_sc_ref, config, adata_gt_svc, None)
benchmark.main(svc)

Run application settings

import scanpy as sc
from revise.application import SpSVC
from revise.conf import ApplicationSpConf

config = ApplicationSpConf(
    sample_name=YOUR_OWN_SAMPLE_NAME,
    annotate_mode="pot",
    raw_data_path=YOUR_OWN_DATA_PATH,
    result_root_path=YOUR_OWN_RESULT_PATH,
    cell_type_col="Level1",
    confidence_col="Confidence",
    unknown_key="Unknown",
    st_file=YOUR_OWN_ST_FILE,
    sc_ref_file=YOUR_OWN_SC_REF_FILE,
)

adata_st = sc.read_h5ad(config.st_file_path)
adata_sc_ref = sc.read_h5ad(config.sc_ref_file_path)
svc = SpSVC(adata_st, adata_sc_ref, config=config, logger=None)
svc.global_anchoring()
svc.local_refinement()

Reproducibility

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

# for bin2cell
bash ./reproduce/benchmark/benchmark_bin2cell.sh

# for batch effect 
bash ./reproduce/benchmark/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.

revise-svc exposes SVC interfaces with matching conf files: every SVC derives from BaseSVC, which defines initialization plus the abstract global_anchoring and local_refinement methods. BaseSVCAnchor extends BaseSVC and provides the shared global_anchoring used by all SVCs. SVCs are grouped into application and benchmark: application implements SpSVC and ScSVC; benchmark implements SpSVC, ScSVCImpute, and ScSVCSr. SpSVC targets segmentation and bin2cell confounding factors; ScSVCImpute targets gene panel and gene dropout; ScSVCSr targets batch effect and spot size. Conf implementations mirror the SVCs one-to-one, with parameters available on the website.

License

REVISE is released under the MIT License.