Unsupervised Machine Learning for Adaptive Immune Receptors with immuneML

This paper introduces an updated release of immuneML that establishes a unified framework for unsupervised machine learning in adaptive immune receptor analysis, enabling robust clustering, interpretable generative modeling, and the systematic evaluation of biological properties and potential confounders.

The Gist

Imagine your immune system as a massive, bustling library containing billions of unique books. Each "book" is a receptor (a protein) on your immune cells, designed to recognize specific invaders like viruses or bacteria. This entire collection is called your Adaptive Immune Receptor Repertoire (AIRR).

Scientists want to read these books to find patterns: Which books fight the flu? Which ones fight cancer? Which ones are just "noise" from a bad batch of photocopying (technical errors)?

The problem? Most of these books are unlabeled. We don't know what they fight, or we only have vague notes like "this whole shelf is sick." Trying to find patterns in billions of unlabeled books using traditional methods is like trying to sort a library by guessing the genre of every book without ever opening one.

Enter immuneML, a new software tool introduced in this paper. Think of it as a super-smart, automated librarian that uses "unsupervised machine learning" to organize this chaotic library without needing a pre-written catalog.

Here is a breakdown of what this new tool does, using simple analogies:

1. The Problem: A Library Without Labels

In the past, scientists mostly used "supervised" learning. This is like a teacher giving a student a flashcard with a picture of a cat and the word "Cat." The student learns to recognize cats. But in immunology, we rarely have perfect flashcards. We have piles of books where we don't know the genre.

Unsupervised learning is different. It's like giving the librarian a million books and saying, "Group these books together based on how similar they look, and tell me what you find." The librarian might discover, "Hey, all these red books seem to talk about dragons," even if no one told them that.

2. The New Tool: immuneML's "Magic Features"

The authors updated the immuneML software to handle this "unlabeled" chaos with three main superpowers:

A. The "Imagination Engine" (Generative Models)

Sometimes, scientists need to invent new immune receptors to test theories or design new medicines.

• The Analogy: Imagine a chef who has tasted thousands of pizzas. A "generative model" is like an AI chef that learns the rules of pizza-making and then invents new pizzas that have never existed before.
• What immuneML does: It lets scientists train these AI chefs to create new immune receptors. The paper tested three different "chefs" (LSTM, VAE, and PWM) to see which one could invent the most realistic, useful new receptors without just copying old ones.

B. The "Sorting Machine" (Clustering)

This is the core of the update. It groups similar receptors together.

• The Analogy: Imagine you dump a bag of mixed LEGO bricks on the floor. You want to sort them by color and shape, but you don't have a manual. You just start grouping them.
• The Innovation: The old way of sorting was risky. You might sort them by color, but maybe the "real" pattern was by shape. The new immuneML doesn't just sort once; it sorts the LEGO bricks hundreds of times in slightly different ways to see if the groups stay the same.
  • If the groups keep changing, the sorting is unstable (like trying to stack Jenga blocks in an earthquake).
  • If the groups stay the same, the pattern is real and robust.
• The Result: It helps scientists figure out if a group of receptors is actually fighting the same virus, or if they just happen to look similar by chance.

C. The "Confounder Detector" (Spotting the Ghosts)

Sometimes, what looks like a biological pattern is actually just a technical glitch.

• The Analogy: Imagine you are sorting people by their favorite music. But you accidentally sorted them by the color of the shirt they wore to the party. You think you found a "Blue Shirt Rock Fan" group, but it's just a coincidence.
• What immuneML does: In the third use case, the team used the tool on real patient data. They asked, "Are we grouping these patients because they have the same disease, or because they were all processed in the same lab on a Tuesday?" The tool helped them realize that while some lab batches looked suspicious, the actual immune sequences weren't being fooled by the lab errors. This saves scientists from chasing "ghosts."

3. Why This Matters

Before this, if a scientist wanted to do this kind of deep, exploratory sorting, they had to write their own code, use different tools for different steps, and hope they didn't make a mistake. It was like trying to build a house using a hammer, a saw, and a wrench from three different toolboxes that didn't fit together.

immuneML puts everything in one toolbox. It:

1. Standardizes the process: Everyone uses the same rules, so results can be compared.
2. Checks its own work: It constantly asks, "Are these groups real, or did I just get lucky?"
3. Makes it visual: It turns complex data into easy-to-read maps and charts.

The Bottom Line

This paper introduces a unified, reliable framework for exploring the immune system's "library" when we don't have the catalog. It allows scientists to:

• Invent new immune tools (Generative Modeling).
• Group similar immune responses to find hidden diseases (Clustering).
• Spot fake patterns caused by lab errors (Confounder Analysis).

By making these complex tasks easier and more reliable, immuneML helps researchers move faster from "what is happening?" to "how can we cure it?"

Technical Summary

1. Problem Statement

Adaptive Immune Receptor Repertoires (AIRRs) are vast, complex datasets (~10⁹ unique sequences per individual) crucial for understanding immune responses, diagnostics, and therapeutics. However, analyzing AIRR data faces significant challenges:

• Data Limitations: Most AIRR datasets are partially labeled, imperfectly annotated, or entirely unlabeled, rendering supervised learning insufficient for many tasks.
• Lack of Unified Framework: There is no standardized framework for unsupervised machine learning (ML) in the AIRR field. Existing tools lack systematic workflows for model selection, stability assessment, and validation.
• Evaluation Difficulties: Validating unsupervised results (clustering, generative modeling) is inherently difficult due to the absence of ground truth, the high dimensionality of sequence space, and the lack of standardized metrics to assess biological relevance versus technical artifacts (e.g., batch effects).
• Fragmented Tools: Current tools focus on specific tasks (e.g., diversity analysis or specific clustering) but do not offer a unified pipeline for representation learning, clustering, generative modeling, and confounder detection.

2. Methodology: The immuneML Platform

The authors present a new release of immuneML, an open-source Python platform, extending its capabilities from supervised classification to a comprehensive unsupervised ML framework.

Core Architectural Features

• Unified Workflow: The platform accepts AIRR datasets and YAML specifications, outputting reproducible HTML reports. It integrates BioNumPy for efficient array programming and data validation.
• Representation Learning: It supports diverse data encodings, including:
  • Traditional: K-mer frequencies, physicochemical features.
  • Pre-computed distances: tcrdist.
  • Protein Language Models (PLMs): Integration of embeddings from ProtT5, TCR-BERT, ESM3, and others.
• Dimensionality Reduction: Implements PCA, t-SNE, and UMAP for visualization and exploratory analysis.

Key Unsupervised Modules

1. Clustering Workflow:

   • Model Selection: Uses a stability assessment approach (based on Lange et al.) where data is split, clustered, and labels are transferred between subsets. Stability is measured via the Adjusted Rand Index (ARI).
   • Validation: Implements a dual-validation framework (Ullmann et al.):
     • Method-based: Independent clustering on discovery vs. validation sets.
     • Result-based: Training a classifier on discovery clusters to predict labels on validation data.
   • Metrics: Reports Adjusted Mutual Information (AMI) for external validation (against biological labels) and Silhouette/Calinski-Harabasz scores for internal quality.

2. Generative Modeling:

   • Integrates models like SoNNia, LSTM, VAE, and ProGen2.
   • Includes LIgO (LIgO tool for AIRR simulation) for generating synthetic datasets with known ground-truth signals (e.g., specific epitope motifs) to benchmark model performance.
   • Provides tools to distinguish between memorized sequences (from training) and novel sequences, and to assess the preservation of biological signals (e.g., epitope specificity).

3. Confounder Analysis:

   • Designed to detect batch effects and other technical biases in experimental data before applying supervised models.

3. Key Contributions

• First Unified Framework: The first platform to provide a cohesive, reproducible workflow for unsupervised learning (clustering, generation, exploration) specifically tailored for AIRR data.
• Rigorous Validation Standards: Introduces stability-based model selection and dual-validation strategies (method-based and result-based) to address the "black box" nature of unsupervised clustering in immunology.
• Integration of PLMs: Seamlessly incorporates state-of-the-art protein language model embeddings into clustering and generative workflows.
• Benchmarking Infrastructure: Provides a standardized environment to compare generative models against ground-truth synthetic data.

4. Results: Three Use Cases

Use Case 1: Benchmarking Generative Models

• Setup: Three models (PWM, VAE, LSTM) were trained on synthetic TCR data with known epitope-specific k-mer signals.
• Findings:
  • LSTM generated the highest percentage of signal-specific sequences (98.88%) but suffered from high memorization (~43% of signals were exact training matches).
  • VAE produced fewer signal-specific sequences (74.52%) but generated a higher proportion of novel sequences (~73% were unseen in training).
  • PWM performed poorly (27% signal specificity) and failed to capture complex sequence distributions.
• Conclusion: The framework successfully quantified the trade-off between signal fidelity and novelty, demonstrating that different models learn different aspects of the sequence space.

Use Case 2: Clustering Epitope-Specific TCRs

• Setup: Applied to a large experimental IEDB dataset (~48k TCRβ sequences) and four synthetic datasets with varying cluster strengths.
• Findings:
  • Baseline: On synthetic data with strong signals, tcrdist + hierarchical clustering achieved high AMI (~0.8).
  • Experimental Data: On the IEDB dataset, no method achieved high AMI (~0.14), reflecting the biological complexity and noise of real-world data.
  • Stability: PLM-based embeddings (TCR-BERT, ProtT5) showed high stability across data splits, whereas tcrdist showed variability depending on cluster numbers.
  • Selection: tcrdist with hierarchical clustering was selected as the best approach for biological interpretability (capturing epitope/HLA info), despite moderate stability, and validated successfully on a held-out dataset.

Use Case 3: Confounder Analysis in IBD Data

• Setup: Analyzed paired single-cell TCR/BCR data from Inflammatory Bowel Disease (IBD) patients and healthy controls to detect batch effects.
• Findings:
  • Exploratory Analysis: Visualizations revealed that certain sequencing batches were exclusively associated with specific disease states (e.g., some batches had only healthy controls).
  • Clustering Stability: Clustering results were highly unstable (low ARI), indicating that no single clustering approach could robustly separate the data.
  • Batch vs. Biology: While some batches dominated specific clusters, the analysis concluded that batch effects did not completely overwrite biological signals. The repertoires did not inherit strong batch-specific sequence signatures that would make them indistinguishable from other batches.
• Conclusion: The workflow successfully identified potential confounders, guiding researchers to stratify by batch in future supervised analyses rather than discarding the data.

5. Significance

This paper marks a paradigm shift in AIRR analysis by moving from ad-hoc, single-task scripts to a systematic, reproducible, and rigorous unsupervised learning framework.

• Scientific Rigor: By enforcing stability assessments and dual-validation, immuneML reduces the risk of overinterpreting spurious clusters, a common pitfall in omics research.
• Biological Insight: The ability to benchmark generative models and detect confounders accelerates the development of biomarkers and therapeutic designs.
• Community Standard: The open-source nature (AGPL-3.0), integration with community standards (AIRR format), and extensive documentation position immuneML as a foundational tool for the next generation of immunological machine learning.