lal3lu03 commited on
Commit
3b9afc6
·
verified ·
1 Parent(s): c1118e3

Upload MODEL_CARD.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. 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