Cell Ranger v7.0 and later supports analyzing Flex data with the cellranger multi pipeline (see Supported Libraries table). Flex data cannot be analyzed with the cellranger count pipeline.
First, generate FASTQ files. For example, if the flow cell ID was HAWT7ADXX and you use cellranger mkfastq to demultiplex, the output FASTQ files will be 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.
Running cellranger multi requires a configuration ("config") CSV, described below, and 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 config CSV file with input libraries and analysis parameters. |
The multi config CSV contains both the library definitions and experimental design variables. The required sections differ slightly for analysis with single-sample ("singleplex") vs. multiplexed configurations. It is composed of up to four sections for Flex data:
- The
[gene-expression]section has two columns that specify parameters relevant to analysis of gene expression data, such as reference genome and cell-calling parameters that apply to the whole library in the case of singleplex Flex. Starting with Cell Ranger v9.0, providing a transcriptome reference is optional when analyzing Flex Gene Expression and Antibody Capture libraries. - The
[feature]section has two columns that specify parameters relevant to analysis of Feature Barcode libraries; required when analyzing singleplex or multiplex Flex data with Cell Surface Protein ("Antibody Capture") and/or CRISPR Guide Capture libraries. - The
[libraries]section has three required columns that specify where the input FASTQ files may be found. - The
[samples]section has two required columns that specify sample information for Fixed RNA Gene Expression with multiple samples or a single sample with multiple Probe Barcodes; it is not valid for singleplex Flex analysis.
Starting with Cell Ranger v9.0, you can enable automated cell type annotations in a multi run by adding parameters to the [gene-expression] section of your multi config CSV. See the example multi config CSV below. Please note that cell type annotations are available only if a Gene Expression library is included in your multi analysis. The currently available annotation models are in beta.
Go to the Cell Ranger Multi Config CSV page for a complete list of options for each section.
Generate a multi config CSV template by running cellranger multi-template, see usage here.
Example formats for different product configurations are illustrated below, or download examples from Flex public datasets here.
After determining the input arguments and config CSV parameters, run cellranger multi (replace example code with your file path and ID name):
cd /home/jdoe/runs
cellranger multi --id=sample345 --csv=/home/jdoe/sample345.csv
Following a series of checks to validate input arguments, the cellranger multi pipeline stages will begin to run:
Martian Runtime - v4.0.8
Running preflight checks (please wait)...
...
By default, Cell Ranger 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 Cell Ranger to using up to sixteen cores at once. Similarly, --localmem will restrict the amount of memory (in GB) used by Cell Ranger.
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, Cell Ranger will assume it is an existing pipestance and attempt to resume running it.
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 pipeline outputs will be saved in a folder named with the run ID you specified (e.g. sample345). The subfolder named outs/ contains the pipeline outputs.
Here are a few example multi config CSVs for some common Flex assay configurations, along with simplified diagrams for the corresponding experimental set up. 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.
Important: In the examples below, we set create-bam to "false" so Cell Ranger will not generate a BAM file. This setting is recommended for Flex libraries and will reduce both the total computation time for the pipestance and the size of the output directory.
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
tenx-cloud-token-path,/path/to/10xcloud_token.json
cell-annotation-model,auto
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
This library configuration does not use the [samples] section in the multi config CSV. The sample ID will be specified by the cellranger multi --id input. See example dataset.
To learn how to generate and access your 10x Cloud Analysis token, visit the cellranger annotate page.
Antibody Capture is compatible in this configuration. There is one sample, one Probe Barcode, and two libraries (Gene Expression and Antibody Capture). This example applies to Antibody Capture libraries created using TotalSeq™-B, TotalSeq™-C, or Proteintech Genomics (PTG) antibodies.
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
flex_ab,/path/to/fastqs,Antibody Capture
[feature]
reference,/path/to/feature_reference.csv
This library configuration does not use the [samples] section in the multi config CSV. The sample ID will be specified by the cellranger multi --id input. See example dataset.
Multiple biological samples
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
[samples]
sample_id,probe_barcode_ids,description
sample1,BC001|BC002,Control
sample2,BC003|BC004,Treated
Single biological sample
In this case, the config CSV must include a [samples] section to specify the Probe Barcodes since two Probe Barcodes were used for a single sample in this experiment.
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
[samples]
sample_id,probe_barcode_ids,description
sample1,BC001|BC002,Control
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
[samples]
sample_id,probe_barcode_ids,description
sample1,BC001,Control
sample2,BC003,Treated
These examples apply to Antibody Capture libraries created using TotalSeq™-C or PTG antibodies.
(Recommended) Specify both the Probe Barcode and Antibody Multiplexing Barcode pairs:
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
flex_ab,/path/to/fastqs,Antibody Capture
[feature]
reference,/path/to/feature_reference.csv
[samples]
sample_id,probe_barcode_ids,description
sample1,BC001+AB005
sample2,BC002+AB006
sample3,BC003+AB007
sample4,BC004+AB008
(Advanced) Specify the Probe Barcode only, Antibody Multiplexing Barcode auto-detected:
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv #e.g., cellranger-x.y.z/probe_sets/Chromium_Human_Transcriptome_Probe_Set_v1.0.1_GRCh38-2020-A.csv
create-bam,false #do not generate BAM file
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
flex_ab,/path/to/fastqs,Antibody Capture
[feature]
reference,/path/to/feature_reference.csv
[samples]
sample_id,probe_barcode_ids,description
sample1,BC001
sample2,BC002
sample3,BC003
sample4,BC004
The analysis of multiplex Flex and CRISPR data is enabled in Cell Ranger v8.0 and later. For instructions on designing probes for CRISPR Guide Capture with the Flex Assay, please refer to this Knowledge Base article.
To analyze multiplex experiments, the multi config CSV must specify both the Probe Barcode and CRISPR Multiplexing Barcode, e.g., BC001+CR001 for the GEX and CRISPR libraries, respectively. Barcode auto-pairing is disabled for CRISPR Guide Capture libraries. See the example below for reference:
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv
create-bam,false
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
flex_cr,/path/to/fastqs,CRISPR Guide Capture
[feature]
reference,/path/to/feature_reference.csv
[samples]
sample_id,probe_barcode_ids
sample1,BC001+CR001
sample2,BC002+CR002
sample3,BC003+CR003
sample4,BC004+CR004
An example multi config CSV for a single biological sample with multiple Probe Barcodes and multiple CRISPR guide RNAs is shown below:
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv
create-bam,false
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
flex_cr,/path/to/fastqs,CRISPR Guide Capture
[feature]
reference,/path/to/feature_reference.csv
[samples]
sample_id,probe_barcode_ids
sample1,BC001+CR001|BC002+CR002|BC003+CR003|BC004+CR004
An example multi config CSV for a four biological samples with one Probe Barcodes, one Antibody barcode, and one CRISPR barcode per sample:
[gene-expression]
reference,/path/to/transcriptome
probe-set,/path/to/probe-set.csv
create-bam,false
[libraries]
fastq_id,fastqs,feature_types
flex_gex,/path/to/fastqs,Gene Expression
flex_cr,/path/to/fastqs,Antibody Capture
flex_cr,/path/to/fastqs,CRISPR Guide Capture
[feature]
reference,/path/to/feature_reference.csv
[samples]
sample_id,probe_barcode_ids
sample1,BC001+AB001+CR001
sample2,BC002+AB002+CR002
sample3,BC003+AB003+CR003
sample4,BC004+AB004+CR004
The probe set reference CSV files for human and mouse are located in the probe_sets directory of the Cell Ranger package (v7.1 and later):
cellranger-9.0.0/probe_sets/
└── Chromium_Human_Transcriptome_Probe_Set_v1.1.0_GRCh38-2024-A.csv
└── Chromium_Mouse_Transcriptome_Probe_Set_v1.1.0_GRCm39-2024-A.csv
For compatibility details between Cell Ranger versions, probe set versions, and transcriptome references, see the FAQs section of the Probe Sets page.
Probe set reference CSV files and additional support files for human and mouse can also be downloaded from the Cell Ranger Downloads page. These files are described in detail on the Probe Sets Overview page.