Ensure that the multi config is saved in CSV format with the CSV extension.
When you enable cell type annotation, your data is securely transmitted to 10x Genomics Cloud Analysis. Since your data is leaving your local environment and entering the 10x Genomics domain, it becomes subject to the terms outlined in the 10x Genomics End User License Agreement (EULA). Please review the EULA carefully to understand how your data will be handled and the associated usage terms.
The cellranger multi pipeline uses a configuration CSV file to specify input file paths and analysis options. For a complete list of input files required to run specific Cell Ranger pipelines, please refer to the List of inputs page.
The general layout of the multi config CSV for all analyses includes the [gene-expression] and [libraries] sections. Additional sections may be included depending on the analysis.
[gene-expression]
reference,/path/to/transcriptome
create-bam,true
[libraries]
fastq_id,fastqs,feature_types
gex1,/path/to/fastqs,Gene Expression
The information below is divided by config section. It notes if an option only applies to certain assays or has unique recommendations for specific analyses. Example multi config CSV layouts for specific assays are available.
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. Optional for Flex Gene Expression and Antibody Capture libraries. |
create-bam | Required. Enable or disable BAM file generation. Setting create-bam=false reduces the total computation time and the size of the output directory (BAM file not generated). We recommend setting create-bam=true if unsure. See https://10xgen.com/create-bam for additional guidance. |
tenx-cloud-token-path | The path to the 10x Cloud Analysis user token used to enable cell annotation. If not supplied, will default to the location stored through 10x Genomics Cloud Analysis authentication setup command cellranger cloud auth setup. Learn how to generate or access the token. |
cell-annotation-model | Cell annotation model to use. Valid model names are: autohuman_pca_v1_betamouse_pca_v1_betaauto, uses the default model for the species. If not given, does not run cell annotation. |
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. By default, the assay configuration is detected automatically (recommended). Typically, users will not need to specify a chemistry. However, options are available if needed. Default: auto. Starting from Cell Ranger v8.0, it is possible to specify library-specific assay configurations. For details, refer to the Libraries section. |
expect-cells | Optional. Override the pipeline’s auto-estimation of cells. See cell calling algorithm overview for details on how this parameter is used. If used, enter the expected number of recovered cells. expect-cells in the [gene-expression] section is only valid for the singleplex Flex configuration; note this option name has a dash (-). |
force-cells | Optional. Force pipeline to use this number of cells, bypassing cell detection. Default: detect cells using Cell Ranger's cell calling algorithm. For Flex, specifying library-level force-cells in the [gene-expression] section is only valid for the singleplex Flex 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. Default: true This option does not apply to Flex analysis. |
no-secondary | Optional. Disable secondary analysis, e.g. clustering. Default: false |
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 |
These are the options for 3', Flex, and 5' chemistries.
auto: Chemistry autodetection (default)threeprime: Single Cell 3'SC3Pv1,SC3Pv2,SC3Pv3,SC3Pv4: Single Cell 3' v1, v2, v3, or v4SC3Pv3HT: Single Cell 3' v3.1 HTSC-FB: Single Cell Antibody-only 3' v2 or 5'fiveprime: Single Cell 5'SC5P-PE: Paired-end Single Cell 5'SC5P-PE-v3: Paired-end Single Cell 5' v3SC5P-R2: R2-only Single Cell 5'SC5P-R2-v3: R2-only Single Cell 5' v3SC5PHT: Single Cell 5' v2 HTSFRP: Flex (Singleplex)MFRP: Flex (Multiplex, Probe Barcode on R2)MFRP-R1: Flex (Multiplex, Probe Barcode on R1)MFRP-RNA: Flex (Multiplex, RNA, Probe Barcode on R2)MFRP-Ab: Flex (Multiplex, Antibody, Probe Barcode at R2:69)MFRP-Ab-R2pos50: Flex (Multiplex, Antibody, Probe Barcode at R2:50)MFRP-RNA-R1: Flex (Multiplex, RNA, Probe Barcode on R1)MFRP-Ab-R1: Flex (Multiplex, Antibody, Probe Barcode on R1)ARC-v1for analyzing the Gene Expression portion of Multiome data. If Cell Ranger auto-detectsARC-v1chemistry, an error is triggered.
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 for details. |
barcode-sample-assignment | Optional. Absolute path to a barcode-sample assignment CSV file that specifies the barcodes that belong to each sample. Also applicable to cell hashing with Antibody Capture. |
Starting with Cell Ranger v9.0, providing a transcriptome reference is optional when analyzing Flex Gene Expression and Antibody Capture libraries.
These [gene-expression] options only apply to Flex data analysis.
| Field | Description |
|---|---|
probe-set | Required. Absolute path to the probe set reference CSV file. 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. |
filter-probes | Optional. Include all non-deprecated probes 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 |
emptydrops_minimum_umis | Optional. For singleplex Flex experiments, use this option to adjust the UMI cutoff during the second step of cell calling. Cell Ranger will still perform the full cell calling process but will only evaluate barcodes with UMIs above the threshold you specify. For example, setting this parameter to 100 will allow Cell Ranger to evaluate barcodes with more than 100 UMIs for cell calling. It is recommended to start with 100, but the optimal value may vary by sample, so trying different thresholds and evaluating results is advised. This option is available only in Cell Ranger v7.1.0 and later. emptydrops_minimum_umis cannot be used in combination with force-cells. See https://10xgen.com/scFFPE-cell-calling for details. See Samples section to set emptydrops_min_umis for multiplex Flex experiments. |
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, 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. |
min-crispr-umi | Optional. Set the minimum number of CRISPR guide RNA UMIs required for protospacer detection. Default: 3 UMIs. If a lower or higher threshold is desired for detection, this value can be customized according to specific experimental needs. Applicable only to datasets that include a CRISPR Guide Capture library. |
The [libraries] section specifies all the input library data (see also Specifying Input FASTQ Files).
| 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. |
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. If the same library was sequenced on multiple flow cells, the FASTQs folder from each flow cell must be specified a separate line in the CSV (see 5' example here). 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 multi on them individually, and then combine them with cellranger aggr. |
feature_types | Required. The underlying feature type of the library (listed below). |
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. |
chemistry | Optional (only applicable to Flex). Library-specific assay configuration. By default, the assay configuration is detected automatically (recommended). Typically, users will not need to specify a chemistry. However, options are available if needed (see chemistry options). Default: auto |
These are the options for 3', Flex, and 5' feature types.
Gene ExpressionAntibody CaptureCRISPR Guide CaptureMultiplexing Capturefor 3' Cell MultiplexingVDJVDJ-TVDJ-T-GDVDJ-BAntigen CaptureCustom
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.
The [samples] section defines sample-level options for multiplexed experiments, including on-chip multiplexing (OCM), 3' Cell Multiplexing (CellPlex), and Antibody Capture-based hashing. Scroll down to find instructions specific to your sample multiplexing method.
| 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 for details. If used, enter the expected number of recovered cells. For Flex, specifying sample-level expect_cells in the [samples] section is only valid for the multiplex Flex 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 Flex, specifying sample-level force_cells in the [samples] section is only valid for the multiplex Flex configuration; note this column name has an underscore (_). |
description | Optional. A description for the sample. |
This [samples] option only applies to 3' and 5' GEM-X On-chip multiplexing (OCM) data analysis.
| Field | Description |
|---|---|
ocm_barcode-ids | Required The OCM barcode IDs used to multiplex this sample. Must be one of OB1, OB2, OB3, OB4. If multiple OCM Barcodes were used for the same sample, you can separate IDs with a pipe (e.g., OB1 |
This [samples] option only applies to ** cell or sample hashing with Antibody Capture** data analysis.
| Field | Description |
|---|---|
hashtag_ids | Required The hashtag IDs used to multiplex this sample. If multiple antibody hashtags were used for the same sample, you can separate IDs with a pipe (e.g., ABHT-1 |
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 Flex data analysis.
| Field | Description |
|---|---|
probe_barcode_ids | Required. The Fixed RNA Probe Barcode IDs, Antibody Multiplexing Barcode IDs, and CRISPR Multiplexing Barcode IDs used in the experiment. 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 will automatically match to the corresponding Antibody Multiplexing Barcode. Barcode auto-pairing is disabled for CRISPR Guide Capture. All CRISPR Multiplexing Barcodes must be specified in the multi config CSV (e.g., BC001+CR001) If multiple Probe Barcodes were used for a sample, separate IDs with a pipe (e.g., BC001|BC002). |
emptydrops_minimum_umis | Optional. For multiplex Flex experiments, use this option to adjust the UMI cutoff during the second step of cell calling. Cell Ranger will still perform the full cell calling process but will only evaluate barcodes with UMIs above the threshold you specify. For example, setting this parameter to 100 will allow Cell Ranger to evaluate barcodes with more than 100 UMIs for cell calling. It is recommended to start with 100, but the optimal value may vary by sample, so trying different thresholds and evaluating results is advised. This option is available only in Cell Ranger v7.1.0 and later. emptydrops_minimum_umis cannot be used in combination with force-cells. See https://10xgen.com/scFFPE-cell-calling for details. See Gene Expression section to set emptydrops_min_umis for singleplex Flex experiments. |
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. May only include ASCII characters and exclude 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. |
Pages listed below detail the process for setting up a cellranger multi analysis for different assays.
- 3' Cell Multiplexing
- Flex
- 5' Gene Expression with V(D)J and Feature Barcode
- 5' Gene Expression with Antigen Capture (BEAM)
Refer to the list of examples below to find the most relevant one for your experiment.
- Singleplex Flex, 1 Probe Barcode
- Singleplex Flex with Antibody Capture, 1 Probe Barcode
- Multiplex Flex, multiple Probe Barcodes/sample
- Multiplex Flex, 1 Probe Barcode/sample
- Multiplex Flex with Antibody Capture, 1 barcode pair/sample
- Multiplex Flex with CRISPR, 1 barcode pair/sample
- Multiplex Flex, multiple Probe Barcodes with multiple CRISPR Guides (sub-pooled sample)
- Multiplex Flex with CRISPR and Antibody Capture, 1 Probe Barcode pair/sample