| --- |
| license: other |
| license_name: mhc-plm-research-weight-notice |
| license_link: https://huggingface.co/zmactep/MHC-PLM/blob/main/LICENSE_WEIGHTS.md |
| library_name: pytorch |
| base_model: |
| - biohub/ESMC-300M |
| - biohub/ESMC-600M |
| tags: |
| - biology |
| - protein-language-model |
| - immunology |
| - mhc |
| - mhc-class-ii |
| - peptide-binding |
| - antigen-presentation |
| - esmc |
| - lora |
| - multiple-instance-learning |
| model-index: |
| - name: MHC-PLM core-selected ensemble |
| results: |
| - task: |
| type: mhc-ii-binding-affinity |
| name: MHC-II binding affinity |
| dataset: |
| type: netmhciipan-4.3-full-fold1-audit |
| name: NetMHCIIpan 4.3 fold 1 audit excluding fixed selection rows |
| metrics: |
| - type: auroc-500nm |
| name: BA AUROC at 500 nM |
| value: 0.8881501373829886 |
| - type: average-precision-500nm |
| name: BA average precision at 500 nM |
| value: 0.8529772425709462 |
| - type: pearson-r |
| name: BA Pearson r |
| value: 0.7654025002504102 |
| - type: spearman-r |
| name: BA Spearman r |
| value: 0.7655603005570821 |
| - type: mse |
| name: BA mean squared error |
| value: 0.028142128247225746 |
| - task: |
| type: mhc-ii-eluted-ligand |
| name: MHC-II eluted-ligand presentation |
| dataset: |
| type: netmhciipan-4.3-full-fold1-audit |
| name: NetMHCIIpan 4.3 fold 1 audit excluding fixed selection rows |
| metrics: |
| - type: auroc |
| name: EL AUROC |
| value: 0.9644079925097755 |
| - type: average-precision |
| name: EL average precision |
| value: 0.8110726901017381 |
| --- |
| |
| # MHC-PLM |
|
|
| MHC-PLM is a research model for joint MHC class II binding-affinity (BA) and |
| eluted-ligand presentation (EL) prediction. The primary release is a four-member ensemble |
| selected on a peptide-9-mer-disjoint subset and frozen before evaluation on the remaining |
| full fold. |
|
|
|  |
|
|
| The architecture combines pinned ESM-C encoders with peptide-to-MHC cross-attention, |
| explicit forward/reverse 9-mer binding-register enumeration, multi-allelic |
| multiple-instance pooling, and an EL-only processing-context branch. The released files |
| are compact LoRA plus interaction-head state dictionaries; the Biohub ESM-C base models |
| are downloaded separately at exact revisions. |
|
|
| This model is **not a medical device**, has not been validated for clinical decision |
| making, and should not be described as state of the art. It requires direct same-row |
| baseline comparisons, all-fold validation, external temporal tests, and uncertainty |
| estimation before such claims. |
|
|
| ## Primary result |
|
|
| | Evaluation | Composite | BA AUROC | BA AP | BA Pearson | EL AUROC | EL AP | |
| |---|---:|---:|---:|---:|---:|---:| |
| | Core-disjoint selection | 0.866341 | 0.879578 | 0.843251 | 0.749431 | 0.963304 | 0.873052 | |
| | Frozen full-fold audit | **0.857258** | **0.888150** | **0.852977** | **0.765403** | **0.964408** | **0.811073** | |
|
|
| The full-fold audit contains 21,794 BA and 1,516,156 EL rows after excluding the fixed |
| model-selection subset; EL positive prevalence is 0.08165. The best individual model is |
| `stage4` with full-fold composite 0.852588. The preselected ensemble improves it by |
| 0.004671. An exploratory full-fold search happened to choose the same four members, but |
| it did not define the primary model. |
|
|
| ## Files and ensemble composition |
|
|
| `ensemble.json` is the authoritative machine-readable release manifest. Inference uses |
| the arithmetic mean of post-sigmoid scores from: |
|
|
| | Member | Backbone | Role | SHA-256 | |
| |---|---|---|---| |
| | `stage3` | ESMC-300M | Main trajectory stage 3 | `2ef7668d…a640892` | |
| | `600m` | ESMC-600M | Independently trained diversity member | `7e6dda37…8dedda` | |
| | `stage4` | ESMC-300M | Best individual, low-LR continuation | `8a2efbde…9493493` | |
| | `replica_s3333` | ESMC-300M | Independent seed trajectory | `aedbaf24…478237` | |
|
|
| The exact base revisions are: |
|
|
| - `biohub/ESMC-300M@a59b831785f907e96e6a246b1d142bfb76df31ee` |
| - `biohub/ESMC-600M@a7e82012c83126b9eedb055fea9fa84b6c02f094` |
|
|
| The CLI checks the complete SHA-256 of every adapter file before loading it. Members are |
| loaded sequentially to limit peak memory. |
|
|
| ## Installation |
|
|
| The model repository contains weights and release metadata only. Install the inference |
| code from the paired [GitHub source repository](https://github.com/zmactep/MHC-PLM): |
|
|
| ```bash |
| git clone https://github.com/zmactep/MHC-PLM.git |
| cd MHC-PLM |
| uv python install 3.10 |
| uv sync --locked --extra gpu |
| ``` |
|
|
| ## Quick start |
|
|
| The GitHub source repository contains `examples/input.tsv`: |
|
|
| ```text |
| id task peptide alleles mhc_sequences context |
| ha_ba ba PKYVKQNTLKLAT DRB1_0101 QEFFIASGAAVDAIMWLFLECYDLQRATYHVGFT |
| ha_el el PKYVKQNTLKLAT DRB1_0101 QEFFIASGAAVDAIMWLFLECYDLQRATYHVGFT XXXPKYLATXXX |
| ``` |
|
|
| Run the full ensemble. The CLI downloads `ensemble.json` and the required weights from |
| this Hugging Face repository automatically: |
|
|
| ```bash |
| uv run --locked --extra gpu mhc2-plm-predict \ |
| --input examples/input.tsv \ |
| --output predictions.tsv |
| ``` |
|
|
| Run the best individual model only: |
|
|
| ```bash |
| uv run --locked --extra gpu mhc2-plm-predict \ |
| --members stage4 \ |
| --input examples/input.tsv \ |
| --output predictions-stage4.tsv |
| ``` |
|
|
| For an offline deployment, download this model repository separately and pass its local |
| path with `--model-dir /path/to/MHC-PLM-model`. |
|
|
| ### Input contract |
|
|
| - `task` is `ba` or `el`. |
| - `peptide` must contain at least nine residues. |
| - `alleles` and `mhc_sequences` are corresponding semicolon-separated lists. The model |
| was trained on MHC-II pseudosequences, not raw allele strings or full chains. |
| - EL `context` contains three upstream residues, the first three peptide residues, the |
| last three peptide residues, and three downstream residues. Missing context is replaced |
| by twelve `X` residues and should be treated as lower-information input. |
| - Up to 14 candidate alleles are pooled as latent alternatives. |
|
|
| The output provides the ensemble score and all selected member scores. BA score is the |
| normalized affinity target, where higher is stronger; the CLI also reports the inverse |
| approximation `IC50 nM = 50000^(1-score)`. EL score is suitable for ranking but is not a |
| calibrated probability. This release does not provide NetMHCIIpan-style percentile ranks. |
|
|
| ## Model architecture |
|
|
| Each member uses: |
|
|
| 1. an ESMC-300M or ESMC-600M encoder with rank-16 LoRA on all linear layers; |
| 2. a 256-dimensional interaction projection; |
| 3. two 8-head peptide-to-MHC cross-attention blocks; |
| 4. all overlapping 9-mer peptide cores in forward and reverse orientations; |
| 5. separate BA and EL register heads; |
| 6. EL-only flanking-context adaptation; |
| 7. temperature-0.15 masked log-mean-exp pooling over candidate allele, register, and |
| orientation. |
|
|
| BA uses Huber loss on normalized affinity. EL uses weighted binary cross-entropy with |
| positive weight 10.04. Optimization uses AdamW with separate backbone/head learning |
| rates, warmup, cosine decay, gradient clipping, and weak register-entropy regularization. |
|
|
| ## Training and evaluation data |
|
|
| The training source was the public NetMHCIIpan 4.3 training pack from DTU Health Tech: |
| 129,110 BA and 7,594,916 EL records across five supplied folds. The source archive SHA-256 |
| was `bde8e21addba99ed8a2202f5c6aff40d653cddc425aa728fb5b9378c3aaa2261`. |
|
|
| A fixed balanced 16,384-row subset of fold 1 was used during iterative model selection. |
| An overlap audit found no exact peptide overlap between fold 1 and folds 2–5, but 62.9% |
| of unique fold-1 peptides contain a 9-mer observed in training. Final ensemble membership |
| was therefore selected on a stricter subset excluding all such peptides and all fixed |
| selection rows. The remaining fold was used once as a frozen natural-prevalence audit. |
|
|
| The original data archive is not included in this repository. See the official |
| [NetMHCIIpan 4.3 service](https://services.healthtech.dtu.dk/services/NetMHCIIpan-4.3/) |
| for data access, descriptions, and citation requirements. |
|
|
| ## What the scaling study found |
|
|
| - Successive low-learning-rate continuations improved ESMC-300M from fixed composite |
| 0.8321 to 0.8908. |
| - ESMC-600M scored 0.8668 fixed and 0.8264 core-disjoint, below the optimized 300M model. |
| - An independent 300M trajectory was also weaker individually but added ensemble diversity. |
| - The full ESMC-6B quality run was cancelled after 600M failed to justify the projected |
| cost. 6B throughput and memory benchmarks were retained in the source repository. |
|
|
| These results indicate that optimization, inductive bias, split design, and model |
| diversity mattered more here than simple backbone scaling. |
|
|
| ## Limitations and responsible use |
|
|
| - Only one supplied fold was used for architecture/ensemble selection. |
| - The official fold has substantial shared-binding-core overlap with training. |
| - No direct identical-row comparison with NetMHCIIpan 4.3, MixMHC2pred, or |
| pMHChat has yet been completed. |
| - Performance has not been established for unseen allele families, temporally new data, |
| rare organisms, altered peptides, or noncanonical amino acids. |
| - Scores are not calibrated and must not be interpreted as clinical probabilities. |
| - Do not use this model as the sole basis for diagnosis, treatment, vaccine design, or |
| safety-critical experimental prioritization. |
|
|
| Recommended next evaluations are all-five-fold replication, per-allele macro metrics, |
| paired bootstrap confidence intervals, leave-one-allele-family-out tests, sequence-clustered |
| and temporal splits, calibration, ablations, and direct baseline reruns on identical rows. |
|
|
| ## Reproducibility and provenance |
|
|
| This Hugging Face repository includes only: |
|
|
| - this Model Card (`README.md`); |
| - the machine-readable ensemble and base-revision manifest (`ensemble.json`); |
| - four adapter/interaction-head checkpoints under `weights/`; |
| - the weight notice (`LICENSE_WEIGHTS.md`) and citation metadata (`CITATION.cff`). |
|
|
| Training, inference, evaluation, tests, locked dependencies, configurations, and |
| machine-readable experiment results are maintained in the paired |
| [GitHub source repository](https://github.com/zmactep/MHC-PLM). |
|
|
| Before release, 21 unit tests passed, Ruff and shell/JSON validation passed, every release |
| weight matched its recorded SHA-256, and an actual pinned ESMC-300M adapter inference was |
| smoke-tested offline. The original experiment bundle separately passed a deep scan over |
| 7,724,026 rows and 21 cached model files. |
|
|
| ## License and citations |
|
|
| MHC-PLM source code is MIT-licensed. Adapter/head weights are published under the |
| research notice in [`LICENSE_WEIGHTS.md`](LICENSE_WEIGHTS.md). Users must separately obey |
| the current Biohub ESM-C license and acceptable-use policy and any DTU terms applying to |
| the NetMHCIIpan training data. Complete ESM-C base weights and the DTU archive are not |
| redistributed here. |
|
|
| Please cite: |
|
|
| - Nilsson et al. *Accurate prediction of HLA class II antigen presentation across all |
| loci using tailored data acquisition and refined machine learning*. Science Advances |
| (2023), DOI: 10.1126/sciadv.adj6367. |
| - The current Biohub ESM-C model and paper listed in the |
| [Biohub ESM repository](https://github.com/Biohub/esm). |
| - MHC-PLM using the included `CITATION.cff`. |
|
|
