DECIPHER

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 25 Open GitHub ↗

DECIPHER for learning high-fidelity disentangled embeddings from spatial omics data

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![stars-badge](https://img.shields.io/github/stars/gao-lab/DECIPHER?logo=GitHub&color=yellow)](https://github.com/gao-lab/DECIPHER/stargazers)
[![Downloads](https://static.pepy.tech/badge/cell-decipher)](https://pepy.tech/project/cell-decipher)
[![build-badge](https://github.com/gao-lab/DECIPHER/actions/workflows/build.yml/badge.svg)](https://github.com/gao-lab/DECIPHER/actions/workflows/build.yml)
[![docs-badge](https://readthedocs.org/projects/cell-decipher/badge/?version=latest)](https://cell-decipher.readthedocs.io/en/latest/)
[![license-badge](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![PyPI](https://img.shields.io/pypi/v/cell-decipher?label=pypi)
![Python 3.10](https://img.shields.io/badge/python->=3.10-blue.svg)

<img src="./docs/_static/DECIPHER.png" width="200">

[Installation](#Installation) • [Documentation](#Documentation) • [Citation](#Citation) • [FAQ](#FAQ) • [Acknowledgement](#Acknowledgement)

</div>

`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](https://www.nature.com/articles/s41467-025-63140-8).

![DECIPHER](https://raw.githubusercontent.com/gao-lab/DECIPHER/main/docs/_static/Model.png)

## 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:

```sh
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](https://docs.rapids.ai/install) to accelerate visualization.

```sh
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](./Dockerfile) or pull image from Docker Hub directly:

```sh
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:

```python
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**](https://cell-decipher.readthedocs.io/en/latest) for all tutorials.

| Name                                    | Description                                                  | Colab                                                        |
| --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| [Basic Model Tutorial](./docs/tutorials/1-train_model.ipynb)                | Tutorial on how to use DECIPHER                            | [![Open In Colab](https://img.shields.io/badge/Colab-PyTorch-blue?logo=googlecolab)](https://colab.research.google.com/drive/14PEtrgqlf-KbLOTfBLc9gbx0YvY6mi0S?usp=sharing) |
| [Multi-slices with Batch Effects](./docs/tutorials/2-remove_batch.ipynb)     | Tutorial on how to apply DECIPHER to multiple slices with batch effects | [![Open In Colab](https://img.shields.io/badge/Colab-PyTorch-blue?logo=googlecolab)](https://colab.research.google.com/drive/1eLJeRDZFq2tlDUWpETlSxVUdzRv9CeSD?usp=sharing) |
| [Identify Localization-related LRs](./docs/tutorials/3-select_LRs.ipynb) | Tutorial on how to identify ligand-receptors which related with cells’ localization based on DECIPHER embeddings | Insufficient resources |
| [Multi-GPUs Training](./docs/tutorials.md#multi-gpu-training)                        | Tutorial on how to use DECIPHER with multi-GPUs on spatial atlas | Insufficient resources |
| [More technologies](./docs/tutorials/4-more_techs.ipynb)                        | 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](https://www.nature.com/articles/s41467-025-63140-8))

> If you want to repeat our benchmarks and case studies, please check the [**benchmark**](./benchmark/) and [**experiments**](./experiments/) folder.

## FAQ
> Please open a new [github issue](https://github.com/gao-lab/DECIPHER/issues/new/choose) 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.

<!-- 2. `CUDA out of memory` error

The `model.train_gene_select()` may need a lot GPU memory. For example, it needs ~40G GPU memory in [Identify Localization-related LRs](./docs/tutorials/3-select_LRs.ipynb) tutorial (with ~700k cells and 1k LRs). If your GPU device do not have enough memory, you still can train model on GPU but set `disable_gpu=True` in `model.train_gene_select()`. -->

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

- [vit-pytorch](https://github.com/lucidrains/vit-pytorch)
- [lightly](https://github.com/lightly-ai/lightly)
- [scib](https://github.com/theislab/scib)
- [rapids_singlecell](https://github.com/scverse/rapids_singlecell/)

DECIPHER

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README