
The three goals of V(D)J contig annotation are to 1) define the alignments of V, D, and J segments to a contig, 2) identify CDR3 sequences, and 3) from these data determine if a contig is productive, meaning that it is likely to correspond to a functional T or B cell receptor. <Image src={"https://cdn.10xgenomics.com/image/upload/v1654273212/software-support/vdj/algorithms/annotation.png"} />

<LinkableSection id={"alignment"} title={"Alignment to the V(D)J reference"}>

Cell Ranger first determines if the data are TCR or BCR. Then it aligns all contigs to the corresponding (TCR or BCR) reference sequences. Occasionally, contigs are aligned to both references. Alignment is seeded on 12-mer perfect matches, followed by heuristic extension. Cell Ranger also searches backwards from C segment alignments for J segment alignments that do not have 12-mer perfect matches, as these will arise occasionally from somatic hypermutation.

The choice of V(D)J reference sequences in an alignment can be arbitrary, depending on how similar the reference sequences are to each other. For D segments, which are short and highly mutated, it may not be possible to find a confident alignment.

</LinkableSection>

<LinkableSection id={"productive"} title={"Productive Contigs"}>

A contig is termed **productive** if the following conditions are met:

- **Full length requirement.** The contig matches the initial part of a V gene. The contig continues on, ultimately matching the terminal part of a J gene.
- **Start requirement.** The initial part of the V matches a start codon on the contig. Note that in the human and mouse reference sequences supplied by 10x Genomics, every V segment begins with a start codon.
- **Nonstop requirement.** There is no stop codon between the V start and the J stop.
- **In-frame requirement.** The J stop minus the V start equals one mod three. This just says that the codons on the V and J segments are in frame.
- **CDR3 requirement.** There is an annotated CDR3 sequence ([see below](#cdr3)).
- **Structure requirement.** Let VJ denote the sum of the lengths of the V and J segments. Let len denote the J stop minus the V start, measured on the contig. Then VJ - len lies between -25 and +25, except for IGH, which must be between -55 and +25. This condition is imposed to preclude anomalous structure changes that are unlikely to correspond to functional proteins.

</LinkableSection>

<LinkableSection id={"cdr3"} title={"CDR3"}>

For each contig, Cell Ranger searches for a CDR3 sequence using the conserved sequence that flanks the CDR3 region. Then the CDR3 sequence and its flanking regions are compared to motifs derived from V and J reference segments for human and mouse, as shown below. A letter represents a specific amino acid and a dot represents any amino acid:

```
left flank   CDR3   right flank
LQPEDSAVYY   C...   LTFG.GTRVTV
VEASQTGTYF          LIWG.GSKLSI
ATSGQASLYL
```

Cell Ranger requires that a CDR3 sequence have at least 5 amino acids, start with a C, and not contain a stop codon. The flanking sequences for a candidate CDR3 are matched against the above motifs, and scored +1 for each position that matches one of the entries in a column.

For example, `LTY....` scores 2 for the first three amino acids in the right flank. `L` matches an entry in the first column, contributing 1 to the score. `T` matches an entry in the second column, contributing 1 to the score. `Y` does not match the third column, and does not contribute to the score.

For a candidate CDR3 to be declared a CDR3 sequence, it must score at least 10. In addition the left flank must contribute at least 3 and the right flank must contribute at least 4.

Next, Cell Ranger finds the implied stop position of the end of the V segment on the contig. The implied stop is the start position of the V segment on the contig plus the length of the V segment. The CDR3 sequence is required to start at most 10 bases before the stop, and at most 20 bases after the stop of the V. These conditions for finding an implied stop are not applied in the denovo case.

If there is more than one CDR3 sequence, Cell Ranger chooses the one with the highest score. If there is a tie, the one with the later start position on the contig is chosen. If a tie remains, the longer CDR3 is chosen.

</LinkableSection>

<LinkableSection id={"inkt"} title={"iNKT and MAIT cell annotation"}>

Cell Ranger v5.0 and later annotates T cells as likely iNKT or MAIT cells based on the TCR V genes, J genes, and CDR3 sequences of the TCR alpha and TCR beta. For more information about iNKT and MAIT cells and how the annotation is performed, please see the [iNKT and MAIT cell Algorithms documentation](/support/software/cell-ranger/7.2/hidden/cr-5p-vdj-algorithm-inktmait).

</LinkableSection>


V(D)J Annotation


<LinkableSection id={"intro"} title={"Assembly process overview"}>

The assembly process takes the reads for a single barcode as input. These reads are then glued together, outputting a set of assembled contigs that represent the best estimate of transcript sequences present. Each base in each contig is assigned a quality value. The numbers of UMIs and reads supporting each contig are also tracked.

<Image src={"https://cdn.10xgenomics.com/image/upload/v1654273212/software-support/vdj/algorithms/assembly.png"} />

**The assembler uses the V(D)J reference sequence during assembly, unless the pipeline is run in de novo mode.** Parts of the [Annotation Algorithm](/support/software/cell-ranger/7.2/hidden/cr-5p-vdj-algorithm-annotations) page may be relevant to learn more about more about the assembly process.

Contig assembly is complicated by noise that can arise from many sources. Some sources of noice include:

- Background (extracellular) mRNA
- Cell doublets
- Errors in transcription in the cell
- Errors in reverse transcription to make cDNA
- Random errors during sequencing
- Index hopping in the sequencing process

### Steps in the assembly algorithm

| Step                                              | Operation                                                                                                                         |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [Adapter trimming](#adapter)                      | Trim adapters using a custom algorithm.                                                                                           |
| [Read subsampling](#subsampling)                  | Downsample reads for a given barcode to retain a maximum of 80,000 reads. >80,000 reads do not improve results.                   |
| [Read trimming](#trimming)                        | Trim off nucleotides in the read after the enrichment primers.                                                                    |
| [Graph formation](#graph)                         | Build a De Bruijn graph using kmer length (k) = 20                                                                                |
| [Reference-free graph simplification](#simp1)     | Simplify the graph by removing noisy edges.                                                                                       |
| [Reference-assisted graph simplification](#simp2) | Use the V(D)J reference to remove noisy edges.                                                                                    |
| [UMI filtering](#umifilt)                         | Filter out UMIs that are likely to be artifacts.                                                                                  |
| [Contig construction](#contigs)                   | Build contigs by looking for the best path through the graph for each UMI.                                                        |
| [Competitive deletion of contigs](#competitive)   | Compare contigs, remove weak contigs that are likely to be artifacts.                                                             |
| [Contig confidence](#confidence)                  | Define high confidence contigs that are likely to represent bona fide transcripts from a single cell (associated to one barcode). |
| [Contig quality scores](#quality)                 | Assign a quality score to each base on each contig.                                                                               |

</LinkableSection>

<LinkableSection id={"adapter"} title={"Adapter trimming"}>

Known adapter and primer sequences from the 5’ and 3’ ends of reads are trimmed using a custom 10x Genomics trimming tool.

</LinkableSection>

<LinkableSection id={"subsampling"} title={"Read subsampling"}>

Some cells have extremely high coverage. High coverage could be either due to true high sequencing coverage, or high mRNA expression in plasma cells (commonly seen in BCR).

Very high coverage (greater than 80,000 reads) of transcripts can be problematic because it degrades computational performance and adds little information. Therefore, coverage is capped to a maximum of 80,000 reads per barcode. If there are more than 80,000 reads for a any given 10x Barcode, the reads are downsampled.

</LinkableSection>

<LinkableSection id={"trimming"} title={"Read trimming"}>

The inner enrichment primers hybridize to constant regions of V(D)J genes. Any bases to the right of those positions should not be present in the data. They are trimmed from the reads.

</LinkableSection>

<LinkableSection id={"graph"} title={"Graph formation"}>

A De Bruijn graph using k = 20 is created and transformed into a directed graph. The edges of the graph are DNA sequences corresponding to unbranched paths in the De Bruijn graph.

</LinkableSection>

<LinkableSection id={"simp1"} title={"Reference-free graph simplification"}>

A collection of heuristic steps is applied to simplify the graph. During this process read support on each edge is tracked and edited. Several examples of simplification steps are described:

1.  **Branch cleaning**:

    - For each branch in the graph, and for each UMI, if one branch has ten times more reads than a second branch, read support for the UMI from the second branch is removed.
    - When two branches emanate from a vertex, the weaker branch is deleted based on these criteria:

      - There are at least twice as many reads on the strong branch.
      - There are fewer than 8 reads for any UMI on the weak branch.
      - For every UMI, the strong branch has twice as many reads as the weak branch with utmost one exception (such as events like alternate splicing) where the event is supported by only one UMI.

2.  **Path cleaning**: For each UMI, the strongest path is defined. Then graph edges that are not on this path are deleted.
3.  **Component cleaning**: For each UMI, if one graph component has ten times more reads supporting it than a second component, the read support for the second component is deleted.

</LinkableSection>

<LinkableSection id={"simp2"} title={"Reference-assisted graph simplification"}>

If the pipeline is run in reference-assisted mode (not de novo assembly), bubbles in the graph are popped with the aid of the reference sequence. There are several heuristic tests, all of which require that both bubble branches have the same length. An example scenario is when branch 1 is supported by at least three UMIs and has a kmer matching the reference, whereas branch 2 is supported by a single UMI, and has no kmers matching the reference. In this scenario, the weaker branch (branch 2) is deleted.

</LinkableSection>

<LinkableSection id={"umifilt"} title={"UMI filtering"}>

UMIs that survive these filtration steps are retained:

1.  Find the single strongest path for each UMI. A strong path either contains a reference kmer, or if assembled de novo, matches a primer (described above).
2.  Find good graph edges that appear on one or more strong paths.
3.  Sort the reads based on these good graph edge assignments.
4.  Find the UMIs for these reads.
5.  Remove any UMI for which less than 50% of kmers are contained in good edges.
6.  For reference-assisted assembly, if none of the strong paths had a V segment annotation, remove all the UMIs for that barcode.

</LinkableSection>

<LinkableSection id={"contigs"} title={"Contig construction"}>

Initially, every strong path that either contains an enrichment primer (de novo assembly) or is annotated by a CDR3 (in the reference-assisted assembly) is called a contig.

Then, in reference-assisted assembly:

- Contigs are trimmed to remove nucleotides occurring before the 5' UTR for a V segment and after enrichment primers.
- Contigs that have only a C annotation are deleted. These deleted contigs are enriched for artifacts.
- If a contig has a single-base indel relative to the reference that is supported by a single UMI (or one UMI plus one additional read), the indel is corrected to reflect the reference sequence.

Contigs with fewer than 300 base pairs are removed.

At this stage in assembly, there can be some redundancy among contigs arising from actual differences in transcripts, laboratory technical artifacts, or artifacts in contig construction.

**Steps to eliminate redundancy**:

1. The number of UMIs assigned to each contig is computed.
2. Junction selection:
   - For reference-assisted assembly, if two productive contigs share the same junction sequence (defined as 100 bases ending at the end of a J segment), the junction supported by the most UMIs is selected. If there is a tie, junction selection is arbitrary.
   - For de novo assembly, if two contigs are annotated with the same CDR3 sequence, the contig with the most UMIs is selected.
3. Non-productive contigs are de-duplicated. Any contig for which at least 75% of its kmers are contained in a productive contig is deleted. If 75% of the kmers in a non-productive contig are contained in a longer non-productive contig, the shorter contig is deleted. In de novo assembly, the same criteria apply, with productive replaced by "has a CDR3".

</LinkableSection>

<LinkableSection id={"competitive"} title={"Competitive deletion of contigs"}>

Competitive deletion of contigs aims to delete contigs that arise from extracellular mRNA in the sample or other background processes.

For reference-assisted assembly, the junction sequence of each productive contig is defined to be 100 nucleotides at the end of the annotated J segment. The junction UMI support for the contig is the number of UMIs that cover the junction sequence. Reads that support the junction sequence make up the junction read support. Suppose we have two contigs with respective (junction UMI support, junction read support) = (u1,n1) and (u2,n2). Suppose that (u1,n1) is sufficiently larger than (u2,n2). For example, u1 ≥ 2, u2 = 1, n1 ≥ 2 \* n2 would qualify. (And there are some similar criteria, not listed here.) Then if the contigs have the same chain type, we delete the second contig.

In de novo mode, a similar criterion is applied to contigs containing a CDR3, but instead of the junction mode used in the reference-assisted assembly, the 100 nucleotides starting at the end of the CDR3 are used. Chain type is not considered when deleting a contig, and the two strongest contigs are protected from deletion.

</LinkableSection>

<LinkableSection id={"confidence"} title={"Contig confidence"}>

Incorrect clonotypes can arise from sources such as extracellular mRNA or doublets. To prevent this, the confidence of a contig is assessed and those declared low confidence are excluded. All non-productive contigs are declared to have low confidence. For reference-assisted assembly, productive contigs have low confidence if any of the following apply:

- There are more than four productive contigs.
- There are more than two contigs for a chain type (e.g. three TRA contigs): It is expected that each cell-associated barcode has one productive TRA and one productive TRB chain for T cells, and one productive heavy and one productive light chain for B cells. Extra productive contigs are less likely to be legitimate.
- There are less than three filtered UMIs each having at least three read pairs
- All productive contigs have junction UMI support at most one, and either there are less than five filtered UMIs each having at least three read pairs, or there are more than two productive contigs
- Some productive contig has junction UMI support at most one, and there are less than three filtered UMIs each having at least n/20 read pairs, where n is the N50, taken over all UMIs in the entire dataset that have at least two read pairs, of the number of read pairs in such UMIs

Individual productive contigs are downgraded if their junction UMI support is at most one and the number of productive contigs exceeds two.

In de novo mode, similar criteria are applied. Here, 'productive contig' is replaced by 'contig having a CDR3 sequence'. The chain type test is not applied.

</LinkableSection>

<LinkableSection id={"quality"} title={"Contig quality scores"}>

Each base in the assembled contig is assigned a Phred-scaled quality value (QV), representing an estimate of the probability of an error at that base. The QV is computed with a hierarchical model that accounts for the errors in:

- Reverse transcription (RT): these errors affect all reads with the same UMI, and
- Sequencing: these errors affect individual reads

The sequencing error model uses the reported sequencer QVs. At recommended sequencing depths, many reads per UMI are observed. This allows for sequencing errors in individual reads to be corrected rapidly.

The estimated error rate for the V(D)J RT reaction is 1e-4 per base. Therefore, assembled bases that are covered by a single UMI are assigned Q40, and bases covered by at least two UMIs are assigned Q60.

</LinkableSection>


V(D)J Assembly


<LinkableSection id={"overview"} title={"Overview"}>

<Image src={"https://cdn.10xgenomics.com/image/upload/v1654273213/software-support/vdj/algorithms/cell-calling.png"} />

In the 10x Genomics system, a large number of GEMs (Gel Beads-in-emulsion) are generated. A fraction of those GEMs contain a cell, some of which are T or B cell.

T or B cell detection occurs by the identification and counting of V(D)J transcripts from those cells. Some T and B cells have very low expression levels for these transcripts, and thus these may not be detected. Conversely, sufficiently high levels of extracellular mRNA may result in some barcodes being misidentified as T or B cells. Thus the goal of the V(D)J cell calling algorithm is to _approximate_ the set of barcodes that contain a T or B cell. **The cell calling algorithm is executed as part of the assembly algorithm**.

</LinkableSection>

<LinkableSection id={"criteria"} title={"Criteria for identifying T and B cells"}>

To be identified as a T or B cell, a barcode must satisfy the following three requirements:

1. There must be a productive, confident contig. If there is only one such contig, there must be more than one UMI supporting its junction region. In de novo mode, the presence of a contig is the only requirement. Although other cell types can exhibit transcription within the TCR and BCR loci, only T and B cells produce fully rearranged transcripts that contain both a V and a C segment. Therefore, having a productive contig serves as evidence that a transcript from a T or B cell was present in the GEM. However, the transcript may not have arisen from an intact cell (background noise), i.e., captured from fluid between cells. To reduce the likelihood of calling such background transcripts as cells, the algorithm requires each barcode to be supported by more than one UMI.

2. There must be at least three filtered UMIs having at least two read pairs each (see [Assembly Algorithm](/support/software/cell-ranger/7.2/hidden/cr-5p-vdj-algorithm-assembly). This reduces the likelihood of misidentifying a cell as a T or B cell based solely on background transcripts.

3. Compute the N50 value of the number of read pairs per UMI, across all barcodes. For a given barcode, if the maximum read pair count across filtered UMIs is less than 3% of this N50, do not call the barcode a cell. This provides some protection against transcripts arising from index hopping on an Illumina flowcell, and from other forms of cross-library contamination.

In addition to the three requirements listed above, Cell Ranger v3.1 (and later) has a filter to account for noise introduced by plasma cells and B cells containing large amounts of RNA (as documented in the [Cell Ranger 3.1 release notes](/support/software/cell-ranger/7.2/release-notes)). This 1) tightens the `is_cell` filter for low-frequency clones that share a chain with a higher-frequency or large clone, and 2) shrinks high-frequency clones to remove noise from mRNA leakage caused by sample processing (e.g. not due to biological clonal expansion).

Additional cell filters are imposed during [clonotype grouping](/support/software/cell-ranger/7.2/hidden/cr-5p-vdj-algorithm-clonotyping).

</LinkableSection>


V(D)J Cell Calling


<LinkableSection id={"overview"} title={"Clonotyping overview"}>

<Image src={"https://cdn.10xgenomics.com/image/upload/v1654273211/software-support/vdj/algorithms/clonotyping.png"} />

During the clonotype grouping stage, cell barcodes are placed in groups called clonotypes. Each clonotype consists of all descendants of a single, fully rearranged common ancestor, as approximated computationally. During this process, some cell barcodes are flagged as likely artifacts and filtered out, meaning that they are no longer called as cells.

**T cells**: The lack of somatic hypermutation (SHM) in T cell receptors
(TCRs) yields biological clonotypes that have identical V(D)J transcripts.
Technical artifacts (e.g. arising in reverse transcription) can result in the
computed clonotypes having isolated differences. These are rare.

**B cells**: Fully rearranged B cell receptors (BCRs) can undergo SHM, which
can increase antigen affinity. Thus for BCRs, V(D)J transcripts in a clonotype
can differ at any position, as shown below:

<Flex style={{
  justifyContent: "center"
}}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1654273421/software-support/vdj/algorithms/what_is_a_clonotype.png"} width={"500px"} length={"500px"} />
</Flex>

B cell clonotypes can be hard to infer accurately because SHM can introduce numerous mutations. Cell Ranger v5.0 and above accomplishes B cell clonotype grouping by invoking a module for clonal analysis called [enclone](https://10xgenomics.github.io/enclone) which simultaneously filters and groups cells into clonotypes.

</LinkableSection>

<LinkableSection id={"grouping"} title={"Clonotype grouping by enclone"}>

For clonotype grouping, enclone mainly gets its information from an internally generated Cell Ranger file called [all_contig_annotations.json](/support/software/cell-ranger/7.2/analysis/outputs/cr-5p-outputs-overview-vdj). The relationship between enclone and Cell Ranger is illustrated here:

<Image src={"https://cdn.10xgenomics.com/image/upload/v1658533891/software-support/vdj/enclone/CellRangerBundle.png"} />

</LinkableSection>

<LinkableSection id={"germline"} nested={true} title={"Germline sequences"}>

For each dataset, enclone derives the reference sequence for V genes in the [donor](/support/software/cell-ranger/7.2/resources/cr-glossary)'s genome (germline sequence) to use as a reference for SHMs.

- For each V segment, one cell from each approximated clonotype is chosen. Approximated clonotypes are not final clonotypes (i.e., those generated as the final step of the clonotype grouping algorithm).
- The distribution of bases in each position on the V segment (excluding the last 15 bases) is determined.
- A V gene position is considered a germline variant if a non reference base is seen in at least 4 approximated clonotypes, comprising at least 25% of the total number of approximated clonotypes.
- This process is repeated for all cells in all the approximated clonotypes.
- The resulting cell-specific "footprint" defines alternative alleles. There is no restriction on the number of possible alternative alleles.

Germline variant assessment for J genes is currently not performed as it does not greatly enhance clonotype specificity.

</LinkableSection>

<LinkableSection id={"exact-subclonotypes"} nested={true} title={"Exact subclonotype grouping"}>

Cells are placed into groupings called [exact subclonotypes](/support/software/cell-ranger/7.2/resources/cr-glossary) if they have identical V(D)J transcripts. Only [productive contigs](/support/software/cell-ranger/7.2/hidden/cr-5p-vdj-algorithm-annotations#productive) are used. Exact subclonotypes must have the same number of chains. They must also be identical in their V(D)J sequences and constant region gene assignments. Exact subclonotypes are not required to have identical 5' UTRs. Additionally, the algorithm does not test for SHM in the 5' UTR or constant region.

</LinkableSection>

<LinkableSection id={"clonotypes"} nested={true} title={"Joining subclonotypes into clonotypes"}>

Exact subclonotypes are iteratively merged into clonotypes based on comparing each pair of exact subclonotypes to each other. Two cells with set criteria of shared differences and minimal CDR3 mutations are deemed to be in the same clonotype. Merging criteria are briefly described here. Visit the [enclone help](https://10xgenomics.github.io/enclone/pages/auto/help.how.html) page for details.

- Initially, pairs of exact subclonotypes having 2-3 chains are considered for joining together into a clonotype. Later stages of the clonotype grouping algorithm evaluate and merge exact subclonotypes with 1 chain. Exact subclonotypes having 4 chains (putative doublets) are not joined.
- Two exact subclonotypes are merged if a pair of chains has V-J genes and CDR3 segments of identical length.
- Next, shared somatic hypermutations (SHM) in V-J sequence outside the junction regions are identified between different exact subclonotypes. A mutation is shared if the two chains carry the same substitution or indel with respect to the reference sequence (donor reference for V and universal reference for J). Using the donor reference sequences enables the exclusion of shared germline mutations. Visit the [enclone help](https://10xgenomics.github.io/enclone/pages/auto/help.how.html) page for details on how the algorithm calculates the probability of these shared mutations occurring by chance.
- Chains that have too many CDR3 mutations are discarded based on a [set threshold](https://10xgenomics.github.io/enclone/pages/auto/help.how.html). CDR3 nucleotide identity of at least 85% is required for exact subclonotype retention.
- Other join criteria may apply and are discussed in the [enclone help](https://10xgenomics.github.io/enclone/pages/auto/help.how.html) page under the step "Other join criteria".

</LinkableSection>

<LinkableSection id={"enclone"} title={"Clonotype and barcode filtering by enclone"}>

During library generation, artifacts can arise by two mechanisms:

(a) Reverse transcription or sequencing can introduce base call errors. These usually occur at bases having low quality scores. Cells with these low quality bases are screened out, typically at a low rate.
(b) Gel Beads-in-emulsion (GEMs) may contain material from two or more cells: entire intact cells, cell fragments, or individual mRNA molecules.

Contamination detection is a complex task and is accomplished via multiple heuristic filters. Some barcode filtering happens during the assembly and cell calling stages of Cell Ranger execution. [enclone](https://10xgenomics.github.io/enclone/index.html) uses Cell Ranger's cell calling information and additionally performs its own barcode and clonotype filtering by employing a series of [heuristic tests](https://10xgenomics.github.io/enclone/pages/auto/default_filters.html). Filtering and clonotype grouping happen simultaneously.

Within Cell Ranger, [enclone](https://10xgenomics.github.io/enclone/index.html) applies these default filters, some of which are recursive:

| Filter                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cell filter                                                               | Remove barcodes not called cells in <samp>cellranger vdj</samp> pipeline.                                                                                                                                                                                                                                                                                                                                                                                             |
| Maximum contigs filter                                                    | Remove barcodes with more than four [productive contigs](/support/software/cell-ranger/7.2/hidden/cr-5p-vdj-algorithm-annotations#productive).                                                                                                                                                                                                                                                                                                                        |
| Graph filter                                                              | Remove some [exact subclonotypes](/support/software/cell-ranger/7.2/resources/cr-glossary) that appear to be background.                                                                                                                                                                                                                                                                                                                                              |
| Cross filter                                                              | Use cross-library information (i.e., from two libraries originating from the same [donor](/support/software/cell-ranger/7.2/resources/cr-glossary)) To remove spurious exact subclonotypes.                                                                                                                                                                                                                                                                           |
| Barcode duplication filter                                                | Remove duplicated barcodes within an exact subclonotype.                                                                                                                                                                                                                                                                                                                                                                                                              |
| Whitelist filter                                                          | Identify and remove any artifactual barcodes that do not match a barcode in the 10x Genomics [barcode inclusion list](https://kb.10xgenomics.com/hc/en-us/articles/115004506263-What-is-a-barcode-whitelist-). Artifactual barcodes are rare and likely arise from Gel Bead contamination.                                                                                                                                                                            |
| [Foursie](/support/software/cell-ranger/7.2/resources/cr-glossary) filter | Remove some [four-chain](/support/software/cell-ranger/7.2/resources/cr-glossary) clonotypes that are biologically irrelevant, e.g., 4 heavy chains.                                                                                                                                                                                                                                                                                                                  |
| Improper filter                                                           | Remove exact subclonotypes having 3 or 4 identical chains.                                                                                                                                                                                                                                                                                                                                                                                                            |
| Weak onesie filter                                                        | Disintegrate some single-chain clonotypes into single cells. If a barcode has a high confidence contig, passes the cell calling filter, and has only 1 chain, it is retained as its own clonotype.                                                                                                                                                                                                                                                                    |
| UMI filter                                                                | Determined a [baseline UMI count](https://10xgenomics.github.io/enclone/pages/auto/default_filters.html) for each dataset and remove any B cells having UMI counts lower than this baseline. Helps eliminate rare clonotype expansion signatures arising from fragmentation of plasma cells or other poorly understood physical processes.                                                                                                                            |
| UMI ratio filter                                                          | Remove some B cells with low UMI counts, relative to mean UMI counts in a given clonotype.                                                                                                                                                                                                                                                                                                                                                                            |
| GEX filter                                                                | If using <samp>cellranger multi</samp>, remove barcodes that were called as cells in the V(D)J but not the GEX library. This filter mitigates any overcalling issues seen in BCR and TCR libraries.                                                                                                                                                                                                                                                                   |
| Doublet filter                                                            | Remove some barcodes that appear to represent [doublets](/support/software/cell-ranger/7.2/resources/cr-glossary) or higher-order [multiplets](/support/software/cell-ranger/7.2/resources/cr-glossary)                                                                                                                                                                                                                                                               |
| Signature filter                                                          | Some complex clonotypes with many chains represent multiple true clonotypes that are glued together into a single clonotype. This filter removes some exact subclonotypes that appear to represent contaminants, based on their chain signature.                                                                                                                                                                                                                      |
| Onesie merger                                                             | Prevent the merger of some single-chain clonotypes into other clonotypes.                                                                                                                                                                                                                                                                                                                                                                                             |
| Weak chain filter                                                         | From the remaining cells, remove any cells that have weak chains. A chain is weak if it is found in &le; 5 other cells, and the total number of cells in that clonotype is less than 5 times that number. E.g., if there are a total of 14 cells in a clonotype, and a given chain is found in only 3 of those cells, all 3 cells are filtered out. However, if there were at least 3 x 5 (15 cells) in the clonotype, the 3 cells with this chain would be retained. |
| Quality merger                                                            | Filter out exact subclonotypes with low quality score positions.                                                                                                                                                                                                                                                                                                                                                                                                      |

Visit the [enclone website](https://10xgenomics.github.io/enclone/pages/auto/default_filters.html) for detailed documentation.

</LinkableSection>

<LinkableSection id={"command-line"} title={"enclone as a command line tool"}>

[enclone](https://10xgenomics.github.io/enclone) is also available in beta for exploratory evaluation via the use of command line arguments, permitting granular control over clonotyping and filtering heuristics. enclone can also display clonotypes and infer phylogenetic trees.

enclone is open source, unsupported, and separate from Cell Ranger.

</LinkableSection>


V(D)J Clonotyping


<LinkableSection id={"overview"} title={"Overview"}>

**What are invariant natural killer T (iNKT) and mucosal-associated invariant T (MAIT) cells?**

Invariant natural killer T cells (iNKT cells) and mucosal-associated invariant T cells (MAIT) cells are T cell populations which recognize and respond to non-peptide antigens using a limited TCR repertoire. For a comprehensive understanding of iNKT and MAIT cells, refer to the detailed review by Mori, et al ([Mori, Lepore, and De Libero in the 2016 Annual Review of Immunology](https://www.annualreviews.org/doi/abs/10.1146/annurev-immunol-032414-112008)).

**HLA-like molecules restrict iNKT and MAIT cells**

A cursory understanding of antigen presentation to T cells is necessary to understand iNKT and MAIT cells. Most T cells recognize peptide epitopes presented in the groove of human leukocyte antigen (HLA, also known as major histocompatibility complex, MHC). A subset of homologous, class I HLA-like proteins can also present non-peptide or peptide hybrid antigens. One such example is the CD1 family, which consists of CD1a-CD1e (CD1d1 and CD1d2 in mice). While CD1 associates with B<sub>2</sub>-microglobulin like HLA class I molecules, it is targeted to vesicles like HLA class II molecules. CD1 family members have a hydrophobic channel that enables binding to hydrocarbon alkyl chains. By anchoring these alkyl chains inwards, CD1 molecules expose carbohydrate and hydrophilic groups of lipids to immune cells (see the table below).

Most T cells restricted by CD1 are thought to be CD4-CD8-, though some CD4+ T cells are known to bind CD1. Of these CD1-binding cells, a subset binds CD1d and its lipid antigens; these T cells express the natural killer cell marker KLRB1C and an invariant TCRα that can pair with multiple TCRβ chains. Hence, these T cells are called invariant natural killer T cells, or iNKT cells. iNKT cells are thought to comprise 0.01 to 0.1% of T cells in the blood.

| CD1 molecule |                    Lipids bound                    | TCRαβ repertoire |
| :----------: | :------------------------------------------------: | :--------------: |
|     CD1a     | Microbial glycolipids, phospholipids, lipopeptides |     Diverse      |
|     CD1b     | Microbial glycolipids, phospholipids, lipopeptides |     Diverse      |
|     CD1c     | Microbial glycolipids, phospholipids, lipopeptides |     Diverse      |
|     CD1d     | Self- and microbial sphingolipids, diacylglycerols |  Invariant TCRα  |
|     CD1e     |                Poorly characterized                |     Unknown      |

MAIT cells [were discovered initially in 1993](https://pubmed.ncbi.nlm.nih.gov/8391057) as a subset of CD4-CD8- TCRT cells expressing the CD8αα homodimer with an invariant TCRα V gene repertoire. MAIT cells typically comprise 5-10% of T cells in the blood, can express either CD4 or CD8, and can comprise 10-50% of T cells in the spleen, gut, lungs, skin, and other organs. The ligands of MAIT cells were unknown until 2012. A second HLA class I-like molecule, **MHC-related protein 1 (MR1)**, is also capable of **displaying non-classical ligands to T cells**, such as folate derivatives and B vitamin metabolites produced by many microbial species. While initial work [described MR1 as a potent activator of MAIT cells](https://pubmed.ncbi.nlm.nih.gov/18443227), the microbial metabolites presented by MR1 were identified instead by researchers attempting to co-crystallize a MAIT TCR and MR1. MR1 could only be successfully folded in media with B vitamins, but this 6-formyl pterin molecule that bound and stabilized MR1 could not activate MAIT cells. Instead, cultures from S. typhimurium and other bacteria [both stabilized MR1 and activated MAIT cells](https://pubmed.ncbi.nlm.nih.gov/23051753). Recent efforts have led to the successful development of MR1 tetramers that can specifically identify antigen-specific MAIT populations.

Note that in addition to iNKT and MAIT cells, there are other T cell subtypes that are not restricted by HLA or MHC, such as germline-encoded mycolyl lipid-reactive (GEM), NKT, and LDN5-like T cells. Cell Ranger does not annotate these cell types.

</LinkableSection>

<LinkableSection id={"id-mait-inkt"} title={"Identifying MAIT and iNKT cells"}>

The restricted diversity of the TRA chain and published CDR3α and CDR3β sequences can be used to identify MAIT/iNKT cells from full length annotated contigs in the 10x V(D)J data.

|  Category  | _TRAV/TRAJ_                                                             | _TRBV/TRBJ_                                                   |
| :--------: | :---------------------------------------------------------------------- | :------------------------------------------------------------ |
| Human MAIT | <ul><li>_TRAV1-2_</li><li>Any of _TRAJ33_, _TRAJ20_, _TRAJ12_</li></ul> | <ul><li>_TRBV20_</li><li>_TRBV6_</li></ul>                    |
| Human iNKT | <ul><li>_TRAV10_</li><li>_TRAJ18_</li></ul>                             | _TRBV25-1_                                                    |
| Mouse MAIT | <ul><li>_TRAV1_</li><li>_TRAJ33_</li></ul>                              | <ul><li>_TRBV19_</li><li>_TRBV13_</li></ul>                   |
| Mouse iNKT | <ul><li>_TRAV11_</li><li>_TRAJ18_</li></ul>                             | <ul><li>_TRBV13-2_</li><li>_TRBV1_</li><li>_TRBV29_</li></ul> |

Users interested in knowing which MAIT and iNKT TCRs are used to annotate for junctional evidence can locate and request changes to our [junction list here](https://github.com/10XGenomics/enclone/blob/cellranger5.0/enclone/src/human_iNKT_CDR3.json).

_Note: In humans, MAIT cell frequencies dwarf those of iNKT cells (MAIT cell frequency in peripheral blood and certain tissues can be more than 100-fold greater than that of iNKT cells), while in laboratory mouse strains, the opposite is true. Due to the abundance of iNKT cells in mice and the earlier development of MAIT cell analysis reagents, iNKT cells have been more extensively studied in mice rather than humans compared to MAIT cells._

</LinkableSection>

<LinkableSection id={"cr-mait-inkt"} title={"How does Cell Ranger annotate iNKT and MAIT cells?"}>

Cell Ranger labels cells as potential iNKT and MAIT cells based on a combination of 1) matching the appropriate V and J genes for the TCR alpha, 2) matching the appropriate V genes for the TCR beta, and 3) matching known V(D)J junctions (CDR3s) from the literature.

Consider the following example label for a given clonotype in the MAIT evidence column of `clonotypes.csv`: `TRA:gene+junction;TRB:gene`. This indicates that the TCR alpha genes for that clonotype match the known _TRAV_ and _TRAJ_ gene criteria for MAIT cells (`TRA:gene`), that the TCR alpha CDR3 matches that of a known MAIT TCR (`TRA:junction`), and that the TCR beta V gene matches the criterion for MAIT cells (`TRB:gene`).

These labels are stored in the Cell Ranger outs folder in **clonotypes.csv**. This filter is deliberately flexible to accommodate new CDR3 junctions that Cell Ranger users may discover. If you believe you have found new MAIT or iNKT junctions, please contact [support@10xgenomics.com](mailto:support@10xgenomics.com).

</LinkableSection>


iNKT and MAIT cells

A set of analysis pipelines that perform sample demultiplexing, barcode processing, single cell 3' and 5' gene counting, V(D)J transcript sequence assembly and annotation, and Feature Barcode analysis from single cell data.

Overview

Getting Started

Download Center

Cell Ranger Commands

Analysis

Tutorials

Algorithms

Advanced

Troubleshooting

Miscellaneous

Release Notes

Glossary

Datasets

Loupe Browser

Cell Ranger 7.2

Cell Ranger

Installation

Get Started with Cell Ranger

Convert BCL to FASTQ with Cell Ranger mkfastq

mkfastq

Cell Ranger mkfastq

Analyze Gene Expression and Feature Barcode data with Cell Ranger count

count

Cell Ranger count

aggr

Cell Ranger aggr

Rerun secondary analysis for a completed cellranger count or aggr run with different parameters

reanalyze

Cell Ranger reanalyze

Build a custom reference using Cell Ranger mkref

mkref

Cell Ranger mkref

Analyze cell multiplexing data with Cell Ranger multi

multi

Cell Ranger multi for 3' Cell Multiplexing

Analyze V(D)J and 5' GEX with Cell Ranger multi

multi for V(D)J

Cell Ranger multi for Immune Profiling

Analyze your GEX + VDJ + B cell Antigen Capture libraries with Cell Ranger multi

Cell Ranger multi for BEAM-Ab

Analyze your GEX + VDJ + T cell Antigen Capture libraries with Cell Ranger multi

Cell Ranger multi for BEAM-T

Analyze V(D)J libraries with Cell Ranger vdj

Cell Ranger vdj

Capturing Neutrophils in 10x Single Cell Gene Expression Data

Capturing neutrophils

Capturing Neutrophils

Analyze scRNA-Seq Data From a Publication Using 10x Software

Data analysis

Example Data Analysis

Analysis and visualization of data in the tumor microenvironment application note using the Loupe and Loupe V(D)J Browsers

Characterize tumor cells

Tumor Microenvironment Data Analysis and Visualization

Understand pipeline telemetry data collection and learn how to disable it if needed

Cell Ranger Pipeline Telemetry

View all tutorials

Learn more about input files required to run Cell Ranger

Inputs

List of Inputs

Generating FASTQs

Specifying FASTQs

A CSV file used to indicate the input FASTQ files for libraries in a Feature Barcode experiment.

Libraries CSV

A CSV file used to indicate the molecule structure and unique Feature Barcode sequence of each feature present in the experiment.

Feature Reference CSV

A CSV files that specifies parameters required to run cellranger multi

Multi Config CSV

Custom Reference with mkref

Custom V(D)J Reference

Running Pipelines

Choosing a pipeline

GEX + Antibody/CRISPR (count)

VDJ-T/B only (vdj)

3'/5' Sample Multiplexing (multi)

VDJ + GEX + Antibody/CRISPR/BEAM (multi)

Flex (multi)

Aggregate Multiple Samples (aggr)

Cell Annotation (annotate)

Custom Analysis (reanalyze)

Learn more about the output files generated by Cell Ranger

Outputs

Web Summary

Metrics

Feature-Barcode Matrices

Molecule Info (H5)

Secondary Analysis

Results of aggr

Gene Expression

Antibody Capture

CRISPR Guide Capture

Sample Multiplexing

VDJ-T/B

VDJ + GEX + BEAM

Flex

What is Cell Ranger?

<Text as={'p'} size={'small'} weight={'medium'}>Cell Ranger v7.2 is the last version to support the analysis of LT (low throughput) libraries.</Text>

We provide resources from protocols, user guides, and free-to-use analysis tools

Algorithms overview

Advanced pipeline content for Cell Ranger.

Browse Q&As from the 10x Genomics support team.

View terms and definitions relevant to Single Cell products.

Access free public Chromium data from 10x Genomics.

A collection of introductions, tutorials, and blogs for data analysis beyond software.

Analysis Guides

Loupe Browser is a desktop application that allows you to interactively visualize data.

Hidden