Reconstruct single-cell resolution from spatial transcriptomics with CellRefiner

CellRefiner is a physical model-based method that integrates a scRNA-seq dataset with a paired spatial transcriptomics (ST) dataset to generate single-cell resolution in the imputed ST data. CellRefiner models cells as particles connected by forces, and then optimizes cell locations with spatial proximity constraints, gene expression similarity, and ligand-receptor interactions between cells.

Installation

CellRefiner requires Python >= 3.9 and NVIDIA GPU with CUDA support.

Step 1: Create and activate a virtual environment

We recommend using Conda or Mamba for environment management. To install Mamba, see https://github.com/conda-forge/miniforge.

mamba create -n cellrefiner_env python=3.9
mamba activate cellrefiner_env

Step 2: Install cellrefiner from GitHub

pip install git+https://github.com/XiangyuKuang/cellrefiner.git

Step 3: Install CuPy (Optional)

CuPy installation will accelerate cellrefiner.preprocessing.spatial_mapping().

We recommend installing CuPy and CUDA toolkit via conda to avoid compatibility issues:

mamba install cupy cudatoolkit -c conda-forge

Expected installation time: Approximately 2 minutes on a desktop computer.

Usage

For detailed examples, please refer to the tutorials folder.

Import packages

import squidpy as sq
import cellrefiner as cr

Load spatial transcriptomics and scRNA-seq datasets (available via the Squidpy package)

adata_st = sq.datasets.visium_fluo_adata_crop()
# select the cortex region
adata_st = adata_st[adata_st.obs.cluster.isin([f"Cortex_{i}" for i in range(1, 5)])].copy()
adata_sc = sq.datasets.sc_mouse_cortex()

Load ligand-receptor database

db_lr = cr.pp.ligand_receptor_database(species = 'mouse')

Map cells to spots and refine the spatial locations of mapped cells

adata_cr = cr.pp.spatial_mapping(adata_st,adata_sc,db_lr,scale=125,cluster_key_sc = 'cell_subclass')

Cell shape modeling and visualization

sem = cr.tl.cell_shape_modeling(adata_cr,cluster_key = 'cell_subclass')
cr.pl.plot_cell_shape(sem)

Contact-based communication analysis

db_lr = cr.pp.filter_lr_database(db_lr, adata_cr)
cr.tl.contact_communication(db_lr, adata = adata_cr)

Expected run time: Approximately 7 minutes on a desktop computer with NVIDIA GPU.

Documentation

See detailed documentation at https://cellrefiner.readthedocs.io/en/latest/.

Citation

This repository accompanies the publication:

Bourgain-Chang, E., Kuang, X., Cang, Z. et al. Reconstructing single-cell resolution from spatial transcriptomics with CellRefiner. Nat Commun (2026). https://doi.org/10.1038/s41467-026-70090-2

Codes used in the paper are archived under release v1.0.0.