Sovereign 8s.is mirror of standardgalactic/cellrefiner
  • Jupyter Notebook 99.1%
  • Python 0.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-03-01 00:58:29 +00:00
cellrefiner finalize 2026-02-25 16:09:02 +00:00
docs add tutorials 2025-09-12 08:03:53 +00:00
tests create setup 2025-09-07 07:40:42 +00:00
tutorials add rare cell type tutorial 2026-01-15 15:34:34 -08:00
.gitignore Initial commit 2025-09-02 16:53:00 -07:00
.readthedocs.yaml update docs 2025-09-10 20:36:03 +00:00
LICENSE Initial commit 2025-09-02 16:53:00 -07:00
MANIFEST.in add tutorials 2025-09-06 11:42:33 +00:00
pyproject.toml create setup 2025-09-07 07:40:42 +00:00
README.md update readme 2026-03-01 00:58:29 +00:00
requirements.txt update 2025-09-07 11:08:36 +00:00
setup.cfg update docs 2025-09-10 20:36:03 +00:00

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.