Choose a product below to filter the page content to your needs:
The 5' Chromium Next GEM Single Cell Immune Profiling Solution with
Feature Barcode technology enables simultaneous profiling of the V(D)J
repertoire, cell surface protein, antigen, and gene expression (GEX) data.
The cellranger multi
pipeline analyzes these multiple library types
together, enabling more consistent cell calling between the V(D)J and gene
expression data.
![](https://cdn.10xgenomics.com/image/upload/v1692811736/software-support/Cell%20Ranger/workflow/VDJMulti_1sample-1GEM-1flowcell.png)
The cellranger multi
pipeline takes a config CSV with paths to FASTQ files from cellranger mkfastq, bcl2fastq, or BCL Convert for any combination of 5' Gene Expression, Feature Barcode (cell surface protein, antibody/antigen, or CRISPR), and V(D)J libraries from a single GEM well. It performs alignment, filtering, barcode counting, and UMI counting on the Gene Expression and/or Feature Barcode libraries. It also performs sequence assembly and paired clonotype calling on the V(D)J libraries. Additionally, the cell calls provided by the gene expression data are used to improve the cell calls from the V(D)J data. Visit the multi tutorial page for self-guided and video tutorials on running cellranger multi
.
Pipeline recommendation depends on the combination of input libraries. In general, cellranger multi
is the recommended pipeline for analyzing a combination of Gene Expression and V(D)J libraries (with or without Feature Barcode libraries) sequenced from the same sample.
This table summarizes a few popular library combinations and their corresponding pipeline recommendations:
Library combination | multi | Other pipelines |
---|---|---|
GEX | Supported | count |
VDJ | Supported | vdj |
Antibody | Supported | count |
CRISPR | Not allowed* | count |
Antigen (BEAM) | Not allowed* | None |
GEX + VDJ | Recommended | count and vdj |
GEX + VDJ + Antibody | Recommended | count and vdj |
GEX + VDJ + Antibody + CRISPR | Recommended | count and vdj |
GEX + VDJ + Antibody + Antigen (BEAM) | Required§ | None |
GEX + Antigen (BEAM) | Not allowed†| None |
Cell Multiplexing | Unsupported | None |
*
Cannot be processed without a GEX library
â€
Cannot be processed without a VDJ library
§
BEAM is unsupported with GEM-X chemistry; therefore, Cell Ranger does not support BEAM/Antigen Capture libraries produced with this chemistry.
The cellranger multi
pipeline improves cell calls in the V(D)J dataset
by discarding any cells that were not also called in the corresponding 5'
Gene Expression dataset. By assigning cells that are called in the V(D)J
results but not in the 5' Gene Expression results as background GEMs in
the V(D)J data, cellranger multi
mitigates any overcalling issues that
may arise in V(D)J data. This improved cell calling is only possible
when both 5' Gene Expression and V(D)J libraries were sequenced from the
same sample.
As shown in the image below, final V(D)J cell calls (intersection area) exclude cells that were only called by the vdj
pipeline (yellow region).
![](https://cdn.10xgenomics.com/image/upload/v1689289740/software-support/vdj/why-use-multi.png)
The 5' Gene Expression cell calls are not affected by the cellranger multi
pipeline. The Gene Expression library is representative of the entire pool of poly-adenylated mRNA transcripts captured within each GEM. VDJ-T or VDJ-B transcripts within the Gene Expression library are then selectively amplified to create the V(D)J library. As a result, the Gene Expression library has greater sensitivity in detecting GEMs that have cells compared to the V(D)J library. When the cellranger multi
pipeline is executed with both 5' Gene Expression and V(D)J data, any barcodes that are not classified as cells in the 5' Gene Expression data are removed from the V(D)J cell set. This process ensures that only the barcodes identified as cells in the Gene Expression library are retained in the V(D)J library for downstream analysis.
The cellranger multi
pipeline takes a config CSV file as input. The config CSV contains paths to FASTQ files for any combination of V(D)J, Gene Expression, and/or Feature Barcode libraries. To generate FASTQ files, follow the instructions for running cellranger mkfastq.
To simultaneously generate single cell feature counts, V(D)J sequences, and annotations for a single library, run cellranger multi
with the following arguments:
Argument | Description |
---|---|
--id | A unique run ID string: e.g. sample345 that is also the output folder name. Cannot be more than 64 characters. |
--csv | Path to multi config CSV file enumerating input libraries and analysis parameters. |
The multi config CSV contains both the library definitions and experiment configuration variables. It is composed of up to four sections: [gene-expression]
, [feature]
, [vdj]
, [antigen-specificity]
and [libraries]
.
The [gene-expression]
, [feature]
, [vdj]
, and [antigen-specificity]
sections have at most two columns and are responsible for configuring their respective portions of the experiment. The [libraries]
section specifies where input FASTQ files may be found.
Go to the Cell Ranger Multi Config CSV page for a complete list of options for each section.
Example multi config CSVs can be downloaded from public datasets. Cell Ranger v7.1 and later also provides the option to download a multi config CSV template via the command line.
Example formats for a few product configurations are below.
After determining the input arguments, run cellranger multi
. Remember to
customize the code with your sample id and csv file path:
mkdir /home/jdoe/runs
cd /home/jdoe/runs
cellranger multi --id=sample345 --csv=/home/jdoe/sample345.csv
Following a series of checks to validate input arguments, cellranger multi
pipeline stages will begin to run:
Martian Runtime - v4.0.8
Running preflight checks (please wait)...
...
By default, cellranger will use all of the cores available on your system to execute pipeline stages. You can specify a different number of cores to use with the --localcores
option; for example, --localcores=16
will limit cellranger to using up to sixteen cores at once. Similarly, --localmem
will restrict the amount of memory (in GB) used by cellranger.
The pipeline will create a new folder named with the run ID you specified using the --id
argument (e.g. /home/jdoe/runs/sample345
) for its output. If this folder already exists, cellranger will assume it is an existing pipestance and attempt to resume running it. If you wish to re-start the run, delete the output folder (sample345/
in this example) and rerun the pipeline.
A successful cellranger multi run should conclude with a message similar to this:
Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!
yyyy-mm-dd hh:mm:ss Shutting down.
Saving pipestance info to "tiny/tiny.mri.tgz"
To learn more about the output files generated, refer to the Outputs for multi section.
Cell Ranger multi
v7.0.0 and later allows users to analyze T cell libraries enriched for gamma (TRG) and delta (TRD) chains. 10x Genomics does not provide reagents or primers for TRG/D chain enrichment. Since this workflow is not fully supported, the Cell Ranger pipeline has not been extensively tested for TRG/D libraries, and the algorithm's performance cannot be guaranteed.
To analyze TRG/D libraries, set feature_types
to VDJ-T-GD
in the [libraries]
section of the multi config CSV. Auto-detection does not work for TRG/D chains. If set to auto-detection, TRG/D libraries are treated as VDJ-T libraries enriched for alpha-beta chains, and the gamma-delta chains are filtered out. The pipeline runs to completion, but zero barcodes are assigned to cells.
Refer to the example multi config CSV for additional configuration guidance. Outputs from a successful gamma-delta run are located in the vdj_t_gd
folder.
The cellranger vdj pipeline cannot process FASTQs from TRG/D enriched libraries.
10x Genomics does not support the use of cellranger aggr
to aggregate the outputs of TRG/D enriched libraries.
Visit the Antigen Capture page for specific information on how to run Cell Ranger multi
to analyze your Antigen Capture/BEAM libraries.
Note: BEAM is unsupported with GEM-X chemistry; therefore, Cell Ranger does not support BEAM/Antigen Capture libraries produced with this chemistry.
In the [libraries]
section of the multi config CSV, setting
feature_types
to VDJ
enables auto-detection of the chain type. Important caveats to auto-detection:
- Auto-detection only works for
VDJ-B
libraries andVDJ-T
libraries with alpha-beta chains. - Auto-detection does not work when more than one FASTQ set is specified. For example:
- Auto-detection with
feature_types
set toVDJ
fails when both VDJ-T and VDJ-B FASTQ sets are included. If your experiment includes both VDJ-T and VDJ-B libraries, you must have a separate row for each library withfeature_type
set toVDJ-T
andVDJ-B
, respectively. - Auto-detection does not work if there are multiple FASTQ sets for a single VDJ library. Adding more than one row with
library_type
set toVDJ
with result in an error.
- Auto-detection with
- If the chain for one V(D)J FASTQ set is specified, chains for all existing V(D)J FASTQ sets must be specified. Valid specifications include,
VDJ
,VDJ-T
,VDJ-B
, orVDJ-T-GD
, and the combinations:- VDJ-T & VDJ-B
- VDJ-T-GD & VDJ-B
- VDJ-T & VDJ-T-GD & VDJ-B
- Auto-detection does not work for TRG/D (gamma-delta) chains. If set to auto-detection (
VDJ
), gamma-delta libraries are treated as VDJ-T, and gamma-delta chains are filtered out. The pipeline runs to completion, but zero barcodes are assigned to cells. For TRG/D chains, setfeature_types
toVDJ-T-GD
.
Auto-detection is enabled for Antigen Capture (BEAM) libraries. Use feature_types
= Antigen Capture
for both TCR and BCR Antigen Capture libraries.
Generate a multi config CSV template by running cellranger multi-template
, see usage here.
Here are the example multi config CSVs for a few commonly used library combinations. Replace /path/to
with the absolute path to your data, and customize the text according to the experiment's sample, library, and file names. Ensure that the multi config is saved in CSV format with the CSV extension.
TRG/D and Antigen Capture config examples are located on their respective pages.
A self-directed tutorial is available
[vdj]
reference,/path/to/vdj_reference
[libraries]
fastq_id,fastqs,feature_types
VDJ_B_fastqs_id,/path/to/vdj_B_fastqs,VDJ-B
A self-directed tutorial is available
[gene-expression]
reference,/path/to/transcriptome
create-bam,true
[vdj]
reference,/path/to/vdj_reference
[libraries]
fastq_id,fastqs,feature_types
GEX_fastqs_id,/path/to/GEX_fastqs,Gene Expression
VDJ_B_fastqs_id,/path/to/vdj_B_fastqs,VDJ-B
[gene-expression]
reference,/path/to/transcriptome
create-bam,true
[vdj]
reference,/path/to/vdj_reference
[feature]
reference,/path/to/feature_ref.csv
[libraries]
fastq_id,fastqs,lanes,feature_types
GEX_fastqs_id,/path/to/GEX1_fastqs,1,Gene Expression
GEX_fastqs_id,/path/to/GEX2_fastqs,2,Gene Expression
GEX_fastqs_id,/path/to/GEX3_fastqs,3,Gene Expression
VDJ_B_fastqs_id,/path/to/vdj_B1_fastqs,1,VDJ-B
VDJ_B_fastqs_id,/path/to/vdj_B2_fastqs,2,VDJ-B
VDJ_B_fastqs_id,/path/to/vdj_B3_fastqs,4,VDJ-B
[gene-expression]
reference,/path/to/transcriptome
create-bam,true
[vdj]
reference,/path/to/vdj_reference
[feature]
reference,/path/to/feature_ref.csv
[libraries]
fastq_id,fastqs,lanes,feature_types
GEX_fastqs_id,/path/to/GEX_fastqs,1|2,Gene Expression
VDJ_B_fastqs_id,/path/to/vdj_B_fastqs,1|2,VDJ-B
VDJ_T_fastqs_id,/path/to/vdj_T_fastqs,1|2,VDJ-T
FB_fastqs_id,/path/to/FB_fastqs,1|2,Antibody Capture
CRISPR_fastqs_id,/path/to/CRISPR_fastqs,1|2,CRISPR Guide Capture
This template also applies to V(D)J + FB (without GEX) libraries. The [gene-expression] reference section is required. However, the GEX FASTQ specification under the [libraries] section must be removed for the VDJ+FB library combinations.
The cellranger multi
pipeline supports downsampling the reads by specifying a rate between 0 and 1 independently for each library. It also allows trimming the reads to a fixed length, which is not supported in the cellranger vdj
pipeline.
The option to run denovo without V(D)J reference (--denovo
) is not supported in cellranger multi
. This option is available in cellranger vdj
.
Next, you may wish to:
- Understand multi outputs.
- Run cellranger aggr to aggregate the outputs from multiple runs of
cellranger multi
and perform analysis on the combined data. - Explore Loupe and Loupe VDJ browser to visualize your data.