[](https://github.com/gao-lab/DECIPHER/stargazers)
[](https://pepy.tech/project/cell-decipher)
[](https://github.com/gao-lab/DECIPHER/actions/workflows/build.yml)
[](https://cell-decipher.readthedocs.io/en/latest/)
[](https://opensource.org/licenses/MIT)
<!-- [](https://codecov.io/gh/gao-lab/DECIPHER) -->
# DECIPHER
<div align="center">
[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.
## 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:
```sh
mamba create -n decipher python==3.11 -c conda-forge -y && conda activate decipher
pip install cell-decipher
install_pyg_dependencies
```
(Optional) You can install [RAPIDS](https://docs.rapids.ai/install) to accelerate visualization.
```sh
mamba create -n decipher -c conda-forge -c rapidsai -c nvidia python=3.11 rapids=25.06 'cuda-version>=12.0,<=12.8' -y && conda activate decipher
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 | [](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 | [](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 wtih 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
*High-fidelity disentangled cellular embeddings for large-scale heterogeneous spatial omics via DECIPHER* ([biorxiv](https://www.biorxiv.org/content/10.1101/2024.11.29.626126v1) 2024)
> 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/)
Raw data
{
"_id": null,
"home_page": null,
"name": "cell-decipher",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "bioinformatics, transformer, single-cell, spatial-omics, deep-learning",
"author": "Chen-Rui Xia",
"author_email": "xiachenrui@mail.cbi.pku.edu.cn",
"download_url": "https://files.pythonhosted.org/packages/07/91/b82327cb0f54dadd6360f603ce3e9182b479efd345da1d5aeb56a688b5de/cell_decipher-0.2.0.tar.gz",
"platform": null,
"description": "[](https://github.com/gao-lab/DECIPHER/stargazers)\n[](https://pepy.tech/project/cell-decipher)\n[](https://github.com/gao-lab/DECIPHER/actions/workflows/build.yml)\n[](https://cell-decipher.readthedocs.io/en/latest/)\n[](https://opensource.org/licenses/MIT)\n\n\n\n<!-- [](https://codecov.io/gh/gao-lab/DECIPHER) -->\n\n# DECIPHER\n<div align=\"center\">\n\n[Installation](#Installation) \u2022 [Documentation](#Documentation) \u2022 [Citation](#Citation) \u2022 [FAQ](#FAQ) \u2022 [Acknowledgement](#Acknowledgement)\n\n</div>\n\n`DECIPHER` aims to learn cells\u2019 disentangled intracellular molecular identity embedding and extracellular spatial context embedding from spatial omics data.\n\n\n\n## Installation\n\n### PyPI\n\n> [!IMPORTANT]\n> Requires Python >= 3.10 and CUDA-enabled GPU (CPU-only device is not recommended).\n\nWe recommend to install `cell-decipher` to a new conda environment:\n\n```sh\nmamba create -n decipher python==3.11 -c conda-forge -y && conda activate decipher\npip install cell-decipher\ninstall_pyg_dependencies\n```\n\n(Optional) You can install [RAPIDS](https://docs.rapids.ai/install) to accelerate visualization.\n\n```sh\nmamba create -n decipher -c conda-forge -c rapidsai -c nvidia python=3.11 rapids=25.06 'cuda-version>=12.0,<=12.8' -y && conda activate decipher\npip install cell-decipher\ninstall_pyg_dependencies\n```\n\n### Docker\n\nBuild docker image from [Dockerfile](./Dockerfile) or pull image from Docker Hub directly:\n\n```sh\ndocker pull huhansan666666/decipher:latest\ndocker run --gpus all -it --rm huhansan666666/decipher:latest\n```\n\n## Documentation\n\n### Minimal example\nHere is a minimal example for quick start:\n\n```python\nimport scanpy as sc\nfrom decipher import DECIPHER\nfrom decipher.utils import scanpy_viz\n\n# Init model\nmodel = DECIPHER(work_dir='/path/to/work_dir')\n\n# Register data (adata.X is raw counts, adata.obsm['spatial'] is spatial coordinates)\nadata = sc.read_h5ad('/path/to/adata.h5ad')\nmodel.register_data(adata)\n\n# Fit DECIPHER model\nmodel.fit_omics()\n\n# Clustering disentangled embeddings\nadata.obsm['X_center'] = model.center_emb # intracellular molecular embedding\nadata.obsm['X_nbr'] = model.nbr_emb # spatial context embedding\nadata = scanpy_viz(adata, ['center', 'nbr'], rapids=False)\n\n# Plot\nadata.obsm['X_umap'] = adata.obsm['X_umap_center'].copy()\nsc.pl.umap(adata, color=['cell_type'])\nadata.obsm['X_umap'] = adata.obsm['X_umap_nbr'].copy()\nsc.pl.umap(adata, color=['region'])\n```\n\n### Tutorials\n> Please check [**documentation**](https://cell-decipher.readthedocs.io/en/latest) for all tutorials.\n\n| Name | Description | Colab |\n| --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [Basic Model Tutorial](./docs/tutorials/1-train_model.ipynb) | Tutorial on how to use DECIPHER | [](https://colab.research.google.com/drive/14PEtrgqlf-KbLOTfBLc9gbx0YvY6mi0S?usp=sharing) |\n| [Multi-slices with Batch Effects](./docs/tutorials/2-remove_batch.ipynb) | Tutorial on how to apply DECIPHER to multiple slices with batch effects | [](https://colab.research.google.com/drive/1eLJeRDZFq2tlDUWpETlSxVUdzRv9CeSD?usp=sharing) |\n| [Identify Localization-related LRs](./docs/tutorials/3-select_LRs.ipynb) | Tutorial on how to identify ligand-receptors which related wtih cells\u2019 localization based on DECIPHER embeddings | Insufficient resources |\n| [Multi-GPUs Training](./docs/tutorials.md#multi-gpu-training) | Tutorial on how to use DECIPHER with multi-GPUs on spatial atlas | Insufficient resources |\n| [More technologies](./docs/tutorials/4-more_techs.ipynb) | Tutorial on how to use DECIPHER with multiple spatial technologies | Insufficient resources |\n\n## Citation\n\n*High-fidelity disentangled cellular embeddings for large-scale heterogeneous spatial omics via DECIPHER* ([biorxiv](https://www.biorxiv.org/content/10.1101/2024.11.29.626126v1) 2024)\n\n\n> If you want to repeat our benchmarks and case studies, please check the [**benchmark**](./benchmark/) and [**experiments**](./experiments/) folder.\n\n## FAQ\n> Please open a new [github issue](https://github.com/gao-lab/DECIPHER/issues/new/choose) if you meet problem.\n\n1. Visium or ST data\n\nDECIPHER 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.\n\n<!-- 2. `CUDA out of memory` error\n\nThe `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()`. -->\n\n\n## Acknowledgement\nWe thank the following great open-source projects for their help or inspiration:\n\n- [vit-pytorch](https://github.com/lucidrains/vit-pytorch)\n- [lightly](https://github.com/lightly-ai/lightly)\n- [scib](https://github.com/theislab/scib)\n- [rapids_singlecell](https://github.com/scverse/rapids_singlecell/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Spatial-omics data embedding and analysis",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://decipher.readthedocs.io/en/latest/",
"Homepage": "https://github.com/gao-lab/decipher",
"Repository": "https://github.com/gao-lab/decipher"
},
"split_keywords": [
"bioinformatics",
" transformer",
" single-cell",
" spatial-omics",
" deep-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ce4b862493f934a3e7a1e3bd4e698f4d10649bb25b3e6a38e0228515d520590e",
"md5": "52d6b855c307efd345adf902eeeb5c90",
"sha256": "9c0d548c964ed2fb94dc79f70f84612287712cfa31c2cfe66cf8fa525f41a414"
},
"downloads": -1,
"filename": "cell_decipher-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52d6b855c307efd345adf902eeeb5c90",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 51288,
"upload_time": "2025-07-11T08:29:21",
"upload_time_iso_8601": "2025-07-11T08:29:21.560237Z",
"url": "https://files.pythonhosted.org/packages/ce/4b/862493f934a3e7a1e3bd4e698f4d10649bb25b3e6a38e0228515d520590e/cell_decipher-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0791b82327cb0f54dadd6360f603ce3e9182b479efd345da1d5aeb56a688b5de",
"md5": "24f00af5a5f67a792b4a0b88ceefa462",
"sha256": "b4c23b90090c091aa595de54dbc3f5f9ca08ea2e2930e84d5c402e12e32190e0"
},
"downloads": -1,
"filename": "cell_decipher-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "24f00af5a5f67a792b4a0b88ceefa462",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40987,
"upload_time": "2025-07-11T08:29:22",
"upload_time_iso_8601": "2025-07-11T08:29:22.641722Z",
"url": "https://files.pythonhosted.org/packages/07/91/b82327cb0f54dadd6360f603ce3e9182b479efd345da1d5aeb56a688b5de/cell_decipher-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 08:29:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gao-lab",
"github_project": "decipher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cell-decipher"
}
JSON
