README.md

metadata

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.

---

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