AMULETY: A Python package to embed adaptive immune receptor sequences

Meng Wang, Yuval Kluger, Steven H. Kleinstein, Gisela GabernetbioRxiv 2025 · DOI

TL;DR

This paper introduces AMULETY, a Python package that simplifies the process of generating embeddings for adaptive immune receptor (AIRR) sequences using various pre-trained language models. By abstracting away complex configurations, AMULETY makes powerful AI tools for immune repertoire analysis more accessible to researchers.

What Problem Does This Paper Address?

The adaptive immune system, with its B-cell receptors (BCRs) and T-cell receptors (TCRs), holds a wealth of information about an individual's immune history and responses. Analyzing these receptors, often represented as amino acid sequences, is crucial for understanding immunity, predicting responses to vaccines, and developing new therapies. To leverage these sequences for downstream applications like prediction tasks, they need to be translated into numerical representations called "embeddings." While several language models (e.g., immune2vec, AntiBERTY, ESM2) have been developed to capture meaningful features of these sequences, using them can be challenging. Researchers often face hurdles with installing multiple dependencies, configuring them for efficient computation (especially on GPUs), and integrating them into their existing workflows. This complexity can be a significant barrier, particularly for those less experienced with machine learning infrastructure.

Methods

AMULETY addresses this by providing a unified, user-friendly Python package. Its core functionality involves:

  • Sequence Standardization: It takes AIRR-formatted data (containing nucleotide sequences and metadata) and uses IgBLAST to align and translate nucleotide sequences into full amino acid sequences, including VDJ region translations. This step ensures consistent input for the language models.
  • Pre-trained Model Integration: AMULETY integrates several state-of-the-art antibody and protein language models, including AntiBERTY, AntiBERTa2, BALM-paired, and ESM2. Users can select the model that best suits their needs based on computational resources and desired embedding characteristics.
  • Flexible Embedding Generation: The package supports embedding for both paired heavy and light chain sequences (common in BCRs) and single chain sequences. It also handles mixed datasets (single-cell and bulk) and provides mechanisms for pairing light chains when multiple are present for a single cell.
  • Accelerated Computation: AMULETY supports mini-batch processing for large datasets and can leverage GPU infrastructure for significantly faster computation.
  • Interoperability: The output embeddings are designed to be compatible with other AIRR data analysis tools, promoting seamless integration into existing research pipelines. Docker containers are also provided for simplified installation.

Datasets

The paper uses a dataset of paired chain nucleotide sequences from antibodies that bind to SARS-CoV-2 spike protein receptor binding domain, categorized by their epitope groups. This dataset was used to evaluate the performance of different embedding models in distinguishing between antibodies targeting different epitopes. No new benchmarks were introduced; rather, existing datasets were used to showcase the utility of AMULETY.

Key Insights and Ideas

  • Democratizing AI for Immunology: The primary contribution is making advanced language model embeddings for immune receptors accessible. By abstracting away technical complexities, AMULETY empowers a broader range of researchers to utilize these powerful tools.
  • Model Variability Matters: Different language models capture distinct aspects of antibody sequences. The study demonstrates that no single model is universally superior; the choice depends on the specific biological question and the desired outcome.
  • Visualizing and Quantifying Embeddings: The paper effectively uses UMAP for visualizing the embedding space and employs clustering metrics (Silhouette Score, Davies-Bouldin Index, Calinski-Harabasz Index) to quantitatively assess how well different models separate antibodies based on their epitope binding.

Key Results

  • AMULETY successfully generates embeddings for adaptive immune receptor sequences using multiple pre-trained language models.
  • UMAP visualizations revealed differences in how the four tested models (antiBERTy, antiBERTa2, BALM-paired, ESM2) cluster antibodies based on their epitope groups.
  • Quantitative evaluation showed that while Silhouette scores were generally low across all models (indicating weak epitope-based separation), the Davies-Bouldin index suggested antiBERTa2 provided slightly better-defined antibody epitope clusters.
  • The Calinski-Harabasz index indicated that BALM-paired captured more distinct cluster structures, suggesting it might be better at identifying nuanced differences.
  • These results collectively suggest that different models excel at capturing different aspects of epitope-specific antibody distinctions.

Limitations and Future Work

  • TCR Support: Currently, AMULETY primarily focuses on antibody sequences. A key future extension is the inclusion of embedding methods specifically for TCRs to enable more comprehensive analysis of adaptive immune repertoires.
  • Modularity and Extensibility: The authors emphasize AMULETY's modular design, which allows for seamless integration with other AIRR processing tools and the accommodation of future developments in both immune repertoire analysis and machine learning models. This suggests a roadmap for continuous improvement and expansion of capabilities.

Summary updated

Abstract

Abstract Large language models have been developed to capture relevant features of adaptive immune receptors, each with unique potential applications. However, the diversity in available models presents challenges in accessibility and usability for downstream applications. Here we present AMULETY (Adaptive imMUne receptor Language model Embedding Tool), a Python-based software package to generate language model embeddings for adaptive immune receptor sequences, enabling users to leverage the strengths of different models without the need for complex configuration. AMULETY offers functions for embedding adaptive immune receptor amino acid sequences using pre-trained protein or antibody language models for paired heavy and light chain or single chain sequences. We showcase the variability on the embedding space for several embeddings on a dataset of antibody binders to several SARS-CoV-2 epitopes and showed that different models may be effective at capturing different aspects of the distinctions between epitope groups. AMULETY is available under GPL v3 license from https://github.com/immcantation/amulety or via pip from the Python Package Index (PyPI) from https://pypi.org/project/amulety/ . Abstract Figure
BibTeX
@misc{wang2025amulety,
  author = {Meng Wang and Yuval Kluger and Steven H. Kleinstein and Gisela Gabernet},
  title = {{AMULETY: A Python package to embed adaptive immune receptor sequences}},
  year = {2025},
  doi = {10.1101/2025.03.21.644583},
  howpublished = {bioRxiv},
}
Figure