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

10x Genomics
Chromium Single Cell Gene Expression

Cell Multiplexing with cellranger multi

Cell Ranger 6.0 introduces support for analyzing 3' Cell Multiplexing data with the cellranger multi subcommand.

Table of Contents

  1. When to use the multi pipeline
  2. Run cellranger mkfastq
  3. Run cellranger multi
  4. Output files
  5. Example multi config CSVs
  6. CMO Reference

When to use the multi pipeline

The cellranger multi subcommand is required to analyze 3' Cell Multiplexing data. Otherwise, users can continue to use cellranger count.

3' GEX3' FBCellPlexUse multi?
YesYesYesRequired
YesYesNoOptional. Prefer count
YesNoYesRequired
YesNoNoOptional. Prefer count
NoYesNoOptional. Prefer count

Run cellranger mkfastq

First, follow the instructions on running cellranger mkfastq to generate FASTQ files. For example, if the flowcell serial number was HAWT7ADXX, then cellranger mkfastq will output FASTQ files in HAWT7ADXX/outs/fastq_path. If you are already starting with FASTQ files, you can skip this step and proceed directly to run cellranger multi.

Run cellranger multi

Running cellranger multi requires a config CSV, described below, invoking 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 config CSV file with input libraries and analysis parameters.

The multi config CSV contains both the library definitions and experimental design variables. It is composed of up to three sections for 3' data: [gene-expression], [feature], and [libraries]. The [gene-expression] and [feature] 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 template for a multi config CSV can be downloaded here, and example multi config CSVs can be downloaded from 6.0 public datasets here.

Multi Config CSV
Section: [gene-expression]
FieldDescription
referencePath of folder containing 10x-compatible reference. Required for gene expression and Feature Barcode libraries.
min-assignment-confidenceThe minimum estimated likelihood to call a sample as tagged with a Cell Multiplexing Oligo instead of "Unassigned". By default, this value is 0.9. Introduced in Cell Ranger 6.0.2.
cmo-setOptional. CMO set CSV file, declaring CMO constructs and associated barcodes.
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, 'threeprime' for Single Cell 3', 'fiveprime' for Single Cell 5', 'SC3Pv1' or 'SC3Pv2' or 'SC3Pv3' for Single Cell 3' v1/v2/v3, 'SC5P-PE' or 'SC5P-R2' for Single Cell 5', paired-end/R2-only, 'SC-FB' for Single Cell Antibody-only 3' v2 or 5'. Default: auto.
expect-cellsOptional. Expected number of recovered cells. Default: 3000.
force-cellsOptional. Force pipeline to use this number of cells, bypassing cell detection. Default: detect cells using EmptyDrops.
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. Default: false.
Section: [feature]
FieldDescription
referenceFeature reference CSV file, declaring Feature Barcode constructs and associated barcodes. Required for Feature Barcode libraries, otherwise optional.
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: [libraries] (see also Specifying Input FASTQ Files for cellranger multi)
ColumnDescription
fastq_idRequired. The Illumina sample name to analyze. This will be as specified in the sample sheet supplied to mkfastq or bcl2fastq.
fastqsRequired. The folder containing the FASTQ files to be analyzed. Generally, this will be the fastq_path folder generated by cellranger mkfastq.
lanesOptional. The lanes associated with this sample, separated by |. Defaults to using all lanes.
feature_typesRequired. The underlying feature type of the library, which must be one of ‘Gene Expression’ (3' and 5'), ‘VDJ’ (5' only), ‘VDJ-T’ (5' only), ‘VDJ-B’ (5' only), ‘Antibody Capture’ (3' and 5'), ‘CRISPR Guide Capture’ (3' only), or ‘Multiplexing Capture’ (3' only).
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.
Section: [samples]
ColumnDescription
sample_idA name to identify a multiplexed sample. Must be alphanumeric with hyphens and/or underscores, and less than 64 characters. Required for cell multiplexing libraries.
cmo_idsThe cell multiplexing oligo IDs used to multiplex this sample, separated by |. Required for cell multiplexing libraries.
descriptionOptional. A description for the sample.

After determining these input arguments, run cellranger:

$ 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.4
 
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.

Output Files

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"

The output of the pipeline will be contained in a folder named with the run ID you specified (e.g. sample345). The subfolder named outs will contain the main pipeline outputs

Example multi config CSVs

Here are a few example multi config CSVs examples for some common product configurations. Make sure to replace /path/to with the actual PATH to the data.

3' Gene Expression with Cell Multiplexing

[gene-expression]
reference,/path/to/transcriptome
[libraries] fastq_id,fastqs,feature_types gex1,/path/to/fastqs,Gene Expression mux1,/path/to/fastqs,Multiplexing Capture
[samples] sample_id,cmo_ids sample1,CMO301|CMO302 sample2,CMO303|CMO304

3' Gene Expression with Feature Barcoding and Cell Multiplexing

[gene-expression]
reference,/path/to/transcriptome
[libraries] fastq_id,fastqs,feature_types gex1,/path/to/fastqs,Gene Expression abc1,/path/to/fastqs,Antibody Capture mux1,/path/to/fastqs,Multiplexing Capture
[samples] sample_id,cmo_ids sample1,CMO301|CMO302 sample2,CMO303|CMO304

3' Gene Expression with CRISPR and Cell Multiplexing

[gene-expression]
reference,/path/to/transcriptome
[libraries] fastq_id,fastqs,feature_types gex1,/path/to/fastqs,Gene Expression csp1,/path/to/fastqs,CRISPR Guide Capture mux1,/path/to/fastqs,Multiplexing Capture
[samples] sample_id,cmo_ids sample1,CMO301|CMO302 sample2,CMO303|CMO304

CMO Reference

The cmo-set option to the [gene-expression] table of the multi config CSV allows you provide a reference for custom multiplexing oligos. The design of this reference is identical to the Feature Barcode Reference used to describe feature barcodes, with one difference: the feature_type is required to be Multiplexing Capture instead of those feature types supported in the feature barcode reference.

Default CMO Reference

id,name,read,pattern,sequence,feature_type
CMO301,CMO301,R2,5P(BC),ATGAGGAATTCCTGC,Multiplexing Capture
CMO302,CMO302,R2,5P(BC),CATGCCAATAGAGCG,Multiplexing Capture
CMO303,CMO303,R2,5P(BC),CCGTCGTCCAAGCAT,Multiplexing Capture
CMO304,CMO304,R2,5P(BC),AACGTTAATCACTCA,Multiplexing Capture
CMO305,CMO305,R2,5P(BC),CGCGATATGGTCGGA,Multiplexing Capture
CMO306,CMO306,R2,5P(BC),AAGATGAGGTCTGTG,Multiplexing Capture
CMO307,CMO307,R2,5P(BC),AAGCTCGTTGGAAGA,Multiplexing Capture
CMO308,CMO308,R2,5P(BC),CGGATTCCACATCAT,Multiplexing Capture
CMO309,CMO309,R2,5P(BC),GTTGATCTATAACAG,Multiplexing Capture
CMO310,CMO310,R2,5P(BC),GCAGGAGGTATCAAT,Multiplexing Capture
CMO311,CMO311,R2,5P(BC),GAATCGTGATTCTTC,Multiplexing Capture
CMO312,CMO312,R2,5P(BC),ACATGGTCAACGCTG,Multiplexing Capture