Metadata-Version: 2.4
Name: ADEX
Version: 0.1.1
Summary: Allen Differential results EXplorer
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: dash[compress]==3.1.0
Requires-Dist: dash-ag-grid>=35.3.0
Requires-Dist: dash-bootstrap-components==2.0.4
Requires-Dist: dash-iconify==0.1.2
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: mygene==3.2.2
Requires-Dist: numpy>=2.0.0
Requires-Dist: polars>=2.1.0

### sc-deg-explorer

A [Plotly Dash](https://dash.plotly.com/) 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](#purpose)
2. [Expected inputs](#expected-inputs)
3. [Example output](#example-output)
3. [Usage](#usage)
4. [Configuration](#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:

<details open>
<summary><strong>1. [Required]: Configuration file</strong></summary>
Manually fill the configuration file <strong>config/template.json</strong> with project-specific details.
</details>

<details open>
<summary><strong>2. [Required]: Differential results from tools like DESeq2</strong></summary>
An example dataset can be found in the file <strong>input-data-examples/deseq2.xlsx</strong>. Make sure to format the data in csv.gz.
</details>

<details>
<summary><strong>3. [Optional]: Enrichment results from GSEA</strong></summary>
An example dataset can be found in the file <strong>input-data-examples/fGSEA.xlsx</strong>. Make sure to format the data in tsv.gz.
</details>

> <u>Note on input data format</u>: 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.

> <u>Note on specifying covariates</u>: 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:

```bash
# 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:

```bash
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/`

![MA Plot](assets/images/screenshot.png)

---

### Test build with Docker
Local builds with Docker can be helpful before deploying to a remote server for production.
```bash
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`.
