ESMCBA Evolutionary Scale Modeling Binding Affinity - Model for binding affinity prediction of the peptide-MHC interaction

Code: https://github.com/sermare/ESMCBA
Models: https://huggingface.co/smares/ESMCBA

This guide shows a new user how to:

• get the code
• download one or more model checkpoints from Hugging Face
• run predictions and get Hidden Layer embeddings with embeddings.py
• understand where files are stored and how to point to them

Quick Start (Run it in Collab)

You can access this notebook to run with google collab:

🚀 Quick Start with pip

ESMCBA is now available on PyPI! Install it with a single command:

pip install esmcba

Basic Usage

Once installed, you can run predictions directly from the command line:

esmcba --hla A0201 \
  --peptides KIQEGVVDYGA VLMSNLGMPS DTLRVEAFEYY \
  --encoding epitope \
  --output_dir ./outputs

Complete Example

Here's a full example with multiple peptides for HLA-A*02:01:

esmcba --hla A0201 \
  --peptides KIQEGVVDYGA VLMSNLGMPS DTLRVEAFEYY AKKPTETI FKLNIKLLGVG \
             ETSNSFDVLK INVIVFDGKSK VDFCGKGYHLM AYPLTKHPNQ RAMPNMLRI \
             FIASFRLFA YIFFASFYYV SLIDFYLCFL FLTENLLLYI YMPYFFTLL \
             FLLPSLATV FLAFLLFLV YFIASFRLFA FFFLYENAFL FLIGCNYLG \
             YLATALLTL FLHFLPRV YLCFLAFLLF YLKLTDNVYI KLMGHFAWWT \
             TLMNVLTLV YLTNDVSFL FLPFAMGI LLADKFPV SMWSFNPET \
             LLMPILTLT LVAEWFLAYI FLYLYALVYF LMSFTVL MWLSYFIA \
             FLNGSCGSV LVLSVNPYV GLCVDIPGI \
  --encoding epitope \
  --output_dir ./outputs

Output Files

After running, you'll find in your output directory:

• A0201-ESMCBA_embeddings.npy - Raw ESM embeddings
• A0201-ESMCBA_umap.csv - UMAP visualization coordinates

Available Options

esmcba --help

Key parameters:

• --hla: HLA allele (e.g., A0201, B1402, C0501)
• --peptides: Space-separated list of peptide sequences
• --encoding: Encoding type (epitope or hla, default: epitope)
• --output_dir: Directory for output files (default: ./outputs)
• --batch_size: Batch size for inference (default: 10)
• --umap_dims: UMAP dimensions, 2 or 3 (default: 2)

1. Requirements

• Python 3.9 or newer
• PyTorch 1.13+ or 2.x
• huggingface_hub for downloads

Install the basics:

# Install core PyTorch and Transformers ecosystem
pip install torch
pip install transformers
pip install esm

# Install Hugging Face Hub utilities
pip install "huggingface-hub<1.0"

# Optional: Install hf_transfer for faster large file downloads
pip install hf_transfer

pip install biopython umap-learn scikit-learn seaborn pandas matplotlib

2. Get the code

git clone https://github.com/sermare/ESMCBA

Inside the repo you should have embeddings.py available. If your file is named embeddings_generation.py, use that name instead in the commands below.

3. Pick a model checkpoint (all models at the end of this Markdown)

All checkpoints live in the model repo: smares/ESMCBA.

Examples of filenames:

• ESMCBA_epitope_0.95_30_ESMMASK_epitope_FT_25_0.001_5e-05_AUG_3_HLAB1402_2_1e-05_1e-06__1_B1402_0404_Hubber_B1402_final.pth
• ESMCBA_epitope_0.95_30_ESMMASK_epitope_FT_25_0.001_5e-05_AUG_6_HLAB1503_2_0.0001_1e-05__2_B1503_0404_Hubber_B1503_final.pth
• ESMCBA_epitope_0.5_20_ESMMASK_epitope_FT_15_0.0001_1e-05_AUG_6_HLAB5101_5_0.001_1e-06__3_B5101_Hubber_B5101_final.pth

You can browse all files here: https://huggingface.co/smares/ESMCBA

4. Download a checkpoint

Option A — download to a folder next to the code

# download everything to ./models
hf download smares/ESMCBA --repo-type model --local-dir ./models

#or just get one model
huggingface-cli download smares/ESMCBA \
  "ESMCBA_epitope_0.8_30_ESMMASK_epitope_FT_5_0.001_1e-06_AUG_6_HLAA0201_2_0.001_1e-06__2_A0201_Hubber_A0201_final.pth" \
  --repo-type model \
  --local-dir ./models

Option B — rely on the Hugging Face cache

If you omit --local-dir, files go into your HF cache, for example:

~/.cache/huggingface/hub/

To move the cache:

export HF_HOME=/path/to/cache

5. Run embeddings.py

Below are example invocations. Replace the checkpoint filename and HLA tag with one that matches your use case.

Example 1 — using a file you downloaded to ./models

python3 embeddings_generation.py   --model_path ./models/ESMCBA_epitope_0.5_20_ESMMASK_epitope_FT_15_0.0001_1e-05_AUG_6_HLAB5101_5_0.001_1e-06__3_B5101_Hubber_B5101_final.pth   --name B5101-ESMCBA   --hla B5101   --encoding epitope   --output_dir ./outputs --peptides ASCQQQRAGHS ASCQQQRAGH ASCQQQRAG DVRLSAHHHR DVRLSAHHHRM GHSDVRLSAHH 

Example 2 — let the script pull from the Hub automatically

If embeddings_generation.py supports resolving from the Hub, you can pass either a file name or an hf:// path and let the script download to cache.

cd ESMCBA/ESMCBA

python3 embeddings_generation.py   --model_path "ESMCBA_epitope_0.95_30_ESMMASK_epitope_FT_25_0.001_5e-05_AUG_3_HLAB1402_2_1e-05_1e-06__1_B1402_0404_Hubber_B1402_final.pth"   --name B1402-ESMCBA   --hla B1402   --encoding epitope   --output_dir ./outputs --peptides ASCQQQRAGHS ASCQQQRAGH ASCQQQRAG DVRLSAHHHR DVRLSAHHHRM GHSDVRLSAHH

or

python3 embeddings_generation.py   --model_path "hf://smares/ESMCBA/ESMCBA_epitope_0.95_30_ESMMASK_epitope_FT_25_0.001_5e-05_AUG_3_HLAB1402_2_1e-05_1e-06__1_B1402_0404_Hubber_B1402_final.pth"   --name B1402-ESMCBA   --hla B1402   --encoding epitope   --output_dir ./outputs --peptides ASCQQQRAGHS ASCQQQRAGH ASCQQQRAG DVRLSAHHHR DVRLSAHHHRM GHSDVRLSAHH

GPU vs CPU

• By default PyTorch will use GPU if available.
• To force CPU, set CUDA_VISIBLE_DEVICES="" or modify embeddings.py to pass map_location="cpu" to torch.load.

6. Minimal pattern inside embeddings.py to resolve paths

If you want the script to accept local files, simple names, or hf://:

import os
from huggingface_hub import hf_hub_download

def resolve_model_path(path_or_name, default_repo="smares/ESMCBA"):
    if os.path.isfile(path_or_name):
        return path_or_name
    if path_or_name.startswith("hf://"):
        # format: hf://<repo_id>/<filename>
        _, _, repo_id, filename = path_or_name.split("/", 3)
        return hf_hub_download(repo_id=repo_id, filename=filename, repo_type="model")
    return hf_hub_download(repo_id=default_repo, filename=path_or_name, repo_type="model")

Then in your loader:

import torch

ckpt_path = resolve_model_path(args.model_path)
state = torch.load(ckpt_path, map_location="cpu")  # change to cuda as needed

7. Common tasks

• List files available in the model repo:

  git lfs ls-files | cat   # if you cloned the HF repo
  

  or browse the Hub page.

• Download all files for offline use:

  hf download smares/ESMCBA --repo-type model --local-dir ./models
  

• Keep outputs tidy:

  mkdir -p ./outputs
  

8. Troubleshooting

• huggingface-cli download is deprecated
  Use hf download instead.

• Permission or quota errors when downloading
  Public models do not require login. For private models, run hf login.

• Slow transfers
  Install hf_transfer and export HF_HUB_ENABLE_HF_TRANSFER=1.

• File not found
  Double check the exact filename on the Hub. Filenames are long. Copy and paste.

9. Models

10. Repro tip for papers and reviews

Record the exact commit of the code and the model snapshot. Example:

Code commit: <git SHA from ESMCBA repo>
Model snapshot: <commit SHA shown in HF snapshots path>
HLA: B5101
Encoding: epitope

11. License and citation

arxiv.org/abs/2507.13077

Follow the license in the GitHub repo for code and the model card in the Hub repo for weights. If you use ESMCBA in research, please cite the associated manuscript or submission.