10x Genomics
Chromium Single Cell Immune Profiling

Cell Ranger2.1, printed on 12/18/2024

Loupe V(D)J Browser: Exploring Clonotypes

Loupe V(D)J Browser includes a variety of tools to explore the diversity of clonotypes across your entire sample, and to more precisely hone in on individual clonotypes, genes, motifs, or even individual cell barcodes. You can use the summary charts to look at the diversity of your data at a high level, and use tools both within the clonotype list and the summary charts to filter clonotypes by a variety of criteria.

Summary Charts

There are seven different charts through which you can investigate the diversity of a V(D)J sample: clonotype abundance, CDR3 abundance, V gene usage, D gene usage, J gene usage, C gene usage, and a V-J gene heatmap. Each chart comes with various viewing options and can be used to filter the clonotype list. They also support the ability to export the data as a CSV table, a PNG image, or an SVG drawing via the Export As button in the upper right. You can select a chart from the Chart Type dropdown at upper left. The question mark above the chart selector will show help text for the current chart, but here's an overview:

Clonotype Abundance

This chart shows the most common clonotypes, from most to least abundant. It's a more compact representation of the barcode counts in the clonotype list at right. You can change the number of top clonotypes to show by typing a new number in the Num Top Clonotypes input box above the chart. As with all bar charts in the Summary Chart View, you can change the y-axis to reflect either absolute clonotype count or percent of clonotypes (or genes) that each bar represents. You should see that the tutorial sample has one fairly abundant clonotype, and a few other repeated clonotypes. Then abundance quickly drops off, and we see a long tail of singleton clonotypes represented once each.

CDR3 Abundance

Select CDR3 Abundance from the Chart Type selector. This chart is similar to the Clonotype Abundance plot except that it shows the abundance of CDR3 sequences within individual chains. It counts all chains with each CDR3 detected in the sample. In this plot, you can view one chain type at a time.

Other features of the CDR3 Abundance chart are the same as the Clonotype Abundance plot. You can change the number of clonotypes shown, as well as the y-axis type.

V, D, J, and C Gene Usage

Select V Gene Usage from the Chart Type selector. The chart in the content panel will change to a histogram of V gene frequency across the sample. The y-axis is the number of cells in which a particular V gene was expressed. You can see that the most numerous V gene in this sample is TRAV1-2, which was detected in transcripts with 229 distinct cell barcodes.

The Chain Type selection box allows you to see all chain types or to limit the chart to one chain type. In this case, we can see options TRA and TRB; if our sample included B cells, we would have IGH, IGK, and IGL as well. In addition, clicking on an individual bar will filter the clonotype list to only those clonotypes with that gene annotated. For example, if you click on the TRAV1-2 bar, you'll only see clonotypes with a TRAV1-2 gene in one of the chain sequences, as shown below:

Note that the clonotype list filter is now populated with Gene Name: TRAV1-1, and that the genes which match the filter are highlighted in the clonotype list at right.

The D, J, and C Gene Usage plots are analogous. They show their respective gene usage charts with the same functionality. You can view them by selecting them from the Chart Type selector.

V-J Gene Heatmap

Finally, select V-J Gene Heatmap from the Chart Type selector to see the V-J Gene Heatmap. Through this chart, you can view the frequency of V-J gene pairings across your sample. Each box in the heatmap represents the number of cells in which Cell Ranger detected transcripts with the specified V gene (column) and J gene (row). If a particular box is yellow, no such transcripts were detected in the sample. Darker colors show more frequent V-J gene pairings. If you hover over each box, you'll see the names of the V and J genes as well as the frequency of the pairing. Clicking on a box will filter clonotypes with chains featuring both the selected V and J genes. After clicking the TRAV10/TRAJ18 cell, you should see the clonotype list filtered as shown below:

Filtering via the Clonotype List

In addition to filtering by clicking on the graphs, you can use the tools below the clonotype list to find clonotypes in a variety of ways. You can select a filtering method via the Filter By box, and enter a value in the input box to its right. To clear a filter and see the complete clonotype list, press the X button at bottom right. Matching chains within a clonotype will appear darkened in the clonotype list. Each filtering method is a little different, as described below:

Gene Names

When the Gene Name filtering method is selected, Loupe V(D)J Browser will attempt to autocomplete the gene you're looking for by popping up a menu above the input box as you start typing. You can select a gene with your mouse or press enter. Selecting a gene will add it to the filter list. The clonotype list will only show chains that match all the gene annotations in the input box. To remove a gene, you can press the X next to a gene, or press delete.

CDR3 Amino and CDR3 Bases

You can filter by CDR3 Amino (residues), or by CDR3 Bases (nucleotides). In both cases, the clonotype list will be filtered by partial CDR3 match; that is, if the CDR3 of any chain in a clonotype contains those residues or bases, the clonotype will remain in the list. Use the '.' character to include a wild-card residue or base match in both modes. For example, in CDR3 Amino mode, the T.N search sequence will find chains with TEN, TSN, TWN residues, among others.

As a convenient shortcut, you can search for all clonotypes containing a chain with the CDR3 of the currently selected chain by clicking the button labeled "Find Like CDR3s", located at the bottom of the content panel.

Clusters

If you have a matching 5′ gene expression dataset, you can load the .cloupe file generated by cellranger count into the Loupe V(D)J Browser to filter the clonotype list by clusters created in Loupe Cell Browser. To learn how to do this as well as other analyses with matching 5′ gene expression and V(D)J data, check out the Loupe Integrated Gene Expression and V(D)J Analysis Tutorial.

Barcode and Contig Id (Advanced)

You may want to search for individual cell barcodes identified by secondary analysis, or compile a list of interesting contigs for a particular sample for further investigation. Searching by barcode or by contig id will allow you to pinpoint these individual cells or contigs. The barcode or contig id must be an exact match; there are no wild cards allowed.

Now that you can find the clonotypes you're looking for, it's time to explore them in more detail, by exploring individual chains.

Next: Exploring Chains