cell-decipher 0.3.2

DECIPHER for learning disentangled cellular embeddings in large-scale heterogeneous spatial omics data

Installation • Documentation • Citation • FAQ • Acknowledgement

DECIPHER aims to learn cells’ disentangled intracellular molecular identity embedding and extracellular spatial context embedding from spatial omics data.

Please check our paper DECIPHER for learning disentangled cellular embeddings in large-scale heterogeneous spatial omics data on Nature Communications.

Installation

PyPI

[!IMPORTANT] Requires Python >= 3.10, install with CUDA-enabled GPU is recommended.

We recommend to install cell-decipher to a new conda environment:

conda create -n decipher -c conda-forge python==3.11 uv -y && conda activate decipher
uv pip install cell-decipher
install_pyg_dependencies

(Optional) You can install RAPIDS to accelerate visualization.

conda create -n decipher -c conda-forge -c rapidsai -c nvidia python=3.11 rapids=25.06 uv 'cuda-version>=12.0,<=12.8' -y && conda activate decipher
uv pip install cell-decipher
install_pyg_dependencies

Docker

Build docker image from Dockerfile or pull image from Docker Hub directly:

docker pull huhansan666666/decipher:latest
docker run --gpus all -it --rm huhansan666666/decipher:latest

Documentation

Minimal example

Here is a minimal example for quick start:

import scanpy as sc
from decipher import DECIPHER
from decipher.utils import scanpy_viz

# Init model
model = DECIPHER(work_dir='/path/to/work_dir')

# Register data (adata.X is raw counts, adata.obsm['spatial'] is spatial coordinates)
adata = sc.read_h5ad('/path/to/adata.h5ad')
model.register_data(adata)

# Fit DECIPHER model
model.fit_omics()

# Clustering disentangled embeddings
adata.obsm['X_center'] = model.center_emb  # intracellular molecular embedding
adata.obsm['X_nbr'] =  model.nbr_emb  # spatial context embedding
adata = scanpy_viz(adata, ['center', 'nbr'], rapids=False)

# Plot
adata.obsm['X_umap'] = adata.obsm['X_umap_center'].copy()
sc.pl.umap(adata, color=['cell_type'])
adata.obsm['X_umap'] = adata.obsm['X_umap_nbr'].copy()
sc.pl.umap(adata, color=['region'])

Tutorials

Please check documentation for all tutorials.

Name	Description	Colab
Basic Model Tutorial	Tutorial on how to use DECIPHER
Multi-slices with Batch Effects	Tutorial on how to apply DECIPHER to multiple slices with batch effects
Identify Localization-related LRs	Tutorial on how to identify ligand-receptors which related with cells’ localization based on DECIPHER embeddings	Insufficient resources
Multi-GPUs Training	Tutorial on how to use DECIPHER with multi-GPUs on spatial atlas	Insufficient resources
More technologies	Tutorial on how to use DECIPHER with multiple spatial technologies	Insufficient resources

Citation

DECIPHER for learning disentangled cellular embeddings in large-scale heterogeneous spatial omics data (Nature Communications)

If you want to repeat our benchmarks and case studies, please check the benchmark and experiments folder.

FAQ

Please open a new github issue if you meet problem.

1. Visium or ST data

DECIPHER is designed for single cell resolution data. As for Visium or ST, you can still use DECIPHER after obtaining single-cell resolution through deconvolution or spatial mapping strategies.

Acknowledgement

We thank the following great open-source projects for their help or inspiration:

• vit-pytorch
• lightly
• scib
• rapids_singlecell