Once Cell Ranger is installed, you are ready to run the cellranger mkfastq pipeline. The cellranger mkfastq pipeline is a wrapper around Illumina’s bcl2fastq2 program for demultiplexing Illumina base call files (BCL). This means that bcl2fastq2 (version 2.20) is a dependency for this pipeline. As the bcl2fastq2 program is not bundled with Cell Ranger, see this Q&A article for installation guidance.
We will call our working directory the yard. First make a directory in the /yard to run the analysis.
mkdir ~/yard/run_cellranger_mkfastq
cd ~/yard/run_cellranger_mkfastq
For this tutorial, we use the tiny BCL dataset. This dataset is solely designed to demo the cellranger mkfastq pipeline. It cannot be used to run downstream pipelines (e.g., cellranger count).
We use the wget command to download the Illumina run directory and the simple sample sheet.
wget https://cf.10xgenomics.com/supp/cell-exp/cellranger-tiny-bcl-1.2.0.tar.gz
wget https://cf.10xgenomics.com/supp/cell-exp/cellranger-tiny-bcl-simple-1.2.0.csv
tar -zxvf cellranger-tiny-bcl-1.2.0.tar.gz
Before building the cellranger mkfastq command, look closer at these files. Use the command cat (for "concatenate") to print the sample sheet to the screen.
cat cellranger-tiny-bcl-simple-1.2.0.csv
The output looks like this:
Lane,Sample,Index
1,test_sample,SI-P03-C9
This file tells the pipeline that the library "test_sample" was sequenced on lane 1 of the flow cell and indexed using the SI-P03-C9 index set. The Sample column is used as the prefix for naming output files. This prefix also serves as the sample id in later Cell Ranger pipelines. In this case the prefix/sample id is test_sample.
The run directory has the following directory structure. Use the tree command to print the directory structure to the screen.
tree -L 2 cellranger-tiny-bcl-1.2.0/
The output will look something like this:
cellranger-tiny-bcl-1.2.0
├── Config
│ ├── h35kcbcxy_Oct-20-16\ 15-51-48_Effective.cfg
│ ├── HiSeqControlSoftware.Options.cfg
│ ├── RTAStart.bat
│ └── Variability_HiSeq_C.bin
├── Data
│ └── Intensities
├── InterOp
│ ├── ControlMetricsOut.bin
│ ├── CorrectedIntMetricsOut.bin
│ ├── ErrorMetricsOut.bin
│ ├── ExtractionMetricsOut.bin
│ ├── ImageMetricsOut.bin
│ ├── QMetricsOut.bin
│ └── TileMetricsOut.bin
├── RTAComplete.txt
├── RunInfo.xml
└── runParameters.xml
Your data may look a little different than this depending on the sequencing instrument used. Looking at the first few levels of directories is a good way to check for completeness. If you do not see the RTAComplete.txt, RunInfo.xml, and runParameters.xml files, then it is likely that the pipeline will fail. If any of these files are missing, contact your sequencing provider and ask for the complete run directory.
If tree is not installed on your system, you can use ls to explore the run directory.
ls -altR cellranger-tiny-bcl-1.2.0/
Now that we have data in the working directory, you are ready to build the command to run cellranger mkfastq. When running any pipeline for the first time, it is helpful to run the command with the --help option to print the usage statement. This shows the proper command syntax, which flags are required or optional, and other necessary information to include.
cellranger mkfastq --help
The output looks similar to this:
/mnt/home/user.name/yard/apps/cellranger-7.2.0/bin
cellranger mkfastq (cellranger-7.2.0)
Copyright (c) 2021 10x Genomics, Inc. All rights reserved.
-------------------------------------------------------------------------------
Run Illumina demultiplexer on sample sheets that contain 10x-specific sample
index sets, and generate 10x-specific quality metrics after the demultiplex.
Any bcl2fastq argument will work (except a few that are set by the pipeline
to ensure proper trimming and sample indexing). The FASTQ output generated
will be the same as when running bcl2fastq directly.
...
Usage:
cellranger mkfastq --run=PATH [options]
cellranger mkfastq -h | --help | --version
Required:
--run=PATH Path of Illumina BCL run folder.
There are three arguments or inputs that are added to the cellranger mkfastq command: –-id, --run, and --csv.
- The
--idcan be anything. It is used by the pipeline to name the output directory that Cell Ranger is going to create to run in. This directory is called a pipestance, which is short for pipeline instance. - The
--runargument points to the Illumina run folder that contains the BCL files. - The
--csvargument is a comma-separated value (CSV) file that describes how samples were indexed on the Illumina flow cell.
Note on CSV files
The CSV file must be formatted as a text file, Unicode (UTF-8) (no BOM) with Unix line-feed (LF) end-of-line markers. Sometimes Microsoft Windows or Mac OS add extra characters to the ends of lines or text encoding. To avoid parsing errors in the pipeline software, text editing programs, such as nano or TextWrangler (Mac OS), are better for creating sample sheets than Microsoft Excel.
Next build the command line using the paths to these data and run it. Be sure to edit the --run and --csv file paths.
cellranger mkfastq --id=tutorial_walk_through \
--run=/mnt/home/user.name/yard/run_cellranger_mkfastq/cellranger-tiny-bcl-1.2.0 \
--csv=/mnt/home/user.name/yard/run_cellranger_mkfastq/cellranger-tiny-bcl-simple-1.2.0.csv
The output looks similar to this:
/mnt/home/user.name/yard/apps/cellranger-7.2.0/bin
cellranger mkfastq (cellranger-7.2.0)
Copyright (c) 2021 10x Genomics, Inc. All rights reserved.
-------------------------------------------------------------------------------
Martian Runtime - v4.0.6
...
Waiting 6 seconds for UI to do final refresh.
Pipestance completed successfully!
2022-01-04 15:05:08 Shutting down.
Saving pipestance info to "tutorial_walk_through/tutorial_walk_through.mri.tgz"
Run times vary based on the system resources, but it shouldn’t take more than a few minutes. Now go to the fastq_path directory.
cd /mnt/home/user.name/yard/run_cellranger_mkfastq/tutorial_walk_through/outs/fastq_path
ls -1
The output looks similar to this:
H35KCBCXY
Reports
Stats
Undetermined_S0_L001_I1_001.fastq.gz
Undetermined_S0_L001_R1_001.fastq.gz
Undetermined_S0_L001_R2_001.fastq.gz
The Undetermined FASTQ files here at this level contain sequences that were unable to be assigned to valid index.
Demultiplexed FASTQ files with valid sequencing indices are found under the directory named after the flow cell id, in this case H35KCBCXY.
ls -1 H35KCBCXY/test_sample
The output looks similar to this:
test_sample_S1_L001_I1_001.fastq.gz
test_sample_S1_L001_R1_001.fastq.gz
test_sample_S1_L001_R2_001.fastq.gz
These outputs from the cellranger mkfastq pipeline serve as input to the cellranger count pipeline described in Running cellranger count.