Command Line Options
This section provides information on all the DRAGEN command-line options, including the name used in the configuration file, the command-line equivalent, a description, and the range of values.
NOTE After upgrading to a new version of DRAGEN, it is recommended to first run with the default DRAGEN options, including all filtering options, and then add any specific filters only if needed.
General Software Options
The following options are in the default section of the configuration file. The default section is at the top of the configuration file and does not have a section name (eg, [Aligner]) associated with it. Some mandatory fields must be specified on the command line and are not present in configuration files.
append-read-index-to-name
By default, DRAGEN names both mate ends of pairs the same. When set to true, DRAGEN appends /1 and /2 to the two ends.
--append-read-index-to-name
true/false
aws-s3-region
Specifies the geographical region of AWS S3 buckets.
--aws-3-region
bam-input
Specifies aligned BAM file for input to the DRAGEN variant caller.
-b, --bam-input
bam-list
Specifies CSV file that contains a list of BAM files to process.
--bam-list
bcl-conversion-only
Performs Illumina BCL conversion to FASTQ format.
--bcl-conversion-only
true/false
bcl-input-directory
Inputs BCL directory for BCL conversion.
--bcl-input-directory
bcl-only-lane
For BCL input, the option converts only specified lane number. By default, all lanes are converted.
--bcl-only-lane
1–8
sample-sheet
For BCL input, the option sets the path to SampleSheet.csv file. The default location is the BCL root directory.
--sample-sheet
strict-mode
For BCL input, the option cancels analysis if any files are missing. The default value is false by default.
--strict-mode
true/false
first-tile-only
Converts only the first tile of each lane during BCL conversion. Use for testing or debugging.
--first-tile-only
true/false
run-info
Sets the path to RunInfo.xml file. The default is <flow cell>/RunInfo.xml.
--run-info
bcl-sampleproject-subdirectories
For BCL conversion, the option outputs to subdirectories based on sample sheet Sample_Project column.
--bcl-sampleproject-subdirectories
no-lane-splitting
Disables splitting output FASTQ files by lane. The default value is false.
--no-lane-splitting
true/false
bcl-only-matched-reads
Specifies if unmapped reads are output to files marked as Undetermined. The default value is false.
bcl-only-matched-reads
true/false
bcl-use-hw
If set to false, the option prevents DRAGEN FPGA acceleration during BCL conversion. The default value is true.
--bcl-use-hw
true/false
bcl-num-parallel-tiles
Specifies the number of tiles to process in parallel. The default value is dynamically determined.
--bcl-num-parallel-tiles
1-
bcl-num-conversion-threads
Specifies the number of conversion threads per tile. The default value is dynamically determined.
--bcl-num-conversion-threads
1-
bcl-num-compression-threads
Specifies the number of CPU threads for output fastq.gz compression. The default value is dynamically determined.
--bcl-num-compression-threads
1-
bcl-num-decompression-threads
Specifies the number of CPU threads for BCL input decompression. The default value is dynamically determined.
--bcl-num-decompression-threads
1-
shared-thread-odirect-output
Uses alternative shared-thread ODIRECT file output. The default value is false.
--shared-thread-odirect-output
true/false
build-hash-table
Generates a reference hash table.
--build-hash-table
true/false
cram-input
Specifies the CRAM file input for the variant caller.
--cram-input
cram-list
Specifies CSV file that contains a list of CRAM files to process.
--cram-list
cram-version
Specifies the CRAM output file format version.
--cram-version
3.0/3.1
cram-reference
Optional CRAM reference file used for decompression. FASTA file, or the directory containing the reference hash table.
--cram-reference
dbsnp
Sets the path to the variant annotation database VCF (or *.vcf.gz) file.
--dbsnp
enable-auto-multifile
Imports subsequent segments of the *_001.{dbam,fastq} files.
--enable-auto-multifile
true/false
enable-bam-indexing
Enables generation of a BAI index file.
--enable-bam-indexing
true/false
enable-cram-indexing
Enables generation of a CRAI index file.
--enable-cram-indexing
true/false
enable-cnv
Enables copy number variant (CNV).
--enable-cnv
true/false
enable-duplicate-marking
Enables the flagging of duplicate output alignment records.
--enable-duplicate-marking
true/false
enable-map-align-output
Enables saving the output from the map/align stage. If only running map/align, the default value is true. If running the variant caller, the default value is false.
--enable-map-align-output
true/false
enable-methylation-calling
Automatically adds tags related to methylation and outputs a single BAM for methylation protocols.
--enable-methylation-calling
true/false
enable-sampling
Automatically detects paired-end parameters by running a sample through the mapper/aligner.
--enable-sampling
true/false
enable-sort
Enables sorting after mapping/alignment.
--enable-sort
true/false
enable-variant-caller
Enables the variant caller.(default=false)
--enable-variant-caller
true/false
enable-variant-deduplication
Enables variant deduplication. The default value is false.
--enable-variant-deduplication
true/false
enable-vcf-compression
Enables compression of VCF output files. The default value is true.
--enable-vcf-compression
true/false
enable-vcf-indexing
Outputs a *.tbi index file in addition to the output VCF/gVCF. The default is true.
--enable-vcf-indexing
true/false
fastq-file1
Specifies FASTQ file to input to the DRAGEN pipeline. Gzipped format can be used.
-1, --fastq-file1
fastq-file2
Specifies second FASTQ file with paired-end reads to input.
-2, --fastq-file2
fastq-list
Specifies CSV file that contains a list of FASTQ files to process.
--fastq-list
fastq-list-sample-id
If the RGSM entry matches the given Sample ID parameter for fastq-list.csv input, the option processes the entry.
--fastq-list-sample-id
fastq-list-all-samples
If true, process all samples in the fastq-list file, even when there are multiple RGSM (Sample ID) values.
--fastq-list-all-samples
true/false
fastq-n-quality
Specifies the base call quality to output for N bases. Automatically added to fastq-n-quality for all output N bases.
--fastq-n-quality
0–255
fastq-offset
Sets the FASTQ quality offset value.
--fastq-offset
33
64
filter-flags-from-output
Filters output alignments with any bits set in val present in the flags field. Hex and decimal values accepted.
--filter-flags-from-output
force
Forces overwrite of existing output file.
-f
force-load-reference
Forces loading of the reference and hash tables before starting the DRAGEN pipeline.
-l
generate-md-tags
Generates MD tags with alignment output records. The default value is false.
--generate-md-tags
true/false
generate-sa-tags
Generates SA:Z tags for records that have chimeric or supplemental alignments.
--generate-sa-tags
true/false
generate-zs-tags
Generate ZS tags for alignment output records. The default value is false.
--generate-zs-tags
true/false
ht-alt-liftover
SAM format liftover file of alternate contigs in reference.
--ht-alt-liftover
ht-mask-bed
Specifies the BED file for base masking.
--ht-mask-bed
ht-allow-mask-and-liftover
Allows the hash table builder to run with both ht-alt-liftover and ht-mask-bed. Default is false.
--ht-allow-mask-and-liftover
true/false
ht-build-cnv-hashtable
Enables generation of CNV hash table files. The default value is false.
--ht-build-cnv-hashtable
true/false
ht-build-rna-hashtable
Enables generation of RNA hash table. The default value is false.
--ht-build-rna-hashtable
true/false
ht-build-hla-hashtable
Enables generation of HLA hash table. The default value is false.
--ht-build-hla-hashtable
true/false
ht-cost-coeff-seed-freq
Sets cost coefficient of extended seed frequency.
--ht-cost-coeff-seed-freq
ht-cost-coeff-seed-len
Sets cost coefficient of extended seed length.
--ht-cost-coeff-seed-len
ht-cost-penalty-incr
Sets cost penalty to incrementally extend a seed another step.
--ht-cost-penalty-incr
ht-cost-penalty
Sets cost penalty to extend a seed by any number of bases.
--ht-cost-penalty
ht-decoys
Specifies the path to a decoys file.
--ht-decoys
ht-max-dec-factor
Sets the maximum decimation factor for seed thinning.
--ht-max-dec-factor
ht-max-ext-incr
Sets the maximum bases to extend a seed by in one step.
--ht-max-ext-incr
ht-max-ext-seed-len
Specifies the maximum extended seed length.
-- ht-max-ext-seed-len
ht-max-seed-freq
Sets the maximum allowed frequency for a seed match after extension attempts.
--ht-max-seed-freq
1–256
ht-max-table-chunks
Specifies the maximum ~1 GB thread table chunks in memory at one time.
--ht-max-table-chunks
ht-mem-limit
Specifies the memory limit (hash table + reference) in units (KB, MB, GB).
--ht-mem-limit
ht-methylated
Automatically generates C->T and G->A converted reference hash tables.
--ht-methylated
true/false
ht-num-threads
Sets maximum worker CPU threads for building hash table.
--ht-num-threads
ht-rand-hit-extend
Includes a random hit with each EXTEND record of the frequency record.
--ht-rand-hit-extend
ht-rand-hit-hifreq
Includes a random hit with each HIFREQ record.
--ht-rand-hit-hifreq
ht-ref-seed-interval
Specifies the number of positions per reference seed.
--ht-ref-seed-interval
ht-reference
References file in FASTA format to build a hash table.
--ht-reference
ht-seed-len
Sets initial seed length to store in hash table.
--ht-seed-len
ht-size
Specifies the size of hash table in units (KB, MB, GB).
--ht-size
ht-soft-seed-freq-cap
Specifies the soft seed frequency cap for thinning.
--ht-soft-seed-freq-cap
ht-suppress-decoys
Suppresses the use of a decoys file when building a hash table.
--ht-suppress-decoys
ht-target-seed-freq
Sets the target seed frequency for seed extension.
--ht-target-seed-freq
validate-pangenome-reference
Should DRAGEN error out if a linear reference is provided for a component that a pangenome reference is recommended.
--validate-pangenome-reference
input-qname-suffix-delimiter
Controls the delimiter used for append-read-index-to-name and for detecting matching pair names with BAM input.
--input-qname-suffix-delimiter
/ :
interleaved
Specifies the interleaved paired-end reads in single FASTQ.
-i
intermediate-results-dir
Specifies directory to store intermediate results in (eg, sort partitions).
--intermediate-results-dir
lic-no-print
Suppresses the license status message at the end of a run.
--lic-no-print
true/false
lic-credentials
Provide your user credentials via a configuration file when running DRAGEN Cloud (refer to Cloud Licensing Reference Section).
--lic-credentials
lic-server
Provide your user credentials via the command line when running DRAGEN Cloud (refer to Cloud Licensing Reference Section)
--lic-server
lic-instance-id-location
Use this option to provide previously downloaded IDMS Documents for running DRAGEN Cloud (refer to Cloud Licensing Reference Section)
--lic-instance-id-location
methylation-generate-cytosine-report
Generates a genome-wide cytosine methylation report.
--methylation-generate-cytosine-report
true/false
methylation-generate-mbias-report
Generates a per system cycle methylation bias report.
--methylation-generate-mbias-report
true/false
methylation-TAPS
If input assays are generated by TAPS, the option is set to true.
--methylation-TAPS
true/false
methylation-match-bismark
If true, the option matches bismark tags exactly, including bugs.
--methylation-match-bismark
true/false
methylation-protocol
Describes library protocol for methylation analysis.
--methylation-protocol
none
directional
nondirectional
directional-complement
num-threads
Specifies the number of processor threads to use.
-n, --num-threads
output-directory
Specifies the output directory.
--output-directory
output-file-prefix
Outputs file name prefix to use for all files generated by the pipeline.
--output-file-prefix
output-format
Sets the format of the output file from the map/align stage. The following values are valid:BAM (the default),CRAM (lossless), SAM, or DBAM (a proprietary binary format)
--output-format
BAM/ CRAM/ SAM / DBAM
pair-by-name
Shuffles the order of BAM input records so paired-end mates are processed together.
--pair-by-name
pair-suffix-delimiter
Changes the delimiter character for suffixes.
--pair-suffix-delimiter
/ . :
preserve-bqsr-tags
Determines whether to preserve BI and BD flags from the input BAM file, which can cause problems with hard clipping.
--preserve-bqsr-tags
true/false
preserve-map-align-order
Produces output file that preserves original order of reads in the input file.
--preserve-map-align-order
true/false
qc-coverage-region-1
Generates coverage region report using bed file 1.
--qc-coverage-region-1
qc-coverage-region-2
Generates coverage region report using bed file 2.
--qc-coverage-region-2
qc-coverage-region-3
Generates coverage region report using bed file 3.
--qc-coverage-region-3
qc-coverage-reports-1
Describes the types of reports requested for qc-coverage-region-1.
--qc-coverage-reports-1
full_res/cov_report
qc-coverage-reports-2
Describes the types of reports requested for qc-coverage-region-2.
--qc-coverage-reports-2
full_res/cov_report
qc-coverage-reports-3
Describes the types of reports requested for qc-coverage-region-3.
--qc-coverage-reports-3
full_res/cov_report
qc-coverage-region-1-thresholds
Declares the thresholds to use in cov_report for qc-coverage-region-1.
--qc-coverage-region-1-thresholds
List of up to 11 numbers separated by commas
qc-coverage-region-2-thresholds
Declares the thresholds to use in cov_report for qc-coverage-region-2.
--qc-coverage-region-2-thresholds
List of up to 11 numbers separated by commas
qc-coverage-region-3-thresholds
Declares the thresholds to use in cov_report for qc-coverage-region-3.
--qc-coverage-region-3-thresholds
List of up to 11 numbers separated by commas
ref-dir
Specifies the directory containing the reference hash table. If the reference is not already loaded into the DRAGEN card, the option automatically loads the reference.
-r, --ref-dir
ref-sequence-filter
Outputs only reads mapping to the reference sequence.
--ref-sequence-filter
remove-duplicates
If true, the option removes duplicate alignment records instead of only flagging them.
true/false
RGCN
Specifies the read group sequencing center name.
--RGCN
RGCN-tumor
Specifies the read group sequencing center name for tumor input.
--RGCN-tumor
RGDS
Provides the read group description.
--RGDS
RGDS-tumor
Provides the read group description for tumor input.
--RGDS-tumor
RGDT
Specifies the read group run date.
--RGDT
RGDT-tumor
Specifies the read group run date for tumor input.
--RGDT-tumor
RGID
Specifies read group ID.
--RGID
RGID-tumor
Specifies read group ID for tumor input.
--RGID-tumor
RGLB
Specifies the read group library.
--RGLB
RGLB-tumor
Specifies the read group library for tumor input.
--RGLB-tumor
RGPI
Specifies the read group predicted insert size.
--RGPI
RGPI-tumor
Specifies the read group predicted insert size for tumor input.
--RGPI-tumor
RGPL
Specifies the read group sequencing technology.
--RGPL
RGPL-tumor
Specifies the read group sequencing technology for tumor input.
--RGPL-tumor
RGPU
Specifies the read group platform unit.
--RGPU
RGPU-tumor
Specifies read group platform unit for tumor input.
--RGPU-tumor
RGSM
Specifies read group sample name.
--RGSM
RGSM-tumor
Specifies read group sample name for tumor input.
--RGSM-tumor
sample-size
Specifies number of reads to sample when enable-sampling is true.
--sample-size
sample-sex
Specifies the sex of the sample.
--sample-sex
strip-input-qname-suffixes
Determines whether to strip read-index suffixes (eg, /1 and /2) from input QNAMEs. If set to false, the option preserves entire name.
--strip-input-qname-suffixes
true/false
tumor-bam-input
Specifies aligned BAM file for the DRAGEN variant caller in somatic mode.
--tumor-bam-input
tumor-bam-list
Specifies CSV file that contains a list of BAM files for the mapper, aligner, and somatic variant caller.
--tumor-bam-list
tumor-cram-input
Specifies aligned CRAM file for the DRAGEN variant caller in somatic mode.
--tumor-cram-input
tumor-cram-list
Specifies a CSV file that contains a list of CRAM files for the mapper, aligner, and somatic variant caller.
--tumor-cram-list
tumor-fastq-list
Inputs a CSV file containing a list of FASTQ files for the mapper, aligner, and somatic variant caller.
--tumor-fastq-list
tumor-fastq-list-sample-id
Specifies the sample ID for the list of FASTQ files specified by tumor-fastq-list.
--tumor-fastq-list-sample-id
tumor-fastq1
Inputs FASTQ file for the DRAGEN pipeline using the variant caller in somatic mode. The input file can be gzipped.
--tumor-fastq1
tumor-fastq2
Inputs second FASTQ file. Reads are paired to tumor-fastq1 reads for the DRAGEN pipeline using the variant caller in somatic mode. The input file can be gzipped.
--tumor-fastq2
vd-eh-vcf
Inputs the DRAGEN-STR repeats VCF file for variant deduplication. The input file can be gzipped.
--vd-eh-vcf
vd-output-match-log
Outputs a file that describes the variants that matched during deduplication. The default value is false.
--vd-output-match-log
true/false
vd-small-variant-vcf
Inputs small variant VCF file for variant deduplication. The input file can be gzipped.
--vd-small-variant-vcf
vd-sv-vcf
Inputs structural variant VCF for variant deduplication. The input file can be gzipped.
--vd-sv-vcf
verbose
Enables verbose output from DRAGEN.
-v
version
Prints the DRAGEN version, the Hash Table version and exits.
-V,--version
Mapper Options
The following options are in the [Mapper] section of the configuration file. For more detailed information on these options, see [DNA Mapping]{.underline}.
ann-sj-max-indel
Specifies maximum indel length to expect near an annotated splice junction.
--Mapper.ann-sj-max-indel
0–63
edit-chain-limit
For edit-mode 1 or 2, the option sets maximum seed chain length in a read to qualify for seed editing.
--Mapper.edit-chain-limit
edit-chain-limit >= 0
edit-mode
Controls when seed editing is used. The following values represent the different edit modes: 0 is no edits, 1 is chain length test, 2 is paired chain length test, 3 is full seed edits
--Mapper.edit-mode
0–3
edit-read-len
For edit-mode 1 or 2, controls the read length for edit-seed-num seed editing positions.
--Mapper.edit-read-len
edit-read-len > 0
edit-seed-num
For edit-mode 1 or 2, controls the requested number of seeds per read to allow editing on.
--Mapper.edit-seed-num
edit-seed-num >= 0
enable-map-align
Enable the mapper/aligner (Default=true)
--enable-map-align
true/false
map-orientations
Restricts the orientation of read mapping to only forward in the reference genome or only reverse-complemented. The following values represent the different orientations (paired end requires normal):0 is normal (paired-end inputs must use normal), 1 is reverse-complemented, 2 is no forward
--Mapper.map-orientations
0–2
max-intron-bases
Specifies maximum intron length reported.
--Mapper.max-intron-bases
min-intron-bases
Specifies minimum reference deletion length reported as an intron.
--Mapper.min-intron-bases
seed-density
Controls requested density of seeds from reads queried in the hash table
--Mapper.seed-density
0 > seed-density > 1
Aligner Options
The following options are in the [Aligner] section of the configuration file. For more information, see [DNA Aligning]{.underline}
aln-min-score
A signed integer that specifies a minimum acceptable alignment score to report the baseline for MAPQ. When using local alignments (global is 0), aln-min-score is computed by the host software as 22 * match-score. When using global alignments (global is 1), aln-min-score is set to -1000000. Host software computation can be overridden by setting aln-min-score in configuration file.
--Aligner.aln-min-score
−2,147,483,648 to 2,147,483,647
clip-pe-overhang
When nonzero, clips 3' read ends overhanging their mate's 5' ends as aligned. Set 1 to soft-clip overhang, 2 to hard-clip.
--Aligner.clip-pe-overhang
0–2
dedup-min-qual
Specifies a minimum base quality for calculating read quality metric for deduplication.
--Aligner.dedup-min-qual
0–63
en-alt-hap-aln
Allows haplotype alignments to be output as supplementary.
--Aligner.en-alt-hap-aln
0–1
en-chimeric-aln
Allows chimeric alignments to be output as supplementary.
--Aligner.en-chimeric-aln
0–1
gap-ext-pen
Specifies the penalty for extending a gap.
--Aligner.gap-ext-pen
0–15
gap-open-pen
Specifies the penalty for opening a gap (ie, insertion or deletion).
gap-open-pen
0–127
global
Controls whether alignment is end-to-end in the read. The following values represent the different alignments: 0 is local alignment (Smith-Waterman) 1 is global alignment (Needleman-Wunsch)
--Aligner.global
0–1
hard-clips
Specifies alignments for hard clipping. The following values represent the different alignments: Bit 0 is primary Bit 1 is supplementary Bit 2 is secondary
--Aligner.hard-clips
3 bits
map-orientations
Constrains orientations to accept forward-only, reverse-complement only, or any alignments. The following values represent the different orientations: 0 is any 1 is forward only 2 is reverse only
--Aligner.map-orientations
0–2
mapq-max
Specifies ceiling on reported MAPQ. The default value is 60.
--Aligner.mapq-max
0–255
mapq-strict-js
Specific to RNA. When set to 0, a higher MAPQ value is returned, expressing confidence that the alignment is at least partially correct. When set to 1, a lower MAPQ value is returned, expressing the splice junction ambiguity.
--mapq-strict-js
0–1
match-n-score
A signed integer that specifies the score increment for matching where a read or reference base is N.
--Aligner.match-n-score
-16–15
match-score
Specifies the score increment for matching reference nucleotide.
--Aligner.match-score
When global = 0, match-score > 0 When global = 1, match-score >= 0
max-rescues
Specifies maximum rescue alignments per read pair. The default value is 10.
--max-rescues
0–1023
min-score-coeff
Sets adjustment to aln-min-score per read base.
--Aligner.min-score-coeff
-64–63.999
mismatch-pen
Defines the score penalty for a mismatch.
--Aligner.mismatch-pen
0–63
no-unclip-score
When set to 1, the option removes any unclipped bonus (unclip-score) contributing to an alignment from the alignment score before further processing.
--Aligner.no-unclip-score
0–1
no-unpaired
Determines if only properly paired alignments should be reported for paired reads.
--Aligner. no-unpaired
0–1