scRepertoire: An R-based toolkit for single-cell immune receptor analysis

Operation

System requirements for running scRepertoire³ include the installation of R v3.5.1 and the the Seurat R package (v3.1.2). Utilization of scRepertoire is dependent on the total number of single-cells being processed, with a base estimate of 1 Gb of random-access memory and a modern CPU.

Data

The isolation and processing of the 10x-Genomics-based single-cell mRNA and V(D)J Chromium sequencing data for immune cells has previously been described^7,8. In addition, T cells were identified using expression values for canonical T cell markers: CD3D, CD4, CD8A, CD8B1 and previous clustering. T cells were isolated and reclustered using the integration method from the Seurat R package (v3.1.2) with 20 principal components and a resolution of 0.5⁴. All code used to generate the figures appearing in the manuscript is available at https://github.com/ncborcherding/scRepertoire.

Implementation

The scRepertoire was built and tested in R v3.5.1. Analysis for scRepertoire was inspired from the bulk immune profiling tcR (v2.2.4) R package without derivations in code⁹. Clonotypes can be called using the combination of immune loci genes, a more sensitive approach, or the nucleotide/amino acid sequence of the complementary-determining region 3 (CDR3). In addition to the base functions in R, data processing was performed using the dplyr (v0.8.3) and reshape2 (v1.4.3) R packages. Visualizations are generated using the ggplot2 (v3.2.1) and ggalluvial (v0.11.1) R packages with color pallets derived from the use of colorRamps (v2.3) and RColorBrewer (v1.1.2) R packages. Diversity metrics are calculated using the vegan (v2.5-6) R package. Visual outputs of functions are stored as layers of geometric or statistical ggplot layering, allowing users to easily modify presentation.

Clonal analysis

scRepertoire³ can be used to call clonotypes using the CDR3 amino acid/nucleotide sequences, by gene usage, or by the combination of CDR3 nucleotide sequences and genes. Using the quantContig function, unique clonotypes can be visualized as raw values or scaled to the size of the library for samples or by type (Figure 2A). The total abundance of clonotypes can also be visualized calling abundanceContig (Figure 2B) or relative abundance of clonotypes (Figure 2C). Additionally, the distribution of CDR3 nucleotide or amino acid sequences for clonotypes can be visualized with lengthContig (Figure 2D). More advance distribution analysis is also available using the clonesizeDistribution function based on recent work using Jensen-Shannon divergence.

Figure 2. Basic clonotypic analysis functions in scRepertoire.

(A) Scaled unique clonotypes by total number of TCRs sequenced by patient and type of sample (peripheral, P; tumor, T), using the quantContig function. (B) Total abundance of clonotypes by sample and type using the abundanceContig function. (C) Relative abundance of clonotypes using density comparing peripheral blood to tumor samples. (D) CDR3 nucleotide length analysis by sample using the lengthContig function. The bimodal nature of the curve is a function of calling clonotypes for cells with both one and two immune receptors sequenced.

Proportional analysis and diversity measures

More in depth analysis of clonal architecture is available. Within the framework of scRepertoire, analysis of clonal homeostasis, or the clonal space occupied by clonotypes of specific proportions, can be visualized by clonalHomeostasis function (Figure 3A). Similarly, clonalProportion can be called to look at the proportion of clonal space occupied by specific clonotypes (Figure 3B). Overlap between the samples can be calculated and visualized with clonalOverlap, using either the overlap coefficient or Morisita index methods (Figure 3C). Measured of diversity across samples or groups can be quantified with the clonalDiversity function, demonstrating an overall reduction in clonal diversity in tumor samples (Figure 3D).

Figure 3. Advanced clonal measures between samples.

(A) Clonal homeostatic space representations across all six samples using the gene and CDR3 AA sequence for clonotype calling. (B) Relative proportional space occupied by specific clonotypes across all six samples using the gene and CDR3 AA sequence for clonotype calling. (C) Morisita overlap quantifications for clonotypes across all six samples. (D) Diversity measures based on clonotypes by sample type using Shannon, Inverse Simpson, Chao, and abundance-based coverage estimator (ACE) indices.

Expression interaction

After the processing and analysis of the TCR repertoire with the base features, the next step is using scRepertoire to interact with the single-cell mRNA data. The expression data for the 12,911 cells built into the package have already been clusters (Figure 4A), with a clear distribution of the clusters into peripheral-blood- versus tumor-predominant (Figure 4B). Using the combineExpression function in scRepertoire, we can look at the clonotypic frequencies of cells that comprise the UMAP-based clusters (Figure 4C). This function also works with the SingleCellExperiment and monocle3 class of expression objects. (Figure 4D). In addition to clonal distribution, we can also use highlightClonotypes to set specific sequences of clonotypes to be visualized (Figure 4D), with clonotype 1 referring to the amino acid sequence “CAVNGGSQGNLIF_CSAEREDTDTQYF” and clonotype 2 for the amino acid sequence "NA_CATSATLRVVAEKLFF". Interesting clonotype 2 is restricted to a subcluster of the C6 cluster (Figure 4D). After combining both the clonotype and expression data, interaction between categories, such as cluster label and clonotype frequency can be visualized with the alluvialClonotypes function (Figure 4E). This function can also be used to examine the dynamics of single or multiple expanded clonotypes across the categorical variables (Figure 4E). Further, after the attachment of the expression information to a single-cell expression object, the function, expression2List() allows users generate analyses based on any categorical variable in the meta data..

Figure 4. Interaction of scRepertoire with the single-cell expression R packages.

(A) UMAP projection from Seurat of the ccRCC T cells (n=12,911) into 12 distinct clusters. (B) UMAP projection with peripheral blood (red) and tumor (blued) populations highlighted and an accompanying relative proportion composition of each cluster, scaled by the total number of peripheral blood and tumor cells, respectively. (C) Using the combineExpression function places individual cells into groups by the number of clonotypes, which then can be displayed overlaid with the UMAP projection. (D) After combining the clonotype information with the Seurat object, highlightClonotypes can be used to specifically highlight the individual clonotypes of interest using the sequence information. (E) Interaction of clonotypes between multiple categories can be examined using the alluvialClonotypes function.

Source data

Zenodo: scRepertoire. https://doi.org/10.5281/zenodo.3856827³.

Folder ‘Data’ contains all data required to run the vignettes described in the Results. This is also available on GitHub.

Data are available under the terms of the Creative Commons Attribution 4.0 International license (CC-BY 4.0).