Skip to content

Latest commit

 

History

History
108 lines (74 loc) · 5.17 KB

README.md

File metadata and controls

108 lines (74 loc) · 5.17 KB
Raw

stars-badge build-badge Code style: black license-badge Python 3.10|3.11|3.12

DECIPHER

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

DECIPHER

Installation

PyPI

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_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 Open In Colab
Multi-slices with Batch Effects Tutorial on how to apply DECIPHER to multiple slices with batch effects Open In Colab
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

Citation

In coming.

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. CUDA out of memory error

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().

  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: