10x Genomics
Chromium Single Cell Immune Profiling
Cell Ranger5.0 (latest), printed on 12/22/2024
Loupe V(D)J Browser User Interface: Clonotype Distribution and Sequence
The first two pages of this tutorial provide a quick tour of the Loupe V(D)J Browser user interface with the tutorial dataset (T cell spike-in) loaded. There are two tabs to explore:
This page is is a walk-through of the Clonotype Distribution and Sequence tab.
Clonotype list and distribution
The Clonotype Distribution and Sequence tab has two main panels. The Clonotype Views (left) panel lists all the clonotypes in the dataset, sorted by abundance. For each clonotype, chains associated with that clonotype (TRA and TRB in this case) are listed as rows, along with their corresponding V, D, and J gene segments, CDR3 sequences, and the number of 10x Barcodes comprising that clonotype.
The right panel is the Clonotype Distribution plot, showing all cells grouped by clonotypes. Each dot represents a single cell (cell-associated 10x Barcode). Barcodes are grouped by clonotype ID and white spaces separate the different clonotypes. Larger clonotypes are in the center and smaller clonotypes are towards the periphery. Hovering over the graph highlights all the cells belonging to that clonotype as well the corresponding row for that clonotype in the Clonotype Views panel.
For example, hovering over the largest clonotype in the T cell spike-in dataset (blue dots) highlights the first row on the Clonotype Views panel.
Click, hold, and move your cursor around to explore the edges of the Clonotype Distribution plot. A zoom panel is provided on the top left to allow close examination of smaller clonotypes.
If an Antigen Capture library was included in the analysis, the cells in the Clonotype Distribution plot can be colored by antigen specificity score or antigen UMI counts (on a linear or log scale). Use the drop-down menu to select your antigen of interest:
Note that Loupe V(D)J Browser v5.0 extracts antigen names from the Feature Reference CSV provided to the Cell Ranger multi pipeline. These names cannot be changed via the Loupe V(D)J browser interface. To rename antigens, you must re-run the Cell Ranger multi pipeline with the correct antigen names in your Feature Reference CSV.
To export the customized Clonotype Distribution plot in PNG or SVG format, click on the Export Plot drop-down button on the top right.
Sequence view
You may click on the clonotype of interest in either the Clonotype Distribution plot (right) or the Clonotype Views list to enter the Sequences view. The default is a zoomed-out view that shows the alignment of the various exact subclonotypes in this clonotype to the universal reference, the donor reference, and the consensus sequence. Each exact subclonotype is a row in the alignment.
Use the Select Antigen(s) section on the top of this view to get antigen specificity scores or UMI counts for each exact subclonotype listed here. In this example, the clonotype includes two exact subclonotypes each with an antigen specificity score of 100 for the SARS-CoV-2 (COVID) antigen; one exact subclonotype has 570 barcodes and the other has a single barcode.
Hover over the exact subclonotype of interest for more information. The pop-up window also has the option to download a list of all barcodes in that exact subclonotype as a CSV file.
You can also star exact subclonotypes of interest by clicking on the star sign displayed in the Sequences view. Starred barcodes can be filtered from the clonotype list on the Clonotype Views panel by toggling to Show Starred Only.
Click on the Zoom + button on the top right of the Sequences view or simply click on the grey part of the sequence alignment to obtain nucleotide sequences for full-length V, D, and J gene segments present in these exact subclonotypes. Start codon, insertions, deletions, mismatches, soft clips, and CDR3 regions are highlighted (see legend).
To export sequences in CSV format, click on the Export Sequences button located at the top right of the Sequences view.
Filtering clonotypes based on antigen specificity or UMI counts per antigen
Video tutorial:
The new Loupe V(D)J browser has an improved user interface with options to filter data based on UMI counts per antigen or antigen specificity scores for antigens of interest. Click on the blue Open Filter button at the top of the Clonotype Views panel to open up the filtering window. Alternatively, clicking on the up arrow at the bottom right of the browser also expands the filtering window, as shown in this image:
In the filter window, there are two tabs:
- Antigen Specificity: only highlight cells that are within a user-specified antigen specificity score range per antigen of interest
- UMI Counts per Antigen: only highlight cells that are within a user-specified range of antigen UMI counts per antigen of interest
Hover over the ? next to each tab to learn more about the metric. The ranges can be customized by dragging the sliding scale bar for each antigen of interest, or by manually entering the desired min and max values in the text boxes provided next to the adjustable scale.
Buttons are provided to quickly Reset all to 0 and Reset all to full range.
The middle section of the filter window has additional filtering options:
- Cluster from an imported
.cloupefile: import a.cloupefile and filter clonotypes belonging to specific graph-based or K-means gene expression clusters. Visit the Integrated Analysis section to learn more. - Barcodes in Clonotype: filter clonotypes based on a numeric range of barcodes (or cells) belonging to that clonotype. For example, setting this range as 450-2,590 filters out any clonotypes that have fewer than 450 or greater than 2,590 cells.
- Gene: enter the name of specific V, D, or J genes of interest and filter out any clonotypes that do not have these genes.
- CDR3 Amino: Filter clonotypes by CDR3 amino acids of interest. If the CDR3 of any chain in a clonotype contains those residues, 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
SAR.Vsearch sequence will find chains withSARAV,SARIV, andSARPVresidues, among others. - CDR3 Bases: Filter clonotypes by CDR3 nucleotide bases of interest.
- Barcode: Search for a specific 10x Barcode of interest. You may want to search for individual cell barcodes identified by secondary analysis, and searching by barcode allows you to pinpoint these individual cells. The barcode must be an exact match; wild cards are not allowed.
- iNKT/MAIT: Filter T cells that have supporting evidence of being iNKT/MAIT. Identifies clonotypes with potential invariant natural killer T (iNKT) and mucosal-associated invariant T (MAIT) cells using the iNKT/MAIT Evidence filter. The resulting list will show clonotypes with cells that have supporting evidence in any of the TRA genes, TRA junctions, TRB genes, or TRB junctions of being an iNKT or MAIT cell. Further details on the identification criteria can be found in the Cell Ranger documentation. In addition to identifying clonotypes with iNKT evidence or MAIT evidence, there is also the option to filter out clonotypes with any evidence using the Neither filter, or use Both for results that show iNKT and MAIT evidence in the same clonotype. Hover over the
?next to metric to learn more. - Isotype: for VDJ-B libraries, Loupe V(D)J Browser includes an isotype filter that allows you to filter for specific B cell isotypes.
In this example, we are filtering for cells that have an antigen specificity score >90 for SARS-CoV-2 (COVID) antigen, and for clonotypes that have the TRBJ2-7 gene with at least 450 barcodes. As you can see, filtering the data dynamically changes the Total Results panel displayed on the bottom right. The current filtration criteria include one clonotype (out of 195) and 571 barcodes.
You can save filtration criteria for future use by clicking on the three dots in the text box by Clonotype Views. Click the Edit View Name to customize the name of the filter.
Loupe V(D)J Browser v5.0 and later also has a Copy Filter Rules button on the top right of the Filter window that copies the filtration criteria to the clipboard. This feature makes it easy for users to copy and paste filtration rules to a text file or digital lab notebook for future use.
Clicking on + New View allows you to visualize the unfiltered data and create new filter settings. The default name of a new filter is 'Untitled_View_#'. You can create multiple filtration views and use the drop-down arrow to toggle between views.
Saving filters
Loupe V(D)J Browser allows you to save your .vloupe file with all the filtration criteria. Click the save button on the top right to overwrite the existing vloupe file. Alternatively, select File --> Save As.. to write to a new .vloupe file.