OmicsML/dance

DANCE is a Python toolkit to support deep learning models for analyzing single-cell gene expression at scale. Our goal is to build up a deep learning community and benchmark platform for computational models in single-cell analysis. It includes three modules at present:

1. Single-modality analysis
2. Single-cell multimodal omics
3. Spatially resolved transcriptomics

Useful links

OmicsML Homepage: https://omicsml.ai
DANCE Open Source: https://github.com/OmicsML/dance
DANCE Documentation: https://pydance.readthedocs.io/en/latest/
DANCE Package Paper: https://www.biorxiv.org/content/10.1101/2022.10.19.512741v2
Survey Paper: https://arxiv.org/abs/2210.12385

Join the Community

Slack: https://join.slack.com/t/omicsml/shared_invite/zt-1hxdz7op3-E5K~EwWF1xDvhGZFrB9AbA
Twitter: https://twitter.com/OmicsML
Wechat Group Assistant: 736180290
Email: [email protected]

Contributing

Community-wide contribution is the key for a sustainable development and continual growth of the DANCE package. We deeply appreciate any contribution made to improve the DANCE code base. If you would like to get started, please refer to our brief guidelines about our automated quality controls, as well as setting up the dev environments.

Citation

If you find our work useful in your research, please consider citing our DANCE package or survey paper:

@article{ding2022dance,
  title={DANCE: A Deep Learning Library and Benchmark for Single-Cell Analysis},
  author={Ding, Jiayuan and Wen, Hongzhi and Tang, Wenzhuo and Liu, Renming and Li, Zhaoheng and Venegas, Julian and Su, Runze and Molho, Dylan and Jin, Wei and Zuo, Wangyang and others},
  journal={bioRxiv},
  year={2022},
  publisher={Cold Spring Harbor Laboratory}
}

@article{molho2022deep,
  title={Deep Learning in Single-Cell Analysis},
  author={Molho, Dylan and Ding, Jiayuan and Li, Zhaoheng and Wen, Hongzhi and Tang, Wenzhuo and Wang, Yixin and Venegas, Julian and Jin, Wei and Liu, Renming and Su, Runze and others},
  journal={arXiv preprint arXiv:2210.12385},
  year={2022}
}

Usage

Overview

In release 1.0, the main usage of the DANCE is to provide readily available experiment reproduction (see detail information about the reproduced performance below). Users can easily reproduce selected experiments presented in the original papers for the computational single-cell methods implemented in DANCE, which can be found under examples/.

Motivation

Computational methods for single-cell analysis are quickly emerging, and the field is revolutionizing the usage of single-cell data to gain biological insights. A key challenge to continually developing computational single-cell methods that achieve new state-of-the-art performance is reproducing previous benchmarks. More specifically, different studies prepare their datasets and perform evaluation differently, and not to mention the compatibility of different methods, as they could be written in different languages or using incompatible library versions.

DANCE addresses these challenges by providing a unified Python package implementing many popular computational single-cell methods (see Implemented Algorithms), as well as easily reproducible experiments by providing unified tools for

• Data downloading
• Data (pre-)processing and transformation (e.g. graph construction)
• Model training and evaluation

Example: run cell-type annotation benchmark using scDeepSort

• Step0. Install DANCE (see Installation)
• Step1. Navigate to the folder containing the corresponding example scrtip. In this case, it is examples/single_modality/cell_type_annotation.
• Step2. Obtain command line interface (CLI) options for a particular experiment to reproduce at the end of the script. For example, the CLI options for reproducing the Mouse Brain experiment is

  python scdeepsort.py --species mouse --tissue Brain --train_dataset 753 3285 --test_dataset 2695

• Step3. Wait for the experiment to finish and check results.

Installation

Quick install

The full installation process might be a bit tedious and could involve some debugging when using CUDA enabled packages. Thus, we provide an install.sh script that simplifies the installation process, assuming the user have conda set up on their machines. The installation script creates a conda environment dance and install the DANCE package along with all its dependencies with a apseicifc CUDA version. Currently, two options are accepted: cpu and cu117. For example, to install the DANCE package using CUDA11.7 in a dance-env conda environment, simply run:

# Clone the repository via SSH
git clone [email protected]:OmicsML/dance.git && cd dance
# Alternatively, use HTTPS if you have not set up SSH
# git clone https://github.com/OmicsML/dance.git  && cd dance

# Run the auto installation script to install DANCE and its dependencies in a conda environment
source install.sh cu117 dance-env

Note: the first argument for cuda version is mandatory, while the second argument for conda environment name is optional (default is dance).

conda create -n dance python=3.8 -y && conda activate dance-dev

conda install pytorch=2.0.0 torchvision torchaudio pytorch-cuda=11.7 -c pytorch -c nvidia -y
conda install pyg=2.3.0 -c pyg -y
conda install dgl=1.0.1 -c dglteam/label/cu117 -y

conda install pytorch=2.0.0 torchvision torchaudio cpuonly -c pytorch -y
conda install pyg=2.3.0 -c pyg -y
conda install dgl -c dglteam -y

pip install pydance

git clone https://github.com/OmicsML/dance.git
cd dance
pip install -e .

Implemented Algorithms

P1 not covered in the first release

Single Modality Module

1）Imputation

Note: scGNN2.0 is evaluated on 2,000 genes with highest variance following the original paper.

2）Cell Type Annotation

3）Clustering

Multimodality Module

1）Modality Prediction

2) Modality Matching

3) Joint Embedding

4) Multimodal Imputation

5) Multimodal Integration

Spatial Module

1）Spatial Domain

2）Cell Type Deconvolution