README.md

metadata

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;
• 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:

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

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. 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; review that repository's license and terms for your intended use.