Convert Clonotypes to Cell Annotations

The Convert Clonotypes to Cell Annotations tool can be found in the Toolbox here:

        Immune Repertoire (Image sc_immune_rept_folder_open_16_n_p) | Convert Clonotypes to Cell Annotations (Image convert_cell_clonotypes_to_cell_annotations_16_n_p)

The tool takes a Cell Clonotypes (Image cell_clonotypes_16_n_p) element as input and produces a single Cell Annotations (Image cell_annotations_16_n_p) element, containing, for each barcode, the following categories for the identified (paired and unpaired) chain types and primary / secondary clonotypes (determined through the number of reads) (see figure 10.5):

Image cell_annotations_view
Figure 10.5: View of a Cell Annotations element obtained from the Convert Clonotypes to Cell Annotations tool, filtered to specific V genes and where only the V and J genes are shown for the primary clonotypes and the TRA + TRB, TRA and TRB chains. Not all barcodes have identified clonotypes for both TRA and TRB chains.

The output Cell Annotations element additionally contains the 'Clone size' for each barcode: the number of barcodes it shares its primary clonotype with.

Note: The clone size reflects only the paired primary clonotypes. Let us consider the following example, where each column represents one barcode, and the rows identify the $ \alpha$ and $ \beta$ clonotypes by name:

  B1 B2 B3  
Primary TRA clonotype TRA-1 TRA-2 TRA-1  
Primary TRB clonotype TRB-1 TRB-2 None  
Secondary TRA clonotype TRA-2 None None  
Secondary TRB clonotype TRB-2 None None  
Each barcode in this example has a clone size of one, because they are not sharing the paired primary TRA and TRB clonotypes with any other barcode, even though they have $ \alpha$ and $ \beta$ clonotypes in common. To obtain the clone size for other than paired primary clonotypes, the input Cell Clonotypes can be first filtered using the Filter Cell Clonotypes tool, see Filter Cell Clonotypes

Using the resulting Cell Annotations element, the cells can be colored by any of the above categories in a Dimensionality Reduction Plot (see Dimensionality reduction) obtained from matched scRNA-Seq data for the same cells (see figure 10.6).

The cells in the Dimensionality Reduction Plot and those in the Cell Annotations need to have the same sample name. Ideally, it should be ensured that these share the sample name as a first step in the analysis pipeline, when running the Annotate Reads with Cell and UMI tool (see Annotate Reads with Cell and UMI), or when importing the Cell Clonotypes element (see Import Cell Clonotypes). If this has not been done, the sample name can be updated using the Update to Common Sample Name tool (see Update to Common Sample Name).

Image umap_with_annotations
Figure 10.6: UMAP view of scRNA-Seq data, where cells are colored by the V gene from the TRB chain.

Note that the Convert Clonotypes to Cell Annotations tool only converts the primary and secondary clontypes for each barcode. The Cell Clonotypes created by the Single Cell TCR-Seq Analysis only contain primary / secondary clonotypes, but the Combine Cell Clonotypes tool can lead to barcodes containing more clonotypes.