HOME  ›   pipelines
If your question is not answered here, please email us at:  ${email.software}

Cell Ranger


Loupe

10x Genomics
Chromium Single Cell Immune Profiling

Direct Demultiplexing with Illumina Software

Overview

There are three options for generating FASTQ files from BCL files, all of which work for 10x Genomics Chromium libraries:

Illumina's software may provide greater control over demultiplexing parameters.

Demultiplexing Chromium data with Illumina's BCL Convert or bcl2fastq software requires the correct specification of the sample sheet and command line options. This guide will walk you through generating Cell Ranger-compatible FASTQs with BCL Convert and bcl2fastq.

Indexing design

Dual indexing

This section describes how to configure bcl2fastq or bcl-convert for libraries created with the dual indexing kits.

These are unique dual-indexing sample indices. This means there is a unique sample index barcode in both the i7 and i5 index reads (also known as I1 and I2). When demultiplexing flow cells where both index reads have been sequenced, bcl2fastq and bcl-convert require that both index sequences match the expected sequence for a read to be assigned to that sample. This solves the "index hopping" issue present on Illumina patterned flow cell sequencers.

Download the dual index kit sample index reference files at these links:

Kit Library
Dual Index Kit TT, Set A
  • 3' Gene Expression
  • 5' Gene Expression/VDJ/CRISPR Guide Capture
  • Fixed RNA Profiling Antibody Capture
  • Dual Index Kit NT, Set A 3' Antibody/CRISPR Guide Capture
    Dual Index Kit TN, Set A 5' Antibody Capture
    Dual Index Kit NN, Set A 3' Cell Multiplexing
    Dual Index Kit TS, Set A Fixed RNA Profiling Gene Expression

    The index sequence in the sample index reference file should be entered into the index column of the bcl2fastq or bcl-convert sample sheet.

    Either the index2_workflow_a or index2_workflow_b sequence should be entered into the index2 column of the bcl2fastq sample sheet, depending on the sequencing instrument used (more information here):

    More information about dual indexing is available in the Illumina Indexed Sequencing Overview Guide.

    Single indexing

    This section describes how to configure bcl2fastq and bcl-convert for libraries created with single indexing kits. Download the single index kit sample index reference files at these links:

    There is a key difference to keep in mind when creating single index sample sheets for a Chromium run. Each Chromium sample index set is actually a blend of four different sequence oligos, and each oligo must be represented as a separate row in the sample sheet. This means that for every sample being demultiplexed from the flow cell, there should be four lines in the sample sheet.

    Select a tab for information about running bcl2fastq or bcl-convert:


    Demultiplexing with bcl2fastq

    Download and install bcl2fastq

    The bcl2fastq software is available for download and installation on the Illumina support website as an RPM package. An Illumina account is required for download. Please contact Illumina Support if you have questions about bcl2fastq versions, or for help troubleshooting its download and installation.

    Creating the sample sheet

    You will need to create a sample sheet in order to get bcl2fastq to correctly embed the names of samples into output FASTQ files. When you plan an experiment, you should know the name of the sample index set used for each sample, which comes from the reagent kit (such as "SI-TT-A1" for dual index or "SI-GA-A1" for single index).

    The Illumina Experiment Manager can also be used to create sample sheets for use with bcl2fastq.

    Dual index sample sheet

    For each sample, enter its lane, sample name, and sample index set into the Illumina bcl2fastq sample sheet. Here is an example using "SI-TT-A1" indices for i7 and index2_workflow_b i5:

    [Data]
    Lane,Sample_ID,index,index2
    1,s1,GTAACATGCG,AGGTAACACT

    Single index sample sheet

    For each sample, enter its lane, sample name, and set of four sample indices into the Illumina bcl2fastq sample sheet. Here is an example using "SI-GA-A1" indices:

    [Data]
    Lane,Sample_ID,index
    1,sample1,GGTTTACT
    1,sample1,CTAAACGG
    1,sample1,TCGGCGTC
    1,sample1,AACCGTAA
    

    If you are only running a single sample in a lane, then you can enter a single line with a blank index, although bcl2fastq will include reads associated with any sample index.

    Running bcl2fastq

    Illumina bcl2fastq must be called with the correct --use-bases-mask argument, and other arguments, in order to properly demultiplex and output FASTQs for all the reads in a Chromium library.

    In the examples below, ${FLOWCELL_DIR} is the directory that contains a flow cell's Data/ folder, ${OUTPUT_DIR} is the directory that you want to output FASTQs to, and ${SAMPLE_SHEET_PATH} is the path to the sample sheet CSV you created.

    For bcl2fastq2 v2.20, these are the most common command line formats for sequencers running RTA 1.18.54 and higher for either dual or single index kits:

    • Dual index demultiplexing (edit the file paths for your data):
    SAMPLE_SHEET_PATH=/path/to/sample/sheet/csv
    OUTPUT_DIR=/path/to/save/outputs
    FLOWCELL_DIR=/path/to/input/BCL/files
    INTEROP_DIR=./stats
     
    bcl2fastq --use-bases-mask=Y28,I10,I10,Y91 \
      --create-fastq-for-index-reads \
      --minimum-trimmed-read-length=8 \
      --mask-short-adapter-reads=8 \
      --ignore-missing-positions \
      --ignore-missing-controls \
      --ignore-missing-filter \
      --ignore-missing-bcls \
      -r 6 -w 6 \
      -R ${FLOWCELL_DIR} \
      --output-dir=${OUTPUT_DIR} \
      --interop-dir=${INTEROP_DIR} \
      --sample-sheet=${SAMPLE_SHEET_PATH}
    
    • Single index demultiplexing (edit the file paths for your data):
    SAMPLE_SHEET_PATH=/path/to/sample/sheet/csv
    OUTPUT_DIR=/path/to/save/outputs
    FLOWCELL_DIR=/path/to/input/BCL/files
    INTEROP_DIR=./stats
     
    bcl2fastq --use-bases-mask=Y26,I8,Y98 \
      --create-fastq-for-index-reads \
      --minimum-trimmed-read-length=8 \
      --mask-short-adapter-reads=8 \
      --ignore-missing-positions \
      --ignore-missing-controls \
      --ignore-missing-filter \
      --ignore-missing-bcls \
      -r 6 -w 6 \
      -R ${FLOWCELL_DIR} \
      --output-dir=${OUTPUT_DIR} \
      --interop-dir=${INTEROP_DIR} \
      --sample-sheet=${SAMPLE_SHEET_PATH}

    To limit bcl2fastq to a subset of lanes, supply values to the --tiles argument.

    Omitting extra bases from reads

    If you add extra bases to a sample index read, you will need to account for this in the --use-bases-mask argument. For example, if you ran a sample index read with nine bases, you will need to truncate the last base in order for Cell Ranger to run correctly.

    You can exclude a single base by adding a single n character to the read argument, or adding n* to exclude all bases after a certain position. See below:

    Read Desired Actual Argument
    i7 Index Read (I1) 8 9 I8n

    Output FASTQs

    A new folder is created (name specified by the --output-dir flag). This folder contains the FASTQ file sets, statistics, and reports.

    Example dataset

    A convenient way to test bcl2fastq is by downloading the tiny-BCL-data example dataset. This dual-indexed iSeq dataset has been selected for its small size (541 MB). The example below is applicable to 3' Single Cell Gene Expression, 5' Immune Profiling, Fixed RNA Profiling, and Visium libraries processed with the TT Set A dual index kit. It should not be used to run downstream pipelines (e.g. cellranger count).

    To follow along:

    tar -xf /working-directory/iseq-DI.tar.gz
    

    Run bcl2fastq (remember to customize the /working-directory/ path with the path to your input/output directory):

    SAMPLE_SHEET_PATH=/working-directory/bcl2fastq_samplesheet.csv
    OUTPUT_DIR=/working-directory/tiny-FASTQs
    FLOWCELL_DIR=/working-directory/iseq-DI
    INTEROP_DIR=/working-directory/stats
     
    bcl2fastq --use-bases-mask=Y28,I10,I10,Y91 \
      --create-fastq-for-index-reads \
      --minimum-trimmed-read-length=8 \
      --mask-short-adapter-reads=8 \
      --ignore-missing-positions \
      --ignore-missing-controls \
      --ignore-missing-filter \
      --ignore-missing-bcls \
      -r 6 -w 6 \
      -R ${FLOWCELL_DIR} \
      --output-dir=${OUTPUT_DIR} \
      --interop-dir=${INTEROP_DIR} \
      --sample-sheet=${SAMPLE_SHEET_PATH}
    

    A folder called tiny-FASTQs is created in the working directory. This folder contains your newly created FASTQ files.

    tiny-FASTQs/
    ├── Reports
    │   └── html
    ├── Stats
    │   ├── AdapterTrimming.txt
    │   ├── ConversionStats.xml
    │   ├── DemultiplexingStats.xml
    │   ├── DemuxSummaryF1L1.txt
    │   ├── FastqSummaryF1L1.txt
    │   └── Stats.json
    ├── iseq-DI_S1_L001_I1_001.fastq.gz
    ├── iseq-DI_S1_L001_I2_001.fastq.gz
    ├── iseq-DI_S1_L001_R1_001.fastq.gz
    ├── iseq-DI_S1_L001_R2_001.fastq.gz
    ├── Undetermined_S0_L001_I1_001.fastq.gz
    ├── Undetermined_S0_L001_I2_001.fastq.gz
    ├── Undetermined_S0_L001_R1_001.fastq.gz
    └── Undetermined_S0_L001_R2_001.fastq.gz
    

    Demultiplexing with BCL Convert

    Illumina's BCL Convert is another software application that converts BCL files into FASTQ files. This page explains how to use BCL Convert for 10x Genomics products and provides example sample sheets to use as inputs. In addition, there is a step-by-step guide with an example BCL dataset for generating FASTQs compatible with Cell Ranger.

    Download and install BCL Convert

    BCL Convert is available for download and installation on the Illumina support website as an RPM package. An Illumina account is required for download. Please contact Illumina Support if you have questions about BCL Convert versions, or need help troubleshooting its download and installation.

    Creating the sample sheet

    BCL Convert uses a sample sheet CSV file to specify sample information and parameters for a run, instead of command line options. For a full description of the sample sheet and list of settings, please see the Illumina documentation.

    The basic sample sheet has three sections. Each section is described here and example sample sheets are provided for both single and dual indexed samples.

    • [Header] can be used to specify the BCL sample sheet version.

    • [BCLConvert_Settings] in a V2 sample sheet, this section is used to specify several FASTQ conversion settings including whether or not to create FASTQ files for indices. Use [Settings] in a V1 sample sheet.

    • [BCLConvert_Data] in a V2 sample sheet, this section is used to sort samples and index adapters based on the following column headers. The [BCLConvert_Data] section must be renamed [Data] or [data] for a V1 sample sheet:

      Column name Description
      Lane Optional. Generates FASTQ files only for the samples with the specified lane number. Allows only one valid integer. If the same sample has been run on multiple lanes of the flow cell, add a new row for each lane. If the lane is not specified, indices are searched in all lanes.
      Sample_ID The sample ID
      index I7 index sequence
      index2 I5 index sequence
      Sample_Project Optional. Used when --bcl-sampleproject-subdirectories is specified in BCL Convert run. Only alphanumeric characters, dashes, and underscores are allowed. Logs or Reports should not be used as directory names for this flag, as they are already default output directories. Learn more.

    Dual index

    This section shows an example sample sheet for libraries created with the Dual Index Plate TT, Set A or Dual Index Plate TN, Set A. The parameter CreateFastqForIndexReads,0 under [BCLConvert_Settings] tells BCL Convert not to generate FASTQ files for indices. Cell Ranger does not require FASTQ files for indices.

    [Header]
    FileFormatVersion,2
     
    [BCLConvert_Settings]
    CreateFastqForIndexReads,0
     
    [BCLConvert_Data]
    Lane,Sample_ID,index,index2
    1,test_sample,GTAACATGCG,AGGTAACACT
    

    Single index

    This section shows an example sample sheet for libraries created with the Single Index Kit T Set A and Single Index Kit N Set A. Other parameters are the same as the dual index example above. Since lane is not specified in this example, indices are searched in all lanes.

    [Header]
    FileFormatVersion,2
     
    [BCLConvert_Settings]
    CreateFastqForIndexReads,0
     
    [BCLConvert_Data]
    Sample_ID,index
    Sample2_SI,GGTTTACT
    Sample2_SI,CTAAACGG
    Sample2_SI,TCGGCGTC
    Sample2_SI,AACCGTAA
    

    Running BCL Convert

    The command to run BCL Convert:

    path/to/binary/bcl-convert --bcl-input-directory <folder-with-bcls> \
     --output-directory <name-of-output-dir-for-FASTQs> \
     --sample-sheet <samplesheet-filename.csv>
    

    Required arguments:

    • --bcl-input-directory: path to the input directory containing BCL files
    • --output-directory: path to an output directory for newly created FASTQ files. This directory must not exist before command execution.
    • --sample-sheet: path to a CSV file containing sample information as described in the creating the sample sheet section. Providing a path to the directory instead of the specific CSV file can cause the software to hang.

    Output FASTQs

    A successful BCL Convert run looks like this:

    bcl-convert Version 00.000.000.3.10.5
    Copyright (c) 2014-2018 Illumina, Inc.
    Command Line: --bcl-input-directory iseq-DI --output-directory tiny-FASTQs --sample-sheet bcl_convert_samplesheet.csv
    # CPU hw threads available: 48
    Parallel Tiles: 1. Threads Per Tile: 48
    SW compressors: 48
    SW decompressors: 24
    Conversion Complete.
    

    A new folder is created (name specified by the --output-directory flag). This folder contains FASTQ file sets, one per sample. The folder also contains Logs and Reports sub-directories that contain the run logs and metrics output files respectively.

    Example dataset

    A convenient way to test BCL Convert is by downloading the iseq-DI example dataset. This dual-indexed iSeq dataset has been selected for its small size (541 MB). The example below applies to 3' Single Cell Gene Expression, 5' Immune Profiling, Fixed RNA Profiling, and Visium libraries processed with the TT Set A dual index kit. It should not be used to run downstream pipelines (e.g. cellranger count).

    To follow along:

    tar -xf /working-directory/iseq-DI.tar.gz
    

    Run BCL Convert:

    bcl-convert --bcl-input-directory /working-directory/iseq-DI \
    --output-directory /working-directory/tiny-FASTQs \
    --sample-sheet /working-directory/bcl_convert_samplesheet.csv
    

    Remember to customize the --bcl-input-directory path with the path to your input directory.

    A folder called tiny-FASTQs is created in the working directory. This folder contains your newly created FASTQ files.

    tiny-FASTQs/
    ├── Logs
    │   ├── Errors.log
    │   ├── FastqComplete.txt
    │   ├── Info.log
    │   └── Warnings.log
    ├── Reports
    │   ├── Adapter_Metrics.csv
    │   ├── Demultiplex_Stats.csv
    │   ├── fastq_list.csv
    │   ├── Index_Hopping_Counts.csv
    │   ├── IndexMetricsOut.bin
    │   ├── Quality_Metrics.csv
    │   ├── RunInfo.xml
    │   ├── SampleSheet.csv
    │   └── Top_Unknown_Barcodes.csv
    ├── iseq-DI_S1_L001_R1_001.fastq.gz
    ├── iseq-DI_S1_L001_R2_001.fastq.gz
    ├── Undetermined_S0_L001_R1_001.fastq.gz
    └── Undetermined_S0_L001_R2_001.fastq.gz
    

    Illumina support and documentation

    Please contact Illumina Support for general questions about BCL Convert. Or refer to BCL Convert documentation:


    Next steps

    Running Cell Ranger with converted FASTQ files

    After generating FASTQs, you are ready to run the cellranger count, cellranger vdj, or cellranger multi pipelines, depending on your data type and experimental design. Visit the Choosing Pipelines page to find the Cell Ranger pipeline relevant to your data: