adex 0.1.0__tar.gz

adex-0.1.0/ADEX.egg-info/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: ADEX
+Version: 0.1.0
+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`.

adex-0.1.0/ADEX.egg-info/SOURCES.txt

@@ -0,0 +1,74 @@
+README.md
+app.py
+preprocess.py
+pyproject.toml
+ADEX.egg-info/PKG-INFO
+ADEX.egg-info/SOURCES.txt
+ADEX.egg-info/dependency_links.txt
+ADEX.egg-info/entry_points.txt
+ADEX.egg-info/requires.txt
+ADEX.egg-info/top_level.txt
+assets/__init__.py
+assets/css/dbc.min.css
+assets/css/layout.css
+assets/css/markdown.css
+assets/css/sidebar.css
+assets/css/startup_modal.css
+assets/images/AI_lens_black.svg
+assets/images/AI_lens_white.svg
+assets/images/AI_medium_white.svg
+assets/images/aifi-white-logo.png
+assets/images/aifi-white-text.png
+assets/images/aifi_logo.png
+assets/images/screenshot.png
+assets/images/template.png
+assets/markdown/covariate-help.md
+assets/markdown/help_page.md
+assets/markdown/startup_modal.md
+assets/markdown/template_help_page.md
+assets/markdown/template_startup_modal.md
+callbacks/__init__.py
+callbacks/create_deg_callbacks.py
+components/__init__.py
+components/create_deg_components.py
+config/__init__.py
+config/template.json
+config/gmt/c2.all.v2026.1.Hs.json.gz
+config/gmt/h.all.v2026.1.Hs.json.gz
+config/gmt/msigdb-all-pathways.json.gz
+preprocessors/__init__.py
+preprocessors/deseq2.py
+preprocessors/gsea.py
+preprocessors/pseudobulk.py
+src/__init__.py
+src/cli.py
+src/deploy.py
+src/utils.py
+src/version.py
+src/app/__init__.py
+src/app/utils.py
+src/app/version.py
+src/app/components/ConfigSingleton.py
+src/app/components/GenePanel.py
+src/app/components/RadioButtons.py
+src/app/components/StartupModal.py
+src/app/components/__init__.py
+src/app/components/app_header.py
+src/app/components/app_help.py
+src/app/components/app_settings.py
+src/app/components/dropdown.py
+src/app/plots/BoxPlot.py
+src/app/plots/DegSummariesPlot.py
+src/app/plots/HeatmapAIO.py
+src/app/plots/MAPlot.py
+src/app/plots/Volcano.py
+src/app/plots/__init__.py
+src/mediators/GeneSelectionMediator.py
+src/mediators/PathwaySelectionMediator.py
+src/mediators/__init__.py
+src/readers/DegByCovariatesReader.py
+src/readers/Deseq2Readers.py
+src/readers/PseudoBulkLoader.py
+src/readers/__init__.py
+ui/__init__.py
+ui/create_deg_layout.py

adex-0.1.0/ADEX.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

adex-0.1.0/ADEX.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+adex-app = app:main
+adex-preprocess = preprocess:main

adex-0.1.0/ADEX.egg-info/requires.txt

@@ -0,0 +1,8 @@
+dash[compress]==3.1.0
+dash-ag-grid>=35.3.0
+dash-bootstrap-components==2.0.4
+dash-iconify==0.1.2
+jsonschema>=4.26.0
+mygene==3.2.2
+numpy>=2.0.0
+polars>=2.1.0

adex-0.1.0/ADEX.egg-info/top_level.txt

@@ -0,0 +1,9 @@
+app
+assets
+callbacks
+components
+config
+preprocess
+preprocessors
+src
+ui

adex-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: ADEX
+Version: 0.1.0
+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`.

adex-0.1.0/README.md

@@ -0,0 +1,121 @@
+### 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`.

adex-0.1.0/app.py

@@ -0,0 +1,88 @@
+"""
+app.py is a template for Allen Institute members to quickly, 
+efficiently, and uniformly develop Dash apps
+"""
+
+import argparse
+from pathlib import Path
+
+from dash import Dash
+from preprocess import GLOBAL_DELIMITER
+
+import assets
+import src.app as adm
+
+from components.create_deg_components import create_deg_components
+from ui.create_deg_layout import create_deg_layout
+from callbacks.create_deg_callbacks import create_deg_callbacks
+from src.cli import default_config_path
+
+
+STYLESHEETS = [
+    "https://storage.googleapis.com/aifi-static-assets/hise-style.css",
+    "https://cdn.jsdelivr.net/npm/bootstrap@5.3.6/dist/css/bootstrap.min.css",
+    "/assets/css/dbc.min.css",
+    "/assets/css/sidebar.css",
+    "/assets/css/markdown.css",
+    "/assets/css/startup_modal.css",
+    "/assets/css/layout.css",
+]
+
+
+def resolve_packaged_markdown_paths(modules: object, assets_dir: Path) -> None:
+    for markdown_key in ("help_page_content", "startup_modal_content", "covariate_help"):
+        markdown_file = getattr(modules, markdown_key, None)
+        if not isinstance(markdown_file, str) or not markdown_file:
+            continue
+
+        markdown_path = Path(markdown_file)
+        if not markdown_path.is_absolute() and not markdown_path.is_file():
+            packaged_path = assets_dir.parent / markdown_path
+            if packaged_path.is_file():
+                setattr(modules, markdown_key, str(packaged_path))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Run the ADEX dashboard. By default, uses config/template.json "
+            "from the current directory, or the packaged template if absent."
+        )
+    )
+    parser.add_argument("-c", "--config", help="Path to an ADEX-compatible JSON configuration file.")
+    parser.add_argument("-s", "--schema", help="Path to a JSON schema to validate configuration against.")
+    args = parser.parse_args()
+
+    assets_dir = Path(assets.__file__).resolve().parent
+    config = adm.ConfigSingleton(
+        config_file=args.config or str(default_config_path()),
+        schema_file=args.schema,
+    )
+    resolve_packaged_markdown_paths(config.app.modules, assets_dir)
+
+    app = Dash(
+        name=config.app.app_title,
+        external_stylesheets=STYLESHEETS,
+        assets_folder=str(assets_dir),
+        update_title="",
+        compress=True,
+    )
+    app._favicon = "images/AI_lens_black.svg"
+
+    deg_components = create_deg_components(config, delimiter=GLOBAL_DELIMITER)
+    app.layout = create_deg_layout(
+        config,
+        components=deg_components,
+        delimiter=GLOBAL_DELIMITER,
+    )
+    create_deg_callbacks(
+        config,
+        components=deg_components,
+        delimiter=GLOBAL_DELIMITER,
+    )
+
+    app.run(host="0.0.0.0", port=8050, debug=False)
+
+
+if __name__ == "__main__":
+    main()