Variable (V), diversity (D), and joining (J) regions of lymphocyte immune cell receptor proteins are capable of undergoing recombination, which produces a set of unique alpha and beta chain pairs (aka clonotypes), the sum totality of which is sometimes called the repertoire of T and B cell populations. Measurements of clonotype diversity give researchers a nuanced and powerful view into the expansion of subpopulations of these cell types. Particular T cell and B cell receptors (TCR / BCR), and the diversity of these epitopes are vital to the proper function of the immune system, and can be indicators of changes in response to system perturbation.(1)

Immune repertoire analysis of single cells is now made possible by advances in single cell RNA sequencing. This is the process by which researchers will characterize T-Cell and B-Cell receptor diversity within a sample of using next generation sequencing techniques from one of a variety of platforms.(2)

However, the task of parsing and illustrating the information from V(D)J recombination can be quite complicated, due to the ‘many to many’ mapping of these relationships. Data required for this task include both the single-cell RNA-sequencing expression matrix for a sample, and the corresponding meta information on V(D)J identification, in CSV format.

The V(D)J Explorer plugin is meant to allow researchers to perform analysis of TCR/BCR sequencing data. Artifacts generated from the plugin, such as the most frequently occurring clonotypes can be used for further in depth analysis throughout SeqGeq’s platforms.


Installing the Plugin

The V(D)J Explorer plugin for SeqGeq has been coded in JavaFX, and therefore does not require any R connection or dependencies, thus you can simply download the plugin JAR file, and place that into your SeqGeq plugins folder. Restarting SeqGeq should illustrate that plugin within the workspace. 

More information on installing plugins.


Samples Section

Once the plugin has been run on an appropriately sequenced gene expression matrix (GEX) file, it will require a researcher connect the file to their V(D)J CSV meta info file, usually named “VDJ_perCell.csv” or “all_contig_annotations.csv”. This is accomplished by clicking on the GEX file within SeqGeq, and opening the VDJ Explorer. Click on “Add Metadata” within the resulting plugin dialog to choose the TCR and/or BCR meta-info CSV file(s):

This image has an empty alt attribute; its file name is MetaData.png

Selecting populations of interest for further comparison will indicate the number of total rows within the Metadata CSV mapped to the population(s) selected there:

Note: Rows in the metadata do not directly correspond to a particular number of cells because each barcode (associated with a given cell) can appear multiple times within the V(D)J sequencing. This is due to the nature of V(D)J sequencing, wherein many T and B cells will generate many different chains. Typically there will be about twice as many mapped rows as the number of cells in the population, since there are typically two chains for each cell. 



The ‘Cells’ tab of the VDJ Explorer gives researchers the ability to filter their Metadata file for cells corresponding to particular clonotypes of interest. This is achieved in part by applying filters to the Metadata columns displayed by right clicking on the column header of interest to apply a filter.

After applying the filter, you can select all of the cells in the list by pressing cmd+A (Ctrl+A on Windows) then right click and choose “Population from Selection” to create a new population in the workspace. You can then rename the population in the workspace appropriately.



Comparisons can be accessed in the Clonotypes and Populations section. Selecting Clonotypes on the left will allow for comparisons to be shown by selecting the Charts option at the top and selecting the desired Chart Type and X Axis options. Here we are comparing the top five clonotypes selected from the left, and their variable regions.

We can create a gate grouping the cells together with a specific clonotype combination by selecting the clonotype and choosing “Gate”. 



Selecting the Populations tab will allow users to perform comparisons between populations based on their V(D)J information. You can then select the Charts option and X Axis comparitor to view different plot types. Here we are comparing the T cell population vs the Top25_clonotype population and their variable gene usage across the populations.

The figures themselves can be exported from the plugin as PNG figures, or directly to the Layout Editor by clicking on the corresponding button within the main window of VDJ Explorer.


Differential Expression and Geneset Enrichment Analysis

As with any population in SeqGeq, we can begin to ask what the transcriptome is doing within clonotypes of interest using the Volcano Plotting tool to analyze differentially expressed genesets there, and follow that with Geneset Enrichment analyses:


Clonotypes Within Clusters

Clonotypes detected by V(D)J sequencing can be compared with unbiased clustering coming from other platforms in SeqGeq, and visualized in dimensionaly reduced spaces:



1. F. Alt, et al. “VDJ recombination.” Immunology Today 13.8. (1992)
2. M. De Simone, et. al. “Single Cell TCR Sequencing: techniques and future challenges.” Frontiers in Immunology 9. (2018)
3. J. Lin. “Divergence measures based on the Shannon entropy.” IEEE Transactions on Information Theory 37.1. (1991)