10x Genomics Support/Cell Ranger 7.2/

Cell Ranger Command Line Arguments (Manual Page)

For a list of subcommands, run cellranger --help. Command line options for each pipeline are divided into arguments and flags. An argument requires an input whereas a flag must not be supplied an input. The Martian runtime arguments and flags are available to all the subcommands.

Usage:

cellranger count --help cellranger count [OPTIONS] --id <ID> --transcriptome <PATH>
ArgumentDescription
--idRequired. A unique run ID string (e.g., sample345). The name is arbitrary and will be used to name the directory containing all pipeline-generated files and outputs. Only letters, numbers, underscores, and hyphens are allowed (maximum of 64 characters).
--output-dirOptional. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: /path/to/<custom name>/outs/. If excluded, the outputs are directed to the default path: /path/to/ID/outs/.
--descriptionOptional. Sample description to embed in output files.
--transcriptomeRequired. Path of folder containing 10x-compatible transcriptome reference.
--fastqsRequired.
- EITHER - Path of the fastq_path folder generated by FASTQ generation software: cellranger mkfastq/ bcl2fastq / bcl-convert e.g. /home/jdoe/runs/HAWT7ADXX/outs/fastq_path. This contains a directory hierarchy that cellranger count will automatically traverse.
- OR - Any folder containing FASTQ files, for example if the FASTQ files were generated by a service provider and delivered outside the context of the mkfastq output directory structure.

Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flow cells. 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 count on them individually, and then combine them with cellranger aggr. This argument cannot be used when performing Feature Barcode analysis; use --libraries instead.
--projectOptional. Name of the project folder within a mkfastq, bcl2fastq, or bcl-convert-generated folder from which to pick FASTQs.
--sampleRequired. Sample name as specified in the sample sheet supplied to the FASTQ generation software (cellranger mkfastq/ bcl2fastq / bcl-convert). Can take multiple comma-separated values, which is helpful if the same library was sequenced on multiple flow cells with different sample names, which therefore have different FASTQ file prefixes. 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 count on them individually, and then combine them with cellranger aggr. Allowable characters in sample names are letters, numbers, hyphens, and underscores.
--lanesOptional. Only use FASTQs from selected lanes.
--librariesOptional. Path to a libraries.csv file declaring FASTQ paths and library types of input libraries. Required for gene expression + Feature Barcode analysis. When using this argument, --fastqs and --sample must not be used. This argument should not be used when performing gene expression-only analysis; use --fastqs instead.
--feature-refRequired for Feature Barcode analysis. Path to a Feature Reference CSV file declaring the Feature Barcode reagents used in the experiment.
--expect-cellsOptional. Override the pipeline’s auto-estimate. See cell calling algorithm for details on how this parameter is used. If used, enter the expected number of recovered cells.
--force-cellsOptional. Force pipeline to use this number of cells, bypassing the cell detection algorithm. Use this if the number of cells estimated by Cell Ranger is not consistent with the barcode rank plot.
--r1-lengthOptional. Limit the length of the input Read 1 sequence of Gene Expression (and any Feature Barcode) library 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 for Single Cell 3′ v2 or Single Cell 5′. This and --r2-length are useful options for determining the optimal read length for sequencing.
--r2-lengthOptional. Limit the length of the input R2 sequence to the first N bases, where N is a user-supplied value. Trimming occurs before sequencing metrics are computed and therefore, limiting R2 read length may affect Q30 scores (true, false).
--include-intronsOptional. Set to false to exclude intronic reads in count. Including introns in analysis is recommended to maximize sensitivity. Default: true.
--chemistryOptional. Assay configuration. NOTE: by default the assay configuration is detected automatically, which is the recommended mode. You should only specify chemistry if there is an error in automatic detection. Select one of:
auto for auto-detection (default),
threeprime for Single Cell 3′,
fiveprime for Single Cell 5′,
SC3Pv2 for Single Cell 3′ v2,
SC3Pv3 for Single Cell 3′ v3,
SC3Pv3LT for Single Cell 3′ v3 LT,
SC3Pv3HT for Single Cell 3′ v3 HT,
SC5P-PE for Single Cell 5′ paired-end (both R1 and R2 are used for alignment),
SC5P-R2 for Single Cell 5′ R2-only (where only R2 is used for alignment).
SC3Pv1 for Single Cell 3′ v1. NOTE: this mode cannot be auto-detected. It must be set explicitly with this option.
ARC-v1 for analyzing the Gene Expression portion of Multiome data. NOTE: this mode cannot be auto-detected.
--check-library-compatibilityOptional. 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 (true, false; default: true).
--no-bamOptional. Add this option to skip BAM file generation. This will reduce the total computation time for the pipestance and the size of the output directory. If unsure, we recommend not using this option, as BAM files can be useful for troubleshooting and downstream analysis. (true, false; default: false).
--nosecondaryOptional. Disable secondary analysis, e.g. clustering (true, false).
-h, --helpPrint help information.
FlagDescription
--no-librariesOptional. Add this flag to proceed with processing data using a --feature-ref but no Feature Barcode data specified with the --libraries flag.

Usage:

cellranger multi --help cellranger multi [OPTIONS] --id <ID> --csv <CSV>
ArgumentDescription
--idRequired. A unique run id and output folder name [a-zA-Z0-9_-]+
--csvRequired. Path of CSV file enumerating input libraries and analysis parameters. See sections below.
--output-dirOptional. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: /path/to/<custom name>/outs/. If excluded, the outputs are directed to the default path: /path/to/ID/outs/.
--descriptionOptional. Sample description to embed in output files.
-h, --helpPrint help information.

Go to this page to view all config CSV options for supported library types.

Usage:

Cell Ranger v7.1 and later enable users to download a multi config CSV template by running:

cellranger multi-template --output=/path/to/FILE.csv

Customize the path to the directory in which you wish to output the template. Omitting the file path downloads the file into your working directory. After downloading, please remember to customize the template based on your assay and experimental design.

To print a list and description of all configurable parameters available in cellranger multi, run

cellranger multi-template --parameters

Run cellranger multi-template --help or cellranger multi-template -h for more information about available options.

cellranger multi-template --help cellranger multi-template [OPTIONS]
FieldDescription
-o, --outputOptional. Output file path.
-p, --parametersPrint multi config parameter options and descriptions.
-h, --helpPrint help information.

Usage:

cellranger vdj --help cellranger vdj [OPTIONS] --id <ID> --fastqs <PATH>
ArgumentDescription
--idRequired. A unique run ID string: e.g. sample345.
--output-dirOptional. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: /path/to/<custom name>/outs/. If excluded, the outputs are directed to the default path: /path/to/ID/outs/.
--descriptionOptional. Sample description to embed in output files.
--fastqsRequired. Path of the FASTQ folder generated by the FASTQ generation software (cellranger mkfastq/ bcl2fastq / bcl-convert) e.g. /home/jdoe/runs/HAWT7ADXX/outs/fastq_path. Can take multiple comma-separated paths, which is helpful if the same library was sequenced on multiple flowcells. Doing this will treat all reads from the library, across flowcells, as one sample.
--referenceRequired. Path to the cellranger vdj compatible reference e.g. /opt/refdata-cellranger-vdj-GRCh38-alts-ensembl-7.1.0. If --denovo is specified, this parameter is optional.
--sampleRequired. Sample name as specified in the sample sheet supplied to the FASTQ generation software (cellranger mkfastq/ bcl2fastq / bcl-convert). Can take multiple comma-separated values, which is helpful if the sample was sequenced on multiple flowcells and the sample name used (and therefore fastq file prefix) is not identical between them. Doing this will treat all reads from the library, across flowcells, as one sample.
--projectOptional. Name of the project folder within a mkfastq, bcl-convert, or bcl2fastq-generated folder to pick FASTQs from.
--inner-enrichment-primersOptional. This argument takes a .txt file containing primer sequences that were used to enrich cDNA for V(D)J sequences. The primers must be listed one per line. If two sets of primers were used for amplification, the .txt file must contain only the innermost reverse PCR primers that are complementary to the constant region. An example .txt file for human TCR dataset would have these lines:
AGTCTCTCAGCTGGTACACG
TCTGATGGCTCAAACACAGC
The --inner-enrichment-primers option is typically used for species other than human or mouse for which primers are not provided by 10x Genomics, Inc. All the provided primers may be found in the appendix section of this document.
--localcoresOptional. Restricts cellranger to use the specified number of cores to execute pipeline stages. By default, cellranger will use all of the cores available on your system.
--localmemOptional. Restricts cellranger to use the specified amount of memory (in GB) to execute pipeline stages. By default, cellranger will use 90% of the memory available on your system.
--lanesOptional. Lanes associated with this sample.
--chainOptional. Force the analysis to be carried out for a particular chain type. The accepted values are:
auto for autodetection based on TR vs IG representation (default),
TR for T cell receptors,
IG for B cell receptors,
Use this in rare cases when automatic chain detection fails.
--sampleOptional. Prefix of the filenames of FASTQs to select.
-h, --helpPrint help information.
FlagDescription
--denovoOptional. If specified, this flag prevents the use of V(D)J reference during the assembly process. --reference is optional. If --denovo is specified and --reference is not, the --inner_enrichment_primers argument is required. The --denovo option is most useful for full de novo assembly without a V(D)J reference. If you have a V(D)J reference, using --denovo will yield similar but slightly degraded results.

Usage:

cellranger aggr --help cellranger aggr [OPTIONS] --id <ID> --csv <CSV>
ArgumentDescription
--idRequired. A unique run ID string: e.g. AGG123
--output-dirOptional. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: /path/to/<custom name>/outs/. If excluded, the outputs are directed to the default path: /path/to/ID/outs/.
--descriptionOptional. Sample description to embed in output files.
--csvRequired. Path of CSV file enumerating 'cellranger count/vdj/multi' outputs.
--normalizeOptional. String specifying how to normalize depth across the input libraries. Valid values: mapped (default) or none (see Depth Normalization).
--nosecondaryOptional. Add this argument to skip secondary analysis which includes dimensionality reduction, clustering, and visualization. This is applicable if you plan to use cellranger reanalyze or your own custom analysis (true, false).
-h, --helpPrint help information.

Usage:

cellranger reanalyze --help cellranger reanalyze [OPTIONS] --id <ID> --matrix <MATRIX_H5>
ArgumentDescription
--idRequired. A unique run ID string: e.g. AGG123_reanalysis
--descriptionOptional. Sample description to embed in output files.
--matrix=H5Required. Path to a filtered_feature_bc_matrix.h5 or raw_feature_bc_matrix.h5, or sample_filtered_feature_bc_matrix.h5 from a completed pipestance (from either cellranger count, cellranger multi, or cellranger aggr). Use the raw_feature_bc_matrix.h5 when specifying a value for --force-cells that exceeds the original cell count.
--paramsOptional. Path to a CSV file containing a list of valid parameters and the values to use for them (see Parameters).
--barcodesOptional. Path to a file containing a list of barcodes (one barcode per line) to use for reanalysis. The first line of file must be a header called Barcode. Header is case sensitive. All barcodes must be present in the matrix.
--genesOptional. Path to a file containing a list of gene IDs (one gene ID per line) to use for reanalysis (corresponding to the gene_id field of the reference GTF). The first line of the genes file must be a header called Gene. Header is case sensitive. All gene IDs included in the list must be present in the matrix. Only gene features are used in the secondary analysis. Feature Barcode features are ignored. An example gene.txt supplied to this argument:
Gene
ENSG00000243485
ENSG00000237613
ENSG00000186092
ENSG00000238009
ENSG00000239945
ENSG00000239906
ENSG00000241599
ENSG00000236601
ENSG00000284733
ENSG00000235146
ENSG00000284662
--exclude-genesOptional. Path to a file containing a list of gene IDs (one gene ID per line) to exclude for reanalysis (corresponding to the gene_id field of the reference GTF). All gene IDs must be present in the matrix. The first line of the genes file must be a header called Gene. The exclusion can be applied with or without the --genes list. When a --genes list is supplied, --exclude-genes searches within the supplied list for exclusion. Note that only gene features are used in secondary analysis. Feature Barcode features are ignored.
--aggOptional. Path to a CSV file that was used for cellranger aggr. This allows you to retain any metadata associated with the samples for display in Loupe Browser. This argument is required if you want to enable Chemistry Batch Correction in your reanalysis.
--force-cellsOptional. Force pipeline to use this number of cells, bypassing the cell detection algorithm. Use this if the number of cells estimated by Cell Ranger is not consistent with the barcode rank plot. If specifying a value that exceeds the original cell count, you must use the raw_feature_bc_matrices_h5.h5. Starting with Cell Ranger 6.1, it is no longer possible to run --force-cells of an aggr output in reanalyze with more cells than were originally called.
-h, --helpPrint help information.

Usage:

cellranger mkfastq --help cellranger mkfastq --run=PATH [options]
ArgumentDescription
--runRequired. The path of Illumina BCL run folder.
--idOptional. Defaults to the name of the flow cell referred to by --run. Name of the folder created by mkfastq. This option does not accept a full directory path. If used, navigate to the specified directory first and then run mkfastq.
--samplesheetOptional. Path to an Illumina Experiment Manager-compatible sample sheet which contains 10x Genomics sample index names (e.g., SI-GA-A1 or SI-TT-A12) in the sample index column. All other information, such as sample names and lanes, should be in the sample sheet.
--sample-sheetOptional. Equivalent to --samplesheet above.
--simple-csvDeprecated. Equivalent to --csv.
--force-single-indexOptional. If 10x-supplied i7/i5 paired indices are specified, but the flowcell was run with only one sample index, allow the demultiplex to proceed using the i7 half of the sample index pair.
--filter-single-indexOptional. Only demultiplex samples identified by an i7-only sample index, ignoring dual-indexed samples. Dual-indexed samples will not be demultiplexed.
--filter-dual-indexOptional. Only demultiplex samples identified by i7/i5 dual-indices (e.g., SI-TT-A6), ignoring single-index samples. Single-index samples will not be demultiplexed.
--rc-i2-overrideOptional. Indicates if the bases in the I2 read are emitted as reverse complement by the sequencing workflow. Set to 'true' for the Reverse Complement Workflow (Workflow B)/ NovaSeq Reagent Kit v1.5 or greater. Set to 'false' for the Forward Strand Workflow (Workflow A) / older NovaSeq Reagent Kits.NOTE: this parameter is autodetected and should only be passed in special circumstances.
--lanesbcl2fastq option. Comma-delimited series of lanes to demultiplex. Shortcut for the --tiles argument.
--use-bases-maskbcl2fastq option. Same as bcl2fastq; override the read lengths as specified in RunInfo.xml. See Illumina bcl2fastq documentation for more information.
--delete-undeterminedbcl2fastq option. Delete the Undetermined FASTQs generated by bcl2fastq. Useful if you are demultiplexing a small number of samples from a large flow cell.
--output-dirbcl2fastq option. Same as in bcl2fastq. Generate FASTQ output in a path of your own choosing, instead of flowcell_id/outs/fastq_path.
--projectbcl2fastq option. Custom project name, to override the samplesheet or to use in conjunction with the --csv argument.
-h, --helpShow this message.
--versionShow version.

Usage:

cellranger mkref --help cellranger mkref --genome=NAME --fasta=PATH --genes=PATH [options]
ArgumentDescription
--genomeRequired. Unique genome name(s), used to name output folder [a-zA-Z0-9_-]+. Specify multiple genomes by specifying the --genome argument multiple times; the output folder will be <name1>_and_<name2>.
--fastaRequired. Path(s) to FASTA file containing your genome reference. Specify multiple genomes by specifying the --fasta argument multiple times.
--genesRequired. Path(s) to genes GTF file(S) containing annotated genes for your genome reference. Specify multiple genomes by specifying the --genes argument multiple times.
--output-dirOptional. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: /path/to/<custom name>/outs/. If excluded, the outputs are directed to the default path: /path/to/ID/outs/.
--memgbRequired. Maximum memory (GB) used during STAR genome index generation. Defaults to 16. Please note, the amount of memory specified must be greater than the number of gigabases in the input reference FASTA file.
--nthreadsOptional. Number of threads used during STAR genome index generation. Defaults to 1.
--ref-versionOptional. Reference version string to include with reference.
-h, --helpShow this message.

Usage:

cellranger mkgtf --help cellranger mkgtf <input_gtf> <output_gtf> [--attribute=KEY:VALUE...]
ArgumentDescription
--input_gtfRequired. Path to input genes GTF file.
--output_gtfRequired. Path to filtered output genes GTF file.
--attribute=<key:value>Key-value pair in attributes field to be kept in the GTF file.
-h, --helpShow this message.
--versionShow version.

Usage:

cellranger mkvdjref --help cellranger mkvdjref --genome=NAME --fasta=PATH --genes=PATH ...[options] cellranger mkvdjref --genome=NAME --seqs=PATH [options] cellranger mkvdjref -h | --help
ArgumentDescription
--genomeRequired. A unique genome name, used to name output folder [a-zA-Z0-9_-]+.
--fastaRequired. Path to FASTA file containing your genome reference.
--genesRequired. One or more GTF files containing annotated genes for your genome reference. Specify multiple files by specifying the --genes argument multiple times. The files will be concatenated.
--seqsOptional. A FASTA file that directly specifies V(D)J sequences. This is mutually exclusive with the the "fasta" and "genes" args above.
--output-dirOptional. Path to a custom output directory for storing the results of the run. When this argument is specified, the outputs are placed in the user designated directory, following the format: /path/to/<custom name>/outs/. If excluded, the outputs are directed to the default path: /path/to/ID/outs/.
--ref-versionOptional. Reference version string to include.
--rm-transcriptsOptional. Path to text file with transcript IDs to ignore. This file should have one transcript ID per line where the IDs correspond to the "transcript_id" key in the GTF info column.
-h, --helpShow this message.

Usage:

cellranger testrun --help cellranger testrun [OPTIONS] --id <ID>
ArgumentDescription
--idRequired. A unique run id and output folder name [a-zA-Z0-9_-]+.
--descriptionOptional. Sample description to embed in output files.
-h, --helpPrint help information.

Usage:

cellranger upload --help cellranger upload <your_email> <file>

Usage:

cellranger sitecheck --help sitecheck
ArgumentDescription
-h, --helpShow this message.
--versionShow version.

To use tarmri to generate a .mri.tgz file for a failed run, call tarmri and give it the path to the failed pipestance (run name specified by --id).

The .mri.tgz file contains a number of logs (including error messages, status reports, and information about the system) that are useful for troubleshooting failures. The .mri.tgz file does not contain sample data or analysis outputs.

Usage:

# Generate mri.tgz file for example analysis --id run1 cellranger-x.y.z/cellranger-cs/x.y.z/tenkit/bin/tarmri path/to/run1 # Share mri.tgz file with 10x Support cellranger upload <your email> <path to log.mri.tgz>

For Cell Ranger v3.1 and earlier, the script is located here: cellranger-x.y.z/cellranger-cs/x.y.z/tenkit/bin/tarmri

For Cell Ranger v4.0 and later, the script is located here: cellranger-x.y.z/bin/tenkit/tarmri

Usage:

cellranger mat2csv --help cellranger mat2csv <input_path> <output_csv> [--genome=GENOME]
ArgumentDescription
input_pathRequired. Path to a Cell Ranger feature-barcode matrix. Can be either a feature-barcode h5 file (recommended) or a path to a MEX Cell Ranger output folder.
output_csvRequired. Output CSV file.
--genome=GENOMERequired. Specify which genome to extract. This only applies to multi-genome h5 input files.
-h, --helpShow this message.
--versionShow version.

The Martian commands work the same as for other 10x Genomics pipelines (i.e., Xenium Ranger, Space Ranger).

ArgumentDescription
--jobmodeJob manager to use. Valid options: local (default), a cluster job mode (i.e., sge, lsf, slurm), or the path to a <jobmode>.template file.
--localcoresSet max cores the pipeline may request at one time. Only applies to local jobs.
--localmemSet max GB the pipeline may request at one time. Only applies to local jobs.
--localvmemSet max virtual address space in GB for the pipeline. Only applies to local jobs.
--mempercoreReserve enough threads for each job to ensure enough memory will be available, assuming each core on your cluster has at least this much memory available. Only applies to cluster jobmodes.
--maxjobsSet max jobs submitted to the cluster at one time. Only applies in cluster jobmodes.
--jobintervalSet delay between submitting jobs to cluster, in ms. Only applies in cluster jobmodes.
--overridesThe path to a JSON file that specifies stage-level overrides for cores and memory. Finer-grained than --localcores, --mempercore and --localmem. Contact support for an example override file.
--uiportThe port to serve web UI at: http://localhost:PORT
--disable-uiBoolean to determine whether to serve the web UI (true, false).
--noexitBoolean to keep web UI running after pipestance completes or fails (true, false).
--nopreflightSpecify the preflight check(s) to skip.
FlagDescription
--dryDo not execute the pipeline. Generate a pipeline invocation (.mro) file and stop.