README.md

---
title: BioLM-NET Workbench
emoji: 🧬
colorFrom: green
colorTo: yellow
sdk: gradio
app_file: app.py
python_version: "3.12"
suggested_hardware: zero-a10g
license: cc-by-nc-4.0
pinned: false
---

# BioLM-NET Workbench

BioLM-NET Workbench is a guided Hugging Face Spaces interface for assembling,
training, exporting, and applying the interpretable dual-omics architecture
described by Rifat et al.

The interface supports:

- the BRCA, COAD, GBM, and scTrioseq2 datasets from
  [`bozdaglab/BioLM-NET`](https://github.com/bozdaglab/BioLM-NET);
- a GitHub dataset folder containing the standard BioLM-NET filenames;
- user uploads for paired gene-expression and DNA-methylation matrices, labels,
  and gene-to-pathway mappings;
- automatic retrieval of the upstream `PDI.csv` and `PPI.csv`, with optional
  custom overrides;
- paper-defined trainable biological masking (`W_masked = W ⊙ M`);
- GenePT-guided, membership-masked pathway attention;
- on-demand ZeroGPU allocation only while model training runs;
- stratified validation, balanced loss, downloadable model artifacts, and a
  separate prediction workflow.

## Data contract

Samples are rows. Omics features are columns named with HGNC gene symbols.
Paired omics files and the label file must have the same row order and count.

| File | Required columns / orientation |
| --- | --- |
| `Gene_Expression.csv` | samples × gene-symbol columns |
| `DNA_Methylation.csv` | samples × gene-symbol columns |
| `label.csv` | exactly one label column |
| `PDI.csv` | `TF`, `Target` |
| `PPI.csv` | `protein1`, `protein2`, `combined_score` |
| gene/pathway mapping | `SYMBOL`, `PathwayID` |

For a GitHub folder, the app expects:

```text
Gene_Expression.csv
DNA_Methylation.csv
label.csv
ge_target_to_KEGG_significant.csv
dna_target_to_KEGG_significant.csv
```

If pathway files are already the significant results of an enrichment analysis,
leave the checkbox enabled. For a complete gene/pathway annotation catalog,
disable it; the app will run over-representation testing and retain pathways
with Benjamini-Hochberg adjusted p-value below 0.05.

## Architecture choices

The implementation follows the paper's mathematical description:

1. PDI edges are binary TF-to-target connections.
2. STRING PPI scores are normalized, filtered above 0.7, and restricted to the
   top score decile. Because PPI is undirected, an input gene can connect to its
   partner from either endpoint.
3. The PDI/PPI matrix masks the trainable first-layer weights directly.
4. Only hidden genes represented by the selected GenePT file are retained.
5. Gene-to-pathway attention scores are masked to actual memberships before the
   softmax; nonmember genes cannot receive pathway attention.
6. Gene-expression and DNA-methylation pathway projections are fused for
   multiclass prediction.

Training scalers are fit only on the training partition and are included in the
exported artifact. Model tensors use `safetensors`; the artifact loader reads
only the four expected files and does not unpickle user content.

## Run locally

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-local.txt
python app.py
```

For local development, install `requirements-local.txt` instead. Hugging Face's
Gradio runtime supplies the platform-managed `spaces` package automatically;
the local requirements file installs its no-op implementation so the same app
also runs on CPU or a conventional GPU.

## Deploy to Hugging Face

Create a Gradio Space, push every file in this folder to the Space repository,
and select **ZeroGPU** in **Settings → Hardware**. The Space runtime installs
`requirements.txt` and starts `app.py`. The training callback uses a dynamic
30–300 second reservation based on dataset size, biological graph size, batch
size, and epochs. Data preparation and prediction remain on CPU and do not
consume GPU quota.

ZeroGPU users have tier-specific daily quotas and may queue during busy periods.
The epoch control is capped at 200 so paper-scale runs can fit within a single
free-tier reservation when the workload permits. If a cohort cannot finish in
five minutes, reduce the epochs or switch the Space to dedicated hardware.

## Scientific and licensing note

This is research software, not a clinical decision system. Users remain
responsible for cohort design, preprocessing, leakage checks, external
validation, and interpretation.

BioLM-NET source and datasets are provided by the Bozdag Lab under
[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/). Cite:

> Rifat, J. I. M. et al. “BioLM-NET: an interpretable deep learning model
> combining prior biological knowledge and contextual LLM gene embeddings on
> multi-omics data to predict disease.” *Pacific Symposium on Biocomputing
> 2026* (2025).

GenePT embeddings are retrieved from
[`honicky/genept-composable-embeddings`](https://huggingface.co/honicky/genept-composable-embeddings);
review that repository's license and terms for your intended use.