[](https://github.com/gao-lab/DECIPHER/stargazers)
[](https://github.com/gao-lab/DECIPHER/actions/workflows/build.yml)
[](https://github.com/psf/black)
[](https://opensource.org/licenses/MIT)
# 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 with [RAPIDS](https://docs.rapids.ai/install) dependencies.
```sh
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](./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 |
## Citation
In coming.
> 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": "https://github.com/gao-lab/decipher",
"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/98/c2/61c6121d53c6c400a332c73014203f8ef43d5430e75588bc9f8a425d3a1c/cell_decipher-0.1.1.tar.gz",
"platform": null,
"description": "[](https://github.com/gao-lab/DECIPHER/stargazers)\n[](https://github.com/gao-lab/DECIPHER/actions/workflows/build.yml)\n[](https://github.com/psf/black)\n[](https://opensource.org/licenses/MIT)\n\n\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 with [RAPIDS](https://docs.rapids.ai/install) dependencies.\n\n```sh\nmamba 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\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\n\n## Citation\nIn coming.\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.1.1",
"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": "",
"digests": {
"blake2b_256": "3c82cca49d2c6137993679908a366f266d1730a18a6d385dd433c7cd8ab54850",
"md5": "c76385abfe8629fad503dd7a47de4b13",
"sha256": "baebb68146a3df0fd14363c2984fa7a9dc42d7199744ad66e14f00d5dd3555f3"
},
"downloads": -1,
"filename": "cell_decipher-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c76385abfe8629fad503dd7a47de4b13",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 56236,
"upload_time": "2024-12-20T05:51:32",
"upload_time_iso_8601": "2024-12-20T05:51:32.595919Z",
"url": "https://files.pythonhosted.org/packages/3c/82/cca49d2c6137993679908a366f266d1730a18a6d385dd433c7cd8ab54850/cell_decipher-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "98c261c6121d53c6c400a332c73014203f8ef43d5430e75588bc9f8a425d3a1c",
"md5": "24b8ee18c00751dba74b92f3d17b9e4a",
"sha256": "b2198f65f5f0b9d98803e6e8258cc8af9880f17e7ed208521cd05471b79d675d"
},
"downloads": -1,
"filename": "cell_decipher-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "24b8ee18c00751dba74b92f3d17b9e4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 45735,
"upload_time": "2024-12-20T05:51:35",
"upload_time_iso_8601": "2024-12-20T05:51:35.228059Z",
"url": "https://files.pythonhosted.org/packages/98/c2/61c6121d53c6c400a332c73014203f8ef43d5430e75588bc9f8a425d3a1c/cell_decipher-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 05:51:35",
"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
