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:

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:

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:

uv run --locked --extra gpu mhc2-plm-predict \
  --input examples/input.tsv \
  --output predictions.tsv

Run the best individual model only:

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

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. 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.
• MHC-PLM using the included CITATION.cff.