# DNA Somatic Tumor-Normal Solid WES UMI A DRAGEN recipe, like this one, is a predefined set of analysis parameters and workflow settings tailored to a specific type of genomic analysis. For clarity, some default parameters are explicitly included and annotated with comments. This recipe includes the recommended commands for solid samples. These settings support fresh frozen samples, as well as some optional settings for FFPE samples. ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX # Inputs --tumor-fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM --tumor-fastq-list-sample-id $STRING --fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM --fastq-list-sample-id $STRING # Mapper --enable-map-align true #optional with BAM/CRAM input --enable-map-align-output true #optionally save the output BAM --enable-sort true #default=true # UMI --umi-enable true --umi-source STRING #Default='qname' --umi-library-type STRING #e.g. random-duplex --tumor-normal-has-umi STRING #Sample(s) containing UMI ['tumor', 'both']. --umi-min-supporting-reads 1 #Default=2 # Small variant caller --enable-variant-caller true --vc-target-bed $VC_TARGET_BED --vc-systematic-noise $PATH #Recommended --vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs --vc-sq-filter-threshold 17.5 #recommended in tumor-normal UMI mode # SV --enable-sv true --sv-exome true --sv-call-regions-bed $SV_TARGET_BED # CNV --enable-cnv true --cnv-use-somatic-vc-baf true --cnv-target-bed $PATH --cnv-combined-counts $PATH #CNV PON # HRD Scoring --enable-hrd true #requires CNV # Annotation --variant-annotation-data PATH --enable-variant-annotation true # TMB --enable-tmb true # HLA genotyper --enable-hla true # Microsatellite Instability (MSI) --msi-command tumor-normal --msi-microsatellites-file $PATH --msi-coverage-threshold 40 ``` ## Notes and additional options ### Hashtable For DRAGEN somatic runs it is recommended to use the linear hashtable. See: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html) ### Input options DRAGEN input sources include: fastq list, fastq, bam, or cram. For BCL input, first create FASTQs using [BCL conversion](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-v4.4/bcl-conversion). FQ list Input ``` --tumor-fastq-list $PATH --tumor-fastq-list-sample-id $STRING --fastq-list $PATH --fastq-list-sample-id $STRING ``` FQ Input ``` --tumor-fastq1 $PATH --tumor-fastq2 $PATH --RGSM-tumor $STRING --RGID-tumor $STRING --fastq-file1 $PATH --fastq-file2 $PATH --RGSM $STRING --RGID $STRING ``` BAM Input ``` --tumor-bam-input $PATH --bam-input $PATH ``` CRAM Input ``` --tumor-cram-input $PATH --cram-input $PATH ``` ### Mapping and Aligning | Option | Description | | -------------------------------- | ---------------------------------------------------------------------------------------------------- | | `--enable-map-align true` | In the TN pipeline this must be set to false for BAM/CRAM input. | | `--enable-map-align-output true` | Optionally save the output BAM (default=false). | | `--Aligner.clip-pe-overhang 2` | Clean up any unwanted UMI indexes. Only use when reads contain UMIs, but UMI collapsing was not run. | ### Fractional (Raw Reads) Downsampling DRAGEN can subsample a random, fractional percentage of reads from an input file using the fractional downsampler. You can use downsampling to subsample data sets in order to simulate different amounts of sequencing. DRAGEN randomly subsamples reads from primary analysis without any modification (e.g. no trimming, no filtering, etc.). Downsampling may be useful to reduce runtime on very deep samples. For Tumor-Normal analyses it is also recommended to use a normal sample with coverage that is less than the tumor sample. If the matched normal has deeper coverage than the tumor sample, then the fractional samples may be used to reduce coverage on the normal sample. | Option | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `--enable-fractional-down-sampler` | Set to true to enable fractional downsampling. The default value is false. | | `--down-sampler-normal-subsample` | Specify the fraction of reads to keep as a subsample of normal input data. The default value is 1.0 (100%). | | `--down-sampler-tumor-subsample` | Specify the fraction of reads to keep as a subsample of tumor input data. The default value is 1.0 (100%). | | `--down-sampler-random-seed` | Specify the random seed for different runs of the same input data. The default value is 42. | ### UMI | Option | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--umi-source STRING` | Specify the input type for the UMI sequence. Options: `qname`, `fastq`, `bamtag`. | | `--umi-library-type STRING` | Set the batch option for different UMIs correction. Options: `random-duplex`, `random-simplex`, `nonrandom-duplex`. | | `--umi-nonrandom-whitelist $PATH` | If UMI is nonrandom, either a whitelist or correction table is required. The whitelist includes a valid UMI sequence per line. | | `--umi-correction-table $PATH` | If UMI is nonrandom, either a whitelist or correction table is required. The correction table defaults to the table used by TruSight Oncology: \/resources/umi/umi\_correction\_table.txt.gz. | | `--umi-min-supporting-reads INT` | Specify the number of matching UMI input reads required to generate a consensus read. Any family with insufficient supporting reads is discarded. The default is 2, but most pipelines perform better with this setting set to 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g. ctDNA). | | `--umi-metrics-interval-file $BED` | Target region in BED format. | | `--umi-emit-multiplicity both` | Set the consensus sequence type to output. DRAGEN UMI allows collapsing duplex sequences from the two strands of the original molecules. For more information, see [Merge Duplex UMIs](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-dna-pipeline/unique-molecular-identifiers#merge-duplex-umis). | | `--umi-start-mask-length INT` | Number of additional bases to ignore from start of read. The default is 0. To reduce FP optionally set to 1. | | `--umi-end-mask-length INT` | Number of additional bases to ignore from end of read. The default is 0. To reduce FP optionally set to 3. | | `--tumor-normal-has-umi STRING` | Specify if only the tumor, or if both the tumor and normal have UMIs. Options: 'both','tumor'. | For more information see: [UMI Options](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-dna-pipeline/unique-molecular-identifiers#umi-options). ### SNV | Option | Description | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--vc-target-bed` | Limit variant calling to region of interest. | | `--vc-combine-phased-variants-distance INT` | Maximum distance in base pairs (BP) over which phased variants will be combined. Set to 0 to disable. Valid range is \[0; 15] BP (Default=2) | | `--vc-systematic-noise $PATH` | Systematic noise file. This filter is recommended for removing systematic noise observed in normal samples (i.e. systematic alignment errors, sequencing errors, etc.). | | `--vc-somatic-hotspots $PATH` | DRAGEN has a default set of hotspot variants (positions and alleles) where it will assign an increased prior probability. Use this option to override with a custom hotspots file. | | `--vc-enable-liquid-tumor-mode true` | Tumor-in-normal contamination. Only use if there is some tumor leakage in the normal control. | | `--vc-override-tumor-pcr-params-with-normal false` | Mixed sample preparation. Only use if the tumor and normal samples exhibit different PCR (indel) noise patterns, e.g., due to using different sample preparation. | | `--vc-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 4. Raise this value to improve specificity at the cost of sensitivity, or lower it to improve sensitivity at the cost of specificity. | | `--vc-systematic-noise-filter-threshold $INT` | Threshold for sensitivity-specificty tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Default value = 10. Raise this value to improve specificity at the cost of sensitivity, or lower it to improve sensitivity at the cost of specificity. | | `--vc-systematic-noise-filter-threshold-in-hotspot $INT` | Threshold for sensitivity-specificty tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Default value = 10. Raise this value to improve specificity at the cost of sensitivity, or lower it to improve sensitivity at the cost of specificity. | | `--vc-excluded-regions-bed $BED` | Hard filter variants that overlap with this region. ALU regions comprise approximately 11% of the genome, and are often exceptionally noisy regions in FFPE samples. Optionally filter out ALU regions using the DRAGEN excluded regions filter. ALU bed files can be downloaded as part of the Bed File Collection: [Bed File Collection](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html) | High-coverage sequencing panels allow for the detection of low-frequency alleles. DRAGEN supports 3 main settings for improved sensitivity on low VAF variant calls. | High Sensitivity Option | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--vc-target-vaf FLOAT` | The default is 0.03 (3%). Set to e.g. 0.01 to improve SNV sensitivity on 1% VAF variants (assuming sufficient coverage). | | `--vc-enable-umi-solid true` | Optimized for 1% and higher VAFs on UMI (or read position collapsed) samples with approx 300-1000X coverage. | | `--vc-enable-umi-liquid true` | Optimized for 0.1% and higher VAFs on UMI samples with 1000X or higher coverage as expected in liquid biopsies. | For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-v4.4/dragen-dna-pipeline/small-variant-calling/somatic-mode) ### HLA | Option | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `--enable-hla` | Enable HLA typer (this setting by default will only genotype class 1 genes) | | `--hla-as-filter-min-threshold` | Internal option to set min alignment score threshold. The default is 59 and works for WES and WGS. Set to 29 for panels. | | `--hla-as-filter-ratio-threshold` | Minimum Alignment score of a read mate to be considered. The default is 0.67 and works for WES and WES. Set to 0.85 for panels. | | `--hla-enable-class-2` | Extend genotyping to HLA class 2 genes (default=true). | ### CNV | Option | Description | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--cnv-enable-gcbias-correction true` | Enable or disable GC bias correction when generating target counts. | | `--cnv-segmentation-mode $SEG_MODE` | Option to override the default segmentation algorithm. Defaults include `slm` for germline WGS, `aslm` for somatic WGS, and `hslm` for targeted analysis. | | `--cnv-segmentation-bed $PATH` | If you are using somatic targeted panels with a set of genes supplied with the capture kit, then you can bypass segmentation by specifying a cnv-segmentation-bed and using cnv-segmentation-mode=bed. | | `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. [Germline-aware Mode](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-dna-pipeline/cnv-calling/available-pipelines/somatic-cnv-calling-wgs#germline-aware-mode). | For more information, see [CNV Calling](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-v4.4/dragen-dna-pipeline/cnv-calling). ### Annotation For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-v4.4/nirvana) ### TMB | Option | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--tmb-vaf-threshold FLOAT` | Variant mininum allele frequency for usable variants (default=0.05) | | `--vc-callability-tumor-thresh INT` | Required read coverage to use a site (default=50). | | `--tmb-enable-proxi-filter BOOL` | Use variant vaf information to increase germline filtering. Recommended for TO, but not for TN. May be overly aggressive at tagging variants as germline (default=false). | See the user guide: [TMB Germline Variants](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-dna-pipeline/biomarkers/biomarker-tmb#id-4.-support-for-germline-variants). ### MSI Microsatellite sites file can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html). | Option | Description and recommended setting | | -------------------------------- | -------------------------------------------------------------------------------------------- | | `--msi-coverage-threshold INT` | Minimum coverage for a microsatellite: 60 (default) | | `--msi-distance-threshold FLOAT` | Minimum Jensen-Shannon distance between tumor and normal for a microsatellite: 0.1 (default) | ### SV | Option | Description | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--sv-call-regions-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. | | `--sv-exclusion-bed` | Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally, you can compress the file in gzip or bgzip format. | | `--enable-variant-deduplication true` | Relevant when both SV and SNV callers are enabled in somatic workflows. Can increase sensitivity and prevent the occurrence of replicated variants within genes such as FLT3 and KMT2A. Filter all small indels in the structural variant VCF that appear and are passing in the small variant VCF. DRAGEN will create a new VCF that contains variants in SV VCF that are not matching a variant from SNV VCF file. The new deduplicated SV VCF file will have the same prefix passed by `--output-file-prefix` followed by `sv.small_indel_dedup`. DRAGEN normalizes variants by trimming and left shifting by up to 500 bases. | | `--sv-systematic-noise $BEDPE` | Systematic noise BEDPE file containing the set of noisy paired regions (optionally gzip or bzip compressed). Optional for WGS Tumor-Normal, but strongly recommended for WGS Tumor-Only. Has not been validated in WES/Panels. | | `--sv-somatic-ins-tandup-hotspot-regions-bed $BED` | Specify a custom BED of ITD hotspot regions to increase sensitivity for calling ITDs in somatic variant analysis. The default file includes FLT3, ARHGEF7, KMT2A, and UBTF exonic regions with some padding on both sides (300 bps) | | `--sv-min-candidate-variant-size` | Run SV caller and report all SVs/indels at or above this size. The default value is set to 10. | | `--sv-min-scored-variant-size` | After candidate identification, only score and report SVs/indels at or above this size. The default value is set to 50. This parameter doesn't affect the somatic hotspot region. | | Option | Recommended Value for Liquid Tumors (e.g. AML/MLL) | | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `--sv-enable-liquid-tumor-mode true` | DRAGEN can account for Tumor-in-Normal (TiN) contamination by running liquid tumor mode. | | `--sv-tin-contam-tolerance $TIN_CONTAM_TOLERANCE` | Set the Tumor-in-Normal (TiN) contamination tolerance level. | For more information, see [Structural Variant Calling](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-v4.4/dragen-dna-pipeline/sv-calling). ## Resource Files DRAGEN requires resource files for components such as SNV, SV, and CNV. The following notes provide references for downloading these files or generating them for custom workflows or assays. ### SNV Systematic Noise Systematic noise files are considered essential in Tumor-Only workflows. It is also recommended for Tumor-Normals workflows. DRAGEN has pre-build systematic noise files for WES/WGS. For high sensitivity applications, including panels or clinical WES/WGS assays, it is recommended to create your own systematic noise file as described under Custom. #### Prebuild Prebuilt systematic noise BED files (WES and WGS) can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html). | Prebuilt WES/WGS noise files | Description | | -------------------------------------------------- | ------------------------ | | `WGS_hg38_v2.0.0_systematic_noise.snv.bed.gz` | For WGS FF | | `FFPE_WGS_hg38_v2.0.0_systematic_noise.snv.bed.gz` | For WGS FFPE (only hg38) | | `WES_hg38_v2.0.0_systematic_noise.snv.bed.gz` | For WES FF and FFPE | #### Custom This section describes how to generate systematic noise files from phenotypically normal (non-tumor) samples to optimize the performance of a specific assay. For best accuracy, the normal samples should ideally closely match the sequencer, sample type, library prep, and coverage of the tumor samples of interest. It is typically recommended to use 30-70 normals when building a noise file, but fewer can be used. **Step 1. Run DRAGEN somatic tumor-only on each of approximately 30-70 normal samples.** ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX --tumor-fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM --tumor-fastq-list-sample-id $STRING --umi-enable true --umi-source STRING #default='qname' --umi-library-type STRING #see 'UMI' --vc-detect-systematic-noise=true --vc-target-bed $VC_TARGET_BED #Region assessed in assay --vc-target-bed-padding 500 --vc-enable-germline-tagging=true --variant-annotation-data $PATH --intermediate-results-dir $PATH --output-directory $PATH --output-file-prefix $STRING ``` For WES and WGS pipelines gather the full paths to the small variant hard filtered VCFs (not GVCFs) from step 1 and create a lines file `${VCF_LIST}` by specifying 1 file per line. **Step 2. Generate the final noise file.** This step generates a bed file containing mean and max noise estimates per position. This can be used directly during variant calling (argument --vc-systematic-noise). The distribution of noise per position can also be plotted to identify particularly noisy positions that could be troubleshooted (e.g. modify assay settings or DRAGEN settings) or blocklisted ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX --build-sys-noise-vcfs-list ${VCF_LIST} ``` The SNV systematic noise files can also be built in the cloud using the [DRAGEN Baseline Builder App on BaseSpace](https://www.illumina.com/products/by-type/informatics-products/basespace-sequence-hub/apps/dragen-baseline-builder.html) or the DRAGEN Systematic Noise File Builder Pipeline on [ICA](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html). ### SV Systematic Noise SV systematic noise files are recommended for WGS workflows. Prebuilt WGS noise files are available. SV systematic noise files are considered experimental in WES and Panels. #### Prebuilt Prebuilt WGS SV systematic noise files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html). | Prebuilt WGS noise files | Description | | --------------------------------------------------- | ---------------- | | `WGS_hg38_v3.0.0_systematic_noise.sv.bedpe.gz` | For WGS, FF/FFPE | | `IDPF_WGS_hg38_v3.0.0_systematic_noise.sv.bedpe.gz` | For WGS, HEME | #### Custom Custom systematic noise files can be generated for WES or Panels. For best accuracy the normal samples should ideally closely match the sequencer, sample type, library prep and coverage of the tumor samples of interest. It is typically recommended to use 30 - 100 normals when building a noise file, but fewer can be used. **Step 1. Run DRAGEN somatic tumor-only on normal samples with `--sv-detect-systematic-noise` set to true to generate VCF output per normal sample.** ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX --tumor-fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM --tumor-fastq-list-sample-id $STRING --umi-enable true --umi-source STRING #default='qname' --umi-library-type STRING #see 'UMI' --sv-detect-systematic-noise true ``` **Step 2. Build the BEDPE file using input VCFs from previous step.** ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX --sv-build-systematic-noise-vcfs-list $VCF_LIST#one VCF per line. ``` Systematic noise BEDPE files can also be built in the cloud using the [DRAGEN Baseline Builder App on BaseSpace](https://www.illumina.com/products/by-type/informatics-products/basespace-sequence-hub/apps/dragen-baseline-builder.html) or the DRAGEN Systematic Noise File Builder Pipeline on [ICA](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html). ### CNV Panel of Normals (PON) For CNV PON requirements and generation options see [CNV Preprocessing | Panel of Normals](https://help.dragen.illumina.com/dragen-v4.4/product-guide/dragen-dna-pipeline/cnv-calling/additional-documentation/cnv-preprocessing#panel-of-normals). If a matched normal is available it is recommended to include it in the PON. **Step 1. Generate CNV target counts of individual normal samples.** Any samples that should not be included in the final PON file can be excluded from this step. Any options used for CNV target counts generation (BED file, GC Bias Correction, etc.) should be matched when processing the case samples. ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX --tumor-fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM --tumor-fastq-list-sample-id $STRING # CNV --enable-cnv true --cnv-target-bed $PATH ``` **Step 2. CNV combined counts file generation.** ``` /opt/dragen/$VERSION/bin/dragen #DRAGEN install path --ref-dir $REF_DIR #path to DRAGEN linear hashtable --output-directory $OUTPUT --intermediate-results-dir $PATH #e.g. SSD /staging --output-file-prefix $PREFIX --enable-cnv true --cnv-generate-combined-counts true --cnv-normals-list $CNV_NORMALS_LIST ``` `$CNV_NORMALS_LIST` is a text file with one line for each path to a CNV target counts file generated in step 1 (either `.target.counts.gz` or `.target.counts.gc-corrected.gz`). Individual target counts files are merged into a single `.combined.counts.txt.gz` PON file in the output directory. The PON file is used for each case sample run of DRAGEN CNV using the `--cnv-combined-counts` option.