DISCOtoolkit 1.2.2

DISCOtoolkit is a Python package for accessing the data and tools of the DISCO database (DISCO v1). Read the documentation, with tutorials and the API reference, at disco.bii.a-star.edu.sg/v1/docs/toolkit/guide.

• Filter and download DISCO data based on sample metadata and cell type information
• Gene search: a gene's expression across cell types and tissues
• CELLiD: cell type annotation
• scEnrichment: gene set enrichment using DISCO DEGs

Use DISCO v1. The toolkit is developed and tested against DISCO v1, which is the default, and that is the server we recommend. DISCO v2 has its own R package (DISCOtoolkit). The Python package can be pointed at a v2 server, but that is not tested; see Choosing a server.

Quickstart (Google Colab)

Installs, checks the server, filters, downloads and plots in about ten cells, with nothing to set up locally.

Installation

Python 3.9 or newer. In your current environment:

pip install discotoolkit

To try the latest development version straight from GitHub:

pip install "git+https://github.com/JinmiaoChenLab/DISCOtoolkit_py.git"

To work on the code, or to test changes before they are released, install from a local clone. -e links the install to the folder, so edits take effect without reinstalling:

git clone https://github.com/JinmiaoChenLab/DISCOtoolkit_py.git
cd DISCOtoolkit_py
pip install -e .

pip install discotoolkit and a local install give the same code when the versions match. The difference is the source: PyPI delivers a released, packaged copy, while a local install uses the files in your folder.

Dependencies (installed automatically): numpy, pandas, scanpy, scipy, joblib, pandarallel, requests, colorcet, leidenalg, h5py, matplotlib, seaborn.

We recommend a virtual environment, for example with miniconda:

conda create --name disco python=3.10
conda activate disco
conda install ipykernel
python -m ipykernel install --user --name disco --display-name "disco"
python -m pip install -U discotoolkit

Choosing a server

import discotoolkit as dt

dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1, the default)
dt.set_server("v2")                   # DISCO v2 (not tested; DISCO v1 is the supported server)
dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API

or set the DISCO_API_URL environment variable before importing the package.

Testing

Two small test files need nothing beyond requests, so they run anywhere, including Colab:

python tests/test_settings.py           # offline: server selection logic
python tests/test_version.py            # offline: setup.py and __init__.py agree on the version
python tests/test_docs.py               # offline: notebooks are clean, every public function is in the API reference
python tests/test_server_contract.py    # online: does the server answer everything the toolkit needs?
python tests/test_server_contract.py <api root>   # check another server

GitHub Actions runs these, and installs the package on Python 3.9-3.12, on every push. Maintainers: see RELEASING.md for how a release, and its documentation, is published.

test_server_contract.py checks status codes and the shape of each response (the columns and file types the toolkit reads). It only samples the large reference files, it does not download them.

Basic Usage

Example in Jupyter notebook.

please select disco as the kernel for running the jupyter notebook

Quickstart for DISCO v1

Filter and download DISCO data

Cell Type Annotation using CELLiD

scEnrichment

Citation

1. Li, Mengwei, et al. "DISCO: a database of Deeply Integrated human Single-Cell Omics data." Nucleic acids research 50.D1 (2022): D596-D602.
2. Mengwei Li, Kok Siong Ang, Brian Teo, Uddamvathanak Rom, Minh N Nguyen, Sebastian Maurer-Stroh, Jinmiao Chen. "Rediscovering publicly available single-cell data with the DISCO platform." Nucleic Acids Research (2024): gkae1108

Follow us on our social media!

• HSCRM2
• JinmiaoChenLab Github repo