Command Line Options

The following command contains the required BCL conversion options for DRAGEN.

dragen

--bcl-conversion-only true

--bcl-input-directory <...>

--output-directory <...>

The following commands are required for bcl-convert:

bcl-convert

--bcl-input-directory <...>

--output-directory <...>

There are many optional command line arguments as well. The following is a list of all command line options:

Software Behavior

Option

Description

Default

--bcl-conversion-only-true

(DRAGEN only) Required for BCL conversion to FASTQ files in the DRAGEN executable

Not applicable

--bcl-input-directory

A main command line option that indicates the path to the run folder directory.

Not applicable

--output-directory

A required command line option that indicates the path to demultuplexed FASTQ output. The directory must not exist, unless -f --force is specified.

Not applicable

--sample-sheet

[Optional] If different from the default, the option indicates the path to the sample sheet to specify the sample sheet location and name.

<--bcl-input-directory>/SampleSheet.csv

--run-info

Overrides the path to the RunInfo.xml file.

--bcl-input-directory

--strict-mode

[Optional]

If true, the option aborts the program if any filter, LOCSlocs, BCLbcl, or BCLbc lane files are missing or corrupt.

If false, the option continues processing if any filter, LOCSlocs, BCLbcl, or BCIbci lane files are missing. Returns a warning message for each missing or corrupt file.

false

--first-tile-only

If true, the option only converts the first tile of input (for testing and debugging).

false

--bcl-only-lane <#>

Convert only the specified lane in this conversion run. Default convert all lanes.

-f --force

Convert to output directory even if the directory exists (force).

--bcl-use-hw-false

Allows concurrent execution of BCL conversion with DRAGEN analysis.

Do not use DRAGEN FPGA acceleration during BCL conversion.

Not applicable

--bcl-sampleproject-subdirectories

[Optional]

If true, the option allows creation of Sample_Project subdirectories as specified in the sample sheet. To use the Sample_Project column in the data section, this option must be set to true for the Sample_Project column in the data section to be used.

false

--no-lane-splitting-true

Output all lanes of a flow cell to the same FASTQ files consecutively.

false

--no-lane-splitting

Consolidates FASTQ files across lanes.

Each sample is provided into the same file on a per-read basis.

•

Must be true or false.

•

Only allowed when Lane column is excluded from the sample sheet.

false

--bcl-only-matched-reads-true

Disable outputting unmapped reads to FASTQ files marked as Undetermined.

false

--tiles

Only converts tiles that match a set of regular expressions.

Not applicable

--exclude-tiles

Do not convert tiles that match a set of regular expressions, even if included in --tiles.

Not applicable

--no-sample-sheet true

Operate without a sample sheet (no demultiplexing or adapter trimming supported).

False

--output-legacy-stats true

Output metrics in bcl2fastq2 Stats directory format in addition to csv.

False

--sample-name-column-enabled true

Use Sample_Name Sample Sheet column for *.fastq file names in Sample_Project subdirectories (requires bcl-sampleproject-subdirectories true as well).

False

--fastq-gzip-compression-level [0-9]

Set gzip compression level for FASTQ files.

-h,
--help

Produces a help message and exits the application.

Not applicable

-V,
--version

Produces a help message and exits the application.

Not applicable

--ora-reference

Required to output compressed FASTQ.ORA files. Specify the path to the directory that contains the compression reference and index file.

Not applicable

--fastq-compression-format

Required for DRAGEN ORA compression to specify the type of compression: use dragen for regular DRAGEN ORA compression, or dragen-interleaved for DRAGEN ORA paired compression.

Software Performance

The following additional options can be used to manually control performance. Use of these options might reduce performance or result in analysis failure, and it is recommended to use the default settings. Contact Illumina Technical Support if issues occur.

Total CPU heavy threads should be less than the number of HW cores you want to use for other processes. The following formula gives the total number of CPU heavy threads used by DRAGEN:

Option	Description	Default
--shared-thread-odirect-output true	Switch to an alternate file output method that is optimized for sample counts greater than 100,000. This option is not recommended for lower sample counts and/or if using distributed file system output targets such as GPFS or Lustre.
--bcl-num-parallel-tiles <#>	Number of tiles processed in parallel.	Determined dynamically
--bcl-num-conversion-threads <#>	Number of conversion threads per tile.	Determined dynamically
--bcl-num-compression-threads <#>	Number of CPU threads for gzip-compressing FASTQ output.	Determined dynamically
--bcl-num-decompression-threads <#>	Number of CPU threads for decompressing input BCL files.	Determined dynamically
--bcl-num-ora-compression-threads-per-file <#>	Optional for DRAGEN ORA compression. Set the number of threads used per file files.	10
--bcl-num-ora-compression-parallel-files <#>	Optional for DRAGEN ORA compression. Set the number of files processed in parallel.	6

It is recommended to only adjust CPU threads when reducing cores used on a shared machine. The total number of CPU-intensive threads used will be: --bcl-num-parallel-tiles * --bcl-num-conversion-threads + --bcl-num-compression-threads + --bcl-num-decompression-threads.

Tile Filtering

DRAGEN BCL Convert uses two command line options to control which tiles are converted. The correct command line depends upon the tile list expression.

•

--tiles—Specifies which tiles to include for analysis.

•

--exclude-tiles—Specifies which tiles to exclude from analysis.

This feature is a replacement for tiles, ExcludeTiles, and ExcludeTilesLaneX in bcl2fastq2. Both --tiles, and --exclude-tiles use a tile name (single regular expression) format. For example:

•

--tiles 1101—Includes the first tile on the first surface and first swath of every lane.

•

--tiles 11101—For NextSeq 500/550 system only. Includes the first tile on the first surface and first swath of every lane.

•

s_—Used to specify a lane. For example:

–

--tiles s_2—Converts all tiles of lane 2.

–

-exclude-tiles s_2_1101—Excludes the first tile on the first surface and first swath of lane 2.

Use square brackets and single digits separated by a hyphen to specify a range. For example:

•

[1-2]101—Select the first tile of both sides of the flow cell.

•

s_[1-2]_[1-2][0–9][0–9][0–9]5—Selects all tiles ending with 5 from surfaces 1–2 and all swaths for lanes 1–2.

To specify multiple tile expressions, use +.

•

s_1_1102+s_[2–8]—Includes the second tile on the first surface and first swath of lane 1 and all tiles in lanes 2–8.

Every component of the regular expression (as separated by +) used for tiles must match at least one tile entry in the input RunInfo tile list. Every term for exclude-tiles must match at least one tile entry in the set produced by tiles if that option is also used, or the RunInfo tile list.

DRAGEN ORA compression from BCL

BCL files can be converted into FASTQ.ORA using two different methods, which cannot be used at the same time.

Method 1: Using command line without a sample sheet:

Set the path to the directory that contains the compression reference and index file with the --ora-reference command.

Specifying the type of DRAGEN ORA compression with the –fastq-compression-format command. The values can be either dragen regular DRAGEN ORA compression or dragen-interleave for DRAGEN ORA paired compression.

Method 2: Using command line with a sample sheet:

Set the path to the directory that contains the compression reference and index file with the --ora-reference command.

Specify the type of DRAGEN ORA compression in the sample sheet. See Sample Sheet Settings for proper syntax.

The reference and index files for ORA compression are available at DRAGEN ORA Compression Software Support Resources. See the DRAGEN ORA Compression and Decompression, and Input File Types sections of the Illumina DRAGEN Bio-IT Platform Online Help for more information.

For information about how to use FASTQ.ORA files see Input File Types.