README.md

---
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.

![MHC-PLM network architecture](https://huggingface.co/zmactep/MHC-PLM/resolve/main/assets/mhc-plm-architecture.svg)

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`.