Introduction

High-throughput sequencing technologies are foundational to modern biomedical innovation, driving advancements across various fields. Single-cell technologies stand out for their unparalleled ability to dissect cellular heterogeneity and dynamics across tissues and conditions, making them indispensable in immunology and oncology research. By combining scRNA-seq with scAIRR-seq, derived either through direct sequencing or inference from transcriptomic data, researchers can concurrently analyze gene expression and immune receptor diversity at the single-cell level [1]. The capability to profile both the transcriptional states and clonotype structures of T and B cells through scRNA and scAIRR data provides a robust framework for tracking immune cell activation, clonal expansion, and persistence. These are critical parameters for assessing vaccine efficacy, evaluating immune responses in cancer, responses in cellular therapies, like chimeric antigen receptor T-cell therapies, and elucidating mechanisms underlying autoimmune diseases [2].

Despite the rapid growth of scAIRR analysis, limitations remain with existing tools (reviewed in S1 Table), primarily available in Python and R [3]. Many tools lack robust integration for immune receptor profiling with transcriptomic data or flexibility in data export formats, which hinders reproducibility and cross-platform compatibility in expanding datasets [3]. The increasing demand for standardized, flexible, and scalable analysis frameworks underscores the need for improved software solutions in this field. The growing size and scope of single-cell data creation also underscores this need for improved standardization and efficiency.

The initial release of scRepertoire addressed some of these needs, establishing itself as an integral tool within single-cell workflows due to its compatibility with widely used R-based single-cell analysis platforms like Seurat and SingleCellExperiment [4]. scRepertoire enabled researchers to merge, filter, and visualize clonotype data, offering essential resources for the in-depth characterization of immune repertoires at the single-cell level. As one of the first open-source packages for scAIRR analysis, scRepertoire has over 32,000 downloads from Bioconductor and is a broad utility for the field. Nevertheless, much like the fast-paced changes in scRNA analysis, scRepertoire required a significant rebuild to support new and emerging analyses and increasing sizes of experimental data sets.

Here, we present the latest release of scRepertoire, which introduces a suite of powerful new features and enhancements aimed at refining immune receptor analysis and visualization and are the focus of the Design and Implementation section. This update includes advanced tools for summarizing amino acid sequences, such as positional entropy and residue-specific composition profiles, alongside visualizations of Kmer distributions and gene pairings. User utilities have been optimized for speed, with faster generation of clonal pairs (S1 Fig), improved clustering, and expanded support for importing and exporting clone data across data types. Additional features include identifying T and B cell receptor (TCR/BCR) doublets and improved repertoire comparisons with customizable normalization. scRepertoire seamlessly interacts with deep learning modules such as Trex [5], Ibex [6], and ImmApex [7] and other packages, such as APackOfTheClones [8], scPlotter [9], and DandelionR [10], facilitating a more comprehensive and scalable approach to single-cell immune profiling.

Design and implementation

Workflow

The scRepertoire package provides a comprehensive, R-based framework for immune repertoire analysis, seamlessly integrating clonotype data with transcriptomic profiles to enable sophisticated insights into immune cell populations (Fig 1). The recent redesign of scRepertoire emphasizes accessibility and usability, with universalized function names and language to make the package approachable for novice and experienced users. Documentation has been significantly expanded, and a dedicated pkgdown website now hosts extensive examples tutorials, and documentation, creating a readily accessible knowledge base for users to maximize the package’s capabilities. A full summary of the changes is available in S2 Table.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 1. Schematic overview of the scRepertoire workflow and analyses.

Sequence alignments from standard pipelines or custom reconstruction methods are directly imported into scRepertoire, which performs filtering and pairing of B- or T-lymphocyte receptors. A variety of clonal analyses and visualizations are then available, with the resulting immune receptor data seamlessly attachable to single-cell RNA, protein, or chromatin assays processed via Seurat or SingleCellExperiment. scRepertoire also offers native compatibility with immApex, Trex, and Ibex, enabling deep-learning–based embeddings of scAIRR sequences for classifier development or multimodal data integration. The figure utilizes images from the NIAID BioArt (https://bioart.niaid.nih.gov/) repository under the CC-BY license.

https://doi.org/10.1371/journal.pcbi.1012760.g001

This workflow processes data from multiple sequencing and alignment formats (e.g., TSV, JSON, CSV) and is compatible with outputs from widely used alignment pipelines, supporting flexibility in data input. Following data import, scRepertoire performs stringent clonal pairing and quality control to assign clonotypes at the single-cell level. The assignment of paired clones allows for robust clonal analysis that quantifies and visualizes clonal expansion and lineage relationships within B-cell and T-cell populations. By linking RNA expression data with clonal sequences, scRepertoire provides an integrative view of immune clonotypes within their transcriptional context, which is essential for uncovering immune cells’ functional states and diversity, such as analyzing pathogenic sequences in autoimmunity [11] (S2 Fig) or vaccination responses [5] (S3 Fig). In addition to core analysis capabilities, scRepertoire supports downstream applications through compatible tools: Trex, Ibex, and immApex, which aid in the development of models and classifiers for the TCR, BCR, or adaptive immune receptors, respectively. These extensions allow users to tailor their analyses toward specific receptor types and leverage advanced computational techniques, including machine learning, for predictive modeling.

Results

An example data set for exploring scRepertoire capabilities is provided by Jiang et al. [13]. This data set includes single-cell RNA and immune profiling (both TCR and BCR) of erythema migrans lesions (SKL) and adjacent normal skin (SKN), offering a unique view into immune activity in distinct tissue microenvironments. The cohort consists of six distinct patients. However, two samples were removed for the downstream analyses due to the lack of scAIRR sequences or lack of sequencing of a secondary tissue. After quality control filtering, individual lymphocytes with productive scAIRR sequences were retained, identifying 13 distinct cell types (Fig 2A). These cell types demonstrated varied clonal expansion profiles, providing insights into immune cell dynamics within the tissue (Fig 2B).

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 2. Single-cell analysis of lymphocytes in erythema migrans lesions and adjacent normal skin.

A. UMAP projection derived from single-cell RNA and TCR/BCR sequencing, revealing distinct lymphocyte subpopulations. B. UMAP overlay highlighting clonal expansion by relative frequency. Bar plots illustrate occupied clonal space, ranked by clone size and stratified by lymphocyte cell type. C. Alluvial plots showing TCR clones shared among erythema migrans lesions (SKL), adjacent normal skin (SKN), and blood (BL), featuring the top 20 clones per patient by repertoire proportion. D. Bootstrapped Shannon and inverse Simpson diversity values for each sequencing run with clonal rarefaction and extrapolation curves based on Shannon diversity indices. E. Proportion of amino acids and mean Atchley factor values across the heavy-chain CDR3 region for samples 192566 and 192567. F. Heatmap of TRAV gene usage alongside principal component analysis of sequencing runs. G. TRA chain clustering based on amino acid sequences using a normalized Levenshtein edit distance threshold (0.85), visualized on a UMAP and via a Fruchterman–Reingold layout in igraph. The dot size indicates the number of sequences or extent of clonal expansion.

https://doi.org/10.1371/journal.pcbi.1012760.g002

Plasma cells exhibited the most prominent clonal expansion among the identified cell types. In the 192567SKL sample, a single clone accounted for over 50% of the cluster, highlighting its dominant presence (Fig 2B). Other cell types with significant expansion included CD4 + tissue effector memory (CD4_TEM) cells, cytotoxic CD8 + T (CD8_CTL) cells, and mucosal-associated invariant T (MAIT) cells. These findings underscore the diversity of clonal activity across immune cell populations.

To further explore immune dynamics, the top 20 TCR clones were examined for clonal sharing across tissues within the same patient (Fig 2C). Notably, overlap was observed between SKN and SKL samples, suggesting potential roles for tissue-resident T cells in both environments. In the 192566 sample, which included sequencing from peripheral blood (BL), top TCR clones shared between BL and SKL samples were mutually exclusive of SKN samples. This finding suggests specific trafficking or retention mechanisms. Interestingly, no BCR clonal sharing was observed across tissues, potentially reflecting different modes of immune compartmentalization or low overall sampling.

To quantify repertoire diversity, scRepertoire applied Shannon diversity and inverse Simpson diversity estimates (Fig 2D). By bootstrapping across the smallest repertoire in the comparison group and averaging results from 100 runs, scRepertoire provided robust diversity estimates. Additionally, diversity metrics enabled interpolation and extrapolation using the iNEXT package [14], facilitating rarefaction and sample completeness assessments. These analyses revealed differences in diversity that may correspond to distinct immune pressures or clonal selection processes.

Repertoire summarization within scRepertoire provided additional insights into amino acid use and sequence properties. For the two samples with BCR sequences within multiple tissues, CDR3 sequence analysis revealed a predominant usage of serine (S) at positions 6 and 11 in sample 192567 (Fig 2E). Analysis of amino acid properties, such as Atchley factors (AF) [16], indicated positional decreases in molecular size (AF3) and electrostatic charge (AF5) associated with these serine-enriched positions, potentially influencing antigen-binding characteristics.

Additional summarization approaches included calculating the percentage of amino acid Kmers, VJ gene pairing, and single gene usage within scAIRR chains (Fig 2F). These metrics provided a comprehensive overview of repertoire composition. Dimensional reduction techniques, such as principal component analysis, were applied to exported data (Fig 2F). Clustering of clones by nucleotide or amino acid sequence, based on normalized Levenshtein distance (using 0.85 as a threshold), can enable the identification of potential antigen-driven selection pressures (Fig 2G). Clustering could be performed across all sequences or grouped by categorical variables, such as patient samples. Moreover, scRepertoire supports exporting clustering networks as igraph objects [17], facilitating integration with network-science-based analytical tools.

These analyses illustrate the breadth of scRepertoire’s capabilities for immune repertoire analysis. Additional analyses across several pathological states are available in S2 and S3 Figs. By integrating sequence-level insights with functional and diversity metrics, scRepertoire provides a robust framework for studying immune responses in complex tissue environments.

Availability and future directions

scRepertoire is built within the R framework and is freely available under the MIT license. It is hosted on Bioconductor (https://bioconductor.org/packages/scRepertoire). Comprehensive documentation, tutorials, and source code are provided to support users at https://github.com/BorchLab/scRepertoire. The code and detailed methods for reproducing the erythema migrans and supplemental analyses are available at https://github.com/BorchLab/scRepertoire.v2_manuscript.

Future development plans for scRepertoire focus on enhancing its interoperability with other immune receptor analysis tools. Improved compatibility will encourage custom extensions and collaborative tool development, fostering the growth of related packages such as ApackOfTheClones [8] and DandelionR [10]. These integrations aim to streamline workflows for users analyzing complex single-cell immune repertoires.

Another key development area is incorporating advanced statistical methods and machine learning applications within scRepertoire and its compatible extensions. These enhancements will allow the uncovering of deeper insights into immune repertoire dynamics, predict immune responses, and identify biomarkers for clinical and research purposes. Many of these areas are active in terms of research and development (reviewed in [18]). In the long term, scRepertoire’s framework should be extended to accommodate multi-omics integration. For example, combining immune repertoire data with spatial transcriptomics or proteomics could provide a more comprehensive picture of immune responses, such as the interaction of adaptive immune cells with the microenvironment (spatial) or high throughput antigen discovery (proteomics).

Supporting information

Acknowledgments

From the time of original publishing to scRepertoire 2, the community that uses scRepertoire has contributed consistently to improving the package. We would like to specifically acknowledge the users that directly contributed code to the package: Massimo Andreatta, Nicholas Bormann, Scott Nicholas Furlan, Gloria Kraus, I-Hsuan Lin, Jacqueline HY Siu, Kelvin Tuong, and Panwen Wang. Also, we thank GitHub users Simon-Leonard and Liripo. In addition, we would like to thank Jonathan Noonan and Kyle Romine their constructive suggestions for scRepertoire improvements. We also thank Philip Mudd and Michael Paley for the valuable insights into their data sets that appear in the supplemental figures.