Metadata-Version: 2.4
Name: ADEX
Version: 0.1.3
Summary: Allen Differential results EXplorer
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
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
Dynamic: license-file

# ADEX: Allen Differential results EXplorer

[![PyPI version](https://img.shields.io/pypi/v/ADEX)](https://pypi.org/project/ADEX/)
[![License](https://img.shields.io/badge/License-Allen%20Institute%20Software%20License-blue)](LICENSE)
[![Maintainer](https://img.shields.io/badge/Maintainer-gartician-blue)](https://github.com/gartician)

ADEX allows life scientists to interactively and efficiently explore large volumes of differential features (genes, peaks, etc.) with minimal coding experience. Given the results of one or (more often) several differential tests and a configuration file, ADEX enable users to:

- **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.

ADEX was built upon [Python](https://www.python.org/) and [Dash](https://dash.plotly.com/), and installation is conveniently facilitated by tools like [pip](https://pypi.org/project/pip/) and [uv](https://docs.astral.sh/uv/). The package itself is hosted by [PyPI](https://pypi.org/project/ADEX). A complete documentation site with examples and user guide is available here: https://www.google.com

---

## Data input

Prepare a project folder containing your configuration file and input data. The example project in [`input-data-examples/deseq2-sound-life-wb-rna-seq`](input-data-examples/deseq2-sound-life-wb-rna-seq) includes a configuration and differential-results file that you can use as a guide.

### 1. Project configuration file [required]

Start with [config/template.json](config/template.json) and save a project-specific copy. You can edit JSON in a text editor; no Python programming is needed. In the copy:

- Set `app_title` to the title you want displayed in the dashboard.
- Under `adex.experiment`, list the names of the experimental variables (covariates) in `covariates`. Each name must match a column in your input file exactly. Set `default_features` to values that occur in those columns, and `default_gene` to a gene or feature in your data.
- Under `adex.preprocess.differential`, set `file` to your differential-results file and update the four `columns` values to the exact headers used for the feature/gene, adjusted p-value, log fold change, and mean-expression columns.
- Choose `adjp_cutoff` for the adjusted p-value threshold used to summarize significant results.

File paths are read from the directory where you run the commands below. Use paths relative to that directory, or provide absolute paths. The configuration template has example values; replace them with values and paths from your own study.

> [!IMPORTANT]
> **Covariate order matters:** the first covariate is the right-hand group in a volcano plot and the second is the left-hand group. Include any other variables, such as cell type, contrast, or analysis method, after those. Covariate names and values must be consistent across differential and GSEA input files.

### Modified differential results file [required]

Provide one comma-separated results file (`.csv` or `.csv.gz`) containing the results for all comparisons you want to explore. It should have one row per tested feature and comparison, with:

- A feature or gene identifier column.
- Adjusted p-value, log fold change, and mean-expression columns.
- One column for each covariate named in `experiment.covariates`. These columns identify the comparison or experimental condition for each row.

The following gives an example for a perturbation experiment where whole blood samples were treated with LPS, PolyIC, SEB, and control treatment followed by RNA-Seq and differential results derived from DESeq2 ([example file](https://github.com/aifimmunology/adex/blob/development/input-data-examples/deseq2-sound-life-wb-rna-seq/deseq2-sound-life-wb-rna-seq-all-differential-results.csv.gz)).

| gene | baseMean | log2FoldChange | padj | **contrast** | **group1** | **group2** |
|---|---:|---:|---:|---|---|---|
| TSPAN6 | 8.336 | -0.155 | 0.477 | **geo.stimulation** | **LPS** | **Null** |
| DPM1 | 173.349 | 0.065 | 0.0447 | **geo.stimulation** | **LPS** | **Null** |
| SCYL3 | 85.631 | 0.308 | 3.72e-12 | **geo.stimulation** | **PolyIC** | **Null** |
| C1orf112 | 13.995 | -0.071 | 0.593 | **geo.stimulation** | **PolyIC** | **Null** |
| FGR | 3168.258 | 1.545 | 1.03e-265 | **geo.stimulation** | **PolyIC** | **Null** |
...

In your project configuration, set `adex.preprocess.differential.columns` to the exact column headers in your file. For the example table above, the section looks like this:

```json
"columns": {
  "gene_col": "gene",
  "padj_col": "padj",
  "lfc_col": "log2FoldChange",
  "mean_col": "baseMean"
}
```

The keys on the left are ADEX settings; the values on the right must match the corresponding input-file headers, including capitalization. The covariate names (`contrast`, `group1`, and `group2` in this example) are configured separately in `adex.experiment.covariates`.



```json
"adex": {
  "experiment": {
    "covariates": ["group1", "group2", "contrast"]
  }
}
```

### GSEA results [optional]

To show pathway-enrichment results, provide a tab-separated file (`.tsv` or `.tsv.gz`) with adjusted p-value, normalized enrichment score (NES), pathway name, source, and leading-edge genes, plus the same covariate columns used for the differential results. In `adex.preprocess`, add an `enrichment` section and set each configured column name to the matching header in your file. Also set `file` to the enrichment results file, `gmt` to a pathway-gene-set file in JSON format, and choose `adjp_cutoff` and `nes_cutoff`. The repository includes an example enrichment configuration in [`config/rheumatoid-arthritis-phase2.json`](config/rheumatoid-arthritis-phase2.json) and pathway files under [`config/gmt`](config/gmt). See [the enrichment input format guide](docs/data_input_format/enrichment.md).

If you do not have enrichment results, leave out the `enrichment` section; differential-results exploration does not require it. When enrichment is configured, preprocessing adds the generated enrichment file locations to your project configuration.

---

## Data output

By default, preprocessing creates Parquet files in a `.adex` folder in the current directory. For differential results, the paths in `adex.data.differential.files` control both where preprocessing writes and where the dashboard reads. You can change these folders and filenames; missing parent folders are created automatically. The additional `deg.parquet` file defaults to `.adex/deg/deg.parquet`; add a `deg` path in the same section to relocate it. You do not need to edit the generated files.

```
.adex/
├── deg/
│   ├── adjp.parquet
│   ├── deg.parquet
│   ├── log2fc.parquet
│   ├── means.parquet
│   ├── meta.parquet
│   ├── summaries.parquet
│   ├── t-adjp.parquet
│   └── t-log2fc.parquet
└── gsea/                 # created only when GSEA is configured
    ├── results.parquet
    ├── meta.parquet
    └── summaries.parquet
```

---

## Usage

You need Python 3.13 or newer. Open a terminal in your project folder (the folder containing your project config), then install ADEX:

```bash
python -m pip install ADEX
```

Replace `config/my-study.json` below with the path to your edited configuration file. Run preprocessing once after preparing or changing your input files or config:

```bash
adex-preprocess --config config/my-study.json
```

After preprocessing finishes, start the dashboard in the same project folder:

```bash
adex-app --config config/my-study.json
```

Open [http://localhost:8050](http://localhost:8050) in your web browser. Keep the terminal running while you use the dashboard; press `Ctrl+C` there to stop it. If port 8050 is already in use, stop the other application using it before starting ADEX.

---

## Example screenshot

![IL6 Screenshot](assets/images/screenshot.png)

---

## Docker

The repository includes a Dockerfile as a starting point for container-based development or deployment. A study-specific container must have your configuration, input data, and preprocessed `.adex` files available, and must start the app with your configuration. For an initial local setup, use the steps in [Usage](#usage); the Docker image is not preconfigured with your study data.
