HOME  ›   pipelines
If your question is not answered here, please email us at:  ${email.software}

10x Genomics
Chromium Single Cell Immune Profiling

Analyzing V(D)J, Gene Expression & Feature Barcode with cellranger multi

In this section, you will learn:

What is multi?

The 5' Chromium Single Cell Immune Profiling Solution with Feature Barcode technology enables simultaneous profiling of V(D)J repertoire, cell surface protein, antigen specificity, 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 GEX data.

cellranger multi takes FASTQ files from cellranger mkfastq or bcl2fastq for any combination of 5' Gene Expression, Feature Barcode (cell surface protein or antigen), 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 library. cellranger multi is the recommended pipeline for processing FASTQ files generated using the 5' the Immune Profiling Solution with Feature Barcode technology.

When to use multi?

Pipeline recommendation depends on the combination of libraries being analyzed. This table summarizes all library combinations and corresponding pipeline recommendations:

V(D)J
5'GEX
5'FB
Use multi?
Recommended. Improves final cell calls in V(D)J library. Learn more.
Recommended. Improves final cell calls in V(D)J library. Learn more.
Optional. Alternative pipeline: count + vdj
Optional. Alternative pipeline: vdj
Optional. Alternative pipeline: count
Optional. Alternative pipeline: count
Optional. Alternative pipeline: count

Why use multi?

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' GEX dataset. By assigning cells that are called in the V(D)J results but not in the 5' GEX results as background GEMs in the V(D)J data, the cellranger multi pipeline mitigates any overcalling issues that may arise in BCR and TCR data. This improved cell calling is only possible when both 5' GEX and V(D)J libraries were sequenced from the same sample.

As shown in the image below, final V(D)J cell calls (green intersection area) exclude cells that were only called by the vdj pipeline (yellow region).

The 5' GEX 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 partition (droplet). The TCR or BCR transcripts in the gene expression library are then selectively amplified to create the V(D)J library. Therefore, the gene expression library has more power to detect partitions containing cells compared to the V(D)J library. If the cellranger multi pipeline is run with both 5' GEX and V(D)J data, then barcodes which are not called as cells in the 5' GEX data will be deleted from the V(D)J cell set.

Arguments and config for multi

The cellranger multi pipeline takes FASTQ files as input. If you do not have FASTQ files for your V(D)J, single cell gene expression and/or Feature Barcode libraries, follow the instructions for running cellranger mkfastq to generate FASTQ files.

To simultaneously generate single cell feature counts, V(D)J sequences and annotations for a single library, run cellranger multi with the following arguments:

ArgumentDescription
--idA unique run ID string: e.g. sample345 that is also the output folder name. Cannot be more than 64 characters.
--csvPath 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], and [libraries]. The [gene-expression], [feature], and [vdj] 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. A customizable template for a multi config CSV can be downloaded here, and example multi config CSVs can be downloaded from public datasets.



multi config CSV
Section: [gene-expression]
FieldDescription
referencePath of folder containing 10x-compatible reference. Required for gene expression and Feature Barcode libraries.
target-panelOptional. Path to a target panel CSV file or name of a 10x Genomics fixed gene panel (pathway, pan-cancer, immunology, neuroscience).
no-target-umi-filterOptional. Disable targeted UMI filtering stage. Default: false.
r1-lengthOptional. Hard trim the input Read 1 of gene expression libraries to this length before analysis. Default: do not trim Read 1.
r2-lengthOptional. Hard trim the input Read 2 of gene expression libraries to this length before analysis. Default: do not trim Read 2.
chemistryOptional. Assay configuration. NOTE: by default, the assay configuration is detected automatically, which is the recommended mode. Users usually will not need to specify a chemistry. Options are: 'auto' for autodetection, 'fiveprime' for Single Cell 5', 'SC5P-PE' for paired end or 'SC5P-R2' for R2-only, 'SC-FB' for Single Cell Antibody-only. Default: auto.
expect-cellsOptional, recommended. Expected number of recovered cells. Default: 3000.
force-cellsOptional. Force pipeline to use this number of cells, bypassing cell-calling algorithm.
include-intronsOptional. Include intronic reads in count. Default: false
no-secondaryOptional. Disable secondary analysis, e.g. clustering. Default: false.
no-bamOptional. Do not generate a bam file.
Section: [feature]
FieldDescription
referenceOptional. Feature reference CSV file, declaring Feature Barcode constructs and associated barcodes. Required only if Feature Barcode libraries are present.
r1-lengthOptional. Hard trim the input Read 1 of Feature Barcode libraries to this length before analysis. Default: do not trim Read 1.
r2-lengthOptional. Hard trim the input Read 2 of Feature Barcode libraries to this length before analysis. Default: do not trim Read 2.
Section: [vdj]
FieldDescription
referencePath of folder containing 10x-compatible VDJ reference. Required for VDJ Immune Profiling libraries.
inner-enrichment-primersOptional. If inner enrichment primers other than those provided in the 10x kits are used, they need to be specified here as a text file with one primer per line.
r1-lengthOptional. Hard trim the input Read 1 of V(D)J libraries to this length before analysis. Default: do not trim Read 1.
r2-lengthOptional. Hard trim the input Read 2 of V(D)J libraries to this length before analysis. Default: do not trim Read 2.
Section: [libraries]
ColumnDescription
fastq_idThe Illumina sample name to analyze. This will be as specified in the sample sheet supplied to mkfastq or bcl2fastq. Required.
fastqsThe folder containing the FASTQ files to be analyzed. Generally, this will be the fastq_path folder generated by cellranger mkfastq. Required.
lanesOptional. The lanes associated with this sample, separated by `|`. Defaults to using all lanes.
feature_typesThe underlying feature type of the library, which must be one of ‘Gene Expression’, ‘VDJ’, ‘VDJ-T’, ‘VDJ-B’, ‘Antigen Capture’ or ‘Antibody Capture’. Setting to ‘VDJ’ will auto-detect the chain type. Auto-detection of chain type only works when all V(D)J FASTQs are the same chain type (i.e. auto-detection with feature_type set to ‘VDJ’ fails if users have both TCR and BCR FASTQ sets). 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’, and the combination ‘VDJ-T’ & ‘VDJ-B’. Required.
subsample_rateOptional. 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.


Running multi

After determining the input arguments, run cellranger multi. Remember to replace the bits of code in red 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.6
 
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 start the run over, delete the output folder (sample345/ in this example) and rerun the pipeline.

Successful multi run

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 under Understanding Outputs.

Additional features in multi

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.

Features absent in multi

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 steps

Next, you may wish to: