Space Ranger1.3, printed on 05/28/2023
The Illumina NovaSeq control software v1.8 upgrade affects the ability of spaceranger mkfastq to autodetect the i5 (Index 2) orientation due to Illumina's reagent name changes in the recipe XML file. This results in all reads going into |
The spaceranger workflow starts by demultiplexing the Illumina sequencer's base call files (BCLs) for each flowcell directory into FASTQ files. 10x has developed spaceranger mkfastq, a pipeline that wraps Illumina's
bcl2fastq and provides a number of convenient features in addition to the features of
bcl2fastqarguments, such as
In this example, there are two 10x libraries (each processed through a separate capture area) that are multiplexed on a single flowcell. Note that after running spaceranger mkfastq, we run a separate instance of the pipeline on each library.
In this example, one 10x library is sequenced on two flowcells. Note that after running spaceranger mkfastq, we run a single instance of the pipeline on all the FASTQ files generated.
spaceranger mkfastq accepts additional options beyond those shown in the table below because it is a wrapper around
bcl2fastq. Consult the User Guide for Illumina's
bcl2fastq for more information.
|--run||(Required) The path of Illumina BCL run folder.|
|--id||(Optional; defaults to the name of the flowcell referred to by |
|--samplesheet||(Optional) Path to an Illumina Experiment Manager-compatible sample sheet which contains 10x sample dual-index names (e.g., SI-TT-A12) in the sample index column. All other information, such as sample names and lanes, should be in the sample sheet.|
|--sample-sheet||(Optional) Equivalent to --samplesheet above.|
|--csv||(Optional) Path to a simple CSV with lane, sample, and index columns, which describe the way to demultiplex the flowcell. The index column should contain a 10x sample dual-index name (e.g., SI-TT-A12). This is an alternative to the Illumina IEM sample sheet, and will be ignored if |
|--simple-csv||(Optional) Equivalent to --csv above.|
|--filter-dual-index||(Optional) 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. Also notice that spaceranger will run single-index data, but it is not supported.|
|--lanes||(bcl2fastq option) Comma-delimited series of lanes to demultiplex (e.g. 1,3). Use this if you have a sample sheet for an entire flowcell but only want to generate a few lanes for further 10x analysis.|
|--use-bases-mask||(bcl2fastq option) Same meaning as for |
|--delete-undetermined||(bcl2fastq option) Delete the |
|--output-dir||(bcl2fastq option) Generate FASTQ output in a path of your own choosing, instead of |
|--project||(bcl2fastq option) Custom project name, to override the samplesheet or to use in conjunction with the |
|--jobmode||(Martian option) Job manager to use. Valid options: |
|--localcores||(Martian option) Set max cores the pipeline may request at one time. Only applies when |
|--localmem||(Martian option) Set max GB the pipeline may request at one time. Only applies when |
spaceranger mkfastq recognizes two file formats for describing samples: a simple, three-column CSV format, and the Illumina Experiment Manager (IEM) sample sheet format used by
bcl2fastq. There is an example below for running mkfastq with each format.
The example (tiny-bcl) dataset is solely designed to demo the spaceranger mkfastq pipeline. It cannot be used to run downstream pipelines (e.g. spaceranger count).
To follow along, do the following:
A simple csv samplesheet is recommended for most sequencing experiments. The simple csv format has only three columns (Lane, Sample, Index), and is thus less prone to formatting errors. You can see an example of this in
Here are the options for each column:
|Lane||Which lane(s) of the flowcell to process. Can be either a single lane, a range (e.g., 2-4) or '*' for all lanes in the flowcell.|
|Sample||The name of the sample. This name is the prefix to all the generated FASTQs, and corresponds to the |
Sample names must conform to the Illumina
|Index||The 10x sample dual-index that was used in library construction, e.g., SI-TT-D9.|
mkfastq with a simple layout CSV, use the
Here's how to run
mkfastq on the
tiny-bcl sequencing run with the simple layout (replace code in red with the path to
tiny_bcl on your system):
$ spaceranger mkfastq --id=tiny-bcl \ --run=/path/to/tiny_bcl\ --csv=spaceranger-tiny-bcl-simple-1.0.0.csv spaceranger mkfastq Copyright (c) 2019 10x Genomics, Inc. All rights reserved. ------------------------------------------------------------------------------- Martian Runtime - 1.3.1-4.0.5 Running preflight checks (please wait)... 2019-11-14 16:33:54 [runtime] (ready) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET 2019-11-14 16:33:57 [runtime] (split_complete) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET 2019-11-14 16:33:57 [runtime] (run:local) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET.fork0.chnk0.main 2019-11-14 16:34:00 [runtime] (chunks_complete) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET ...
The spaceranger mkfastq pipeline can also be run with a samplesheet in the Illumina Experiment Manager (IEM) format. If you didn't sequence with sample indices, you'll need to use this format. Briefly look at
spaceranger-tiny-bcl-samplesheet-1.0.0.csv before running the pipeline. You
will see a number of fields specific to running on Illumina platforms, and then a [Data] section. That section is where you put your sample, lane and index information. Here's an example:
[Data] Lane,Sample_ID,Sample_Name,Sample_Plate,Sample_Well,I7_Index_ID,index,I5_Index_ID,index2,Sample_Project,Description 1,s1,test_sample,,,SI-TT-D9,SI-TT-D9,SI-TT-D9,SI-TT-D9,p1,
Here, SI-TT-D9 refers to a 10x sample dual-index.
In this example, only reads from lane 1 will be used. To demultiplex the given sample index across all lanes, omit the lanes column entirely.
Sample names must conform to the Illumina
bcl2fastq naming requirements. Specifcally only letters, numbers, underscores and hyphens area allowed. No other symbols, including dots (.) are allowed.
Also note that while an authentic IEM sample sheet will contain other sections above the [Data] section, these are optional for demultiplexing. For demultiplexing an existing run with spaceranger mkfastq, only the [Data] section is required.
Next, run the spaceranger mkfastq pipeline, using the --samplesheet
argument (replace code in red with the path to
tiny_bcl on your system):
$ spaceranger mkfastq --id=tiny-bcl \ --run=/path/to/tiny_bcl \ --samplesheet=spaceranger-tiny-bcl-samplesheet-1.0.0.csv spaceranger mkfastq Copyright (c) 2019 10x Genomics, Inc. All rights reserved. ------------------------------------------------------------------------------- Martian Runtime - 1.3.1-4.0.5 Running preflight checks (please wait)... 2019-11-14 16:35:49 [runtime] (ready) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET 2019-11-14 16:35:52 [runtime] (split_complete) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET 2019-11-14 16:35:52 [runtime] (run:local) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET.fork0.chnk0.main 2019-11-14 16:35:58 [runtime] (chunks_complete) ID.tiny-bcl.MAKE_FASTQS_CS.MAKE_FASTQS.PREPARE_SAMPLESHEET ...
If you encounter any preflight errors, refer to the Troubleshooting page.
Once the spaceranger mkfastq pipeline has successfully completed, the output can be found in a new folder named with the value you provided to spaceranger mkfastq in the
--id option (if not specified, defaults to the name of the flowcell):
$ ls -l drwxr-xr-x 4 jdoe jdoe 4096 Nov 14 12:05 tiny-bcl
The key output files can be found in
outs/fastq_path, and are organized
in the same manner as a conventional
$ ls -l tiny-bcl/outs/fastq_path/ drwxr-xr-x 3 jdoe jdoe 3 Nov 14 12:26 Reports drwxr-xr-x 2 jdoe jdoe 8 Nov 14 12:26 Stats drwxr-xr-x 3 jdoe jdoe 3 Nov 14 12:26 tiny-bcl -rw-r--r-- 1 jdoe jdoe 20615106 Nov 14 12:26 Undetermined_S0_L001_I1_001.fastq.gz -rw-r--r-- 1 jdoe jdoe 51499694 Nov 14 12:26 Undetermined_S0_L001_R1_001.fastq.gz -rw-r--r-- 1 jdoe jdoe 152692701 Nov 14 12:26 Undetermined_S0_L001_R2_001.fastq.gz $ tree tiny-bcl/outs/fastq_path/tiny_bcl/ tiny-bcl/outs/fastq_path/tiny_bcl/ Sample1 Sample1_S1_L001_I1_001.fastq.gz Sample1_S1_L001_R1_001.fastq.gz Sample1_S1_L001_R2_001.fastq.gz
This example was produced with a sample sheet that included "tiny-bcl" as the Sample_Project, so the directory containing the sample folders is named tiny-bcl. If a Sample_Project wasn't specified, or if a simple layout CSV file was used (which does not have a Sample_Project column), the directory containing the sample folders would be named according to the flow cell ID instead.
If you want to remove the
Undetermined FASTQs from the output to save space, you can run
--delete-undetermined flag. To see all spaceranger mkfastq options, run spaceranger mkfastq --help.
If you encounter a crash while running spaceranger mkfastq, upload the tarball (with the extension .mri.tgz) in your output directory:
spaceranger upload [email protected] jobid.mri.tgz
where jobid is what you input into the --id option of mkfastq (if not specified, defaults to the ID of the flowcell). This tarball contains numerous diagnostic logs that we can use for debugging.
You will receive an automated email from 10x Genomics. If not, email [email protected] For the fastest service, respond with the following: