BioBlobs EC-L3 model with RVQ-K8 (M-CSA results, NeurIPS 2026)

README.md

@@ -0,0 +1,73 @@
+---
+license: mit
+tags:
+  - biology
+  - protein
+  - enzyme
+  - ec-number
+  - interpretability
+---
+
+# BioBlobs
+
+The BioBlobs model behind the M-CSA results of **Unsupervised discovery of Functional
+Substructures** (Xin Wang, Kaiwen Shi and Carlos Oliver, NeurIPS 2026).
+[Paper](https://arxiv.org/abs/2510.01632) · [Code](https://github.com/OliverLaboratory/BioBlobs)
+
+The model predicts third-level Enzyme Commission (EC) classes, 242 in total, from frozen ESM2-T30
+residue embeddings and the protein structure. It splits each protein into 8 spatially local blobs
+and quantizes their embeddings with residual vector quantization. The blobs it relies on most
+point to candidate catalytic sites, although training uses only protein-level EC labels.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `model.safetensors` | model weights (59 MB) |
+| `config.yaml` | model configuration |
+| `classes.json` | EC class names and their indices |
+| `training_log.jsonl` | training log |
+
+## Use
+
+```bash
+git clone https://github.com/OliverLaboratory/BioBlobs.git
+cd BioBlobs
+uv sync && source .venv/bin/activate
+huggingface-cli download xwang112358/BioBlobs --local-dir bioblobs-mcsa-rvq-k8
+python inference.py --model bioblobs-mcsa-rvq-k8 --pdb-dir my_pdbs --out results
+```
+
+For each protein, the output lists the top EC classes, the blobs ranked by importance score with
+their residue numbers, and per-residue scores. The repository's `INFERENCE.md` describes the
+options and outputs, and `docs/REPRODUCE.md` shows how to retrain the model and evaluate it on
+M-CSA.
+
+## Training data
+
+Swiss-Prot enzymes from the [EC-Bench](https://github.com/dsaeedeh/EC-Bench) training set, with
+AlphaFold DB v6 structures. Training keeps proteins of up to 1,000 residues with a complete
+third-level EC number, split into training and validation sets at 30% sequence identity with
+MMseqs2. The GitHub repository ships the training and validation ids.
+
+## Limitations
+
+- The model only knows the 242 EC classes in its training data.
+- Class probabilities are softmax scores, not calibrated confidence.
+- A blob that overlaps annotated catalytic residues is evidence for, not proof of, its role in
+  catalysis.
+
+## Citation
+
+```bibtex
+@inproceedings{wang2026bioblobs,
+  title     = {Unsupervised discovery of Functional Substructures},
+  author    = {Wang, Xin and Shi, Kaiwen and Oliver, Carlos},
+  booktitle = {Advances in Neural Information Processing Systems},
+  year      = {2026}
+}
+```
+
+## License
+
+MIT

classes.json

@@ -0,0 +1,244 @@
+{
+ "1.1.1": 0,
+ "1.1.2": 1,
+ "1.1.3": 2,
+ "1.1.4": 3,
+ "1.1.5": 4,
+ "1.1.9": 5,
+ "1.1.98": 6,
+ "1.1.99": 7,
+ "1.10.2": 8,
+ "1.10.3": 9,
+ "1.10.5": 10,
+ "1.10.9": 11,
+ "1.11.1": 12,
+ "1.11.2": 13,
+ "1.12.1": 14,
+ "1.12.2": 15,
+ "1.12.5": 16,
+ "1.12.7": 17,
+ "1.12.98": 18,
+ "1.12.99": 19,
+ "1.13.11": 20,
+ "1.13.12": 21,
+ "1.13.99": 22,
+ "1.14.11": 23,
+ "1.14.12": 24,
+ "1.14.13": 25,
+ "1.14.14": 26,
+ "1.14.15": 27,
+ "1.14.16": 28,
+ "1.14.17": 29,
+ "1.14.18": 30,
+ "1.14.19": 31,
+ "1.14.20": 32,
+ "1.14.21": 33,
+ "1.14.99": 34,
+ "1.15.1": 35,
+ "1.16.1": 36,
+ "1.16.3": 37,
+ "1.16.5": 38,
+ "1.17.1": 39,
+ "1.17.2": 40,
+ "1.17.4": 41,
+ "1.17.5": 42,
+ "1.17.7": 43,
+ "1.17.8": 44,
+ "1.17.98": 45,
+ "1.17.99": 46,
+ "1.18.1": 47,
+ "1.18.6": 48,
+ "1.2.1": 49,
+ "1.2.3": 50,
+ "1.2.4": 51,
+ "1.2.5": 52,
+ "1.2.7": 53,
+ "1.2.98": 54,
+ "1.2.99": 55,
+ "1.20.1": 56,
+ "1.20.4": 57,
+ "1.20.9": 58,
+ "1.21.1": 59,
+ "1.21.3": 60,
+ "1.21.4": 61,
+ "1.21.98": 62,
+ "1.21.99": 63,
+ "1.23.1": 64,
+ "1.23.5": 65,
+ "1.3.1": 66,
+ "1.3.2": 67,
+ "1.3.3": 68,
+ "1.3.4": 69,
+ "1.3.5": 70,
+ "1.3.7": 71,
+ "1.3.8": 72,
+ "1.3.98": 73,
+ "1.3.99": 74,
+ "1.4.1": 75,
+ "1.4.3": 76,
+ "1.4.4": 77,
+ "1.4.5": 78,
+ "1.4.7": 79,
+ "1.4.9": 80,
+ "1.4.99": 81,
+ "1.5.1": 82,
+ "1.5.3": 83,
+ "1.5.4": 84,
+ "1.5.5": 85,
+ "1.5.8": 86,
+ "1.5.98": 87,
+ "1.5.99": 88,
+ "1.6.1": 89,
+ "1.6.2": 90,
+ "1.6.3": 91,
+ "1.6.5": 92,
+ "1.6.99": 93,
+ "1.7.1": 94,
+ "1.7.2": 95,
+ "1.7.3": 96,
+ "1.7.6": 97,
+ "1.7.7": 98,
+ "1.7.99": 99,
+ "1.8.1": 100,
+ "1.8.2": 101,
+ "1.8.3": 102,
+ "1.8.4": 103,
+ "1.8.5": 104,
+ "1.8.7": 105,
+ "1.8.98": 106,
+ "1.8.99": 107,
+ "1.9.3": 108,
+ "1.9.6": 109,
+ "1.97.1": 110,
+ "2.1.1": 111,
+ "2.1.2": 112,
+ "2.1.3": 113,
+ "2.1.4": 114,
+ "2.10.1": 115,
+ "2.2.1": 116,
+ "2.3.1": 117,
+ "2.3.2": 118,
+ "2.3.3": 119,
+ "2.4.1": 120,
+ "2.4.2": 121,
+ "2.4.99": 122,
+ "2.5.1": 123,
+ "2.6.1": 124,
+ "2.6.99": 125,
+ "2.7.1": 126,
+ "2.7.10": 127,
+ "2.7.11": 128,
+ "2.7.12": 129,
+ "2.7.13": 130,
+ "2.7.14": 131,
+ "2.7.2": 132,
+ "2.7.3": 133,
+ "2.7.4": 134,
+ "2.7.6": 135,
+ "2.7.7": 136,
+ "2.7.8": 137,
+ "2.7.9": 138,
+ "2.7.99": 139,
+ "2.8.1": 140,
+ "2.8.2": 141,
+ "2.8.3": 142,
+ "2.8.4": 143,
+ "2.9.1": 144,
+ "3.1.1": 145,
+ "3.1.11": 146,
+ "3.1.12": 147,
+ "3.1.13": 148,
+ "3.1.2": 149,
+ "3.1.21": 150,
+ "3.1.22": 151,
+ "3.1.25": 152,
+ "3.1.26": 153,
+ "3.1.27": 154,
+ "3.1.3": 155,
+ "3.1.30": 156,
+ "3.1.31": 157,
+ "3.1.4": 158,
+ "3.1.5": 159,
+ "3.1.6": 160,
+ "3.1.7": 161,
+ "3.1.8": 162,
+ "3.10.1": 163,
+ "3.11.1": 164,
+ "3.13.1": 165,
+ "3.2.1": 166,
+ "3.2.2": 167,
+ "3.3.1": 168,
+ "3.3.2": 169,
+ "3.4.11": 170,
+ "3.4.13": 171,
+ "3.4.14": 172,
+ "3.4.15": 173,
+ "3.4.16": 174,
+ "3.4.17": 175,
+ "3.4.18": 176,
+ "3.4.19": 177,
+ "3.4.21": 178,
+ "3.4.22": 179,
+ "3.4.23": 180,
+ "3.4.24": 181,
+ "3.4.25": 182,
+ "3.5.1": 183,
+ "3.5.2": 184,
+ "3.5.3": 185,
+ "3.5.4": 186,
+ "3.5.5": 187,
+ "3.5.99": 188,
+ "3.6.1": 189,
+ "3.6.2": 190,
+ "3.6.3": 191,
+ "3.6.4": 192,
+ "3.6.5": 193,
+ "3.7.1": 194,
+ "3.8.1": 195,
+ "3.9.1": 196,
+ "4.1.1": 197,
+ "4.1.2": 198,
+ "4.1.3": 199,
+ "4.1.99": 200,
+ "4.2.1": 201,
+ "4.2.2": 202,
+ "4.2.3": 203,
+ "4.2.99": 204,
+ "4.3.1": 205,
+ "4.3.2": 206,
+ "4.3.3": 207,
+ "4.3.99": 208,
+ "4.4.1": 209,
+ "4.5.1": 210,
+ "4.6.1": 211,
+ "4.7.1": 212,
+ "4.99.1": 213,
+ "5.1.1": 214,
+ "5.1.2": 215,
+ "5.1.3": 216,
+ "5.1.99": 217,
+ "5.2.1": 218,
+ "5.3.1": 219,
+ "5.3.2": 220,
+ "5.3.3": 221,
+ "5.3.4": 222,
+ "5.3.99": 223,
+ "5.4.1": 224,
+ "5.4.2": 225,
+ "5.4.3": 226,
+ "5.4.4": 227,
+ "5.4.99": 228,
+ "5.5.1": 229,
+ "5.99.1": 230,
+ "6.1.1": 231,
+ "6.1.2": 232,
+ "6.2.1": 233,
+ "6.3.1": 234,
+ "6.3.2": 235,
+ "6.3.3": 236,
+ "6.3.4": 237,
+ "6.3.5": 238,
+ "6.4.1": 239,
+ "6.5.1": 240,
+ "6.6.1": 241
+}

config.yaml

@@ -0,0 +1,43 @@
+encoders:
+  name: esm2_static
+  model_name: facebook/esm2_t30_150M_UR50D
+  output_dim: 640
+partitioners:
+  name: bioblobs
+  num_blobs: 8
+  seed_radius: 12.0
+  proximity_bias: 0.25
+  seed_hidden_dim: 128
+  attn_dim: 128
+  seed_tau:
+  - 1.0
+  - 0.25
+  - 0.95
+  membership_tau:
+  - 1.0
+  - 0.25
+  - 0.95
+decoders:
+  name: mil
+  mil_dim: 512
+  dropout: 0.1
+  hidden_multipliers:
+  - 4
+  - 2
+  use_blob_interaction: false
+codebooks:
+  enabled: true
+  num_codes: 1024
+  num_quantizers: 8
+  code_dim: null
+  beta: 0.25
+  ema_decay: 0.99
+  ema_eps: 1.0e-05
+  normalize_input: true
+  dead_code_revival: true
+  revive_every_steps: 250
+  revive_threshold: 1.0
+  revive_frac: 0.0
+  warmup_epochs: 2
+  data_init: true
+num_classes: 242

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f975d161df68960a51b10452dc3c557eb7a3fa76341f258ce0556c300f2a192e
+size 58925913