Output Options
The following command line options for output are mandatory:
| • | --output-directory <out_dir>—Specifies the output directory for generated files. |
| • | --output-file-prefix <out_prefix>—Specifies the output file prefix. DRAGEN appends the appropriate file extension onto this prefix for each generated file. |
| • | -r [ --ref-dir ]—Specifies the reference hash table. |
The following examples do not include these mandatory options.
For mapping and aligning, the output is sorted and compressed into BAM format by default before saving to disk. You can control the output format from the map/align stage with the --output-format <SAM|BAM|CRAM> option. If the output file exists, DRAGEN issues a warning and exits. To force overwrite if the output file already exists, use the -f [ --force ] option.
For example, the following commands output to a compressed BAM file, and then forces overwrite:
dragen ... -f
dragen ... -f --output-format bam
To generate a BAI-format BAM index file (*.bai), set --enable-bam-indexing to true.
The following example outputs to a SAM file, and then forces overwrite:
dragen ... -f --output-format sam
The following example outputs to a CRAM file, and then forces overwrite:
dragen ... -f --output-format cram
DRAGEN only outputs lossless CRAM files. All QNAMEs and BAM tags are preserved in the CRAM file.
Alignment tags
DRAGEN can generate mismatch difference (MD) tags, as described in the BAM standard. The feature is turned off by default because there is a small performance cost to generate these strings. To generate MD tags, set --generate-md-tags to true.
To generate ZS:Z alignment status tags, set --generate-zs-tags to true. These tags are only generated in the primary alignment and when a read has suboptimal alignments qualifying for secondary output (even if none were output because --Aligner.sec-aligns was set to 0). The following are valid tag values:
|
Tag |
Tag meaning |
|---|---|
|
ZS:Z:R |
Multiple alignments with similar score were found. |
|
ZS:Z:NM |
No alignment was found. |
|
ZS:Z:QL |
An alignment was found but it was below the quality threshold. |
To generate SA:Z tags, set --generate-sa-tags to true (the default). The tags provide alignment information (position, cigar, orientation) of groups of supplementary alignments, which are useful in structural variant calling.
To generate pair score in a ps:i tag, set --generate-ps-tags to true (false is the default for DNA, true is the default for RNA). The pair score is used in DRAGEN for computing MAPQ and can be used to check how well alignment candidates score against each other.
DRAGEN can also output mate alignment tags.
| • | To generate the mate cigar in the MC:Z tag, set --generate-mc-tags to true (true is the default). |
| • | To generate the mate mapping quality in the MQ:i tag, set --generate-mq-tags to true (true is the default). |
| • | To generate mate sequence in the R2:Z tag and mate base qualities in the Q2:Z tag, set --generate-r2-tags to true (false is the default), and set --generate-q2-tags to true (false is the default). |
If enabled, R2:Z and Q2:Z tags are only emitted for improperly paired read alignments with fragment length's of at least 1,000 bp. Methylation pipelines do not support the output of mate alignment tags.
CRAM Output
When CRAM is selected as the output, DRAGEN generates a CRAM file with the following features:
| • | The CRAM file is created in V3.0 format |
| • | The CRAM file is lossless. Lossy compression is not employed and is not an option |
| • | The quality score compression is lossless and read names are preserved |
| • | Only the GZIP compression algorithm is employed for maximum compatibility. Bgzip and lzma are not employed. RANS is used for quality scores |
| • | All input BAM tags are preserved |
| • | The DRAGEN Hash Table provided during the map/align run is the reference used to compress the CRAM file. When decompressing the CRAM file with a FASTA file and third-party tools, the FASTA file that was used to generate the Hash Table must be used. |
| • | A CRAM index file is produced in a .crai format |
| • | CRAM output is only possible when sort is enabled. CRAM alignments will always be positionally sorted |
The following list of default settings are used for the CRAM output
|
CRAM Option |
Value |
Description |
|---|---|---|
|
SEQS_PER_SLICE |
1000 |
Max sequences per slice |
|
BASES_PER_SLICE |
SEQS_PER_SLICE*500 |
Max bases per slice |
|
SLICE_PER_CNT |
1 |
Max slices per container |
|
embed_ref |
0 |
Do not embed reference sequence |
|
noref |
0 |
Do not embed reference sequence |
|
multiseq |
-1 |
Do not use multiple references per slice |
|
unsorted |
0 |
Do not use unsorted mode |
|
use_bz2 |
0 |
Do not compress using bzip2 |
|
use_lzma |
0 |
Do not compress using lmza |
|
use_rans |
1 |
Use rANS for quality score compression |
|
binning |
NONE |
Qual score binning not used |
|
preserve_aux_order |
1 |
Preserve all aux tags and order (incl RG,NM,MD) |
|
preserve_aux_size |
0 |
Aux tag sizes not preserved ('i', 's', 'c') |
|
lossy_read_names |
0 |
Preserve read names |
|
lossy |
0 |
Do not enable Illumina 8 quality-binning system |
|
ignore_md5 |
0 |
Enable all checking of checksums |
|
decode_md |
0 |
Do not (re)generate MD and NM tags |
