---
title: EPGFRE
emoji: 🧬
colorFrom: green
colorTo: red
sdk: gradio
sdk_version: 6.18.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
short_description: E. coli Pan‑Genome Fluoroquinolone (FQ) Resistance Explorer.

---

---
title: E. coli Fluoroquinolone Resistance Explorer
emoji: 
colorFrom: teal
colorTo: navy
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit

---

# 🧬 E. coli Pan‑Genome Fluoroquinolone (FQ) Resistance Explorer

**An open‑source machine learning pipeline for predicting fluoroquinolone resistance from pan‑genome presence/absence profiles.**

[![Open in Hugging Face](https://img.shields.io/badge/🤗-Open%20in%20Hugging%20Face-blue)](https://huggingface.co/spaces/your-username/your-space-name)

---

##  Overview

A **random forest classifier** trained on binary presence/absence of **11,208** pan‑genome gene families from **2,715** *E. coli* genomes, with curated fluoroquinolone antibiograms from the Bacterial and Viral Bioinformatics Resource Center (BV‑BRC).

The model achieves **AUC 0.914 ± 0.014** under five‑fold stratified cross‑validation, confirmed non‑random by a leakage‑corrected permutation test (**p = 0.001**, 1000 shuffles).

---

##  Key Results

| Metric | Value |
|--------|-------|
| **5‑fold CV AUC** | **0.914 ± 0.014** |
| **Permutation test p‑value** | **0.001** (1000 shuffles) |
| **Feature space** | **11,208** PGFam gene families |
| **Training genomes** | **2,715** *E. coli* |
| **Multi‑drug generalisation** | Median AUC **0.91** (37 drugs, range 0.634–0.996) |
| **Temporal holdout** | AUC **0.757** (≤2017 train, ≥2019 test) |
| **10‑gene clinical panel** | AUC **0.684** (Sens 0.726, Spec 0.601) |

### Key findings

- The pan‑genome model outperforms a curated eight‑gene resistance‑marker baseline by **0.12 AUC points** (0.914 vs. 0.796).
- Top predictive features are **exclusively plasmid‑borne mobile genetic elements** (PemI/PemK toxin–antitoxin, IntI1 integrase, BlaTEM, BlaCTX‑M, Mph(A)) – **no direct fluoroquinolone resistance genes** (`gyrA`/`parC`/`qnr`) appear among the top predictors.
- The same feature matrix, retrained independently per antibiotic, generalises to **37 additional drug classes** (median AUC 0.91), supporting the **plasmid‑burden** interpretation.

---

##  How to Use

### Predict tab (real model)
1. **Upload a CSV** containing binary presence/absence (0/1) for the 11,208 gene families the model expects.
2. **Click "Run prediction"** to get a resistance probability, classification, and visualisations.
3. **Interpret the results** – the model returns:
   - **Resistance probability** (0–100%)
   - **Binary classification** (RESISTANT / SUSCEPTIBLE) at default 50% threshold
   - **Feature coverage** – percentage of expected gene families found in your file
   - **Driving genes** – bar chart of the most influential genes in your sample
   - **Population context** – where your sample falls relative to the training cohort

### Explore tab (teaching sandbox)
- Toggle the 10 SHAP‑selected marker genes on/off to see how each one shifts the prediction.
- This panel alone reaches AUC **0.684** on held‑out genomes – well below the full model – and exists to build intuition, not to diagnose a real genome.

---

##  File Requirements

For the **Predict** tab to work, place these two files in the same directory as `app.py`:

- **`model.joblib`** – the trained Random Forest model
- **`gene_features_list.pkl`** – the list of 11,208 PGFam feature names (in the exact order used during training)

If these files are missing, the Predict tab will show a clear error message rather than silently falling back to a weaker model.

---

##  Citation

If you use this tool in your research, please cite the accompanying paper:

> *[Your paper title].* [Journal/Conference], [Year]. DOI: [10.xxxx/xxxxx]

---

## License

MIT © Zaeem Ahmad Mansoori

---

## Acknowledgements

- **BV‑BRC** for genome annotations and antibiogram data
- **Zenodo** for the curated antibiogram dataset (record 15809334)

---

##  Disclaimer

This tool is a **research prototype**. It is not a clinical diagnostic, not a substitute for phenotypic susceptibility testing, and not validated outside the 2,715‑genome training cohort. Always confirm clinically relevant calls with laboratory methods.

---

**Deployment instructions** (for your own Hugging Face Space):

1. Upload `app.py`, `requirements.txt`, `model.joblib`, and `gene_features_list.pkl` to your Space.
2. Set SDK to **Gradio**.
3. Commit and wait for the build to complete.

---

*Built with ❤️ using Gradio, scikit‑learn, and BV‑BRC data.*


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference