This guide walks you through generating Space Ranger-compatible FASTQs with Illumina's BCL Convert software. Demultiplexing Visium data with BCL Convert requires the correct specification of the sample sheet and command line options.
All Visium libraries use dual index sets. This section describes how to configure BCL Convert for libraries created with these 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, BCL Convert requires 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 | Visium HD 3' Spatial Gene Expression, Visium Spatial Gene Expression |
| Dual Index Kit TS, Set A | Visium HD Spatial Gene Expression |
| Dual Index Kit TS, Set A | Visium CytAssist Spatial Gene Expression for FFPE |
| Dual Index Kit TS, Set A | Visium CytAssist Spatial Gene Expression for Fresh Frozen |
The index sequence in the sample index reference file should be entered into the index column of the BCL Convert sample sheet.
Either the index2_workflow_a or index2_workflow_b sequence should be entered into the index2 column of the sample sheet, depending on the sequencing instrument used (learn more here):
index2_workflow_a: NovaSeq™ 6000 v1, MiSeq™, MiniSeq™ with Rapid Reagent Kits, HiSeq™ 2500, and HiSeq™ 2000.index2_workflow_b: NovaSeq™ 6000 v1.5, iSeq™ 100, MiniSeq™ with Standard Reagent Kits, NextSeq™, HiSeq™ X, and HiSeq™ 3000/4000. More information about dual indexing is available in the Illumina Indexed Sequencing Overview Guide.
Illumina's BCL Convert software converts BCL files into FASTQ files. This page explains how to use BCL Convert for 10x Genomics Visium data 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 Space Ranger.
Contact Illumina Support for questions about BCL Convert versions or troubleshooting help. Refer to BCL Convert documentation for download and installation steps:
- BCL Convert User Guides
- BCL Convert Software Downloads. Available as an RPM package. An Illumina account is required for download.
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.
Do not trim adapters during demultiplexing. Leave these settings blank. Trimming adapters from reads can potentially damage the 10x barcodes and the UMIs, resulting in pipeline failure or data loss.
If you are using an Illumina sample sheet for demultiplexing with BCL Convert, remove these lines under the [Settings] section: Adapter or AdapterRead1 or AdapterRead2.
The basic sample sheet has three sections. Each section is described here and example sample sheets are provided for 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 TS, Set A. The parameter CreateFastqForIndexReads,0 under [BCLConvert_Settings] tells BCL Convert not to generate FASTQ files for indices. Space Ranger does not require FASTQ files for indices.
[Header] FileFormatVersion,2 [BCLConvert_Settings] CreateFastqForIndexReads,0 TrimUMI,0 [BCLConvert_Data] Lane,Sample_ID,index,index2 1,test_sample,GTAACATGCG,AGGTAACACT
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>
The required arguments are:
--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.
This is the expected output after a successful BCL Convert run.
bcl-convert Version 00.000.000.4.00.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.
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 Visium libraries, 3' Single Cell Gene Expression, 5' Immune Profiling, and Fixed RNA Profiling libraries processed with the TT Set A dual index kit. It should not be used to run downstream pipelines (e.g. spaceranger count).
To follow along:
- Download the iseq-DI.tar file
- Uncompress the tar file by running:
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
After generating FASTQs, you are ready to run the spaceranger count pipeline following instructions on this page.