Where can I find the AB Barcode Rank Plot? This depends on the Cell Ranger pipeline and experimental setup.

In the `cellranger count` web summary: 

 * This plot is shown for Antibody-only analysis. It is it not generated if a Gene Expression library was present in the Cell Ranger analysis.


In the `cellranger multi` web summary:

 * For GEX + Antibody Capture analyses, it will always be generated.
 * For **single-sample experiments**: this plot will only be shown in the Library view's Antibody tab.
 * For **3' Cell Multiplexing experiments**: this plot will be shown in the Library view's Antibody tab (i.e., if multiple antibody-stained samples are labeled with CMO tags and pooled in one GEM well, resulting in three libraries - Gene Expression, Multiplexing Capture, Antibody Capture).
 * For **multiplex Fixed RNA Profiling experiments**: this plot will be shown in both the Cells view and the Library view Antibody tabs (i.e., if multiple antibody-stained FRP samples are pooled in one GEM well). In this scenario, the barcode rank plots for each sample (on Cells view) are most helpful for sample-specific quality assessment and troubleshooting. 

Overview

Like the [Gene Expression barcode rank plot](/support/software/cell-ranger/analysis/outputs/cr-barcode-rank-plot), the y-axis shows UMI counts on a logarithmic scale and the x-axis shows barcodes sorted in decreasing order from the number of UMIs on a logarithmic scale. Note that the order of barcodes in the Antibody barcode rank plot is not the same as the order in the corresponding Gene Expression barcode rank plot.

The blue regions of the curve represent cells called using the Gene Expression data (if present), not the Antibody Capture library. The Antibody Capture library is used for cell calling only in Antibody-only analysis (no paired gene expression library). The gray regions represent background.

 <Flex justifyContent={"center"}><Image src={"https://cdn.10xgenomics.com/image/upload/v1693525938/software-support/Cell%20Ranger/cr7.2-ab-barcode-rank-plot/example_ab_rank_plt_zoom1.png"} width={'400px'}/></Flex> 


Click on the `?` for a high-level summary of the AB Barcode Rank Plot. 

You can zoom in and out along the X and Y axes and hover your mouse over specific data points. Percentage values appear as you hover over different regions of the plot. These numbers show the proportion of barcodes that were assigned as cells by the [Gene Expression data cell calling algorithm](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm) for a given UMI range. 

 The blue color gradient is proportional to the fraction of cells in a given subset of barcodes; darker blue indicates a higher proportion of cell barcodes versus background. An example is shown below for interpreting two different percentage values that pop-up while hovering over data points.

 <Image src={"https://cdn.10xgenomics.com/image/upload/v1693525938/software-support/Cell%20Ranger/cr7.2-ab-barcode-rank-plot/example_ab_barcode_rank_plt_zoom2.png"} width={'300px'}/> | <Image src={"https://cdn.10xgenomics.com/image/upload/v1693525938/software-support/Cell%20Ranger/cr7.2-ab-barcode-rank-plot/example_ab_barcode_rank_plt_zoom3.png"} width={'300px'}/> 
 --- | ---
 2247 of 2427 (93%) barcodes in this UMI range were called as cells | 1271 of 1533 (83%) barcodes in this UMI range were called as cells

Interpreting the plot

Barcodes associated with [antibody aggregates](/support/software/cell-ranger/algorithms-overview/cr-ab-algorithm#protein-aggr) are detected and removed from cell calling. Often, these barcodes have unusually high antibody UMI counts and appear at the top left of the AB Barcode Rank Plot. This region will consequently be gray if the algorithm regards it as background.

For example, in these example plots, the fraction of antibody reads in aggregate barcodes is 1.58% (left) and 20.81% (right):

 <Image src={"https://cdn.10xgenomics.com/image/upload/v1693527573/software-support/Cell%20Ranger/cr7.2-ab-barcode-rank-plot/antibody_aggregate_example.png"}/>

 The "Fraction antibody reads in aggregate barcodes" metric is listed in the Mapping Metrics table of the `multi` web summary.


The barcodes removed by aggregate filtering can be found in the `aggregate_barcodes.csv` file described [here](/support/software/cell-ranger/analysis/outputs/cr-outputs-ab-overview#protein-aggregate-barcodes).

Antibody aggregates

Antibody data quality can vary depending on the antibody panel and the sample complexity.

The AB Barcode Rank Plot may have a "cliff-and-knee" shape, similar to the typical shape of [Gene Expression Barcode Rank Plots](/support/software/cell-ranger/analysis/outputs/cr-barcode-rank-plot#barcode-rank-plots-of-compromised-samples-cc019d). 

However, an AB Barcode Rank Plot that does not have an obvious "cliff-and-knee" shape does not always indicate poor antibody data quality. For example, this sample has a reasonably high percentage of antibody reads in cells (68.23%), despite the linear barcode rank plot shape and high percentage of antibody reads in aggregate barcodes (21.49%):

 <Flex justifyContent={"center"}><Image src={"https://cdn.10xgenomics.com/image/upload/v1693528793/software-support/Cell%20Ranger/cr7.2-ab-barcode-rank-plot/antibody_aggregate_ok_sample.png"} width={'400px'}/></Flex> 


Here is an example of a poor AB Barcode Rank Plot. For this library, only 27.93% of antibody reads are in cells (few cells called in the top left high UMI region) and 19.15% of antibody reads are in aggregate barcodes. 

 <Flex justifyContent={"center"}><Image src={"https://cdn.10xgenomics.com/image/upload/v1694212511/software-support/Cell%20Ranger/cr7.2-ab-barcode-rank-plot/example_poor_ab_rank_plt.png"} width={'400px'}/></Flex> 


For this example, many barcodes with high antibody UMI counts (>2000) are not called as cells in the corresponding gene expression data, suggesting high ambient antibody signal. In general, when the fraction of antibody reads in cells and/or usable antibody reads are low and there is an indicator of high ambient antibody signal, the sample may have one or more of the issues below:

 * Insufficient washing of the cells
 * High amount of cell debris in the sample
 * High number of antibody aggregates in the sample

Barcode rank plot shape

Cell Ranger's Web Summary Antibody Barcode Rank Plot

The Barcode Rank Plot is an interactive plot that shows all barcodes detected in an experiment, ranked from highest to lowest UMI count. It is useful for understanding Cell Ranger’s cell calling algorithm and its performance on your data, and for providing insights into your sample quality.

The Barcode Rank Plot can be found under the Cells dashboard of the [web summary file](/support/software/cell-ranger/analysis/outputs/cr-outputs-web-summary) (an output file of [cellranger count](/support/software/cell-ranger/analysis/running-pipelines/cr-gex-count) and [cellranger multi](/support/software/cell-ranger/analysis/running-pipelines/cr-3p-multi)).

<Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1682627718/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-1.png'}
/>

Expand the question mark tab in the Cells section for details about the different metrics within that section of the web summary, along with a high-level summary of the Barcode Rank Plot.

<Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1682627723/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-2.png'}
/>

You can zoom in and out along the X and Y axes and hover your mouse over specific data points.

<Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1682627715/software-support/3p-Single-Cell-GEX/barcode-rank-plot/GIF-1and3.gif'} width={'500px'}
/>

Percentage values appear as you hover over different regions of the Barcode Rank Plot. These numbers show the proportion of barcodes that were assigned as cells by the [cell calling algorithm](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm) for a given UMI range. The blue color gradient is proportional to the fraction of cells in a given subset of barcodes; darker blue indicates a higher proportion of cell barcodes versus background. An example of how to interpret two different percentage values that pop-up while hovering over data points on a Barcode Rank Plot is shown below.

<Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1682627718/software-support/3p-Single-Cell-GEX/barcode-rank-plot/GIF-2.gif'} width={'500px'}
/> <Flex justifyContent={"center"}><Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1682627715/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-4.png'} width={'250px'}
/></Flex>

Supporting documentation for interpreting the Barcode Rank Plot and web summary metrics are provided on the [10x support site](/support/software/cell-ranger/analysis/outputs/cr-outputs-web-summary) and in this technical note: [Interpreting Cell Range Web Summary Files for Single Cell Gene Expression Assays](/support/single-cell-gene-expression/documentation/steps/sequencing/interpreting-cell-ranger-web-summary-files-for-single-cell-gene-expression-assays).

<Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1682627717/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-3.png'}
/>

Supporting documentation

The [cell calling algorithm](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm#cell_calling) is a multi-step process that determines which barcodes/GEMs are likely to contain an intact cell and uses those for downstream analysis. The cell calling algorithm can be broadly divided into two major steps:

* Step 1. Identify barcodes/GEMs that are likely to contain an intact cell based on the expected cell number and UMI counts.
* Step 2. Distinguish low RNA content cells from empty droplets based on the expression profiles using the [EmptyDrops](https://genomebiology.biomedcentral.com/articles/10.1186/s13059-019-1662-y) method.[](<>)

Overview of the cell calling algorithm

In this step, barcodes are called cells if the total UMI counts for a barcode exceed m/10, where m is the 99th percentile of Nexpect cell barcodes based on total UMI counts. An example is provided below to illustrate.

Cell Ranger uses an algorithm to calculate the metric `--expect-cells`. More information about how this metric is calculated in the latest versions of cell ranger can be found on our [algorithms page](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm#cell_calling#cell_calling). Starting from Cell Ranger 7.0, `--expect-cells` can either be auto-estimated using the algorithm or provided by the user with a reasonable estimate of recovered cells.

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682627715/software-support/3p-Single-Cell-GEX/barcode-rank-plot/GIF-1and3.gif'}
/>

In this example, if `–-expect-cells = 30,000`, the 99th percentile barcode is barcode 30. The number of UMIs at barcode 30 is ~26,050. Any barcode with greater than 26,050/10 = 2,605 UMIs is called a cell. These are the 11,101 out of 11,101 (100%) barcodes that are initially called as cells in the Barcode Rank Plot and can be seen as the segment of dark blue (with 100% cells) on the Barcode Rank Plot. Starting from Cell Ranger v7.1.0, the range of barcodes that can be considered for expect-cells auto-estimation is 2-45k.

Step 1: Which GEMs are likely to contain an intact cell?

In the second step of the cell calling algorithm, Cell Ranger selects a set of low UMI barcodes (for the standard 3’ Single Cell Gene Expression* assay, barcodes within rank 45k-90k) to represent background GEMs and uses these as a reference to identify all of the remaining barcodes as either background barcodes or cell barcodes. First, Cell Ranger generates a background gene expression model. The RNA profile of each barcode that was not called a cell in the first step is then compared to the background model. Barcodes whose RNA profile significantly differs from the background model are added to the set of positive cell calls. This second step identifies cells that are distinguishable from the profile of empty GEMs, despite having much lower RNA content than the largest cells in the experiment.

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682627719/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-5.png'}
/>

Since barcodes can be determined to be cell-associated based on their UMI count or by their RNA profiles, some regions of the graph can contain both cell and background barcodes. The color of the graph represents the local density of barcodes that are cell-associated where darker blue indicates a higher proportion of cell barcodes and lighter shades indicate a lower proportion of cell barcodes

Lastly, Cell Ranger removes barcodes with a total UMI count \<500 or

`TotalUMICount < median(InitialCellUmis)∗0.01`

`InitialCellUmis` is the distribution of UMI counts for the barcodes initially called as cells in Step 1 of the algorithm. As you can see from the Barcode Rank Plot, barcodes with UMI count \<500 were called background, and therefore removed from downstream analysis.

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682627717/software-support/3p-Single-Cell-GEX/barcode-rank-plot/GIF-4.gif'}
/>

*Note: Cell Ranger processes [Chromium Next GEM Single Cell 3’ and 5' HT kits (referred to as high throughput or HT)](/support/software/cell-ranger/getting-started/cr-what-is-HT) similarly to standard libraries except for minor adjustments to certain parameters in the cell calling algorithm. These kits can process 2,000-20,000 cells per channel (3' and 5') or 2,000-60,000 cells per channel with CellPlex (3' only)*

Step 2: Which GEMs are empty droplets containing ambient RNA?

The overall shape of the Barcode Rank Plot is a useful indicator of sample quality. A “cliff-and-knee” shape in the Barcode Rank Plot is indicative of a good quality sample.

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682627716/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-6.png'}
/>

In this case, the steep cliff, followed by the plateaued knee, demonstrates that the cell calling algorithm was able to distinguish between intact cells and background barcodes.

The shape of the Barcode Rank Plot can reveal compromises in sample quality or workflow. Two such compromises are: loss of single cell behavior and low barcode counts.

Loss of single cell behavior can occur due to workflow problems, like high levels of debris that prevent the creation of GEMs (also called a wetting failure). When there is a wetting failure, the estimated number of cells is unreliable because the algorithm has trouble discerning cells from background. An example of a wetting failure Barcode Rank Plot is shown below:

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682628237/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-7_new.png'}
/>

A clog in the chip (due to clumping in the single cell suspension and/or high debris) can result in low barcode counts. This, in turn, leads to lower-than-expected cell recovery based on the targeted cell number and can be seen in the Barcode Rank Plot (example below).

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682628310/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-8_new.png'}
/>

Barcode Rank Plots of compromised samples

Lastly, the Barcode Rank Plot can help identify heterogeneous samples. Heterogeneous samples appear as two cliffs and knees in the plot (see example below). In general, the cell calling algorithm can identify true cells in heterogeneous samples. However, in rare cases, heterogeneity may only be observable by eye. The `--force-cells` option in`cellranger count` can be used to identify the true cells in the heterogeneous sample.

<Image src={'https://cdn.10xgenomics.com/image/upload/v1682629020/software-support/3p-Single-Cell-GEX/barcode-rank-plot/BRP-9.png'}
/>

For an in-depth look at how to identify a heterogeneous sample using the Barcode Rank Plot and use the `--force-cells` option, see our [Capturing Neutrophils](/support/software/cell-ranger/tutorials/cr-tutorial-neutrophils) tutorial.

Barcode Rank Plots of heterogeneous samples

Cell Ranger's Web Summary Barcode Rank Plot

Installing the Cell Ranger software on a cluster is identical to [installation on a local server](/support/software/cell-ranger/downloads). After confirming that the `cellranger` commands can run in *single server* mode, configure the *job submission template* that Cell Ranger uses to submit jobs to the cluster. Assuming Cell Ranger is installed to `/opt/cellranger-7.1.0`, the process is as follows.

**Step 1.** Navigate to the Martian runtime's `jobmanagers/` directory that contains example jobmanager templates.

```
# command to change directory
cd /opt/cellranger-7.1.0/external/martian/jobmanagers

# command to list files
tree -L 2
.
├── config.json
├── hydra.template
├── lsf.template.example
├── pbspro.template.example
├── retry.json
├── sge_queue.py
├── sge.template.example
├── slurm.template.example
└── torque.template.example
```

**Step 2.** Make a copy of the cluster's example template (SGE or LSF) to either `sge.template` or `lsf.template` in the `jobmanagers/` directory.

```
# command to copy file
cp -v sge.template.example sge.template

`sge.template.example' -> `sge.template'

# command to list files
tree -L 2
.
├── config.json
├── hydra.template
├── lsf.template.example
├── pbspro.template.example
├── retry.json
├── sge_queue.py
├── sge.template.example
├── sge.template
├── slurm.template.example
└── torque.template.example
```

The job submission templates contain several special variables that are substituted by the Martian runtime when each stage is submitted. Specifically, the following variables are expanded when a pipeline is submitting jobs to the cluster:

| Variable                                                | Must be present? | Description                                                                 |
| ------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------- |
| `__MRO_JOB_NAME__`                                      | Yes              | Job name composed of the sample ID and stage being executed                 |
| `__MRO_THREADS__`                                       | No               | Number of threads required by the stage                                     |
| `__MRO_MEM_GB__` `__MRO_MEM_MB__`                       | No               | Amount of memory (in GB or MB) required by the stage                        |
| `__MRO_MEM_GB_PER_THREAD__` `__MRO_MEM_MB_PER_THREAD__` | No               | Amount of memory (in GB or MB) required per thread in multithreaded stages. |
| `__MRO_STDOUT__` `__MRO_STDERR__`                       | Yes              | Paths to the `_stdout` and `_stderr` metadata files for the stage           |
| `__MRO_CMD__`                                           | Yes              | Bourne shell command to run the stage code                                  |

**It is critical that the special variables listed as required are present in the final template you create.** For more information on how the template should appear for a cluster, consult your cluster administrator or help desk.

Configuring cluster template

Depending on which job scheduler you have, select an option below.

### S﻿GE

For SGE cluster, you MUST replace `<pe_name>` within the example template to reflect the name of the cluster's multithreaded parallel environment. To view a list of the cluster's parallel environments, use the `qconf -spl` command.

The most common modifications to the job submission template include adding additional lines to specify:

1. The research group's queue. For example, `#$ -q smith.q`
2. The account to which jobs will charge. For example, `#$ -A smith_lab`

### L﻿SF

The most common modifications to the job submission template include adding additional lines to specify:

1. Your research group's queue. For example, `#BSUB -q smith_queue`
2. The account to which your jobs will charge. For example, `#BSUB -P smith_lab`

Additional template considerations

To run a Cell Ranger pipeline in cluster mode, add the `--jobmode=sge` or `--jobmode=lsf` command-line option when using the `cellranger` commands. It is also possible to use `--jobmode=<PATH>`, where `<PATH>` is the full path to the cluster template file.

To validate that cluster mode is properly configured, follow the same validation instructions given for `cellranger` in the [Installation](/support/software/cell-ranger/downloads) page, but add `--jobmode=sge` or `--jobmode=lsf`.

```
cellranger mkfastq --run=./tiny-bcl --samplesheet=./tiny-sheet.csv --jobmode=sge
 
Martian Runtime - 7.1.0
 
Running preflight checks (please wait)...
2016-09-13 12:00:00 [runtime] (ready) ID.HAWT7ADXX.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET
2016-09-13 12:00:00 [runtime] (split_complete) ID.HAWT7ADXX.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET
...
```

Once the preflight checks are finished, check the job queue to see stages queuing up:

```
qstat
job-ID prior name user state submit/start at queue slots ja-task-ID
-----------------------------------------------------------------------------------------------------------------
8675309 0.56000 ID.HAWT7AD jdoe qw 09/13/2016 12:00:00 all.q@cluster.university.edu 1
8675310 0.55500 ID.HAWT7AD jdoe qw 09/13/2016 12:00:00 all.q@cluster.university.edu 
```

In the event of a pipeline failure, an error message is displayed.

```
[error] Pipestance failed. Please see the log at:
HAWT7ADXX/MAKE_FASTQS_CS/MAKE_FASTQS/MAKE_FASTQS_PREFLIGHT/fork0/chnk0/_errors
 
Saving diagnostics to HAWT7ADXX/HAWT7ADXX.debug.tgz
For assistance, upload this file to 10x by running:
 
uploadto10x <your_email> HAWT7ADXX/HAWT7ADXX.debug.tgz
```

The `_errors` file contains a `jobcmd error`:

```
cat HAWT7ADXX/MAKE_FASTQS_CS/MAKE_FASTQS/MAKE_FASTQS_PREFLIGHT/fork0/chnk0/_errors
 
jobcmd error:
exit status 1
```

The most likely reason for this failure is an invalid job submission template. This occurs when the job submission via `qsub` or `bsub` commands failed.

The "tiny" dataset doesn't stress the cluster, so it is worthwhile to follow up with a more realistic test using one of our [sample datasets](/resources/datasets?menu%5Bproducts.name%5D=Single+Cell+Gene+Expression).

Validating template configuration

There are two subtle variants of running `cellranger` pipelines in cluster mode, each with its pitfalls. Check with your cluster administrator to see which approach is compatible with your institution's setup.

1. **Run `cellranger` with `--jobmode=sge` on the head node**. Cluster mode was originally designed for this use case. However, this approach leaves `mrp` and `mrjob` running on the head node for the duration of the pipeline, and some clusters impose time limits to prevent long-running processes.
2. **Use a job script to submit a `cellranger` command with `--jobmode=sge`**: With this approach, `mrp` and `mrjob` run on a cluster mode. However, the cluster must allow jobs to be submitted from a compute node to make this viable.

When `cellranger` is run in cluster mode, a single library analysis is partitioned into *hundreds* and potentially *thousands* of smaller jobs. The underlying Martian pipeline framework launches each stage job using the `qsub` or `bsub` commands when running on SGE or LSF cluster, respectively. As stage jobs are queued, launched, and completed, the pipeline framework tracks their status using the metadata files that each stage maintains in the pipeline output directory.

Like *single server* pipelines, cluster-mode pipelines can be restarted after a failure. They maintain the same order of execution for dependent stages of the pipeline. All executed stage code is identical to *single server* mode, and the quantitative results are identical to the limit of each stage's reproducibility.

<SupportCallout level={"warning"}>
 <Text as={"span"}>
 {"Cluster-mode pipelines that are stopped (either by you or due to a stage failure) do *not* delete pending stages that have already been submitted to the cluster queue. As a result, some pipeline stages may continue to execute after the `cellranger` commands have exited."}
 </Text>
</SupportCallout>

In addition, the [Cell Ranger UI](/support/software/cell-ranger/advanced/cr-monitoring-ui) can still be used with cluster mode. Because the Martian pipeline framework runs on the node from which the command was issued, the UI will also run from that node.

Cluster Mode mechanics

Stages in the Cell Ranger pipelines each request a specific number of cores and memory to aid with resource management. These values are used to prevent oversubscription of the computing system when running pipelines in single server mode. The way CPU and memory requests are handled in cluster mode is defined by the following:

* How the `__MRO_THREADS__` and `__MRO_MEM_GB__` variables are used within the job template.
* How your specific cluster's job manager schedules resources.

Depending on which job scheduler you have, select an option below.

Memory requests and consumption

SGE supports requesting memory via the `mem_free` resource natively, although your cluster may have another mechanism for requesting memory. To pass each stage's memory request through to SGE, add line to your `sge.template` that requests `mem_free`, `h_vmem`, `h_rss`, or the custom memory resource defined by your cluster:

```
cat sge.template
#$ -N __MRO_JOB_NAME__
#$ -V
#$ -pe threads __MRO_THREADS__
#$ -l mem_free=__MRO_MEM_GB__G
#$ -cwd
#$ -o __MRO_STDOUT__
#$ -e __MRO_STDERR__
 
__MRO_CMD__
```

<SupportCallout level={"info"}>
 <Text as={"span"}>
 {"In the above example, the trailing G in the highlighted __MRO_MEM_GB__G is required by SGE to denote that mem_free is being expressed in GB units."}
 </Text>
</SupportCallout>

The `h_vmem` (virtual memory) and `mem_free`/`h_rss` (physical memory) represent two different quantities and that Cell Ranger stages' `__MRO_MEM_GB__` requests are expressed as physical memory. Using `h_vmem` in your job template may cause certain stages to be unduly killed if their virtual memory consumption is substantially larger than their physical memory consumption. It follows that we do not recommend using `h_vmem`.

<SupportCallout level={"info"}>
 <Text as={"span"}>
 {"If you do use h_vmem in a template, it is recommended that you use the __MRO_MEM_GB_PER_THREAD__ or __MRO_MEM_MB_PER_THREAD__ variables instead of __MRO_MEM_GB__ and __MRO_MEM_MB__. To determine memory limits for a multicore job, SGE will multiply the number of threads by the value in h_vmem. The __MRO_MEM_GB__ and __MRO_MEM_MB__ variables already reflect the sum amount of memory across all threads needed to run the job. Using those variables as h_vmem will inflate the memory required for multithreaded jobs."}
 </Text>
</SupportCallout>

For clusters whose job managers do not support memory requests, it is possible to request memory in the form of cores via the `--mempercore` command-line option. This option scales up the number of threads requested via the `__MRO_THREADS__` variable according to how much memory a stage requires.

For example, given a cluster with nodes that have 16 cores and 128 GB of memory (8 GB per core), the following pipeline invocation command

cellranger mkfastq --run=./tiny-bcl --samplesheet=./tiny-sheet.csv --jobmode=sge --mempercore=8

will issue the following resource requests:

* A stage that requires 1 thread and less than 8 GB of memory will pass `__MRO_THREADS__` of `1` to the job template.
* A stage that requires 1 thread and 12 GB of memory will pass `__MRO_THREADS__` of `2` to the job template because (12 GB) / (8 GB/core) = 2 cores.
* A stage that requires 2 threads and less than 16 GB of memory will pass `__MRO_THREADS__` of `2` to the job template.
* A stage that requires 2 threads and 40 GB of memory will pass `__MRO_THREADS__` of `5` to the job template because (40 GB) / (8 GB/core) = 5 cores.

As the final bullet point illustrates, this mode can result in wasted CPU cycles and is only provided for clusters that cannot allocate memory as an independent resource.

Every cluster configuration is different. If you are unsure of how your cluster resource management is configured, contact your cluster administrator or help desk.

LSF supports job memory requests through the `-M` and `-R [mem=...]` options, but these requests generally must be expressed in MB, not GB. As such, your LSF job template should use the `__MRO_MEM_MB__` variable rather than `__MRO_MEM_GB__`. For example,

```
cat bsub.template
#BSUB -J __MRO_JOB_NAME__
#BSUB -n __MRO_THREADS__
#BSUB -o __MRO_STDOUT__
#BSUB -e __MRO_STDERR__
#BSUB -R "rusage[mem=__MRO_MEM_MB__]"
#BSUB -R span[hosts=1]
 
__MRO_CMD__
```

For clusters whose job managers do not support memory requests, it is possible to request memory in the form of cores via the `--mempercore` command-line option. This option scales up the number of threads requested via the `__MRO_THREADS__` variable according to how much memory a stage requires.

For example, given a cluster with nodes that have 16 cores and 128 GB of memory (8 GB per core), the following pipeline invocation command

cellranger mkfastq --run=./tiny-bcl --samplesheet=./tiny-sheet.csv --jobmode=sge --mempercore=8

will issue the following resource requests:

* A stage that requires 1 thread and less than 8 GB of memory will pass `__MRO_THREADS__` of `1` to the job template.
* A stage that requires 1 thread and 12 GB of memory will pass `__MRO_THREADS__` of `2` to the job template because (12 GB) / (8 GB/core) = 2 cores.
* A stage that requires 2 threads and less than 16 GB of memory will pass `__MRO_THREADS__` of `2` to the job template.
* A stage that requires 2 threads and 40 GB of memory will pass `__MRO_THREADS__` of `5` to the job template because (40 GB) / (8 GB/core) = 5 cores.

As the final bullet point illustrates, this mode can result in wasted CPU cycles and is only provided for clusters that cannot allocate memory as an independent resource.

Every cluster configuration is different. If you are unsure of how your cluster resource management is configured, contact your cluster administrator or help desk.

Each stage requests several threads and maximum free memory. These values are hardcoded into each stage and determined empirically by looking at in-house data runs, as well as reports from our customers. You may find that on your data, certain stages do not require as much memory as requested, or may require *more* memory than our defaults. The latter is more serious, as clusters may impose strict memory limits, and kill a job if those limits are exceeded.

You can override the defaults of a stage by supplying an `override.json` file, and specifying this file as the `--override` argument to your pipeline. Here is an example of an override JSON file to Cell Ranger, which overrides the memory requests of the `count` pipelines:

```
{
 "SC_RNA_COUNTER_CS.SC_MULTI_CORE.MULTI_GEM_WELL_PROCESSOR.COUNT_GEM_WELL_PROCESSOR._BASIC_SC_RNA_COUNTER._MATRIX_COMPUTER.MAKE_SHARD": {
    "chunk.mem_gb": 16,
    "chunk.threads": 2
  }
}
```

This configuration will increase the memory and threads requested (originally 6GB and 1 thread).

To run a pipeline with the above configuration, supply the JSON file as the `--override` parameter:

```
cellranger count --id=sample ... --override=./override.json
```

Overrides apply to pipelines executed both on the cluster and in local mode, but are likely most applicable to cluster mode users.

Overriding default sage memory and thread requests

Some Cell Ranger pipeline stages are divided into hundreds of jobs. By default, the rate at which these jobs are submitted to the cluster is throttled to at most 64 at a time and at least 100 ms between each submission to avoid running into limits on clusters that impose quotas on the total number of pending jobs a user can submit.

If your cluster does not have these limits or is not shared with other users, you can control how the Martian pipeline runner sends job submissions to the cluster by using the `--maxjobs` and `--jobinterval` parameters.

To increase the cap on the number of concurrent jobs to 200, use the `--maxjobs` parameter:

```
cellranger count --id=sample ... --jobmode=sge --maxjobs=200
```

You can also change the rate limit on how often the Martian pipeline runner sends submissions to the cluster. To add a five-second pause between job submissions, use the `--jobinterval` parameter:

```
cellranger count --id=sample ... --jobmode=sge --jobinterval=5000
```

The job interval parameter is in milliseconds. The minimum allowable value is 1.

Controlling rate of job submissions

Cluster Mode

Usage:
```
cellranger count --help
cellranger count [OPTIONS] --id <ID> --transcriptome <PATH>
```
| Argument | Description |
| --- | --- |
| `--id` | *Required*. A unique run ID string (e.g., sample345). The name is arbitrary and will be used to name the directory containing all pipeline-generated files and outputs. Only letters, numbers, underscores, and hyphens are allowed (maximum of 64 characters). |
| `--output-dir` | *Optional*. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: `/path/to/<custom name>/outs/`. If excluded, the outputs are directed to the default path: `/path/to/ID/outs/`.|
| `--description` | *Optional*. Sample description to embed in output files. |
| `--transcriptome` | *Required*. Path of folder containing 10x-compatible transcriptome reference. |
| `--fastqs` | *Required*. Either: Path of the `fastq_path` folder generated by `cellranger mkfastq` e.g. `/home/jdoe/runs/HAWT7ADXX/outs/fastq_path`. This contains a directory hierarchy that cellranger count will automatically traverse. - OR - Any folder containing fastq files, for example if the fastq files were generated by a service provider and delivered outside the context of the `mkfastq` output directory structure. See input FASTQ page for help. Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flow cells. Doing this will treat all reads from the library, across flow cells, as one sample. If you have multiple libraries for the sample, you will need to run cellranger count on them individually, and then combine them with `cellranger aggr`. This argument cannot be used when performing Feature Barcode analysis; use `--libraries` instead. |
| `--project` | *Optional*. Name of the project folder within a `mkfastq` or `bcl2fastq`-generated folder from which to pick FASTQs. |
| `--sample` | *Required*. Sample name as specified in the sample sheet supplied to cellranger `mkfastq`. Can take multiple comma-separated values, which is helpful if the same library was sequenced on multiple flow cells with different sample names, which therefore have different FASTQ file prefixes. Doing this will treat all reads from the library, across flow cells, as one sample. If you have multiple libraries for the sample, you will need to run `cellranger count` on them individually, and then combine them with `cellranger aggr`. Allowable characters in sample names are letters, numbers, hyphens, and underscores. |
| `--lanes` | *Optional*. Only use FASTQs from selected lanes. | 
| `--libraries` | *Optional*. Path to a `libraries.csv` file declaring FASTQ paths and library types of input libraries. Required for gene expression + Feature Barcode analysis. When using this argument, `--fastqs` and `--sample` must not be used. This argument should not be used when performing gene expression-only analysis; use `--fastqs` instead. | 
| `--feature-ref` | *Required for Feature Barcode analysis*. Path to a [Feature Reference CSV](/support/software/cell-ranger/analysis/running-pipelines/cr-feature-bc-analysis#feature-ref) file declaring the Feature Barcode reagents used in the experiment. |
| `--expect-cells` | *Optional*. Override the pipeline’s auto-estimate. See [cell calling algorithm](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm) for details on how this parameter is used. If used, enter the expected number of recovered cells. |
| `--force-cells` | *Optional*. Force pipeline to use this number of cells, bypassing the cell detection algorithm. Use this if the number of cells estimated by Cell Ranger is not consistent with the barcode rank plot. |
| `--r1-length` | *Optional*. Limit the length of the input Read 1 sequence of Gene Expression (and any Feature Barcode) library to the first N bases, where N is a user-supplied value. Note that the length includes the 10x Barcode and UMI sequences so do not set this below 26 for Single Cell 3′ v2 or Single Cell 5′. This and `--r2-length` are useful options for determining the optimal read length for sequencing. |
| `--r2-length` | *Optional*. Hard trim the input Read 2 to this length before analysis. | 
| `--include-introns` | *Optional*. Limit the length of the input R2 sequence to the first N bases, where N is a user-supplied value. Trimming occurs before sequencing metrics are computed and therefore, limiting R2 read length may affect Q30 scores (true, false). | 
| `--chemistry` | *Optional*. Assay configuration. NOTE: by default the assay configuration is detected automatically, which is the recommended mode. You should only specify chemistry if there is an error in automatic detection. Select one of: auto for auto-detection (default), threeprime for Single Cell 3′, `fiveprime` for Single Cell 5′, `SC3Pv2` for Single Cell 3′ v2, `SC3Pv3` for Single Cell 3′ v3, `SC3Pv3LT` for Single Cell 3′ v3 LT, `SC3Pv3HT` for Single Cell 3′ v3 HT, `SC5P-PE` for Single Cell 5′ paired-end (both R1 and R2 are used for alignment), `SC5P-R2` for Single Cell 5′ R2-only (where only R2 is used for alignment). `SC3Pv1` for Single Cell 3′ v1. NOTE: this mode cannot be auto-detected. It must be set explicitly with this option. ARC-v1 for analyzing the Gene Expression portion of Multiome data. NOTE: this mode cannot be auto-detected. |
| `--check-library-compatibility` | *Optional*. This option allows users to disable the check that evaluates 10x Barcode overlap between libraries when multiple libraries are specified (e.g., Gene Expression + Antibody Capture). Setting this option to `false` will disable the check across all library combinations. We recommend running this check (default), however if the pipeline errors out, users can bypass the check to generate outputs for troubleshooting (true, false; default: true). |
| `--no-bam` | *Optional*. Add this option to skip BAM file generation. This will reduce the total computation time for the pipestance and the size of the output directory. If unsure, we recommend not using this option, as BAM files can be useful for troubleshooting and downstream analysis. (true, false; default: false). |
| `--nosecondary` | *Optional*. Disable secondary analysis, e.g. clustering (true, false). |
| `-h`, `--help` | Print help information. |



| Flag | Description |
| --- | --- |
| `--no-libraries` | *Optional*. Add this flag to proceed with processing data using a `--feature-ref` but no Feature Barcode data specified with the `--libraries` flag. |

count

Usage: 
```
cellranger multi --help
cellranger multi [OPTIONS] --id <ID> --csv <CSV>
```

| Argument | Description |
| --- | --- |
| `--id` | *Required*. A unique run id and output folder name [a-zA-Z0-9_-]+ | 
| `--csv` | *Required*. Path of CSV file enumerating input libraries and analysis parameters. [See sections below](#multi-config-csv-options). | 
| `--output-dir` | *Optional*. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: `/path/to/<custom name>/outs/`. If excluded, the outputs are directed to the default path: `/path/to/ID/outs/`.|
| `--description` | *Optional*. Sample description to embed in output files. |
| `-h`, `--help` | Print help information. |

multi

Go to [this page](/support/software/cell-ranger/advanced/cr-multi-config-csv-opts) to view all config CSV options for supported library types.

multi config CSV options

Usage: 

Cell Ranger v7.1 and later enable users to download a multi config CSV template by running:

```
cellranger multi-template --output=/path/to/FILE.csv
```

Customize the path to the directory in which you wish to output the template. Omitting the file path downloads the file into your working directory. After downloading, please remember to customize the template based on your assay and experimental design.

To print a list and description of all configurable parameters available in `cellranger multi`, run

```
cellranger multi-template --parameters
```
Run `cellranger multi-template --help` or `cellranger multi-template -h` for more information about available options.

```
cellranger multi-template --help
cellranger multi-template [OPTIONS]
```
| Field	| Description | 
| --- | --- |
| `-o`, `--output` | *Optional*. Output file path. | 
| `-p`, `--parameters` | Print multi config parameter options and descriptions. |
| `-h`, `--help` | Print help information. | 

multi-template

Usage:
```
cellranger vdj --help
cellranger vdj [OPTIONS] --id <ID> --fastqs <PATH>
```
| Argument | Description | 
| --- | --- |
| `--id` | *Required*. A unique run ID string: e.g. sample345. |
| `--output-dir` | *Optional*. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: `/path/to/<custom name>/outs/`. If excluded, the outputs are directed to the default path: `/path/to/ID/outs/`.|
| `--description` | *Optional*. Sample description to embed in output files. |
| `--fastqs` | *Required*. Path of the FASTQ folder generated by `cellranger mkfastq` e.g. `/home/jdoe/runs/HAWT7ADXX/outs/fastq_path`. Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flowcells. Doing this will treat all reads from the library, across flowcells, as one sample. |
| `--reference`	| *Required*. Path to the Cell Ranger V(D)J compatible reference e.g. `/opt/refdata-cellranger-vdj-GRCh38-alts-ensembl-7.1.0`. If `--denovo` is specified, this parameter is optional.`--sample`	Required. Sample name as specified in the sample sheet supplied to `mkfastq`. Can take multiple comma-separated values, which is helpful if the sample was sequenced on multiple flowcells and the sample name used (and therefore fastq file prefix) is not identical between them. Doing this will treat all reads from the library, across flowcells, as one sample. |
| `--project` | *Optional*. Name of the project folder within a `mkfastq` or `bcl2fastq`-generated folder to pick FASTQs from. |
| `--inner-enrichment-primers` | 	*Optional*. This argument takes a `.txt` file containing primer sequences that were used to enrich cDNA for V(D)J sequences. The primers must be listed one per line. If two sets of primers were used for amplification, the `.txt` file must contain only the innermost reverse PCR primers that are complementary to the constant region. An example `.txt` file for human TCR dataset would have these lines: AGTCTCTCAGCTGGTACACG TCTGATGGCTCAAACACAGC The `--inner-enrichment-primers` option is typically used for species other than human or mouse for which primers are not provided by 10x Genomics, Inc. All the provided primers may be found in the appendix section of [this document](/support/single-cell-immune-profiling/documentation/steps/library-prep/chromium-single-cell-5-reagent-kits-user-guide-v-2-chemistry-dual-index-with-feature-barcoding-technology-for-cell-surface-protein-and-immune-receptor-mapping).|
| `--localcores` | *Optional*. Restricts `cellranger` to use the specified number of cores to execute pipeline stages. By default, cellranger will use all of the cores available on your system. |
| `--localmem`	| *Optional*. Restricts `cellranger` to use the specified amount of memory (in GB) to execute pipeline stages. By default, `cellranger` will use 90% of the memory available on your system. |
| `--lanes`	| *Optional*. Lanes associated with this sample. | 
| `--chain`	| *Optional*. Force the analysis to be carried out for a particular chain type. The accepted values are: `auto` for autodetection based on TR vs IG representation (default), `TR` for T cell receptors, `IG` for B cell receptors, Use this in rare cases when automatic chain detection fails.|
| `--sample` | *Optional*. Prefix of the filenames of FASTQs to select. |
| `-h`, `--help` | Print help information. |


| Flag | Description |
| --- | --- |
| `--denovo`	| *Optional*. If specified, this flag prevents the use of V(D)J reference during the assembly process. `--reference` is optional. If `--denovo` is specified and `--reference` is not, the `--inner_enrichment_primers` argument is required. The `--denovo` option is most useful for full de novo assembly without a V(D)J reference. If you have a V(D)J reference, using `--denovo` will yield similar but slightly degraded results. |

Usage: 
```
cellranger aggr --help
cellranger aggr [OPTIONS] --id <ID> --csv <CSV>
```

| Argument | Description |
| --- | --- |
| `--id` | *Required*. A unique run ID string: e.g. `AGG123` |
| `--output-dir` | *Optional*. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: `/path/to/<custom name>/outs/`. If excluded, the outputs are directed to the default path: `/path/to/ID/outs/`.|
| `--description` | *Optional*. Sample description to embed in output files. |
| `--csv` | *Required*. Path of CSV file enumerating 'cellranger count/vdj/multi' outputs. |
| `--normalize` | *Optional*. String specifying how to normalize depth across the input libraries. Valid values: `mapped` (default) or `none` (see [Depth Normalization](/support/software/cell-ranger/analysis/running-pipelines/cr-3p-aggr#depth_normalization)).|
| `--nosecondary` | *Optional*. Add this argument to skip secondary analysis which includes dimensionality reduction, clustering, and visualization. This is applicable if you plan to use `cellranger reanalyze` or your own custom analysis (true, false). |
| `-h`, `--help` | Print help information. |

aggr

Usage: 
```
cellranger reanalyze --help
cellranger reanalyze [OPTIONS] --id <ID> --matrix <MATRIX_H5>
```
| Argument | Description |
| --- | --- | 
| `--id` | *Required*. A unique run ID string: e.g. `AGG123_reanalysis` | 
| `--description` | *Optional*. Sample description to embed in output files. |
| `--matrix=H5` | *Required*. Path to a `filtered_feature_bc_matrix.h5` or `raw_feature_bc_matrix.h5`, or `sample_filtered_feature_bc_matrix.h5` from a completed pipestance (from either `cellranger count`, `cellranger multi`, or `cellranger aggr`). Use the `raw_feature_bc_matrix.h5` when specifying a value for `--force-cells` that exceeds the original cell count. |
| `--params` | *Optional*. Path to a CSV file containing a list of valid parameters and the values to use for them (see Parameters). |
| `--barcodes` | *Optional*. Path to a file containing a list of barcodes (one barcode per line) to use for reanalysis. The first line of file must be a header called Barcode. Header is case sensitive. All barcodes must be present in the matrix. | 
| `--genes` | *Optional*. Path to a file containing a list of gene IDs (one gene ID per line) to use for reanalysis (corresponding to the gene_id field of the reference GTF). The first line of the genes file must be a header called Gene. Header is case sensitive. All gene IDs included in the list must be present in the matrix. Only gene features are used in the secondary analysis. Feature Barcode features are ignored. An example gene.txt supplied to this argument: Gene ENSG00000243485 ENSG00000237613 ENSG00000186092 ENSG00000238009 ENSG00000239945 ENSG00000239906 ENSG00000241599 ENSG00000236601 ENSG00000284733 ENSG00000235146 ENSG00000284662 | 
| `--exclude-genes` | *Optional*. Path to a file containing a list of gene IDs (one gene ID per line) to exclude for reanalysis (corresponding to the gene_id field of the reference GTF). All gene IDs must be present in the matrix. The first line of the genes file must be a header called Gene. The exclusion can be applied with or without the `--genes` list. When a `--genes` list is supplied, `--exclude-genes` searches within the supplied list for exclusion. Note that only gene features are used in secondary analysis. Feature Barcode features are ignored. |
| `--agg` | *Optional*. Path to a CSV file that was used for `cellranger aggr`. This allows you to retain any metadata associated with the samples for display in Loupe Browser. This argument is required if you want to enable Chemistry Batch Correction in your reanalysis. | 
| `--force-cells` | *Optional*. Force pipeline to use this number of cells, bypassing the cell detection algorithm. Use this if the number of cells estimated by Cell Ranger is not consistent with the barcode rank plot. If specifying a value that exceeds the original cell count, you must use the `raw_feature_bc_matrices_h5.h5`. Starting with Cell Ranger 6.1, it is no longer possible to run `--force-cells` of an `aggr` output in reanalyze with more cells than were originally called. |
| `-h`, `--help` | Print help information. |

reanalyze

Usage: 
```
cellranger mkfastq --help
cellranger mkfastq --run=PATH [options]
```
| Argument | Description |
| --- | --- | 
|`--run` | *Required*. The path of Illumina BCL run folder. |
| `--id` | *Optional*. Defaults to the name of the flow cell referred to by `--run`. Name of the folder created by `mkfastq`. This option does not accept a full directory path. If used, navigate to the specified directory first and then run `mkfastq`. |
| `--samplesheet` | *Optional*. Path to an Illumina Experiment Manager-compatible sample sheet which contains 10x Genomics sample index names (e.g., `SI-GA-A1` or `SI-TT-A12`) in the sample index column. All other information, such as sample names and lanes, should be in the sample sheet. | 
| `--sample-sheet` | *Optional*. Equivalent to `--samplesheet` above. |
| `--simple-csv` | Deprecated. Equivalent to `--csv`. | 
| `--force-single-index` | *Optional*. If 10x-supplied i7/i5 paired indices are specified, but the flowcell was run with only one sample index, allow the demultiplex to proceed using  the i7 half of the sample index pair. |
| `--filter-single-index` | *Optional*. Only demultiplex samples identified  by an i7-only sample index, ignoring dual-indexed samples. Dual-indexed samples will not be demultiplexed. | 
| `--filter-dual-index` | *Optional*. Only demultiplex samples identified by i7/i5 dual-indices (e.g., SI-TT-A6), ignoring single-index samples. Single-index samples will not be demultiplexed. |
| `--rc-i2-override` | *Optional*. Indicates if the bases in the I2 read are emitted as reverse complement by the sequencing workflow. Set to 'true' for the Reverse Complement Workflow (Workflow B)/ NovaSeq Reagent Kit v1.5 or greater. Set to 'false' for the Forward Strand Workflow (Workflow A) / older NovaSeq Reagent Kits.NOTE: this parameter is autodetected and should only be passed in special circumstances. |
| --lanes | *bcl2fastq option*. Comma-delimited series of lanes to demultiplex. Shortcut for the `--tiles` argument. | 
| `--use-bases-mask` | *bcl2fastq* option. Same as `bcl2fastq`; override the read lengths as specified in RunInfo.xml. See Illumina *bcl2fastq*  documentation for more information. |
| `--delete-undetermined` | *bcl2fastq* option. Delete the Undetermined FASTQs generated by `bcl2fastq`. Useful if you are demultiplexing a small number of samples from a large flow cell. | 
| `--output-dir`   | *bcl2fastq* option. Same as in `bcl2fastq`. Generate FASTQ output in a path of your own choosing, instead of `flowcell_id/outs/fastq_path`. | 
| `--project` | *bcl2fastq* option. Custom project name, to override the samplesheet or to use in conjunction with the `--csv` argument. |
| `-h`, `--help` | Show this message. |
|  `--version` | Show version. | 

mkfastq

Usage: 
```
cellranger mkref --help
mkref --genome=NAME --fasta=PATH --genes=PATH [options]
```

| Argument | Description |
| --- | --- | 
| `--genome` | *Required*. Unique genome name(s), used to name output folder [a-zA-Z0-9_-]+. Specify multiple genomes by specifying the `--genome` argument multiple times; the output folder will be `<name1>_and_<name2>`. |
| `--fasta` | *Required*. Path(s) to FASTA file containing your genome reference. Specify multiple genomes by specifying the `--fasta` argument multiple times. |
| `--genes` | *Required*. Path(s) to genes GTF file(S) containing annotated genes for your genome reference. Specify multiple genomes by specifying the `--genes` argument multiple times. |
| `--output-dir` | *Optional*. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: `/path/to/<custom name>/outs/`. If excluded, the outputs are directed to the default path: `/path/to/ID/outs/`.|
| `--memgb` |*Required*. Maximum memory (GB) used during STAR genome index generation. Defaults to 16. Please note, the amount of memory specified must be greater than the number of gigabases in the input reference FASTA file. |
| `--nthreads` | *Optional*. Number of threads used during STAR genome index generation. Defaults to 1. |
| `--ref-version` | *Optional*. Reference version string to include with reference. |
| `-h`, `--help`| Show this message. |

mkref

Usage: 
```
cellranger mkgtf --help
mkgtf <input_gtf> <output_gtf> [--attribute=KEY:VALUE...]
```
| Argument | Description |
| --- | --- | 
| `--input_gtf` | *Required*. Path to input genes GTF file. | 
| `--output_gtf` | *Required*. Path to filtered output genes GTF file. |
| `--attribute=<key:value>` | Key-value pair in attributes field to be kept in the GTF file.
| `-h`, `--help` | Show this message. |
| `--version` | Show version. |

mkgtf

Usage: 
```
cellranger mkvdjref --help
mkvdjref --genome=NAME --fasta=PATH --genes=PATH ...[options] mkvdjref --genome=NAME --seqs=PATH [options] mkvdjref -h | --help 
```
| Argument | Description |
| --- | --- | 
| `--genome` | *Required*. A unique genome name, used to name output folder [a-zA-Z0-9_-]+.|
| `--fasta` | *Required*. Path to FASTA file containing your genome reference.|
| `--genes` | *Required*. One or more GTF files containing annotated genes for your genome reference. Specify multiple files by specifying the `--genes` argument multiple times. The files will be concatenated. |
| `--seqs` | *Optional*. A FASTA file that directly specifies V(D)J sequences. This is mutually exclusive with the the "fasta" and "genes" args above. |
| `--output-dir` | *Optional*. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: `/path/to/<custom name>/outs/`. If excluded, the outputs are directed to the default path: `/path/to/ID/outs/`.|
| `--ref-version` | *Optional*. Reference version string to include.|
| `--rm-transcripts` | *Optional*. Path to text file with transcript IDs to ignore. This file should have one transcript ID per line where the IDs correspond to the "transcript_id" key in the GTF info column.|
| `-h`, `--help` | Show this message. |

mkvdjref

Usage:
```
cellranger testrun --help
cellranger testrun [OPTIONS] --id <ID>
```
| Argument | Description |
| --- | --- | 
| `--id` | *Required*. A unique run id and output folder name [a-zA-Z0-9_-]+. |
| `--description` | *Optional*. Sample description to embed in output files. |
| `-h`, `--help` | Print help information. |

testrun

Usage: 
```
cellranger upload --help
cellranger upload <your_email> <file>
```

upload

Usage: 
```
cellranger sitecheck --help 
sitecheck
```
| Argument | Description |
| --- | --- | 
| `-h`, `--help` | Show this message. |
| `--version` |  Show version. | 

sitecheck

To use `tarmri` to generate a `.mri.tgz` file for a failed run, call `tarmri` and give it the path to the failed pipestance (run name specified by `--id`).

The `.mri.tgz` file contains a number of logs (including error messages, status reports, and information about the system) that are useful for troubleshooting failures. The `.mri.tgz` file does not contain sample data or analysis outputs. 

Usage:
```
# Generate mri.tgz file for example analysis --id run1
cellranger-x.y.z/cellranger-cs/x.y.z/tenkit/bin/tarmri path/to/run1

# Share mri.tgz file with 10x Support
cellranger upload <your email> <path to log.mri.tgz>
```

For Cell Ranger v3.1 and earlier, the script is located here:
`cellranger-x.y.z/cellranger-cs/x.y.z/tenkit/bin/tarmri`

For Cell Ranger v4.0 and later, the script is located here:
`cellranger-x.y.z/bin/tenkit/tarmri`

tarmri

Usage: 
```
cellranger mat2csv --help
mat2csv <input_path> <output_csv> [--genome=GENOME]
```

| Argument | Description |
| --- | --- | 
| `input_path` | *Required*. Path to a Cell Ranger feature-barcode matrix. Can be either a feature-barcode h5 file (recommended) or a path to a MEX Cell Ranger output folder. |
| `output_csv` | *Required*. Output CSV file. |
| `--genome=GENOME` | *Required*. Specify which genome to extract. This only applies to multi-genome h5 input files. |
| `-h`, `--help` | Show this message. |
| `--version` | Show version. |

mat2csv

The Martian commands work the same as for other 10x Genomics pipelines (i.e., Xenium Ranger, Space Ranger). 
| Argument | Description |
| --- | --- |
|`--jobmode` | Job manager to use. Valid options: local (default), a cluster job mode (i.e., sge, lsf, slurm), or the path to a `<jobmode>.template` file. |
| `--localcores` | Set max cores the pipeline may request at one time. Only applies to local jobs.| 
| `--localmem` | Set max GB the pipeline may request at one time. Only applies to local jobs. | 
| `--localvmem` | Set max virtual address space in GB for the pipeline. Only applies to local jobs.| 
| `--mempercore` | Reserve enough threads for each job to ensure enough memory will be available, assuming each core on your cluster has at least this much memory available. Only applies to cluster jobmodes. |
| `--maxjobs` | Set max jobs submitted to the cluster at one time. Only applies in cluster jobmodes.| 
| `--jobinterval` | Set delay between submitting jobs to cluster, in ms. Only applies in cluster jobmodes.| 
| `--overrides` | The path to a JSON file that specifies stage-level overrides for cores and memory. Finer-grained than `--localcores`, `--mempercore` and `--localmem`. Contact support for an example override file.| 
| `--uiport` | The port to serve web UI at: http://localhost:PORT |
| `--disable-ui` | Boolean to determine whether to serve the web UI (true, false). | 
| `--noexit` | Boolean to keep web UI running after pipestance completes or fails (true, false).|
| `--nopreflight` | Specify the preflight check(s) to skip.|

| Flag | Description |
| --- | --- |
| `--dry` | Do not execute the pipeline. Generate a pipeline invocation (`.mro`) file and stop. |

Runtime options

Cell Ranger Commands

Cell Ranger Command Line Arguments (Manual Page)

Select a job scheduler tab below to see a sample job script.

<SupportCallout level={"info"}>
 <Text as={"span"}>
 {"10x does not officially support Slurm or Torque/PBS. However, many customers have successfully used Cell Ranger with those job schedulers in job submission mode. Sample job scripts are shown below."}
 </Text>
</SupportCallout>

Step 1

Copy the sample job script to a text editor, and replace all the variables enclosed within braces (e.g. *`{JOB_NAME}`* or *`{STDOUT_LOG}`*) with literal names, paths, and values. The last line, *`{PIPELINE_CMD}`* , is replaced by a Cell Ranger command, specifying `--jobmode=local`, `--localcores={NUM_THREADS}` and `--localmem=0.9*{MEM_GB}` to restrict CPU and memory use that's consistent with the directives in the job script. For example, if the job script requests 8 cores and 64GB of memory from the cluster, then the Cell Ranger command should include `--jobmode=local --localcores=8 --localmem=57`.

<SupportCallout level={"info"}>
 <Text as={"span"}>
 {"Since cluster setup and policy vary greatly from one institution to another, the sample job scripts provided below should be treated as a starting point. Consult with your local cluster administrator to see if additional directives are required."}
 </Text>
</SupportCallout>

Step 2



```
  #!/usr/bin/env bash

  #

  # =============================================================================

  # Setup Instructions

  # =============================================================================

  #

  # 1. Substitute {PE_NAME} below with name of your cluster's shared-memory

  #    parallel environment. If your cluster does not have a parallel environment,

  #    delete this line. However, the job will run with only 1 thread.

  #

  # =============================================================================

  # Job Script

  # =============================================================================

  #

  #$ -N {JOB_NAME}

  #$ -V

  #$ -pe {PE_NAME} {NUM_THREADS}

  #$ -cwd

  #$ -l mem_free={MEM_GB}G

  #$ -o {STDOUT_LOG}

  #$ -e {STDERR_LOG}

  #$ -S "/usr/bin/env bash"


  {PIPELINE_CMD} 
```

If this job script is saved as **runJob.bash**, then the following command submits the job to the cluster:

```
  $ qsub runJob.bash
```

```

  #!/usr/bin/env bash

  #

  # =============================================================================

  # Job Script

  # =============================================================================

  #

  #BSUB -J {JOB_NAME}

  #BSUB -n {NUM_THREADS}

  #BSUB -o {STDOUT_LOG}

  #BSUB -e {STDERR_LOG}

  #BSUB -R "rusage[mem={MEM_MB}]"

  #BSUB -R span[hosts=1]


  {PIPELINE_CMD} 

```

**Step 3.** If this job script is saved as **runJob.bash**, then the following command submits the job to the cluster:

```

  $ bsub runJob.bash

```

```
#!/usr/bin/env bash
#
#!!! This is not officially supported by 10x
#
# =============================================================================
# Job Script
# =============================================================================
#
#SBATCH -J {JOB_NAME}
#SBATCH --export=ALL
#SBATCH --nodes=1 --ntasks-per-node={NUM_THREADS}
#SBATCH --signal=2
#SBATCH --no-requeue
### Alternatively: --ntasks=1 --cpus-per-task={NUM_THREADS}
###   Consult with your cluster administrators to find the combination that
###   works best for single-node, multi-threaded applications on your system.
#SBATCH --mem={MEM_GB}G
#SBATCH -o {STDOUT_LOG}
#SBATCH -e {STDERR_LOG}

{PIPELINE_CMD} 
```

If this job script is saved as **runJob.bash**, then the following command submits the job to the cluster:

```
$ sbatch runJob.bash
```

Slurm


```

  #!/usr/bin/env bash

  #

  #!!! This is not officially supported by 10x

  #

  # =============================================================================

  # Job Script

 # =============================================================================

 #

  #PBS -N {JOB_NAME}

  #PBS -V

  #PBS -l nodes=1:ppn={NUM_THREADS}

  #PBS -l mem={MEM_GB}gb

  #PBS -o {STDOUT_LOG}

  #PBS -e {STDERR_LOG}


  cd {JOB_WORKDIR}


  {PIPELINE_CMD} 

```

If this job script is saved as **runJob.bash**, then the following command submits the job to the cluster:

```

  $ qsub runJob.bash

```

Torque/PBS

Job Submission Mode

When the pipeline runs, it will display the URL for the UI.

```
$ cellranger count --id=sample345 \
 --transcriptome=/opt/refdata-gex-GRCh38-2020-A \
 --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \
 --indices=SI-3A-A1 \
 --expect-cells=1000 \


 
Martian Runtime - v4.0.8
Serving UI at http://host.example.com:5603/?auth=mcV3MKANWfNTERRGASgYV8aXskx-rSH7hxynAdsTieA
2012-01-01 12:00:00 [runtime] Reattaching in local mode.
 
Running preflight checks (please wait)...
```

The UI will become unavailable once the pipeline completes unless the `--noexit` flag is passed.

While a pipeline is running, you can open the url ( `http://host.example.com:5603/?auth=mcV3MKANWfNTERRGASgYV8aXskx-rSH7hxynAdsTieA`) in your web browser to view the pipeline process graph:

<Image src={'https://cdn.10xgenomics.com/image/upload/v1688580323/software-support/Cell%20Ranger/graph.png'}
/>

Clicking on any of the graph's nodes will reveal more information about that stage in the right pane. This info pane is broken into several sections, and the topmost shows high-level details about the stage's execution. For example, the `RUN_KMEANS` stage would show:

<Image src={'https://cdn.10xgenomics.com/image/upload/v1688580324/software-support/Cell%20Ranger/meta-details.png'}
/>

This includes the state of the stage (running, failed, or complete), the fully-qualified stage name (`FQName`), the directory in which the stage is running (`Path`), the stagecode that is being run (the location of the Python package being run in the above example), and any information about parameter sweeping that may apply to this stage.

Clicking the arrow next to the stage name (`← RUN_KMEANS` in the above example) will return to the pipeline-level metadata view.

The **Sweeping** section allows you to view the MRO call used to invoke this stage (`invocation`) and information about the split and join components of the stage if it was parallelized.

<Image src={'https://cdn.10xgenomics.com/image/upload/v1688580326/software-support/Cell%20Ranger/meta-sweep.png'}
/>

<SupportCallout level={"info"}>
 <Text as={"span"}>
 {"Martian, the pipeline framework used by Cell Ranger, supports parameter sweeping for pipelines. The Forks and Permute fields in the Sweeping section would display information about different parameters being swept, but no Cell Ranger pipeline currently performs parameter sweeping. These fields will always contain only trivial information as a result."}
 </Text>
</SupportCallout>

The **Argument Bindings** and **Return Bindings** sections display the inputs and outputs of the stage:

<Image src={'https://cdn.10xgenomics.com/image/upload/v1688580328/software-support/Cell%20Ranger/meta-bindings.png'}
/>

In general, only top-level pipeline stages (those represented by rectangular nodes in the process graph) contain return bindings.

The **Chunking** section displays information about the parallel execution of the stage:

<Image src={'https://cdn.10xgenomics.com/image/upload/v1688580339/software-support/Cell%20Ranger/meta-chunks.png'}
/>

Many stages are automatically parallelized and process different pieces (chunks) of the same input dataset in parallel. In the above example, the input dataset (the BAM file from the `SORT_BY_BC` stage according to the **Argument Bindings** section above) was split into 39 chunks for this stage. Chunks 0-30 already completed, 31-35 are in flight, and 36-38 are waiting for CPU and/or memory to become available before running.

Clicking on an individual chunk exposes additional options for viewing metadata about that chunk's execution, including any errors, standard output, and in cluster mode the job script used to queue the job to the cluster. The `jobinfo` includes information about how a chunk was executed, selected environment variables, and for completed chunks various perfomance statistics such as peak memory usage and CPU time used. As with the **Sweeping** section, additional metadata associated with the chunk execution can also be viewed.

Understanding the UI

You can also examine pipestances that have already completed using the Cell Ranger UI. Assuming your pipestance output directory was `/home/jdoe/runs/sample345`, simply re-run the `cellranger` command with the `--noexit` option to re-attach the UI:

```
$ cellranger count --id=sample345 \
                 --transcriptome=/opt/refdata-gex-GRCh38-2020-A \
                 --fastqs=/home/jdoe/runs/HAWT7ADXX/outs/fastq_path \
                 --indices=SI-3A-A1 \
                 --expect-cells=1000 \
                 --noexit

 
Martian Runtime - v4.0.8
Serving UI at http://host.example.com:3600
2012-01-01 12:00:00 [runtime] Reattaching in local mode.
 
Running preflight checks (please wait)...
Pipestance completed successfully, staying alive because --noexit given.
```

Because `cellranger` assumes it is resuming an incomplete pipeline job when re-attaching, the pipeline must be valid and preflight checks must still be passed. As such, relocating a complete pipeline may prevent the UI from re-attaching.

Launching the UI for existing pipelines

If you run pipelines on a server that blocks access to all ports except SSH, you can still access the Cell Ranger UI using SSH forwarding. Assuming you have a `cellranger` pipeline running on port `3600` on `cluster.university.edu`, you can type the following from your laptop:

```
$ ssh -NT -L 9000:cluster.university.edu:3600 jdoe@cluster.university.edu
jdoe@cluster.university.edu's password:
```

Upon entering your password (assuming you are `jdoe@cluster.university.edu`), the command will appear to hang. However, in the background it has mapped port 9000 on your laptop to port 3600 on `cluster.university.edu` through the ssh connection for which you just entered your password.

This allows you to go to http://localhost:9000/ in your web browser and access the UI running on `cluster.university.edu:3600`. Once you are done examining the UI, use `Ctrl+C` in your `ssh -NT -L ...` terminal window to terminate this SSH forwarder.

A full explanation of SSH forwarding is beyond the scope of this guide, please see [SSH/OpenSSH/PortForwarding](https://help.ubuntu.com/community/SSH/OpenSSH/PortForwarding).

Accessing the UI through a firewall

The Cell Ranger User Interface

The [`cellranger multi` pipeline](/support/software/cell-ranger/advanced/cr-command-line-arguments#multi) uses a configuration CSV file to specify input file paths and analysis options. The general layout for all analyses includes the `[gene-expression]` and `[libraries]` sections. The other sections may be included depending on the analysis. 

The information below is divided by config section and it is noted if the option only applies to certain assays or has unique recommendations for specific analyses. Example config CSV layouts for specific assays are shown on these pages:

 * [3' Cell Multiplexing](/support/software/cell-ranger/analysis/running-pipelines/cr-3p-multi)
 * [Fixed RNA Profiling (FRP)](/support/software/cell-ranger/analysis/running-pipelines/cr-flex-multi-frp)
 * [5' Gene Expression with V(D)J and Feature Barcode](/support/software/cell-ranger/analysis/running-pipelines/cr-5p-multi)
 * [5' Gene Expression with Antigen Capture (BEAM)](/support/software/cell-ranger/analysis/running-pipelines/cr-5p-antigen)

The `[gene-expression]` section specifies information about the Gene Expression library.

 | Field | Description |
 | --- | --- |
 | `reference` | *Required*. Absolute path to folder containing 10x Genomics-compatible genome reference. |
 | `r1-length` | *Optional*. Limit the length of the input Read 1 sequence of Gene Expression libraries to the first N bases, where N is a user-supplied value. Note that the length includes the 10x Barcode and UMI sequences so do not set this below 26. This and r2-length are useful options for determining the optimal read length for sequencing. Default: do not trim Read 1. |
 | `r2-length` | *Optional*. Limit the length of the input Read 2 sequence of Gene Expression libraries to the first N bases, where N is a user-supplied value. Trimming occurs before sequencing metrics are computed and therefore, limiting the length of Read 2 may affect Q30 scores. Default: do not trim Read 2. |
 | `chemistry` | *Optional*. Assay configuration. Note: by default, the assay configuration is detected automatically (recommended). Users will typically not need to specify a chemistry, options are listed [below](#chem-opts). Default: `auto` |
 |`expect-cells`	|*Optional*. Override the pipeline’s auto-estimation of cells. See [cell calling algorithm overview](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm) for details on how this parameter is used. If used, enter the expected number of recovered cells. <li>Up to 30,000 cells are supported with standard kits for 3' Cell Multiplexing and up to 60,000 cells for HT kits.</li> <li>For FRP, specifying library-level `expect-cells` in the `[gene-expression]` section is only valid for the singleplex FRP configuration; note this option name has a dash (-).</li> |
 | `force-cells` | *Optional*. Force pipeline to use this number of cells, bypassing cell detection. Default: detect cells using Cell Ranger's [cell calling algorithm](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm). For FRP, specifying library-level `force-cells` in the `[gene-expression]` section is only valid for the singleplex Fixed RNA Profiling configuration; note this option name has a dash (-). |
 | `include-introns` | *Optional*. Set to false to exclude intronic reads in count. Including introns in analysis is recommended to [maximize sensitivity](/support/software/cell-ranger/miscellaneous/cr-intron-mode-rec). Default: true This option does not apply to Fixed RNA Profiling analysis. | 
 | `no-secondary` | *Optional*. Disable secondary analysis, e.g. clustering. Default: false |
 | `no-bam` | *Optional*. Set this argument to true to skip [BAM file](/support/software/cell-ranger/analysis/outputs/cr-outputs-bam) generation. This will reduce the total computation time for the pipestance and the size of the output directory. If unsure, we recommend not using this option, as BAM files can be useful for troubleshooting and downstream analysis. Default: false However, we recommend setting this option to true for Fixed RNA Profiling analysis to reduce the total computation time for the pipestance and the size of the output directory. |
 | `check-library-compatibility` | *Optional*. This option allows users to disable the check that evaluates 10x Barcode overlap between libraries when multiple libraries are specified (e.g., Gene Expression + Antibody Capture). Setting this option to false will disable the check across all library combinations. We recommend running this check (default), however if the pipeline errors out, users can bypass the check to generate outputs for troubleshooting. Default: true |

Gene Expression

These are the options for 3', Fixed RNA Profiling (FRP), and 5' chemistries.

 * `auto`: Chemistry autodetection (default)
 * `threeprime`: Single Cell 3'
 * `SC3Pv1`, `SCPv2`, `SCPv3`: Single Cell 3' v1, v2, or v3
 * `SCPv3HT`: Single Cell 3' v3.1 HT
 * `SC-FB`: Single Cell Antibody-only 3' v2 or 5'
 * `fiveprime`: Single Cell 5'
 * `SC5-PE`: Paired-end Single Cell 5'
 * `SC5P-R2`: R2-only Single Cell 5'
 * `SFRP`: Singleplex FRP
 * `MFRP`: Multiplex FRP (Probe Barcode on R2)
 * `MFRP-R1`: Multiplex FRP (Probe Barcode on R1)

Chemistry options

These `[gene-expression]` options only apply to 3' Cell Multiplexing data analysis.

 |Field | Description|
 |---|---|
 | `min-assignment-confidence` | *Optional*. The minimum estimated likelihood to call a sample as tagged with a Cell Multiplexing Oligo (CMO) instead of "Unassigned". Users 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. By default, this value is 0.9. Contact support@10xgenomics.com for further advice. |
 | `cmo-set` | *Optional*. The default CMO reference IDs are built into the Cell Ranger software and do not need to be specified. However, this option can be used to specify the path to a custom CMO set CSV file, declaring CMO constructs and associated barcodes. See [CMO Reference section](/support/software/cell-ranger/analysis/running-pipelines/cr-3p-multi) for details. |
 | `barcode-sample-assignment` | *Optional*. Absolute path to a barcode-sample assignment CSV file that specifies the barcodes that belong to each sample. See details below to set up this file.|

3' Cell Multiplexing only

These `[gene-expression]` options only apply to Fixed RNA Profiling data analysis.

 |Field|Description|
 |---|---|
 | `probe-set`	| *Required*. Absolute path to the [probe set reference CSV file](/support/software/cell-ranger/analysis/cr-flex-multi-frp#probe-set-files). This file is included with the Cell Ranger package v7.0 and later (i.e., `cellranger-x.y.z/probe_sets/`) and on the [Downloads page](/support/software/cell-ranger/downloads). |
 | `filter-probes`	| *Optional*. Include all [non-deprecated probes](/support/software/cell-ranger/algorithms-overview/cr-flex-frp-algorithm#probe-filtering) listed in the probe set reference CSV file. Probes that are predicted to have off-target activity to homologous genes are excluded from analysis by default. Setting `filter-probes` to false 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. Default: true | 

Fixed RNA Profiling only

The `[feature]` section specifies information about the Feature Barcode library.

 | Field | Description |
 | --- | --- |
 | `reference` | *Required only for Antibody Capture, Antigen Capture, or CRISPR Guide Capture libraries*. Absolute path to the [Feature reference CSV file](/support/software/cell-ranger/analysis/running-pipelines/cr-feature-bc-analysis#feature-ref), declaring Feature Barcode constructs and associated barcodes. |
 | `r1-length` | *Optional*. Limit the length of the input Read 1 sequence of Feature Barcode libraries to the first N bases, where N is a user-supplied value. Note that the length includes the 10x Barcode and UMI sequences so do not set this below 26. This and r2-length are useful options for determining the optimal read length for sequencing. Default: do not trim Read 1. |
 | `r2-length` | *Optional*. Limit the length of the input Read 2 sequence of Feature Barcode libraries to the first N bases, where N is a user-supplied value. Trimming occurs before sequencing metrics are computed and therefore, limiting the length of Read 2 may affect Q30 scores. Default: do not trim Read 2. |

Feature

The `[libraries]` section specifies all the input library data (see also [Specifying Input FASTQ Files](/support/software/cell-ranger/analysis/inputs/cr-specifying-fastqs)).

 | Field | Description |
 | --- | --- |
 | `fastq_id` | *Required*. The Illumina sample name to analyze. This will be as specified in the sample sheet supplied to the [demultiplexing software](/support/software/cell-ranger/analysis/inputs/cr-direct-demultiplexing). |
 | `fastqs` | *Required*. Absolute path to the folder containing the FASTQ files to be analyzed. Generally, this will be the `fastq_path` folder generated by the demultiplexing software. |
 | `feature_types` | *Required*. The underlying feature type of the library (listed [below](#feature-types)). |
 |`lanes` | *Optional*. The lanes associated with this sample, separated with a pipe (e.g., `1\|2`). Default: uses all lanes |
 | `physical_library_id` | *Optional*. Library type. Note: by default, the library type is detected automatically based on specified `feature_types` (recommended). Users typically do not need to include the `physical_library_id` column in the CSV file. | 
 | `subsample_rate` | *Optional*. The rate at which reads from the provided FASTQ files are sampled. Must be strictly greater than 0 and less than or equal to 1. |

Libraries

These are the options for 3', Fixed RNA Profiling (FRP), and 5' feature types.

 * `Gene Expression`
 * `Antibody Capture`
 * `CRISPR Guide Capture`
 * `Multiplexing Capture` for 3' Cell Multiplexing
 * `VDJ`
 * `VDJ-T`
 * `VDJ-T-GD`
 * `VDJ-B`
 * `Antigen Capture`


`Antigen Capture` should be used only for BEAM libraries. For other (non-BEAM) antigen libraries (TotalSeq™-C, Immudex's dMHC Dextramer® libraries with dCODE Dextramers), set `feature_types` to `Antibody Capture`. Setting this option to `VDJ` will autodetect the chain type.

Feature types

The `[samples]` is used to specify sample-level options for multiplexed experiments.

 | Field	| Description | 
 | --- | --- |
 | `sample_id` | *Required*. A name to identify a multiplexed sample. Must be alphanumeric with hyphens and/or underscores, and less than 64 characters. | 
 | `expect_cells` | *Optional*. Override the pipeline’s auto-estimation of cells. See [Gene Expression algorithm overview](/support/software/cell-ranger/algorithms-overview/cr-gex-algorithm) for details. If used, enter the expected number of recovered cells. For FRP, specifying sample-level `expect_cells` in the `[samples]` section is only valid for the multiplex Fixed RNA Profiling configuration; note this column name has an underscore (_).|
 | `force_cells` | *Optional*. Force pipeline to use this number of cells, bypassing cell detection. Default: detect cells using EmptyDrops. For FRP, specifying sample-level `force_cells` in the `[samples]` section is only valid for the multiplex Fixed RNA Profiling configuration; note this column name has an underscore (_). |
 | `description` | *Optional*. A description for the sample. | 


This `[samples]` option only applies to **3' Cell Multiplexing** data analysis.

 |Field|Description|
 |---|---|
 | `cmo_ids` | *Required*. The Cell Multiplexing oligo IDs used to multiplex this sample. Only input CMOs used in the experiment. If multiple CMOs were used for a sample, separate IDs with a pipe (e.g., `CMO301\|CMO302`). | 


This `[samples]` option only applies to **Fixed RNA Profiling** data analysis.

 | Field	| Description | 
 | --- | --- |
 | `probe_barcode_ids` | *Required*. The Fixed RNA Probe Barcode IDs used for this sample, and for multiplex GEX + Antibody Capture libraries, the corresponding Antibody Multiplexing Barcode IDs. We recommend specifying both barcodes in the config CSV (e.g., `BC001+AB001`) when an Antibody Capture library is present. The barcode pair order is BC+AB and they are separated with a "+" (no spaces). Alternatively, you can specify the Probe Barcode ID alone and Cell Ranger’s [barcode pairing auto-detection algorithm](/support/software/cell-ranger/algorithms-overview/cr-flex-frp-algorithm#auto-pair) will automatically match to the corresponding Antibody Multiplexing Barcode. If multiple Probe Barcodes were used for a sample, separate IDs with a pipe (e.g., `BC001\|BC002`).|

Samples

The `[vdj]` section specifies information about the V(D)J library.

 | Field	| Description | 
 | --- | --- |
 | `reference`	| *Required for V(D)J Immune Profiling libraries*. Absolute path of folder containing 10x Genomics-compatible V(D)J reference.  |
 | `inner-enrichment-primers` | *Optional*. If inner enrichment primers other than those provided in the 10x Genomics kits are used, they need to be specified here as a text file with one primer per line. | 
 | `r1-length` | *Optional*. Limit the length of the input Read 1 sequence of V(D)J libraries to the first N bases, where N is a user-supplied value. Note that the length includes the Barcode and UMI sequences so do not set this below 26. This and r2-length are useful options for determining the optimal read length for sequencing. Default: do not trim Read 1. |
 | `r2-length`	| *Optional*. Limit the length of the input Read 2 sequence of V(D)J libraries to the first N bases, where N is a user-supplied value. Trimming occurs before sequencing metrics are computed and therefore, limiting the length of Read 2 may affect Q30 scores. Default: do not trim Read 2. | 

This `[antigen-specificity]` section is recommended if an Antigen Capture (BEAM) library is present. It is needed to calculate the antigen specificity score.

 | Field | Description |         
 | --- | --- |
 | `control_id`| *Required*. A user-defined ID for any negative controls used in the T/BCR Antigen Capture assay. Must match id specified in the [Feature Reference CSV](/support/software/cell-ranger/analysis/running-pipelines/cr-feature-bc-analysis#feature-ref). May only include ASCII characters and must not use whitespace, slash, quote, or comma characters. Each ID must be unique and must not collide with a gene identifier from the transcriptome. |
 | `mhc_allele` | The MHC allele for TCR Antigen Capture libraries. Must match mhc_allele name specified in the Feature Reference CSV. For BCR Antigen Capture library, analysis runs with or without this header. If you keep the header, leave rows blank. |

Antigen Specificity

Cell Ranger Multi Config CSV (Manual Page)

Cell Ranger's notion of a pipeline is very flexible in that a pipeline can be composed of *stages* that run *stage code* or *sub-pipelines* that may themselves contain stages or sub-pipelines.

Cell Ranger pipelines follow the convention that stages are named with verbs (e.g., `ALIGN_READS`, `MARK_DUPLICATES`, `FILTER_BARCODES`) and sub-pipelines are named with nouns and prefixed with an underscore (e.g., `_BCSORTER`). Each stage runs in its own directory bearing its name, and each stage's directory is contained within its parent pipeline's directory.

For example, the `cellranger mkfastq` pipeline has the following process graph:

<Image src=
 {'https://cdn.10xgenomics.com/image/upload/v1688581764/software-support/Cell%20Ranger/mkfastq-in-flight.png'}
/>

where

* `MAKE_FASTQS_CS` is the *top-level pipeline stage*
* `MAKE_FASTQS` is a *sub-pipeline* contained in `MAKE_FASTQS_CS`
* `PREPARE_SAMPLESHEET`, `BCL2FASTQ_WITH_SAMPLESHEET`, `MAKE_QC_SUMMARY`, and `MERGE_FASTQS_BY_LANE_SAMPLE` are *stages* contained in the `MAKE_FASTQS` *sub-pipeline*.
* `MAKE_FASTQS_PREFLIGHT` and `MAKE_FASTQS_PREFLIGHT_LOCAL` are *preflight stages*, which validate inputs prior to running the other stages. These also belong to `MAKE_FASTQS`, but have no connections to other stages because they don't produce any outputs.

<SupportCallout level={"info"}>
 <Text as={"span"}>
 {"The MAKE_FASTQS_CS stage is not strictly necessary since it contains no stages and only one child pipeline (MAKE_FASTQS); however, it serves to mask some of the low-level inputs required by the MAKE_FASTQS pipeline."}
 </Text>
</SupportCallout>

Pipeline structure

Every pipestance operates wholly inside of its *pipeline output directory*. When the pipestance completes, this *pipestance output directory* contains three outputs: metadata files, the pipestance output file directory, and the top-level pipeline stage directory.

* **Metadata files** are files prefixed with an underscore (`_`) and usually contain unstructured text or JSON-encoded arrays and hashes.
* The **pipestance output file directory** is a directory called `outs/` that contains the pipestance's output files.
* The **top-level pipeline stage directory** is a directory named according to the top-level pipeline stage that contains the child *stage directories* that compose this pipestance.

The *top-level pipeline stage* directory is a *stage directory* that contains any number of child stage directories as well as one *stage output directory* for each *fork* run by that stage. There are four possible top-level pipeline stages:

* `MAKE_FASTQS_CS` for [cellranger mkfastq](/support/software/cell-ranger/analysis/inputs/cr-mkfastq)
* `SC_RNA_COUNTER_CS` for [cellranger count](/support/software/cell-ranger/analysis/running-pipelines/cr-gex-count)
* `SC_RNA_AGGREGATOR_CS` for [cellranger aggr](/support/software/cell-ranger/analysis/running-pipelines/cr-3p-aggr)
* `SC_RNA_REANALYZER_CS` for [cellranger reanalyze](/support/software/cell-ranger/analysis/running-pipelines/cr-3p-reanalyze)

All of the Cell Ranger pipelines only contain single-fork stages, so there will only ever be a `fork0` *stage output directory* within each *stage directory*. *Chunk output directories* are a subset of *stage output directories* that additionally contain runtime information specific to the job or process being run by that chunk (e.g., a process ID or cluster job ID).

For example, the `cellranger mkfastq` pipeline's *pipeline output directory* contains the following directory structure:

| **Directory**                                                      | **Description**                    |
| ------------------------------------------------------------------ | ---------------------------------- |
| _log                                                               | Metadata file                      |
| outs/                                                              | Pipestance output file directory   |
| MAKE_FASTQS_CS/                                                    | Top-level pipeline stage directory |
| MAKE_FASTQS_CS/fork0/                                              | Stage output directory             |
| MAKE_FASTQS_CS/fork0/files/                                        | Stage output files                 |
| MAKE_FASTQS_CS/MAKE_FASTQS/                                        | Stage directory                    |
| MAKE_FASTQS_CS/MAKE_FASTQS/fork0/                                  | Stage output directory             |
| MAKE_FASTQS_CS/MAKE_FASTQS/fork0/files/                            | Stage output files                 |
| MAKE_FASTQS_CS/MAKE_FASTQS/BCL2FASTQ_WITH_SAMPLESHEET/             | Stage directory                    |
| MAKE_FASTQS_CS/MAKE_FASTQS/BCL2FASTQ_WITH_SAMPLESHEET/fork0/       | Stage output directory             |
| MAKE_FASTQS_CS/MAKE_FASTQS/BCL2FASTQ_WITH_SAMPLESHEET/fork0/chnk0/ | Chunk output directory             |

Directory structure

The metadata contained in the *pipeline output directory* includes

| File Name     | Description                                                                                                                               |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `_finalstate` | Metadata cache that is populated when a pipestance completes to minimize re-aggregation of metadata                                       |
| `_invocation` | The MRO call used to invoke this pipestance                                                                                               |
| `_log`        | The log messages that are reported to your terminal window when running `cellranger` commands                                             |
| `_mrosource`  | The entire MRO describing the pipeline with all `@include` statements dereferenced                                                        |
| `_perf`       | Detailed runtime performance data for every stage in the pipestance                                                                       |
| `_timestamp`  | The start and finish time for this pipestance                                                                                             |
| `_vdrkill`    | A list of all of the volatile data (temporary files) removed during pipeline execution as well as total number of files and bytes deleted |
| `_versions`   | Versions of the components used by the pipeline                                                                                           |

*Stage directories* contain *stage output directories*, *stage output files*, and the *stage directories* of any child stages or pipelines.

*Stage output directories* typically contain:

| File Name     | Contents                                                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `files/`      | Directory containing any files created by this stage that were not considered volatile (temporary)                                        |
| `split/`      | A special *stage output directory* for the step that divided this stage's input into parallel chunks                                      |
| `chnkN/`      | A *chunk output directory* for the Nth parallel chunk executed                                                                            |
| `join/`       | A special *stage output directory* for the step that recombined this stage's parallel output chunks into a single output dataset again    |
| `_complete`   | A file that, when present, signifies that this stage has successfully completed                                                           |
| `_errors`     | A file that, when present, signifies that this stage failed. Contains the errors that resulted in stage failure.                          |
| `_invocation` | The MRO call used to execute this stage by the Martian framework                                                                          |
| `_outs`       | The output files generated by this stage                                                                                                  |
| `_vdrkill`    | A list of all of the volatile data (temporary files) removed during pipeline execution as well as total number of files and bytes deleted |

*Chunk output directories* are a subset of *stage output directories* that, in addition to the aforementioned stage output, may contain:

| File Name    | Contents                                                                                                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_args`      | The arguments passed to the stage's *stage code*                                                                                                                                   |
| `_jobinfo`   | Metadata describing the stage's execution, including performance metrics, job manager jobid and jobname, and process ID                                                            |
| `_jobscript` | The script submitted to the cluster job manager ([cluster mode](/support/software/cell-ranger/advanced/cr-cluster-mode) |
| `_stdout`    | Any *stage code* output that was printed to the stdout stream                                                                                                                      |
| `_stderr`    | Any *stage code* output that was printed to the stderr stream                                                                                                                      |

These metadata files should be treated as read-only, and altering the contents of metadata files is not recommended.

Commonly generated metadata

Pipestance output directories can demonstrate very complicated structures, and re-attaching the [Cell Ranger UI](/support/software/cell-ranger/advanced/cr-monitoring-ui) is the easiest way to quickly navigate to a pipeline stage of interest and examine its metadata. In the absence of being able to access the UI, the standard `find` command can quickly return high-level information about a pipestance.

For example, to find the stages that resulted in the overall failure of a pipestance whose output directory is `sample345/`,

```
$ find sample345/ -name _errors
sample345/SC_RNA_COUNTER_CS/SC_RNA_COUNTER/SUMMARIZE_REPORTS/fork0/chnk0/_errors
```

This tells us that the failed stage was `SUMMARIZE_REPORTS`.

It can be helpful to view all `_errors` files' contents at once by piping to `xargs cat`:

```
$ find sample345/ -name _errors | xargs cat
 
Traceback (most recent call last):
  File "/home/jdoe/cellranger-7.1.0/cellranger-cs/7.1.0/mro/stages/cellranger/summarize_reports/__init__.py", line 62, in main
    filtered_gene_bc_matrices=args.filtered_gene_bc_matrices)
  File "/home/jdoe/cellranger-7.1.0/cellranger-cs/7.1.0/lib/python/cellranger/webshim/common.py", line 625, in build_web_summary_html
    filtered_gene_bc_matrices=filtered_gene_bc_matrices)
  File "/home/jdoe/cellranger-7.1.0/cellranger-cs/7.1.0/lib/python/cellranger/webshim/common.py", line 614, in build_web_summary_json
    filtered_gene_bc_matrices=filtered_gene_bc_matrices)
  File "/home/jdoe/cellranger-7.1.0/cellranger-cs/7.1.0/lib/python/cellranger/webshim/common.py", line 579, in build_charts
    plot_data = plot_preprocess_func(sample_properties, filtered_matrices, gene_index)
  File "/home/jdoe/cellranger-7.1.0/cellranger-cs/7.1.0/lib/python/cellranger/webshim/common.py", line 319, in plot_preprocess
    silhouette_score = metrics.silhouette_score(kmeans_matrix, clusters, metric='cosine')
  File "/home/jdoe/cellranger-7.1.0/anaconda-cs/2.2.0/lib/python2.7/site-packages/sklearn/metrics/cluster/unsupervised.py", line 84, in silhouette_score
    "and less than n_samples - 1" % n_labels)
ValueError: Number of labels is 5 but should be more than 2 and less than n_samples - 1
```

In the above case, the error is an unhandled exception whose cause is not obvious; these sorts of failures should be reported to [the 10x Genomics software support team](mailto:support@10xgenomics.com) for assistance with diagnosis.

Stages whose stage code run external binaries (for example, the `ALIGN_READS` stage which runs STAR) often generate output to their stdout and stderr streams. These messages are captured in the `_stdout` and `_stderr` metadata files within the chunk output directories, and combining `find` and `xargs cat` to examine their contents can also assist with troubleshooting.

Navigating pipestances

Pipestance Structure

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.

Getting Started

Downloads & Installation

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

Cell Ranger mkfastq

Analyze Gene Expression and Feature Barcode data with Cell Ranger count

Cell Ranger count

Cell Ranger aggr

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

Cell Ranger reanalyze

Build a custom reference using Cell Ranger mkref

Cell Ranger mkref

Analyze cell multiplexing data with Cell Ranger 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

View all tutorials

Learn more about input files required to run Cell Ranger

Inputs

Generating FASTQs (mkfastq)

Specifying FASTQs

FASTQs with Illumina software

Custom Reference (mkref)

Running Pipelines

Choosing a pipeline

GEX (count)

Antibody/CRISPR (count)

3' Cell Multiplexing (multi)

VDJ-T/B only (vdj)

VDJ + GEX + FB/BEAM (multi)

Fixed RNA Profiling (multi)

Aggregate Multiple Samples (aggr)

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

Antibody Capture

CRISPR Guide Capture

Cell Multiplexing

VDJ-T/B

VDJ + GEX + BEAM

Fixed RNA Profiling

What is Cell Ranger?

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