Cell Ranger 6.0 introduced support for Cell Multiplexing with the `cellranger multi` pipeline. The algorithms are similar to `cellranger count` in many ways, but an additional tag calling step is required, shown below.

<Image src={"https://cdn.10xgenomics.com/image/upload/v1688669077/software-support/3p-Single-Cell-GEX/Cell-Multiplexing/multiplexing_algorithms_1.png"} />

Cell-associated barcodes are identified as singlets, multiplets, or blanks (considered to have lower than expected tag counts for all tags used) according to a probabilistic model. A key benefit of this algorithm is the ability to detect and filter most multiplets and blanks from the data.

<LinkableSection id={"cellplex"} title={"Tag assignment algorithm"}>

Cell Ranger 6.0 and later features a probabilistic model for assigning Cell Multiplexing Oligo (CMO) tags to cell-associated barcodes. The algorithm employs a latent variable model over a state space composed of each sample used in the experiment. To make the algorithm computationally tractable, the model explicitly accounts for the type and quantity of the different multiplets expected. For example, there is a “Blanks” state for barcodes associated with cells that have not been stained with any tag, a singlet state for each tag used in the experiment, and different states for each type of multiplet based on how many tags were used (up to 12 supported).

Each tag is assumed to have a distribution of counts amongst cells that have not been stained with the tag (background distribution) and another distribution of counts amongst cells that have been stained with the tag (signal distribution). Both the background and the signal distribution are assumed to be Gaussian with different means but the same variance. The parameters for the distributions of counts for latent states are efficiently derived as linear combinations of the individual cell-states (stained or not) present in the latent state, allowing states which are rarely, or never, observed in the data to still be accurately estimated. The parameters for the Gaussian distributions and the latent state assignments for each barcode are estimated using a customization of the Expectation-Maximization (EM) algorithm (Dempster et al., 1977).

Cell Ranger models the count distribution of each CMO tag with the following assumptions:

- Each tag has a non-zero mean background (μb).
- if a cell corresponding to the tag is present, then the tag count will be higher than background by Δ.
- Tag count is normally distributed.
- A different tag will have different set of μb, Δ, σ parameters.
- Use the EM algorithm to fit μb, Δ, σ parameters for all CMO tags based on observed tag counts.

<Flex justifyContent={"center"}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1688669121/software-support/3p-Single-Cell-GEX/Cell-Multiplexing/em_algorithm.png"} width={"500px"} length={"500px"} />
</Flex>

When the EM optimization converges, Cell Ranger calculates, for each barcode, the probability that it belongs to each latent state in the model. Following this, Cell Ranger combines all the different multiplet states into one coarse-grained Multiplet state by summing their probabilities.

For each barcode:

- Calculate the probability of P(Blanks), P(Sample A), P(Sample B), and P(Multiplet). These probabilities sum up to 1.
- By default, if a particular state has probability >= 0.9, the barcode is assigned to that state. This threshold can be adjusted, see [confidence thresholding section](#conf-thresh) below.

<Flex justifyContent={"center"}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1688669121/software-support/3p-Single-Cell-GEX/Cell-Multiplexing/em_algorithm_2.png"} width={"500px"} length={"500px"} />
</Flex>

Cell Ranger adds a fifth "Unassigned" category for cells that cannot be confidently assigned to any other state. This is done by enforcing a minimum confidence threshold to filter out low confidence assignments, as detailed below in the “Confidence thresholding” section. Being more stringent about the minimum confidence necessary to make an assignment results in greater accuracy (lower mis-assignment rate) at the cost of yield (fewer singlets).

<Flex justifyContent={"center"}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1688669121/software-support/3p-Single-Cell-GEX/Cell-Multiplexing/em_algorithm_4.png"} width={"500px"} length={"500px"} />
</Flex>

Ultimately barcodes that are classified as Multiplet, Blanks, or Unassigned are filtered out. **Note that the algorithm cannot filter out multiplets containing only one tag.**

</LinkableSection>

<LinkableSection id={"conf-thresh"} title={"Confidence thresholding"}>

There is an inherent trade-off between yield (number of singlets assigned a single tag) and accuracy (as defined by the rate of mis-assignment). Being more stringent about the minimum confidence necessary to make an assignment results in greater accuracy (lower mis-assignment rate) at the cost of yield (fewer singlets).

Based on analysis of the yield-accuracy tradeoff in representative datasets, a default minimum confidence threshold for assignments was set at 0.9. (Since these probabilities are not exact, this corresponds typically to a mis-assignment rate significantly less than 1%.) When the most likely state for a barcode has a likelihood of less than 0.9, we label it as "Unassigned". Only barcodes with a singlet likelihood of 90% or greater are considered singlets by the model and assigned to a sample.

For particular datasets of interest, the user may wish to tolerate a higher rate of mis-assignment in order to obtain more singlets to include in their analysis, or a lower rate of mis-assignment at the cost of obtaining fewer singlets. As of Cell Ranger 6.0.2, users can adjust the default threshold by changing the `min-assignment-confidence` parameter in the [multi config CSV file](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-3p-multi).

</LinkableSection>

<LinkableSection id={"thru-detect"} title={"Throughput detection"}>

Some of the metrics and algorithms in the CellPlex processing pipeline rely on correct estimation of the number of singlets and multiplets in the reaction - i.e., cell barcodes that were stained by one, two, or more CellPlex tags. That Poisson calculation depends on the cell load and the number of GEMs generated during a Chromium run. While the number of cells is a variable based on the actual number of loaded cells and what Cell Ranger detected, the number of GEMs is unique to each 10x Genomics chip. In Standard Kit (SK) chips, about 95,000 GEMs are generated, while in High Throughput (HT) chips, about 190,000 are generated.

For CellPlex data, Cell Ranger 6.1 attempts to correctly detect throughput to update the number of GEMs in downstream calculations, so metrics like `Singlet Capture Ratio` are produced correctly.

<SupportCallout level={"info"}>
<Text as={"span"}>Throughput detection is not necessary for non-CellPlex data as the multiplet ratios are not calculated. Since these calculations are only important for 3' CellPlex experiments, Cell Ranger 6.1 runs throughput auto-detection when it detects both GEX and CMO libraries.</Text>
</SupportCallout>
 

Shown below are the knee plots of an SK run (left) and an HT run (right). The plots are on a log-log scale. The UMI count profile is different for barcodes between the 95,000-190,000 region for SK vs. HT runs. In the first step, two algorithms are run in parallel which independently attempt to determine the throughput. The first one looks at the ratio of the UMI count of the 130,000th barcode divided by the UMI count of the 100th barcode and decides whether that is significantly high; the second one finds the steepest cliff in the barcode rank plot after the 70,000th barcode and determines if that cliff happens **after** the 130,000th barcode (red lines). The blue lines indicate barcodes 70,000 and 220,000.

<Image src={"https://cdn.10xgenomics.com/image/upload/v1688669144/software-support/3p-Single-Cell-GEX/Cell-Multiplexing/SK_vs_HT_rankplot2.png"} />

In the second step, the pipeline compares the results of both algorithms. If both decisions were returned as true, the final throughput will be chosen as HT and number of GEMs used for Poisson calculation will be 190,000, otherwise the software will default to SK and number of GEMs to 95,000. If it detects an HT run, the web summary will show 'HT' appended to the detected chemistry. If the algorithms fail, users can choose to run with `chemistry=SC3Pv3HT` to indicate HT, where Cell Ranger 6.1 will use HT defaults for downstream calculations. If the throughput detection algorithm does not detect HT where user has indicated HT, the software will report an alert on the web summary describing the throughput discrepancy.

</LinkableSection>

<LinkableSection id={"noise-signal"} title={"CMO signal-to-noise ratio"}>

As described above in the [cell tagging algorithm section](#cellplex), each CMO tag is assumed to have a background distribution of counts amongst cells that have not been stained with the tag (left, noise distribution) and another foreground distribution of counts amongst cells that have been stained with the tag (right, signal distribution).

Higher signal-to-noise ratios can help to indicate whether there is sufficient separation between the distributions for clean tag assignment. The histogram of CMO counts and CMO signal-to-noise ratio are displayed on the [multi web summary output](/support/software/cell-ranger/latest/analysis/outputs/cr-3p-outputs-web-summary-multi) **Multiplexing** tab.

This ratio is computed as the difference between the mean background (left, noise distribution) and foreground (right, signal distribution) CMO counts on a log scale divided by the variance (assumed to be the same for both peaks), illustrated below for CMO301:

<Image src={"https://cdn.10xgenomics.com/image/upload/v1654039301/software-support/3p-Single-Cell-GEX/Cell-Multiplexing/cmo_hist_calc.png"} />

</LinkableSection>

<LinkableSection id={"references"} title={"References"}>

- Dempster AP, Laird NM, and Rubin DB. Maximum likelihood from incomplete data via EM algorithm. _J R Stat Soc Ser B Methodol._ 39:1–38, 1977.

</LinkableSection>

Cell Ranger's Cell Multiplexing Algorithm

The [cellranger multi](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-multi#beam) algorithm processes [Chromium Single Cell 5' with Feature Barcode Technology for Barcode Enabled Antigen Mapping (BEAM)](/support/software/cell-ranger/latest/getting-started/cr-5p-what-is-antigen-capture)/Antigen Capture, Gene Expression, V(D)J, and Antibody Capture libraries simultaneously. This page describes the unique aspects of the `multi` algorithm designed to process Antigen Capture libraries.

<DocumentCallout>
<Text as={"span"}>BEAM is unsupported with GEM-X chemistry; therefore, Cell Ranger does not support BEAM/Antigen Capture libraries produced with this chemistry.</Text>
</DocumentCallout>

<LinkableSection id={"cell-calling"} title={"Cell calling"}>

Cell calling is the process of finding and assigning 10x Barcodes as cell-associated or cellular barcodes (vs. background/noise barcodes).

Initially, the identification of cellular barcodes takes place independently for [Gene expression](/support/software/cell-ranger/latest/algorithms-overview/cr-gex-algorithm) and [V(D)J](/support/software/cell-ranger/latest/resources/cr-5p-vdj-algorithm-callcells) libraries generated from a single [Gel Beads-in-emulsion (GEM) well](/support/software/cell-ranger/latest/resources/cr-glossary). The cellular barcodes identified in the Gene Expression library are then used to inform the cellular barcodes identified in the V(D)J library. Specifically, any barcodes that were not assigned as cells in the Gene Expression library are filtered out of the V(D)J library as well, making V(D)J cells a subset of the gene expression cells.

This process prevents background or empty barcodes from being identified as T/B cells and helps make V(D)J cell calling more accurate. You can learn more about `cellranger multi` cell calling in the [Why use multi?](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-multi#why) section of the `cellranger multi` pipeline page.

</LinkableSection>

<LinkableSection id={"aggregates"} title={"Antigen aggregate detection and filtering"}>

Occasionally, during sample processing for Antigen Capture and Antibody Capture library creation, proteins may clump together nonspecifically to form large aggregate molecules. Any GEMs that contain these aggregated molecules will have unusually large UMI counts.

Since the protein aggregates are nonspecific, barcodes affected by antigen or [antibody aggregates](/support/software/cell-ranger/latest/algorithms-overview/cr-ab-algorithm) must be removed. This 10x Genomics Knowledge Base article describes why you may observe a [high fraction of reads coming from barcodes with high UMI counts](https://kb.10xgenomics.com/hc/en-us/articles/360042247271-High-fraction-of-reads-coming-from-barcodes-with-very-high-UMI-counts).

In Cell Ranger, aggregate detection happens before [cell calling](#cell-calling); any barcodes associated with aggregation are removed and the remaining barcodes go through cell calling.

During aggregate detection, the algorithm selects the top 100 cell barcodes with the highest antigen UMIs. Outliers are then identified and filtered out from this set of 100 barcodes based on the interquartile range (IQR) of:

$$Q3 + (Q3-Q1)*3$$

Antigen aggregates can be seen as a sharp beak at the top of the antigen barcode rank plot reported in the Antigen tab (Libraries section) of the web_summary.html. Refer to the antigen barcode rank plot in your web summary to QC your data for antigen aggregates.

This example antigen barcode rank plot (below) has been annotated with a dotted line to show the first 100 barcodes. The aggregate barcodes removed by the antigen aggregate detection algorithm are shown in orange.

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

Aggregate barcodes are reported in the [aggregate_barcodes.csv](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-per-sample-outs-multi#count) file located in the `per_samples_outs/sample_name/count` directory. Aggregate barcodes are retained in the [raw_feature_bc_matrix](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-raw-outs-multi#count).

Please note:

- The [sample_filtered_feature_bc_matrix](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-per-sample-outs-multi#count) and the [Loupe Browser compatible .cloupe file](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-per-sample-outs-multi) are computed only with cellular barcodes.
- [Antigen specificity scores](#ag-spc-score) are not calculated for aggregate barcodes. They are calculated only for cellular barcodes in the Gene Expression library (all of which are present in the feature-barcode matrix and the `.cloupe` file).
- The [Loupe V(D)J Browser compatible .vloupe](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-per-sample-outs-multi#vdj) file is created for all the cellular barcodes in the V(D)J library (which is a subset of the cellular barcodes in the Gene Expression library).

Although both antigen and antibody aggregates are reported in the same CSV file ([aggregate_barcodes.csv](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-per-sample-outs-multi#count)), the process of detecting and filtering out antigen aggregates is different from that used for [antibody aggregates](/support/software/cell-ranger/latest/algorithms-overview/cr-ab-algorithm).

</LinkableSection>

<LinkableSection id={"ag-spc-score"} title={"Antigen specificity score"}>

The antigen specificity score is the likelihood of an antigen binding to a specific receptor compared to the negative control. Cell Ranger uses a beta distribution to model the probability that a given T or B cell receptor is biased towards binding a particular antigen versus the negative control. This probability is calculated for a confidence level of 0.925 or more.

Mathematically, the antigen specificity score is calculated using the expression:

$$(1 - beta.cdf(0.925, AntigenUMI + 1, ControlUMI + 3)) * 100$$

Where `beta.cdf` is the cumulative distribution function of the beta distribution, `AntigenUMI` is the UMI count for the target antigen, and `ControlUMI` is the UMI count for the negative control. Pseudo counts of +1 and +3 are added to the antigen and control UMI counts, respectively, because the beta distribution is undefined when UMI counts are 0.

The cumulative probability distribution function for a few different antigen-negative control UMI counts is shown below:

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

Confidence level is plotted on the X-axis, and the dotted line corresponds to a confidence level of 0.925. The antigen specificity score is the numerical value of the area under the curve, to the right of the dotted line.

Please note:

- An antigen specificity score is calculated per cell barcode for each antigen-negative control pair specified in the [Feature Reference CSV](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-antigen#feature-ref) and [multi config CSV](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-antigen#config).
- A given cell can have high antigen specificity scores for more than one antigen.
- Antigen specificity scores are not calculated if a negative control antigen is not specified.

### Properties of the antigen specificity score

- Antigen specificity scores tend to cluster at the extremes (~0 or 100).
- Cells with larger UMI support tend to have higher antigen specificity scores. For a given antigen UMI:control UMI ratio, the confidence in the probability that a receptor binds to the antigen versus negative control is higher for cells with a larger number of UMIs.
- For cells with zero antigen or control UMIs, the pseudo counts of 1 and 3 (see mathematical equation above) add a small residual value. These residual values should be ignored as they are biologically meaningless.

### Antigen specificity score is not a measure of antigen affinity or avidity

Immunologists describe the binding strength of an antigen in terms of antigen affinity and antigen avidity. Antigen affinity is the strength of interaction between the antigen and its T or B cell receptor at a singular binding site. Antigen avidity is a measure of the overall strength of interaction between an antigen and its receptor, summed across all points of interaction.

Cell Ranger's antigen specificity score indicates whether or not a given T or B cell receptor associates with an antigen. The antigen specificity score is **not** a measure of binding strength, and therefore, cannot be used as a proxy for antigen avidity or affinity.

### Antigen specificity score output file and documentation

Cell Ranger outputs antigen specificity scores in a CSV file called [antigen_specificity_scores.csv](/support/software/cell-ranger/latest/analysis/outputs/cr-5p-outputs-per-sample-outs-multi#antigen-specificity-score). It is located in the `outs/` folder, here: `/outs/per_sample_outs/sample_name/antigen_analysis/antigen_specificity_scores.csv`.

</LinkableSection>

Cell Ranger's Antigen Capture (BEAM) Algorithm

The [cellranger vdj](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-vdj) pipeline can be used to analyze 5' Single Cell V(D)J libraries. It takes FASTQ files for V(D)J libraries and performs sequence assembly and paired clonotype calling. The pipeline uses the [Chromium Cell Barcodes](/support/software/cell-ranger/latest/resources/cr-glossary) (also called 10x Barcodes) and UMIs to assemble V(D)J transcripts per cell. Clonotypes and CDR3 sequences are output as a `.vloupe` file which can be loaded into [Loupe V(D)J Browser](/support/software/loupe-vdj-browser/latest). Visit the [What is Cell Ranger](/support/software/cell-ranger/latest/getting-started/cr-what-is-cell-ranger) page to learn more about Cell Ranger for Immune Profiling.

This page provides an overview of the `cellranger vdj` algorithm. Click on the sections below to learn more about each step.

## Algorithm overview

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

<LinkableSection id={"assembly"} title={"1: Assemble contigs"}>

The assembly process combines reads for a single barcode into assembled contigs, representing the best estimate of the transcript sequences present. [Learn about the assembly algorithm here](/support/software/cell-ranger/latest/resources/cr-5p-vdj-algorithm-assembly)

- Filter out reads with noisy barcodes and UMIs that may arise from PCR errors, sequencing errors, etc.
- Trim adaptors and primer sequences from 5' and 3' ends of the reads.
- Generate full-length transcripts (contigs) from each chain in all observed GEMs/barcodes.
</LinkableSection>

<LinkableSection id={"annotate"} title={"2: Annotate contigs"}>

V(D)J contig annotation involves aligning V, D, and J gene segments to contigs, identifying CDR3 sequences, and assessing whether each contig is productive, indicating a likely functional T or B cell receptor. [Learn about the assembly algorithm here](/support/software/cell-ranger/latest/resources/cr-5p-vdj-algorithm-annotations)

- Annotate contigs with V(D)J segment labels and locate CDR3 regions that form the transcript.
- Filter contigs that are full-length and productive.
</LinkableSection>

<LinkableSection id={"call-cells"} title={"3: Call cells"}>
Identify barcodes/GEMs that contain T or B cells. [Learn about the assembly algorithm here](/support/software/cell-ranger/latest/resources/cr-5p-vdj-algorithm-callcells)
</LinkableSection>

<LinkableSection id={"generate-clonotyes"} title={"4: Generate clonotypes"}>
Group cell-associated barcodes into clonotypes and filter out some cells. [Learn about the assembly algorithm here](/support/software/cell-ranger/latest/resources/cr-5p-vdj-algorithm-clonotyping)

</LinkableSection>

Cell Ranger's V(D)J Algorithm

While most of the antibody-related metrics and counts are computed in parallel with their gene expression counterparts, there are some unique aspects of protein libraries that require specific analysis steps in Cell Ranger.

<SupportCallout level={"info"}>
<ListItem>
<Text as={"span"}>The same Cell Ranger algorithm is used to process Antibody Capture and antigen-multimer staining assay libraries (TotalSeq™-C, Immudex's dMHC Dextramer® libraries with dCODE Dextramers).</Text>
</ListItem>
<ListItem>
<Text as={"span"}>Antigen-multimer staining assay library construction and analysis in the absence of Gene Expression and Antibody Capture is not recommended.</Text>
</ListItem>
</SupportCallout>

<SupportCallout level={"info"}>

<Text as={"span"}>To learn about the Cell Ranger algorithm used to process Barcode Enabled Antigen Mapping (BEAM)/ Antigen Capture libraries, **[Click here.](/support/software/cell-ranger/latest/algorithms-overview/cr-5p-antigen-algorithm)**</Text>
</SupportCallout>
 

<LinkableSection id={"protein-aggr"} title={"Protein aggregate detection and filtering"}>

Protein aggregates in antibody staining experiments can result in a few GEMs having significantly elevated UMI counts. To tackle this issue, a two-step process is implemented to identify and exclude the barcodes associated with these problematic GEMs.

1. First, as part of the UMI counting pipeline, Cell Ranger identifies pairs of UMIs that differ by only one base (i.e., having a Hamming distance of one) and applies a process called `UMI correction`. During this step, reads associated with these UMIs are merged into a single UMI count by correcting the UMI with fewer reads using the UMI with more reads.

 Although such correction events are typically uncommon, there have been instances where correction rates are unusually high in Antibody Capture libraries. This phenomenon consistently correlates with extremely high UMI counts. Such high UMI counts can cause saturation of the UMI space, resulting in false UMI corrections. Protein aggregates represent a prominent cause of these elevated UMI counts and correction rates.

 This accompanying plot shows an extreme case of protein aggregation, where a few barcodes account for nearly 77% of all reads, with extremely high correction rates in these reads. Currently, a barcode is classified as an aggregate if it has more than 10K reads, 50% of which were subject to correction.

 <Flex justifyContent={"center"}>
 <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100034/software-support/3p-Single-Cell-GEX/antibody-aggregates.png"} width={"600px"} length={"600px"} />
 </Flex>

2. Additionally, Cell Ranger employs protein counts to directly detect aggregation events alongside monitoring UMI correction events. The underlying insight is that large antibody panels are commonly employed to stain a diverse range of cell types. Consequently, observing high counts of numerous unrelated proteins within a GEM serves as an indicator of protein aggregates.

 This algorithm is activated when five or more antibodies (or antigens, dextramers, or other features designated as "Antibody Capture" in the Feature Reference) each have at least 1,000 counts. Based on the total number of such features, Cell Ranger dynamically determines the required percentage for these features to be detected within a GEM to warrant further consideration. Subsequently, if the necessary number of antibodies exceeds their predefined thresholds for high counts (currently defined as being among the 25 highest counts across all GEMs), the GEMs are flagged as protein aggregates.

 This accompanying plot exemplifies an aggregate barcode. Unrelated antibodies, such as CD3, CD19, CD14, CD56, and even mouse isotype controls IgG1 and IgG2a, are enriched in the orange barcode (top right corner), which the pipeline identifies as an aggregate.

 | <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100698/software-support/3p-Single-Cell-GEX/antibody-aggregates1.png"} /> | <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100698/software-support/3p-Single-Cell-GEX/antibody-aggregates2.png"} /> | <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100698/software-support/3p-Single-Cell-GEX/antibody-aggregates3.png"} /> |
 | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |

 Cell Ranger combines the aggregate barcodes identified from both aforementioned steps and removes them from the final feature-barcode matrix. The fraction of reads associated with these barcodes is reported as the "Antibody: Fraction Reads in Aggregate Barcodes" metric in the web summary. Furthermore, two related metrics are available in `metrics_summary.csv`: "Antibody: Number of Aggregate Barcodes" indicates the number of detected aggregate barcodes, while "Antibody: Fraction Reads that have Corrected UMIs" represents the fraction of all reads that underwent a correction event.

</LinkableSection>

<LinkableSection id={"pca"} title={"PCA"}>

In order to reduce the gene expression matrix to its most important features, Cell Ranger uses Principal Components Analysis (PCA) to change the dimensionality of the dataset from (cells x genes) to (cells x _M_) where _M_ is a user-selectable number of principal components (via [num_principal_comps](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-3p-reanalyze#params)).

The pipeline uses a python implementation of the IRLBA algorithm, (Baglama & Reichel, 2005), which we modified to reduce memory consumption. For samples where Antibody Capture is an input library, the pipeline will slice out the feature counts from the full matrix and perform a PCA on these log-transformed antibody counts, $log_{2}\text{(count + 1)}$.

</LinkableSection>

<LinkableSection id={"tsne"} title={"t-SNE"}>

Since cell surface proteins offer a unique and complementary view of the cell types on top of the genes they express, Cell Ranger runs a popular t-distributed Stochastic Neighbor Embedding (t-SNE) algorithm to visualize the protein counts in 2-D space. For samples where Antibody Capture is an input library, the pipeline will slice out the feature counts from the full matrix and perform a t-SNE on these log-transformed antibody counts, $log_{2}\text{(count + 1)}$ (unlike the gene expression part of the feature-barcode matrix, where t-SNE is run on the PCA-reduced space from raw counts). These t-SNE projections can then be visualized with Loupe Browser versions 3.0 and later.

Below, the left panel shows a traditional t-SNE with gene counts only, overlaying the counts of CD8a antibody. The middle panel shows CD8a protein expression overlaid on t-SNE projections computed on antibody counts only. The right panel shows the expression of CD8A gene on the antibody-derived t-SNE projections for comparison.

| <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100698/software-support/3p-Single-Cell-GEX/gex-tSNE-CD8a.png"} /> | <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100698/software-support/3p-Single-Cell-GEX/antibody-tSNE-CD8a_antibody.png"} /> | <Image src={"https://cdn.10xgenomics.com/image/upload/v1689100698/software-support/3p-Single-Cell-GEX/antibody-tSNE-CD8A_gene.png"} /> |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |

</LinkableSection>

<LinkableSection id={"umap"} title={"UMAP"}>

Cell Ranger also supports visualization with UMAP (Uniform Manifold Approximation and Projection), which estimates a topology of the high dimensional data and uses this information to estimate a low dimensional embedding that preserves relationships present in the data (McInnes et al, 2018). The pipeline uses the python implementation of this algorithm by McInnes et al (2018). UMAP coordinates are available in the pipeline output `analysis/umap` directory. Similar to t-SNE plots, in samples with Antibody Capture reads, the pipeline will slice out these feature counts from the full feature-barcode matrix and perform UMAP on log-transformed antibody counts, $log_{2}\text{(count + 1)}$.

</LinkableSection>

<LinkableSection id={"references"} title={"References"}>

- Baglama J and Reichel L. [Augmented implicitly restarted Lanczos bidiagonalization Methods](https://epubs.siam.org/doi/abs/10.1137/04060593X). _SIAM Journal on Scientific Computing_ 27: 19–42, 2005.

- McInnes L, Healy J, and Melville J. [UMAP: Uniform Manifold Approximation and Projection for dimension reduction](https://arxiv.org/abs/1802.03426). _arXiv_, 2018.

</LinkableSection>

Cell Ranger's Antibody Capture (Cell Surface Protein) Algorithm

<SupportCallout>
The annotation models were co-developed by 10x Genomics and the Cellarium AI Lab at the Data Sciences Platform of the Broad Institute. 
</SupportCallout>


Cell Ranger introduces a new [pipeline for automated cell type annotation](/support/software/cloud-analysis/latest/tutorials/CA-cell-annotation-pipeline), which can be applied to the Gene Expression outputs of Cell Ranger count, multi, and aggr to generate accurate cell type labels. This method assigns cell types by comparing gene expression profiles to annotated reference datasets, avoiding reliance on marker genes or tissue-specific references. Please note that the cell annotation models are in [beta](/support/software/cloud-analysis/latest/faqs/CA-frequently-asked-questions#cell-annotations).

Specifically, each cell barcode's gene expression profile is compared to a model built on the Chan Zuckerberg CELL by GENE (CZ CELLxGENE) census to identify the most similar cell types. A consensus label is then assigned to each barcode, with the results summarized in the `web_summary.html`. These labels can be viewed in Loupe Browser or accessed via the `cell_types.csv` output file which also contains the primary fine grain cell annotation.

The algorithm generates an embedding for each cell barcode. The gene expression profile of each cell barcode being analyzed is projected into the same embedding. To classify a cell, the algorithm performs an approximate nearest-neighbor (ANN) search, identifying the 500 most similar cells in the reference set based on these embeddings. The most common cell type among these nearest neighbors is then assigned to the query cell. Models may differ in their inputs (e.g., all genes vs specific genes) and how they calculate embeddings. The models are described in more detail below. 

<Image src="https://cdn.10xgenomics.com/image/upload/v1726272036/software-support/Cell%20Ranger/cell-annotation/Embedding.png"/>

This figure shows the gene expression profile of a single 10x Barcode (shown in red), transformed into an embedding. The approximate nearest neighbors (primarily yellow cells) of the 10x Barcode are shown within the grey circle.

Cell type terms are sourced from the [Cell Ontology](https://www.ebi.ac.uk/ols4/ontologies/cl), which CZ CELLxGENE uses to annotate all datasets. The reference datasets can vary in the granularity of annotations— some experts may assign highly specific terms like "CD8-positive, CD25-positive, alpha-beta regulatory T cell," while others might use broader classifications such as "T cell." Please note that the cell annotation algorithm may show poor performance with samples such as cancers or cell lines, as these are not well represented in the CZ CELLxGENE database.

Our goal is to help users identify high-level cell types (e.g., T cells, B cells). To achieve this, the algorithm maps specific terms from the Cell Ontology to selected high-level cell types. These broader categories are displayed in both the web_summary.html and the .cloupe file. Some selected groups are illustrated in the figure below:

<Image src="https://cdn.10xgenomics.com/image/upload/v1726272038/software-support/Cell%20Ranger/cell-annotation/CellTypesTree.png"/>

Coarse and fine cell type annotations are available in the [cell_types.csv](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-cell-annotation-pipeline#cell-types-csv) file, which offers the option to refine classifications further.

We aim to support users seeking high-level cell type groupings. Coarse and fine cell type annotations are available in the `cell_types.csv` file, which offers the option to refine classifications further. 

Release dates for the latest models can be found on the [Annotation Models Release Notes](/support/software/cell-ranger/latest/release-notes/cr-aca-model-release-notes) page.

<LinkableSection id={"human-models"} title={"Human Models"}>

The human `human_pca_v1_beta` model is generated by first applying principal component analysis (PCA) to the reference dataset, extracting the top 512 components for each reference cell.

The inputs to the model are normalized to control for differences in library size, where normalization is:

$\frac{tc \times x_{ng}}{tmu_{n}}$

where tc = 10000; tc is the target count, a constant equal to 10,000, 
 
$tmu_{n} = \sum _{g=1}^{G} x_{ng}$


tmu represents the total mRNA UMIs, which is the sum of all counts per cell. 

$x_{ng}$ represents the expression value of gene g in cell n. This value is a measure of gene expression, such as counts or normalized expression levels, and is used as the input for various normalization and modeling procedures.

These values are then Log1p normalized and Z-score normalized. These are defined as:
- Log1p normalization: This is defined as $\log_e(1 + x_{ng})$


- Z-score normalization: Transform the expression data so that it has a mean of 0 and a standard deviation of 1. 

It is defined as:
$\frac{x_{ng} - \mu_g}{\sigma_g}$

Z-score normalization requires a summary statistics artifact, which includes mean (µ) and standard deviation (σ). When Z-score normalization is used in conjunction with Log1p, the summary statistics artifact is calculated based on the Log1p-transformed data.

We benchmarked five human tissues—brain, blood, heart, kidney, and lung—some of which included multiple tissue types. The datasets consisted of both cell and nuclei data, tested using 3’ Single Cell Gene Expression v2 and v3 chemistries, as well as 5’ Single Cell Immune Profiling v1 and v2 chemistries.

</LinkableSection>

<LinkableSection id={"mouse-models"} title={"Mouse Models"}>
The mouse `mouse_pca_v1_beta` model is generated by first identifying the top 10,000 highly variable genes in the reference database. The inputs to the model are normalized to control for differences in library size, where normalization is:

$\frac{tc \times x_{ng}}{tmu_{n}}$


where tc = 10000; tc is the target count, a constant equal to 10,000, 
 
$tmu_{n} = \sum _{g=1}^{G} x_{ng}$


tmu represents the total mRNA UMIs, which is the sum of all counts per cell. 

$x_{ng}$ represents the expression value of gene g in cell n. This value is a measure of gene expression, such as counts or normalized expression levels, and is used as the input for various normalization and modeling procedures.

These values are then Log1p normalized and Z-score normalized. These are defined as:
- Log1p normalization: This is defined as $\log_e(1 + x_{ng})$

- Z-score normalization: Transform the expression data so that it has a mean of 0 and a standard deviation of 1. 

It is defined as:
$\frac{x_{ng} - \mu_g}{\sigma_g}$

Z-score normalization requires a summary statistics artifact, which includes mean (µ) and standard deviation (σ). When Z-score normalization is used in conjunction with Log1p, the summary statistics artifact is calculated based on the Log1p-transformed data.

Principal component analysis (PCA) is performed on the normalized expression values of the highly variable genes and the top 128 components for each reference cell are used for the embedding.
</LinkableSection>

Cell Ranger's Cell Annotation Algorithm

<LinkableSection id={"pooled-crispr"} title={"Pooled CRISPR screens"}>

Feature Barcode technology may be used to perform pooled CRISPR screens in an efficient and scalable fashion. For an introduction to pooled CRISPR screens, see: Perturb-Seq (Adamson et al., 2016, and Dixit et al., 2016), CRISP-seq (Jaitin et al., 2016), CROP-seq (Datlinger et al., 2017), or CRISPR-QTL (Gasperini et al., 2019). See the [Glossary](/support/software/cell-ranger/latest/resources/cr-glossary) for definitions of terms.

The goal of a pooled CRISPR screen is to use CRISPR to perturb the expression of a list of pre-identified genes and quantitatively measure the effects of those perturbations on the transcriptome of the cells of interest. The cells are typically transfected in a pooled fashion with a number of plasmids that code for guide RNAs that target the pre-selected genes of interest. Since the assay captures both transcripts and transfected guide RNAs from each cell, one can correlate the changes in the transcriptome with the perturbations received by each sub-group of cells.

</LinkableSection>

<LinkableSection id={"exp-design"} title={"Experimental design"}>

A wide variety of experimental designs are used in pooled CRISPR screens, depending on the nature of the biological questions being investigated and the scope of the experiment. We emphasize three general principles commonly employed in such experiments.

1. **Multiple guide RNAs per target gene.** In general, it is hard to predict the functional efficacy of a guide RNA construct purely from its _in silico_ design. In order to mitigate the risk of non-functional guide RNA molecules that do not perturb the expression of their target genes significantly, pooled CRISPR screens typically employ 2-5 guide RNA constructs per target gene.

2. **Non-targeting guide RNAs that function as negative controls.** In order to measure the effectiveness of a particular guide RNA construct in perturbing the expression of its target gene, or the effects of such a perturbation on the rest of the transcriptome, one would need to perform a differential expression analysis where the cells expressing the relevant guide RNA(s) are compared with control cells. The experimental design typically includes control guide RNA constructs that are explicitly designed not to target any annotated genes in the reference transcriptome; these guide RNAs are called "non-targeting" guides. The control cells used in the differential expression analyses are typically cells identified as containing only (some combination of) non-targeting guides. In order to account for possible error in the design or transfection of these non-targeting guide RNA constructs, typically more than one such construct (usually 2-5) are used in the experiment.

3. **Carefully designed and validated transfection protocol.** Based on the particular transfection protocol used in the assay, the distribution of guide RNA constructs among cells can vary widely, from as few as a median of 1 guide per cell to as high as 15 per cell. The transfection protocol is usually carefully designed based on the requirements imposed by the biological questions of interest, such as the median number of guide RNA constructs per cell or the number of cells required per perturbation of interest. In addition, typically the transfection protocol is validated by some combination of PCR-based techniques and next-generation sequencing (see Methods sections of the [References](#references)).

</LinkableSection>

<LinkableSection id={"protospacer-calling"} title={"Protospacer calling"}>

In pooled CRISPR screens, the presence of low levels of ambient guide RNA in solution typically leads to a small number of "background" UMI counts even in cells that do not express any guide RNA constructs. Protospacer calling is used to identify CRISPR sgRNA associated with cell barcodes and separate signal from background UMIs.

During the Protospacer Calling step, Cell Ranger identifies, for each guide RNA construct specified in the Feature Reference CSV File, the sub-population of cells that express that particular guide RNA significantly above background.

Cell Ranger models two cell populations for each guide RNA: those expressing the guide and those with UMI counts from ambient guide RNA only. It then fits a Gaussian Mixture Model to the log-transformed distribution of Molecules/Cell for each guide RNA to differentiate these populations. This model assesses the likelihood that a cell is part of the guide-expressing population versus the background. Cells are classified as expressing the guide RNA if they have a high probability of belonging to that guide-expressing population and possess at least **three** guide RNA UMIs. This process is applied separately for each guide RNA in the Feature Reference CSV File. Refer to the [Experimental Planning Guide](/support/universal-three-prime-gene-expression/documentation/steps/sample-prep/chromium-single-cell-crispr-screening-experimental-planning-guide) for details.

Cell Ranger v7.0 and later allow CRISPR Guide Capture datasets to be [aggregated](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-3p-aggr#aggr_count). Protospacer calling is performed again on the aggregated data.

</LinkableSection>

<LinkableSection id={"perturb-eff"} title={"Perturbation efficiency and transcriptome-wide effects"}>

In pooled CRISPR screens, two central questions arise. First, to what extent did the expression of the target genes change amongst those cells expressing the guide RNAs that targeted those genes ("Perturbation Efficiency")? Second, what effects did these perturbations have on the transcriptome of those cells ("Perturbation Effects")?

Both questions rely on differential expression analyses. As with Gene Expression, Cell Ranger uses the quick and simple method sSeq (Yu, Huber, & Vitek, 2013) in order to find differentially expressed genes between the perturbed cells and the control cells (cells that only contain guide RNAs designed specifically to be non-targeting). For details on the implementation of sSeq within Cell Ranger, see [**Gene Expression**](/support/software/cell-ranger/latest/algorithms-overview/cr-gex-algorithm).

To quantify Perturbation Efficiency, we report the log2-fold-change in the expression of each target gene. To address transcriptome-wide Perturbation Effects, we provide a list of top perturbed genes for each perturbation, in addition to a list of how every gene in the reference transcriptome changed under each perturbation.

Each of the above results are calculated "by feature," where the cells are grouped based on the combinations of guide RNAs they contain, or "by target," where they are grouped based on the combinations of genes targeted by those guide RNAs. (The latter can lead to increased statistical power in cases where each gene is targeted by multiple guides, since cells where the same combinations of genes are perturbed may be grouped together.)

CRISPR output files are described in detail, with examples, here: [**CRISPR output files**](/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-crispr-overview).

</LinkableSection>

<LinkableSection id={"references"} title={"References"}>

- Adamson B, et al. [A multiplexed single-cell CRISPR screening platform enables systematic dissection of the unfolded protein response](https://www.sciencedirect.com/science/article/pii/S0092867416316609). _Cell_ 167: 1867-1882, 2016.

- Datlinger P, et al. [Pooled CRISPR screening with single-cell transcriptome readout](https://www.nature.com/articles/nmeth.4177). _Nature Methods_ 14: 297–301, 2017.

- Dixit A, et al. [Perturb-Seq: Dissecting molecular circuits with scalable single-cell RNA profiling of pooled genetic screens](https://www.sciencedirect.com/science/article/pii/S0092867416316105). _Cell_ 167: 1853–1866, 2016.

- Gasperini M, et al. [A Genome-wide framework for mapping gene regulation via cellular genetic screens](https://www.sciencedirect.com/science/article/pii/S009286741831554X). _Cell_ 176: 377-390, 2019.

- Jaitin D, et al. [Dissecting immune circuits by linking CRISPR-pooled screens with single-cell RNA-Seq](https://www.sciencedirect.com/science/article/pii/S0092867416316117). _Cell_ 167: 1883–1896, 2016.

- Yu D, Huber W, and Vitek O. [Shrinkage estimation of dispersion in Negative Binomial models for RNA-seq experiments with small sample size](https://academic.oup.com/bioinformatics/article/29/10/1275/259212). _Bioinformatics_ 29: 1275–1282, 2013.

</LinkableSection>

Cell Ranger's CRISPR Guide Capture Algorithm

<SupportCallout>
<text as={"span"}>Fixed RNA Profiling has been renamed Flex. All future updates, documentation, and support will reference Flex.</text>
</SupportCallout>

<LinkableSection id={"flex-gex"} title={"Gene Expression library algorithms"}>

Cell Ranger 7.0 introduces support for Flex libraries using the `cellranger multi` pipeline. While some steps are similar to the existing algorithm for [Gene Expression](/support/software/cell-ranger/latest/algorithms-overview/cr-gex-algorithm), there are a few differences illustrated and described below for singleplex and multiplex Flex experiments.

**Singleplex Flex steps**<Image src={"https://cdn.10xgenomics.com/image/upload/v1691170867/software-support/Fixed-RNA-Profiling/flex-cr7.2/SFRP-GEX-algo.png"} />

**Multiplex Flex steps**<Image src={"https://cdn.10xgenomics.com/image/upload/v1691170865/software-support/Fixed-RNA-Profiling/flex-cr7.2/MFRP-GEX-algo.png"} />

</LinkableSection>

<LinkableSection id={"assign-reads"} nested={true} title={"Assigning reads to samples"}>

### Singleplex workflow

The cell barcode will be composed only of the 10x GEM Barcode and all reads with valid barcodes are considered to be part of the sample. This configuration does not use a `[samples]` section in the multi config file.

### Multiplex workflow

The cell barcode will be composed of both the 10x GEM Barcode and the Probe Barcode. Reads must have valid 10x GEM and Probe Barcodes in order to be assigned to a sample. The corrected Probe Barcode sequence is mapped to its corresponding Probe Barcode ID. If this ID has been specified within the `probe_barcode_ids` column of the `[samples]` section, the read is assigned to the sample associated with this Probe Barcode ID.

Note that each Probe Barcode ID (e.g., BC001) is actually a mix of four distinct barcode sequences, which ensures balanced base composition during sequencing. Raw Probe Barcode sequences are first corrected independently of the corresponding 10x GEM Barcode using the full list of all Probe Barcode sequences from probe construction. These corrected sequences are then collapsed such that the Probe Barcode sequence used within the cell barcode is always lexicographically the first barcode amongst the four barcodes from a given mixture. For example, if the four Probe Barcodes are `ACTTTAGG`, `CGAGGGTA`, `GACACTAC`, and `TTGCACCT`, all instances of these Probe Barcodes will be converted to `ACTTTAGG` for use within the Cell Ranger pipeline and outputs (e.g., feature-barcode matrix). The original sequence will be maintained in uncorrected form within the raw [cell barcode tag (`CR`)](/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-bam#bam-bc-tags) included in the BAM file.

</LinkableSection>

<LinkableSection id={"probe-alignment"} nested={true} title={"Probe alignment"}>

Cell Ranger 7.0 introduces support for analyzing fixed RNA using the [cellranger multi](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-flex-multi-frp) pipeline. During the fixed RNA workflow, whole transcriptome probe panels, consisting of multiple pairs of probes for each targeted gene, are added to the tissue. These probe pairs hybridize to their target transcript and are then ligated together.

To analyze fixed RNA data, the `probe-set` parameter must be used to specify a probe set reference CSV file. When this parameter is used, Cell Ranger will count ligation events using the probe aligner algorithm (reads are also aligned to the reference transcriptome using STAR, but only to determine their alignment positions and CIGAR strings; STAR alignments are not used to assign reads to genes for fixed RNA data).

Distinct ligation events are counted for Flex rather than distinct transcripts. Sequencing reads are aligned to the probe set reference and assigned to the genes they target. For genes targeted by more than one probe pair, the UMI counts of all probe pairs targeting that gene are summed up and output as the UMI count for that gene in the feature-barcode matrix (for more information, see [this article](https://kb.10xgenomics.com/hc/en-us/articles/6771829458445-Does-Cell-Ranger-normalize-UMI-counts-based-on-the-coverage-of-genes-in-Fixed-RNA-Profiling-)).

The probe alignment algorithm is similar to a seed-and-extend aligner, where each half of the read is a seed, as described in detail below:

- Build an index of the half-probe sequences in the probe set reference CSV.
- For each read, look up each read half in this index, allowing up to one mismatch and no indels.
- If both halves of the read map to the same probe ID, the read is confidently mapped with a [MAPQ](/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-bam#frp-mapq) (mapping quality) of 255.
- If one half maps and the other half does not map, compare the sequence of the unmapped half to the expected sequence for that probe, allowing mismatches but not indels. If the match exceeds the minimum alignment score (30, scoring +1 for a match and -1 for a mismatch), the read is confidently mapped.
- If the unmapped half of the read does not match the expected sequence for that probe, the read is half-mapped with a MAPQ of 1, and does not contribute to UMI counts.
- If both halves of the probe map but to different probes, the read is ambiguously mapped with a MAPQ of 3, and does not contribute to UMI counts.
- If neither probe half aligns to the probe set reference by the probe aligner algorithm, the read is unmapped and will have MAPQ=0 (column 5). If neither probe half aligns to the probe set reference by the probe aligner algorithm and the reference transcriptome by STAR, the read will be UNMAPPED (0x4) in `FLAG` (column 2) and also have MAPQ=0.
- All reads with up to three mismatches are guaranteed to align.

<Flex justifyContent={"center"}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1658251158/software-support/Fixed-RNA-Profiling/TRTL-FRP-MappingMetrics.png"} width={"600px"} length={"600px"} />
</Flex>

The BAM tag `pr:Z` reports a semicolon-separated list of probe IDs. See [BAM alignment tags](/support/software/cell-ranger/latest/analysis/outputs/cr-outputs-bam#bam-align-tags) for a detailed description.

</LinkableSection>

<LinkableSection id={"call-cells"} nested={true} title={"Calling cell barcodes"}>

The cell calling algorithm is the same as described on the [Gene Expression algorithm page](/support/software/cell-ranger/latest/algorithms-overview/cr-gex-algorithm), but done for each sample individually.

</LinkableSection>

<LinkableSection id={"probe-filtering"} nested={true} title={"Probe filtering"}>

Probes that are predicted to have off-target activity to homologous genes or sequences are excluded from analysis by default (all probes are present in the raw matrix file). These probes are marked with `FALSE` in the included column of the probe set reference CSV. Any gene that has at least one probe with predicted off-target activity will be excluded from filtered outputs. Setting `filter-probes` to `false` in the multi config file for `cellranger multi` will result in UMI counts from all non-deprecated probes, including those with predicted off-target activity, to be used in the analysis. Probes whose ID is prefixed with `DEPRECATED` are always excluded from the analysis. Please see the [Probe Set Overview](https://support.10xgenomics.com/fixed-rna-profiling/probe-sets/overview) for details on the probes.

</LinkableSection>

<LinkableSection id={"high-occ-gem"} nested={true} title={"High occupancy GEM filtering"}>

Cell calling is performed and we utilize the 10x GEM and Probe Barcodes to estimate the mean of the Poisson distribution that should describe the number of Probe Barcodes observed per GEM under optimal chip loading. Note that the mean of this distribution will increase roughly linearly with cell load. Using the expected distribution, we estimate the 99.9th percentile for the number of Probe Barcodes observed per GEM, and remove all cells belonging to GEMs that fall beyond this threshold in the observed distribution to mitigate higher than expected barcode collision rates.

High amounts of filtering due to high occupancy GEMs may reflect partial clogs/wetting failures or significant deviations from the recommended chip loading protocol. In an optimal experiment, the percentage of cells passing high occupancy GEM filtering that can be used for analysis is usually more than 90%.

The lefthand plot below shows an example of a multiplex Flex experiment with 16 Probe Barcodes aiming to capture 100,000 cells. Cells contained in GEMs falling in the red zone in the observed distribution will be removed from Cell Ranger's filtered outputs (1.14% removed, 98.86% used). Note that the Y-axes of the histograms are log10 scaled.

For comparison, the righthand plot illustrates an experiment with a lower targeted cell number (5,000 cells) with 16 Probe Barcodes, for which 0.12% of cells are removed and 99.88% can be used.

<Image src={"https://cdn.10xgenomics.com/image/upload/v1647895483/software-support/Fixed-RNA-Profiling/high_occupancy_gem_figure.png"} />

</LinkableSection>

<LinkableSection id={"gdna"} nested={true} title={"Estimation of genomic DNA level"}>

In Flex, as long as the standard workflow is followed, probe accessibility to genomic DNA (gDNA) should be limited. The expectation is that gDNA should have a negligible (less than 1%) contribution to sequenced ligation events.

The two exceptions are:

- If samples are decrosslinked during an antigen retrieval step (>70°C)
- Samples are relatively low in complexity (lower UMI counts)

Cell Ranger uses a subset of transcript probes that have a mix of exon-junction-spanning (spliced) and non-exon-junction-spanning (unspliced) probes for the same gene to estimate gDNA content. Counts from probes that do **not** span an exon-exon junction include some background signal, as these probes can hybridize to gDNA. Probes that **do** span an exon-exon junction will specifically detect spliced transcripts with no or minimal signal due to gDNA background. This method estimates the proportion of UMIs that are derived from background ligation events.

The relationship between the counts from exon-exon-junction-spanning and non-exon-junction-spanning probes can be visualized in a scatter plot as shown below.

<Flex justifyContent={"center"}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1668734687/software-support/Fixed-RNA-Profiling/gDNAplot.png"} width={"500px"} length={"500px"} />
</Flex>

Each point in the plot reflects the relationship between two pseudo-bulk counts for a gene. The x-axis represents the sum of the junction-spanning probe counts across barcodes per gene. The y-axis represents the sum of the non-junction-spanning probe counts across barcodes for the same gene.

The difference in the counts due to background becomes apparent at low probe counts. The relationship between the pseudo-bulk counts switches from being linearly correlated (turquoise) to non-correlated (purple) in the figure above.

A segmented linear model is used to estimate where the unspliced and spliced counts begin to deviate. The mean of unspliced counts (purple) estimates the UMI background level per unspliced probe. Counts less than this value have a high probability of stemming from gDNA.

Starting in Cell Ranger 7.1, the [web summary](/support/software/cell-ranger/latest/analysis/outputs/cr-3p-outputs-web-summary-multi) and `metrics_summary.csv` will report genomic DNA metrics when the v1.0.1 probe set reference CSV with the `region` column is used. The metrics are shown in the Library view for a singleplex experiment and in the Library and Cells views for a multiplex experiment.

- The metric `Estimated UMIs from Genomic DNA` is the estimated fraction of filtered UMIs derived from gDNA based on the discordance between probes targeting exon-junction-spanning regions and non-exon-junction-spanning regions. Normally, `Estimated UMIs from Genomic DNA` should be less than 5% in Flex data with good quality samples. The fraction is calculated as follows,

 $$ \frac{\text{Estimated UMIs from genomic DNA per unspliced probe}\times{\text{Number of unspliced probes}}}{\text{Total number of filtered UMIs}} $$

- The `Estimated UMIs from genomic DNA per unspliced probe` is the estimated number of UMIs derived from gDNA for each probe targeting non-exon-junction-spanning regions. A probe not spanning an exon junction with a total UMI count below this value has a high likelihood of its UMIs being derived primarily from hybridization to genomic DNA rather than mRNA.

</LinkableSection>

<LinkableSection id={"secondary"} nested={true} title={"Secondary analysis of gene expression"}>

The secondary analyses are described on the [Gene Expression algorithm page](/support/software/cell-ranger/latest/algorithms-overview/cr-gex-algorithm#secondary-analysis).

</LinkableSection>

<LinkableSection id={"assign-reads"} title={"Antibody Capture library algorithms"}>

<Image src={"https://cdn.10xgenomics.com/image/upload/v1692392920/software-support/Fixed-RNA-Profiling/flex-cr7.2/MFRP-GEX-Ab-algo.png"} />

</LinkableSection>

<LinkableSection id={"ab-aggregate"} nested={true} title={"Antibody aggregate detection"}>

The algorithms used for Flex experiments with Antibody Capture libraries are the same as those documented on the Antibody Capture algorithm [page](/support/software/cell-ranger/latest/algorithms-overview/cr-ab-algorithm).

After reads are assigned to samples, the aggregate filtering algorithm is applied per sample (not per barcode), followed by per sample cell calling using the Gene Expression data. In antibody-only analyses, cell calling is done with the Antibody Capture data.

</LinkableSection>

<LinkableSection id={"auto-pair"} nested={true} title={"Detecting multiplex barcode pairs"}>

Starting in v7.2, there is a multiplexing barcode pair auto-detection algorithm for Flex multiplex GEX + Antibody Capture experiments.

The algorithm automatically detects the corresponding Antibody Multiplexing Barcode (e.g., "AB001") for a Probe Barcode (e.g., "BC001") that is specified in the multi config CSV file. If the user specifies the pairing (e.g., "BC001+AB001") in the multi config CSV file, the result of the auto-pairing algorithm is only used to provide a warning if its result disagrees with the explicit pairing.

The barcodes are paired based on a whitelist with Probe Barcodes and Antibody Multiplexing Barcodes using a subset of all reads for each library during the chemistry detection phase. The algorithm:

- Removes any Probe Barcode (BC) or Antibody Multiplexing Barcode (AB) that appears in < 0.5% of all GEMs observed in the read subset.
- Computes the cell barcode overlap coefficient between all possible pairings of BC and AB barcodes.
- Uses a greedy approach to pair the BC and AB barcodes with the highest overlap coefficient, continuing until all multiplexing barcodes are uniquely paired or the pool of possible pairs is exhausted.

During barcode correction and feature counting, each paired AB barcode is translated into its corresponding BC barcode to ensure that gene expression and antibody feature counts from the same cell appear in the count matrix with the same cell barcode.

Barcode pair syntax:

- For a GEX + Antibody analysis, either specify all `probe_barcode_ids` as "BC00X+AB00X" or "BC00X"; do not mix these formats in one config file.
- For Antibody Capture-only analysis, only specify the "AB00X" barcode in the config CSV; do not mix with GEX analysis in one config file.

Barcode auto-pairing is disabled for CRISPR Guide Capture. CRISPR Multiplexing Barcodes must be specified in the [multi config CSV](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-flex-multi-frp#mfrp-gex-crispr) (e.g., `BC001+CR001`)
</LinkableSection>

<LinkableSection id={"barcode-correlation"} title={"Unexpected multiplexing barcode correlation detection"}>

For Flex multiplex GEX + Antibody Capture experiments, there is an algorithm to identify potentially unexpected correlations between pairs of BC and AB barcodes (BC-AB, BC-BC, AB-AB pairs). These correlations could be indicative of a workflow error or a mistake in the multi config CSV file if an explicit barcode pairing was provided, for example:

- One Probe Barcode is detected as being associated with more than one Antibody Multiplexing Barcode
- Antibody Multiplexing Barcode has no associated Probe Barcode
- Incorrect pairing specified in the multi config CSV (Cell Ranger will run to completion with a web summary error message about the detected incorrect pairing)

The correlations are identified using the cell barcode overlap coefficient between all possible pairings of BC and AB barcodes besides the pairs used in the analysis. Any pairing with an overlap coefficient ≥ 0.6 will be reported in the web summary. If present, barcode overlap metrics are provided in the `frp_gem_barcode_overlap.csv` [output file](/support/software/cell-ranger/latest/analysis/outputs/cr-flex-outputs-frp#mfrp-multidir). The calculation for Antibody Multiplexing Barcode contamination detection is similar to Probe Barcode contamination detection:

Overlap coefficient = $ \frac{{\text{Common GEMS}}} {\text{min(Barcode 1 GEMS, Barcode 2 GEMS)}} $

</LinkableSection>

Cell Ranger's Flex Algorithm

Cell Ranger's Gene Expression Algorithm

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

Supported Libraries

Download Center

Cloud Analysis

Cell Ranger Commands

Analysis

Tutorials

Algorithms

Advanced

Troubleshooting

Miscellaneous

Release Notes

Glossary

Datasets

Loupe Browser

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?

<Flex flexDirection={'column'} gap={'0.5rem'}><div><Text as={'span'} size={'small'} weight={'medium'}>{'Starting with v9.0, anonymized telemetry data is collected and sent to 10x Genomics. '}</Text><Anchor href={'https://10xgen.com/pipeline-telemetry'}><Text as={'span'} color={'inherit'} size={'small'} weight={'medium'}>{'Learn how to disable.'}</Text></Anchor></div><Text as={'p'} size={'small'} weight={'medium'}>Fixed RNA Profiling has been renamed Flex. All future updates, documentation, and support will reference Flex.</Text><Text as={'p'} size={'small'} weight={'medium'}>The cellranger mkfastq pipeline is deprecated and will be removed in a future release. Please use Illumina’s BCL Convert to generate Cell Ranger-compatible FASTQ files.</Text></Flex>

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.

Algorithms Overview