Upload MODEL_CARD.md with huggingface_hub
Browse files- MODEL_CARD.md +106 -0
MODEL_CARD.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: apache-2.0
|
| 3 |
+
library_name: pytorch
|
| 4 |
+
language:
|
| 5 |
+
- en
|
| 6 |
+
tags:
|
| 7 |
+
- protein-pocket-detection
|
| 8 |
+
- esm2
|
| 9 |
+
- binding-site-prediction
|
| 10 |
+
---
|
| 11 |
+
|
| 12 |
+
# PockNet – Selective SWA Epoch09_12
|
| 13 |
+
|
| 14 |
+
## Model Summary
|
| 15 |
+
|
| 16 |
+
- **Architecture:** Fusion transformer combining tabular SAS descriptors with ESM2-3B residue embeddings
|
| 17 |
+
- **Checkpoint:** `selective_swa_epoch09_12.ckpt` (SWA blend of epoch 09 baseline and epoch 12 finetune)
|
| 18 |
+
- **Input:** H5 files generated via `generate_h5_v2_optimized.py` (contains tabular + ESM tensors)
|
| 19 |
+
- **Output:** Residue-wise ligandability probabilities + pocket clusters (P2Rank-style CSV/visualisations)
|
| 20 |
+
- **Tasks:** Protein binding-pocket detection / ligandability ranking
|
| 21 |
+
|
| 22 |
+
## Intended Use & Limitations
|
| 23 |
+
|
| 24 |
+
| Intended Use | Notes |
|
| 25 |
+
|--------------|-------|
|
| 26 |
+
| Structure-based binding-pocket detection for academic or non-commercial research | Designed to reproduce and extend P2Rank experiments using BU48 and related datasets |
|
| 27 |
+
| Evaluation via the provided `auto-run` / `predict-dataset` orchestration | Ensures calibration, clustering, and reporting match the release scripts |
|
| 28 |
+
|
| 29 |
+
**Limitations**
|
| 30 |
+
- Trained on BU48-style protein chains with solvent-accessible surface sampling; transfer to radically different proteins is unverified.
|
| 31 |
+
- Requires pretrained ESM2-3B embeddings; ensure consistent preprocessing (chain-level `.pt` files) for best results.
|
| 32 |
+
|
| 33 |
+
## Training Data & Procedure
|
| 34 |
+
|
| 35 |
+
- **Datasets:** BU48 plus auxiliary P2Rank-style splits encoded via `.ds` manifests.
|
| 36 |
+
- **Features:** Generated using `src/datagen/extract_protein_features.py` and merged with chain-fixed CSVs.
|
| 37 |
+
- **Embeddings:** `generate_esm2_embeddings.py` (ESM2_t36_3B_UR50D) per chain.
|
| 38 |
+
- **H5 assembly:** `generate_h5_v2_optimized.py` storing tabular features, embeddings, neighbour tensors, and split labels.
|
| 39 |
+
- **Training:** `python src/train.py experiment=fusion_transformer_aggressive_oct17 ...`
|
| 40 |
+
- **Checkpoint selection:** SWA blend (50/50) between epoch 09 baseline and epoch 12 finetune, validated on held-out BU48.
|
| 41 |
+
|
| 42 |
+
## Metrics
|
| 43 |
+
|
| 44 |
+
| Metric | Value | Notes |
|
| 45 |
+
|--------|-------|-------|
|
| 46 |
+
| Validation AUPRC | ~0.31 | On BU48 validation split |
|
| 47 |
+
| Test AUPRC | ~0.445 | Single-seed evaluation on BU48 test split |
|
| 48 |
+
| DCA Success@1 | 75% | From P2Rank-like DBSCAN analysis |
|
| 49 |
+
| DCC Success@1 | 39% | From P2Rank-like DBSCAN analysis |
|
| 50 |
+
|
| 51 |
+
Refer to `outputs/pocknet_eval_run*/summary/summary.csv` for the exact values produced by the release pipeline.
|
| 52 |
+
|
| 53 |
+
## How to Use
|
| 54 |
+
|
| 55 |
+
### 1. Download with `huggingface_hub`
|
| 56 |
+
```python
|
| 57 |
+
from huggingface_hub import hf_hub_download
|
| 58 |
+
ckpt_path = hf_hub_download("lal3lu03/PockNet", "selective_swa_epoch09_12.ckpt")
|
| 59 |
+
print(ckpt_path) # local file path
|
| 60 |
+
```
|
| 61 |
+
|
| 62 |
+
### 2. Run the end-to-end pipeline (Docker / local)
|
| 63 |
+
```bash
|
| 64 |
+
python src/scripts/end_to_end_pipeline.py auto-run data/bu48.ds \
|
| 65 |
+
--checkpoint /path/to/selective_swa_epoch09_12.ckpt \
|
| 66 |
+
--output outputs/bu48_release
|
| 67 |
+
```
|
| 68 |
+
|
| 69 |
+
The command creates all intermediate artefacts (`features/`, `embeddings/`, `h5/`) and writes pockets + metrics under `<output>/predictions`.
|
| 70 |
+
|
| 71 |
+
### 3. Direct dataset inference
|
| 72 |
+
If you already have an H5 + vectors CSV:
|
| 73 |
+
```bash
|
| 74 |
+
python src/scripts/end_to_end_pipeline.py predict-dataset \
|
| 75 |
+
--checkpoint /path/to/selective_swa_epoch09_12.ckpt \
|
| 76 |
+
--h5 data/h5/all_train_transformer_v2_optimized.h5 \
|
| 77 |
+
--csv data/vectorsTrain_all_chainfix.csv \
|
| 78 |
+
--output outputs/pocknet_eval_cli
|
| 79 |
+
```
|
| 80 |
+
|
| 81 |
+
## Files Included in the Hugging Face Repo
|
| 82 |
+
|
| 83 |
+
- `selective_swa_epoch09_12.ckpt` – release checkpoint
|
| 84 |
+
- `MODEL_CARD.md` – this document
|
| 85 |
+
- (Optional) auxiliary scripts / instructions for inference
|
| 86 |
+
|
| 87 |
+
## Citation
|
| 88 |
+
|
| 89 |
+
If you use PockNet in your work, please cite:
|
| 90 |
+
|
| 91 |
+
```
|
| 92 |
+
@misc{lal3lu03_pocknet_2025,
|
| 93 |
+
title = {PockNet Fusion Transformer Release},
|
| 94 |
+
author = {Hageneder, Max},
|
| 95 |
+
year = {2025},
|
| 96 |
+
url = {https://huggingface.co/lal3lu03/PockNet}
|
| 97 |
+
}
|
| 98 |
+
```
|
| 99 |
+
|
| 100 |
+
## License
|
| 101 |
+
|
| 102 |
+
Apache License 2.0. Refer to the repository `LICENSE` for full terms and ensure compliance with upstream dataset/ESM2 licenses when redistributing.
|
| 103 |
+
# PockNet – Selective SWA Epoch09_12
|
| 104 |
+
---
|
| 105 |
+
license: apache-2.0
|
| 106 |
+
# PockNet – Selective SWA Epoch09_12
|