DECIPHER aims to learn cells’ disentangled intracellular molecular identity embedding and extracellular spatial context embedding from spatial omics data.
Important
Requires Python >= 3.10 and CUDA-enabled GPU (CPU-only device is not recommended).
We recommend to install cell-decipher to a new conda environment with RAPIDS dependencies.
mamba create -n decipher -c conda-forge -c rapidsai -c nvidia python=3.11 rapids=24.04 cuda-version=11.8 cudnn cutensor cusparselt -y && conda activate decipher
pip install cell-decipher
install_pyg_dependenciesBuild docker image from Dockerfile or pull image from Docker Hub directly:
docker pull huhansan666666/decipher:latest
docker run --gpus all -it --rm huhansan666666/decipher:latestHere 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'])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 wtih 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 |
In coming.
If you want to repeat our benchmarks and case studies, please check the benchmark and experiments folder.
Please open a new github issue if you meet problem.
CUDA out of memoryerror
The model.train_gene_select() function in Identify Localization-related LRs tutorial (~700k cells and 1k LRs) uses ~40G GPU memory. If your GPU device do not have enough memory, you still can train model on GPU but set use_gpu=False in model.train_gene_select().
- 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.
We thank the following great open-source projects for their help or inspiration: