ADEX 0.1.0

sc-deg-explorer

A Plotly Dash web application for interactively exploring Differentially Expressed Genes (DEGs) from single-cell RNA sequencing experiments. Its reusable Dash components and plots are included in the ADEX package, which provides a configurable, dataset-agnostic interface that can be pointed at new datasets simply by swapping a JSON configuration file — no code changes required.

Table of Contents

1. Purpose
2. Expected inputs
3. Example output
4. Usage
5. Configuration

Purpose

sc-deg-explorer is designed to make DEG results from single-cell pseudobulk analyses immediately accessible to wet-lab and computational scientists alike. After running a DESeq2-based differential expression pipeline, users can point this app at the output files and interactively:

• Explore DEGs through interactive volcano plots, MA plots, and per-covariate DEG views.
• Investigate gene expression for any selected gene using pseudo-bulk box plots stratified by donor, condition, or cell type.
• Analyze pathway enrichment results via GSEA volcano plots and pathway selection dropdowns.
• Filter by cell type and experimental covariates (e.g., day, treatment, cytokine) using sidebar dropdowns that dynamically update all plots.
• Browse gene panels to quickly navigate to genes of interest.

The app is designed to be deployed as an internal data portal, enabling research teams to rapidly iterate on hypotheses without writing additional analysis code.

Expected inputs

The major inputs to the program are:

Note on input data format: The overall intention of the input data format is to use a set of columns to specify important combinations of independent variables, which will demarcate several DE tests into one file. These covariate columns must be present and match across every input data type.

Note on specifying covariates: While there are instructions in the config file, this small piece of information is important to get right: the order of covariates written in the config file matters. The first covariate should reflect the group that appears on the right side of a volcano plot, and the second covariate is the left side of a volcano plot. Additional covariates can be specified without further constraints.

Expected output files

The pipeline produces Parquet files that are scanned, selected, filtered, and collected to be served to the user's front-end.

results/
├── deg
│   ├── adjp.parquet
│   ├── deg.parquet
│   ├── log2fc.parquet
│   ├── means.parquet
│   ├── meta.parquet
│   ├── summaries.parquet
│   ├── t-adjp.parquet
│   └── t-log2fc.parquet
└── gsea
    ├── results.parquet
    ├── meta.parquet
    ├── summaries.parquet
    ...

Usage

Install ADEX with pip (Python 3.13 or newer), then run the commands from the directory containing your project configuration and input data:

# Install ADEX
python -m pip install git+https://github.com/aifimmunology/sc-deg-explorer.git

# Prepare config/template.json with project-specific settings and data paths.

# Preprocess differential results
adex-preprocess --config config/template.json

# Start the dashboard
adex-app --config config/template.json

For development from a source checkout, install the Pixi environment with pixi install --frozen, then run:

pixi run python preprocess.py --config config/template.json
pixi run python app.py --config config/template.json

Example Output

The following screenshot is an example of a working app. After starting the app, it can be accessed via the following URL: http://0.0.0.0:8050/

Test build with Docker

Local builds with Docker can be helpful before deploying to a remote server for production.

docker build --platform=linux/arm64/v8 -t rheumatoid-arthritis . # 'rheumatoid-arthritis' can be any string
docker run -p 8050:8050 rheumatoid-arthritis

The app will be available at http://localhost:8050.