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