# Illumina® DRAGEN™ Secondary Analysis
Illumina DRAGEN (Dynamic Read Analysis for GENomics) secondary analysis was developed to address important challenges associated with analyzing NGS (Next Generation Sequencing) data for a range of applications, including genome, exome, transcriptome, and methylome studies. DRAGEN secondary analysis processes NGS data and enables tertiary analysis to drive insights. The available tools make up a highly accurate, comprehensive, and efficient solution that enables labs of all sizes and disciplines to do more with their genomic data.
**Product highlights**
**Accurate results:**
* Pangenome reference genome and machine learning drive unprecedented accuracy
* 99.89% accuracy score with the Precision FDA Truth Challenge V2 benchmark data (*2,3*)
**Comprehensive platform:**
* Analyze NGS data from whole genomes, exomes, methylomes, and transcriptomes
* Available on platform of choice and scalable based on needs
**Efficient analysis:**
* Process a 34x genome in \~ 30 minutes, with all supported callers with DRAGEN server v4 (*1*)
* Reduce FASTQ file sizes up to 5x with DRAGEN ORA Compression
\
\
*References:*
1. Illumina data on file, 2022.
2. Illumina DRAGEN Secondary Analysis is the first single platform to achieve 99.89% accuracy based on [PrecisionFDA v2 Truth Challenge Benchmark Data](https://precision.fda.gov/challenges/10). Details here [DRAGEN sets new standard for data accuracy in PrecisionFDA benchmark data](https://www.illumina.com/science/genomics-research/articles/dragen-shines-again-precisionfda-truth-challenge-v2.html). Accessed March 22, 2023
3. PrecisionFDA Truth Challenge V2: Calling Variants from Short and Long Reads in Difficult-to-Map Regions. [precision.fda.gov/challenges/10](https://precision.fda.gov/challenges/10). Accessed November 3, 2020.
# DRAGEN Applications
## Applications
DRAGEN analysis offers a large selection of application pipelines.
| Pipeline | Description | Variant Types Detected | Metrics Provided |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ |
| DRAGEN Demultiplexing | Rapid demultiplexing of NGS analysis | N/A | N/A |
| DRAGEN ORA Compression | DRAGEN ORA compression is optimized for high compression ratios of FASTQ files, as well as rapid compression and decompression, all while preserving data integrity. | N/A | Compression Ratio Run Time |
| DRAGEN Map + Align | The DRAGEN Map + Align can be run as a standalone or as part of DRAGEN’s suite of pipelines | N/A | Mapping metrics Duration Metrics Coverage Metrics |
| DRAGEN Germline | The DRAGEN Germline Pipeline provides end-to-end NGS analysis, including advanced error model calibration for increased accuracy, and repeat expansion detection and genotyping through Illumina Expansion Hunter. | SNV/Indel CNV SV Repeat Expansions | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Somatic | The DRAGEN Somatic Pipeline includes tumor-only and tumor–normal modes, designed for detecting somatic variants in tumor samples. Both modes make no ploidy assumptions, enabling detection of low-frequency alleles. | SNV/Indel CNV SV TMB MSI HLA | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Enrichment | The DRAGEN Enrichment Pipeline combines DRAGEN’s germline and somatic callers into a pipeline designed specifically for analyzing enrichment samples. Includes a full suite of enrichment metrics and reporting. | SNV/Indel CNV SV | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN RNA | The DRAGEN RNA Pipeline performs transcriptome analysis starting with splice junction discovery and alignment, followed by rapid alignment and splice junction mapping and quantification. For differential expression, Illumina recommends the DRAGEN Differential Expression app on BaseSpace Sequence Hub. | Gene fusion SNV/Indel | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Single Cell RNA | The DRAGEN Single Cell RNA pipeline performs demultiplexing, cell-barcode and UMI error correction, sequence alignment, and quantification of gene expression. | N/A | Mapping Metrics Duration Metrics Coverage Metrics Callability Report Cell Metrics |
| DRAGEN Joint Genotyping | The DRAGEN Joint Genotyping/Population Pipeline calls variants jointly across multiple genomes and scales to large cohorts of samples at expedited speeds with uncompromising accuracy. | SNV/Indel CNV SV Repeat Expansions | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Methylation | The DRAGEN Methylation Pipeline performs alignment, methyl calling, and calculates alignment and methylation metrics. | N/A | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Reference Builder | Accepts FASTA files, and builds the proprietary reference used by the DRAGEN apps. | N/A | N/A |
| DRAGEN TruSight Oncology 500 ctDNA Analysis Software | Secondary analysis support for Illumina’s TruSight Oncology 500 ctDNA. Available on the local DRAGEN Server version 3 and later. | SNV/Indel CNV DNA fusions MSI TMB | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Imputation | The DRAGEN Imputation pipeline is an end to end user friendly tool that enables scalable low pass whole genome sequencing analysis | N/A | Impute ≤100 samples simultaneously 1.7x faster compared to original GLIMPSE code |
## Analysis Uses
DRAGEN analysis can be used in numerous fields in the biological sciences.
| Analysis | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Genetic Diseases | Reduce time required for genomic analysis, with high accuracy and comprehensiveness |
| Oncology | Analyze tumor-only and tumor/normal samples with accuracy, comprehensiveness, and efficiency |
| Cell and Molecular Biology | Advance understanding of cellular mechanisms with rapid analysis pipelines for bulk and single cell samples |
| Population Genomics | Accurately and efficiently analyze sequenced genomes at scale. Accelerate re-analysis as computational tools improve over time |
| Infectious Disease | Detect and characterize infectious diseases with a comprehensive solution |
| Agrigenomics | Efficiently analyze animals and plants of varying genomic complexities with custom reference |
# DRAGEN User Guides
Visit the links below for DRAGEN technical user guides.
[DRAGEN v4.5](https://help.dragen.illumina.com/dragen-v4.5)
[DRAGEN v4.5 for Illumina TruPath Genome](https://help.dragen.illumina.com/dragen-v4.5-trupath)
[DRAGEN v4.4](https://help.dragen.illumina.com/dragen-v4.4)
[DRAGEN v4.3](https://help.dragen.illumina.com/dragen-v4.3)
# Deployment Options
DRAGEN analysis is available on multiple platforms.
| Platform | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| DRAGEN on-premises server test | DRAGEN on-premises server offers highly accurate secondary analysis in a fraction of time compared with a traditional CPU-based system.
- Analyze and store data locally
- Supports varying levels of command line interface
- Replace up to 30 traditional compute instances
- Fully process a 34× whole human genome in \~30 minutes. (1)
- One unit supports two NovaSeq 6000 Systems running at full capacity
|
| DRAGEN analysis on Illumina Connected Analytics | Couples the accuracy and speed of the DRAGEN with the ability to customize analysis pipeline to operationalize informatics on a secure platform. |
| DRAGEN on BaseSpace Sequence Hub (BSSH) | Push button analysis capability in an intuitive, easy-to-use interface with compliance, and storage features of BaseSpace Sequence Hub and Amazon Web Services (AWS). |
| DRAGEN onboard NovaSeq X Series | - Flexibly runs multiple secondary analysis pipelines in parallel.
- Performs up to four simultaneous applications per flow cell in a single run.
- Brings up to 5x lossless data compression, and analysis with supported applications
- Provides savings on analysis, which over five years can exceed the price of the sequencer
|
| DRAGEN onboard NextSeq 1000 and NextSeq 2000 Systems | - Provides access to select DRAGEN analysis informatics pipelines
- Enables users to generate results in as little as two hours
- Uses intuitive pipeline algorithms to reduce reliance on external informatics experts
|
| DRAGEN onboard MiSeq i100 Series | Intuitive, ultra-rapid analysis including DRAGEN BCL convert, DRAGEN Library QC, DRAGEN small WGS and DRAGEN Microbial Enrichment Plus.
- Rapid results with comprehensive secondary analysis generated in two hours or less (2)
- Highly efficient workflow with a single user touchpoint to VCF and/or html report and no intermediate file transfers
- Exceptionally easy with an intuitive interface for non-expert users
|
| DRAGEN on AWS, Azure | DRAGEN supports the FPGA enabled instance types of AWS, Azure. Rpm installers and the Kernel driver can be installed on images managed by the user, and DRAGEN can be run by purchasing a license. |
| DRAGEN on AWS and Azure Marketplace | Pre-configured Amazon Machine Images (AMI) and Azure Virtual Machines with DRAGEN installed can be accessed from the respective marketplace offerings in a Pay-As-You-Use model. |
| DRAGEN on GCP | DRAGEN is made available on the Google Cloud Platform. Pre-configured instances with DRAGEN installed can be accessed through the GCP application interface. Limited availability. Please reach out to your Illumina representative for access. |
> (1) HG002 from PrecisionFDA truth challenge V2 run with DRAGEN analysis v4.0 on DRAGEN server v4, all callers
> (2) When run according to sample recommendations
# Illumina Assay to DRAGEN Cloud Pipeline Mapping
This table identifies the appropriate DRAGEN pipeline for analyzing data output from Illumina assay kits. Visit [Illumina BioInsight Platform Core](https://help.ica.illumina.com/) or [Illumina BaseSpace Sequence Hub](https://help.basespace.illumina.com/) for more information on accessing DRAGEN pipelines in the cloud.
| Assay | DRAGEN Pipeline |
| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Illumina Spatial Transcriptome Prep, FF (L) Cloud | DRAGEN Spatial Transcriptome |
| Illumina Spatial Transcriptome Prep, FF (S) Cloud | DRAGEN Spatial Transcriptome |
| Illumina Spatial Transcriptome Prep, FF (L) Cloud Starter | DRAGEN Spatial Transcriptome |
| Illumina Spatial Transcriptome Prep, FF (S) Cloud Starter | DRAGEN Spatial Transcriptome |
| ILMN Protein Prep 9.5k Plasma 96 Reactions | DRAGEN Protein Quantification |
| ILMN Protein Prep 9.5k Serum 96 Reactions | DRAGEN Protein Quantification |
| Illumina 5-Base DNA Prep (24 Samples) Early Access | DRAGEN Germline: 5-Base |
| Illumina 5-Base DNA Prep with Enrichment (24 Samples) Early Access | DRAGEN Enrichment: 5-Base |
| Illumina 5-Base DNA Prep (24 Samples) | DRAGEN Germline: 5-Base |
| Illumina 5-Base DNA Prep with Enrichment (24 Samples) | DRAGEN Enrichment: 5-Base |
| Illumina Single Cell 3' RNA Prep, T2 (8 samples, 2000 cells/sample) | DRAGEN Single Cell RNA: T2 |
| Illumina Single Cell 3' RNA Prep, T10 (8 samples, 10,000 cells/sample) | DRAGEN Single Cell RNA: T10 |
| Illumina Single Cell 3' RNA Prep, T20 (4 samples, 20,000 cells/sample) | DRAGEN Single Cell RNA: T20 |
| Illumina Single Cell 3' RNA Prep, T100 (2 samples, 100,000 cells/sample) | DRAGEN Single Cell RNA: T100 |
| Illumina Single Cell CRISPR Prep, T10 (8 samples, 10,000 cells/sample) | DRAGEN Single Cell CRISPR: T10 |
| Illumina Single Cell CRISPR Prep, T100 (2 samples, 100,000 cells/sample) | DRAGEN Single Cell CRISPR: T100 |
| Illumina Single Cell CRISPR Prep, M1 (1 sample, 1 million cells/sample) | DRAGEN Single Cell CRISPR: M1 |
| Illumina Single Cell CRISPR Prep, M10 (10 samples, 1 million cells/sample) | DRAGEN Single Cell CRISPR: M10 |
| Illumina TruPath Genome (NovaSeq X C8 Flowcell) | DRAGEN Germline: TruPath |
| Illumina TruPath Genome (NovaSeq X C2 Flowcell) | DRAGEN Germline: TruPath |
| Ribo-Zero Plus Mcrbm Dpltn Kit, 96 | DRAGEN Microbiome Metatranscriptomics |
| ILMN VSP V2 Kit, Set A (96 spl) | DRAGEN Microbial Enrichment Plus |
| ILMN VSP V2 Kit, Set B (96 spl) | DRAGEN Microbial Enrichment Plus |
| ILMN VSP V2 Kit, Set C (96 spl) | DRAGEN Microbial Enrichment Plus |
| ILMN VSP V2 Kit, Set D (96 spl) | DRAGEN Microbial Enrichment Plus |
| IMAP with MiniSeq Core Cons Kit 48 smp | DRAGEN Microbial Amplicon |
| IMAP with MiSeq Core Cons Kit 48 smp | DRAGEN Microbial Amplicon |
| Illumina Microbial Amplicon Prep, 48 sample | DRAGEN Microbial Amplicon |
| lLMN Microb Amp Prep Infl. A/B (48 Spl) | DRAGEN Microbial Amplicon |
| Resp Virus Enrich Kit A (96 idx,96 spl) | DRAGEN Microbial Enrichment Plus |
| Resp Virus Enrich Kit B (96 idx,96 spl) | DRAGEN Microbial Enrichment Plus |
| Resp Virus Enrich Kit C (96 idx,96 spl) | DRAGEN Microbial Enrichment Plus |
| Resp Virus Enrich Kit D (96 idx,96 spl) | DRAGEN Microbial Enrichment Plus |
| RPIP Enrich Kit (RUO)(96 idx,96 spl)-A | DRAGEN Microbial Enrichment Plus |
| RPIP Enrich Kit (RUO)(96 idx,96 spl)-B | DRAGEN Microbial Enrichment Plus |
| RPIP Enrich Kit (RUO)(96 idx,96 spl)-C | DRAGEN Microbial Enrichment Plus |
| RPIP Enrich Kit (RUO)(96 idx,96 spl)-D | DRAGEN Microbial Enrichment Plus |
| RPIP with MiSeq Core Cons Kit 96 smp | DRAGEN Microbial Enrichment Plus |
| RPIP with NS1K2K Core Cons Kit 96 smp | DRAGEN Microbial Enrichment Plus |
| Urinary Path. ID/AMR Enrichment Kt SetA | DRAGEN Microbial Enrichment Plus |
| Urinary Path. ID/AMR Enrichment Kt SetC | DRAGEN Microbial Enrichment Plus |
| VSP w ILMN RNA Prep w Enrich A, 96 Rxns | DRAGEN Microbial Enrichment Plus |
| VSP w ILMN RNA Prep w Enrich B, 96 Rxns | DRAGEN Microbial Enrichment Plus |
| VSP with MiniSeq Core Cons Kit 96 smp | DRAGEN Microbial Enrichment Plus |
| VSP with MiSeq Core Cons Kit 96 smp | DRAGEN Microbial Enrichment Plus |
| ILMN VSP V2 Panel (96 spl) | DRAGEN Microbial Enrichment Plus |
| RESP. VIRUS OLIGO PANEL v2 | DRAGEN Microbial Enrichment Plus |
| Viral Surveillance Panel, RUO 96 rxns | DRAGEN Microbial Enrichment Plus |
| IDT ILMN UMI DNA/RNA UDI A Lig 96Id96Spl | DRAGEN ILMN cfDNA prep w/Enrichment |
| IDT ILMN UMI DNA/RNA UDI B Lig 96Id96Spl | DRAGEN ILMN cfDNA prep w/Enrichment |
| TruSight Oncology Comprehensive (EU) Kit | TruSight Oncology Comprehensive (LRM) |
| TruSight Oncology DNA Control | TruSight Oncology Comprehensive (LRM) |
| TruSight Oncology RNA Control | TruSight Oncology Comprehensive (LRM) |
| TruSight Onco 500 DNA Kt (48 Spl) | DRAGEN TSO 500 |
| TruSight Onco 500 DNA Kt, NSQ (48 Spl) | DRAGEN TSO 500 |
| TruSight Onco 500 DNA/RNA Kt,NSQ(24 Spl) | DRAGEN TSO 500 |
| TruSightOnco 500 DNA Auto Kt,NSQ(64 Spl) | DRAGEN TSO 500 |
| TS Onc 500 DNA HT (144 Spl) | DRAGEN TSO 500 |
| TS Onc 500 DNA/RNA HT (72 Spl) | DRAGEN TSO 500 |
| TSO 500 ctDNA Kit (48 smpl) + Velsera | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 + S2 (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 + S4 (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 Auto (48 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 Auto + S4 (48 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 DNA HT (48 Spl)+Velsera | DRAGEN TSO 500 |
| TSO 500 DNA/RNA Auto Kt,NSQ(32 Spl) | DRAGEN TSO 500 |
| TSO 500 DNA/RNA HT (24 Spl)+Velsera | DRAGEN TSO 500 |
| TSO 500 DNA/RNA HT (72 Spl)+Velsera | DRAGEN TSO 500 |
| TSO500 DNA Kit (48 samples)+Velsera | DRAGEN TSO 500 |
| TSO500 DNA Kit NextSeq (48Spl)+Velsera | DRAGEN TSO 500 |
| TSO500 DNA/RNA Auto Kt NSQ(32) + Velsera | DRAGEN TSO 500 |
| TSO500 DNA/RNA HT Auto (32 spls)+Velsera | DRAGEN TSO 500 |
| TSO500 DNA/RNA HT Auto(72 spls)+Velsera | DRAGEN TSO 500 |
| TSO500 DNA/RNA Kit (24Spl)+Velsera | DRAGEN TSO 500 |
| TSO500 DNA/RNA Kit NextSeq (24)Velsera | DRAGEN TSO 500 |
| TSO500 DNA/RNA Kit NextSeq (24) plus Illumina Connected Insights Software | DRAGEN TSO 500 |
| TSO500 DNA/RNA HT Auto (32 spls) plus Illumina Connected Insights Software | DRAGEN TSO 500 |
| TSO 500 DNA/RNA HT (24 Spl) plus Illumina Connected Insights Software | DRAGEN TSO 500 |
| TSO500 DNA/RNA Auto Kt NSQ(32) plus Illumina Connected Insights Software | DRAGEN TSO 500 |
| TruSight Oncology 500 ctDNA v2 (24 samples) plus Connected Insights Interpretation Report | DRAGEN TruSight Oncology 500 ctDNA |
| TruSight Oncology 500 ctDNA v2 for Automation (48 samples) plus Connected Insights Interpretation Report | DRAGEN TruSight Oncology 500 ctDNA |
| TruSight Oncology 500 ctDNA v2 plus Connected Insights Interpretation Report, for use with NovaSeq 6000 S2 (24 samples) | DRAGEN TruSight Oncology 500 ctDNA |
| TruSight Oncology 500 ctDNA v2 plus Connected Insights Interpretation Report, for use with NovaSeq 6000 S4 (24 samples) | DRAGEN TruSight Oncology 500 ctDNA |
| TruSight Oncology 500 ctDNA v2 Automation Kit plus Connected Insights Interpretation Report, for use with NovaSeq 6000 S2 (48 samples) | DRAGEN TruSight Oncology 500 ctDNA |
| TruSight Oncology 500 ctDNA v2 Automation Kit plus Connected Insights Interpretation Report, for use with NovaSeq 6000 S4 (48 samples) | DRAGEN TruSight Oncology 500 ctDNA |
| oncoReveal Myeloid Panel plus Illumina Connected Insights software | DRAGEN Amplicon Pipeline |
| oncoReveal Multi-Cancer CNV + Fusion plus Illumina Connected Insights software | DRAGEN Amplicon Pipeline |
| oncoReveal BRCA1 & BRCA2 + CNV plus Illumina Connected Insights software | DRAGEN Amplicon Pipeline |
| oncoReveal Essential MPN Panel plus Illumina Connected Insights software | DRAGEN Amplicon Pipeline |
| TruSight Oncology Comprehensive | TruSight Oncology Comprehensive (LRM) |
| TSO 500 ctDNA v2 +S4 +Velsera (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| oncoReveal BRCA1 & BRCA2 + CNV plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Essential MPN Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Multi-Cancer CNV + Fusion plus Correlation Engine software (48 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Myeloid Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Essential LBx Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Core LBx Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Fusion LBx Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Multi-Cancer + Fusion Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Solid Tumor v2 Panel plus Correlation Engine software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Essential LBx Panel plus Illumina Connected Insights software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Core LBx Panel plus Illumina Connected Insights software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Fusion LBx Panel plus Illumina Connected Insights software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Multi-Cancer + Fusion Panel plus Illumina Connected Insights software (24 samples) | DRAGEN Amplicon Pipeline |
| oncoReveal Solid Tumor v2 Panel plus Illumina Connected Insights software (24 samples) | DRAGEN Amplicon Pipeline |
| TruSight Oncology 500 DNA High-Throughput Kit (144 Samples), plus Velsera | DRAGEN TSO 500 |
| TruSight Oncology 500 DNA Automation Kit plus Velsera interpretation report (16 indexes, 64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 DNA/RNA Automation Kit plus Velsera interpretation report (16 indexes, 32 Samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 High-Throughput DNA for Automation (64 Samples), Plus Velsera | DRAGEN TSO 500 |
| TruSight Oncology 500 High-Throughput DNA for Automation (144 Samples), Plus Velsera | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit (96 samples) | DRAGEN TSO 500 |
| TSO 500 v2 DNA/RNA Kit NSQ (24 spl) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit, For Use with NextSeq 550 (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit, For Use with NextSeq 550 (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit, For Use with NextSeq 550 (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit, For Use with NextSeq 1000/2000 P2 (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit, For Use with NextSeq 1000/2000 P2 (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit, For Use with NextSeq 1000/2000 P2 (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit, For Use with NextSeq 1000/2000 P2 (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit plus Velsera interpretation report (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit plus Velsera interpretation report (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Velsera interpretation report (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit plus Velsera interpretation report (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Velsera interpretation report (96 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit plus Velsera interpretation report, For Use with NextSeq 550 (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit plus Velsera interpretation report, For Use with NextSeq 550 (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Velsera interpretation report, For Use with NextSeq 550 (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit plus Velsera interpretation report, For Use with NextSeq 550 (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit plus Velsera interpretation report, For Use with NextSeq 1000/2000 P2 (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit plus Velsera interpretation report, For Use with NextSeq 1000/2000 P2 (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Velsera interpretation report, For Use with NextSeq 1000/2000 P2 (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit plus Illumina Connected Insights Software (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit plus Illumina Connected Insights Software (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Illumina Connected Insights Software (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit plus Illumina Connected Insights Software (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Illumina Connected Insights Software (96 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit plus Illumina Connected Insights Software, For Use with NextSeq 550 (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit plus Illumina Connected Insights Software, For Use with NextSeq 550 (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Illumina Connected Insights Software, For Use with NextSeq 550 (32 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Automation Kit plus Illumina Connected Insights Software, For Use with NextSeq 550 (64 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Kit plus Illumina Connected Insights Software, For Use with NextSeq 1000/2000 P2 (24 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA Kit plus Illumina Connected Insights Software, For Use with NextSeq 1000/2000 P2 (48 samples) | DRAGEN TSO 500 |
| TruSight Oncology 500 v2 DNA/RNA Automation Kit plus Illumina Connected Insights Software, For Use with NextSeq 1000/2000 P2 (32 samples) | DRAGEN TSO 500 |
| TSO 500 ctDNA v2 + P4 (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 Auto + S2 (48 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 + Velsera (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 Auto + Velsera(48 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 +P4 +Velsera (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 +S2 +Velsera (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 Auto+S2+Velsera(48spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 ctDNA v2 Auto+S4+Velsera(48spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TruSight Oncology 500 ctDNA v2 plus Illumina Connected Insight Software (24 spls) | DRAGEN TruSight Oncology 500 ctDNA |
| TSO 500 v2 DNA Auto Kit ICI P2 (64 spl) | DRAGEN TSO 500 |
| TSO500 DNA Auto Kt NSQ(64Spl)+Velsera | DRAGEN TSO 500 |
| oncoReveal Myeloid Panel | DRAGEN Amplicon Pipeline |
| oncoReveal Multi-Cancer CNV + Fusion | DRAGEN Amplicon Pipeline |
| oncoReveal BRCA1 & BRCA2 + CNV | DRAGEN Amplicon Pipeline |
| oncoReveal Essential MPN Panel | DRAGEN Amplicon Pipeline |
| oncoReveal Essential LBx Panel | DRAGEN Amplicon Pipeline |
| oncoReveal Core LBx Panel | DRAGEN Amplicon Pipeline |
| oncoReveal Fusion LBx Panel | DRAGEN Amplicon Pipeline |
| oncoReveal Multi-Cancer Fusion Panel | DRAGEN Amplicon Pipeline |
| oncoReveal Solid Tumor v2 Panel | DRAGEN Amplicon Pipeline |
# Illumina® DRAGEN™ Secondary Analysis
Illumina DRAGEN (Dynamic Read Analysis for GENomics) secondary analysis was developed to address important challenges associated with analyzing NGS (Next Generation Sequencing) data for a range of applications, including genome, exome, transcriptome, and methylome studies. DRAGEN secondary analysis processes NGS data and enables tertiary analysis to drive insights. The available tools make up a highly accurate, comprehensive, and efficient solution that enables labs of all sizes and disciplines to do more with their genomic data.
**Product highlights**
**Accurate results:**
* Pangenome reference genome and machine learning drive unprecedented accuracy
* 99.89% accuracy score with the Precision FDA Truth Challenge V2 benchmark data (*2,3*)
**Comprehensive platform:**
* Analyze NGS data from whole genomes, exomes, methylomes, and transcriptomes
* Available on platform of choice and scalable based on needs
**Efficient analysis:**
* Process a 34x genome in \~ 30 minutes, with all supported callers with DRAGEN server v4 (*1*)
* Reduce FASTQ file sizes up to 5x with DRAGEN ORA Compression
\
*References:*
1. Illumina data on file, 2022.
2. Illumina DRAGEN Secondary Analysis is the first single platform to achieve 99.89% accuracy based on [PrecisionFDA v2 Truth Challenge Benchmark Data](https://precision.fda.gov/challenges/10). Details here [DRAGEN sets new standard for data accuracy in PrecisionFDA benchmark data](https://www.illumina.com/science/genomics-research/articles/dragen-shines-again-precisionfda-truth-challenge-v2.html). Accessed March 22, 2023
3. PrecisionFDA Truth Challenge V2: Calling Variants from Short and Long Reads in Difficult-to-Map Regions. [precision.fda.gov/challenges/10](https://precision.fda.gov/challenges/10). Accessed November 3, 2020.
# DRAGEN Applications
## Applications
DRAGEN analysis offers a large selection of application pipelines.
| Pipeline | Description | Variant Types Detected | Metrics Provided |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ |
| DRAGEN Demultiplexing | Rapid demultiplexing of NGS analysis | N/A | N/A |
| DRAGEN ORA Compression | DRAGEN ORA compression is optimized for high compression ratios of FASTQ files, as well as rapid compression and decompression, all while preserving data integrity. | N/A | Compression Ratio Run Time |
| DRAGEN Map + Align | The DRAGEN Map + Align can be run as a standalone or as part of DRAGEN’s suite of pipelines | N/A | Mapping metrics Duration Metrics Coverage Metrics |
| DRAGEN Germline | The DRAGEN Germline Pipeline provides end-to-end NGS analysis, including advanced error model calibration for increased accuracy, and repeat expansion detection and genotyping through Illumina Expansion Hunter. | SNV/Indel CNV SV Repeat Expansions | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Somatic | The DRAGEN Somatic Pipeline includes tumor-only and tumor–normal modes, designed for detecting somatic variants in tumor samples. Both modes make no ploidy assumptions, enabling detection of low-frequency alleles. | SNV/Indel CNV SV TMB MSI HLA | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Enrichment | The DRAGEN Enrichment Pipeline combines DRAGEN’s germline and somatic callers into a pipeline designed specifically for analyzing enrichment samples. Includes a full suite of enrichment metrics and reporting. | SNV/Indel CNV SV | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN RNA | The DRAGEN RNA Pipeline performs transcriptome analysis starting with splice junction discovery and alignment, followed by rapid alignment and splice junction mapping and quantification. For differential expression, Illumina recommends the DRAGEN Differential Expression app on BaseSpace Sequence Hub. | Gene fusion SNV/Indel | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Single Cell RNA | The DRAGEN Single Cell RNA pipeline performs demultiplexing, cell-barcode and UMI error correction, sequence alignment, and quantification of gene expression. | N/A | Mapping Metrics Duration Metrics Coverage Metrics Callability Report Cell Metrics |
| DRAGEN Joint Genotyping | The DRAGEN Joint Genotyping/Population Pipeline calls variants jointly across multiple genomes and scales to large cohorts of samples at expedited speeds with uncompromising accuracy. | SNV/Indel CNV SV Repeat Expansions | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Methylation | The DRAGEN Methylation Pipeline performs alignment, methyl calling, and calculates alignment and methylation metrics. | N/A | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Reference Builder | Accepts FASTA files, and builds the proprietary reference used by the DRAGEN apps. | N/A | N/A |
| DRAGEN TruSight Oncology 500 ctDNA Analysis Software | Secondary analysis support for Illumina’s TruSight Oncology 500 ctDNA. Available on the local DRAGEN Server version 3 and later. | SNV/Indel CNV DNA fusions MSI TMB | Mapping metrics Duration Metrics Coverage Metrics Variant Metrics Callability Report |
| DRAGEN Imputation | The DRAGEN Imputation pipeline is an end to end user friendly tool that enables scalable low pass whole genome sequencing analysis | N/A | Impute ≤100 samples simultaneously 1.7x faster compared to original GLIMPSE code |
## Analysis Uses
DRAGEN analysis can be used in numerous fields in the biological sciences.
| Analysis | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Genetic Diseases | Reduce time required for genomic analysis, with high accuracy and comprehensiveness |
| Oncology | Analyze tumor-only and tumor/normal samples with accuracy, comprehensiveness, and efficiency |
| Cell and Molecular Biology | Advance understanding of cellular mechanisms with rapid analysis pipelines for bulk and single cell samples |
| Population Genomics | Accurately and efficiently analyze sequenced genomes at scale. Accelerate re-analysis as computational tools improve over time |
| Infectious Disease | Detect and characterize infectious diseases with a comprehensive solution |
| Agrigenomics | Efficiently analyze animals and plants of varying genomic complexities with custom reference |
# Deployment Options
DRAGEN analysis is available on multiple platforms.
| Platform | Description |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| DRAGEN on-premises server | DRAGEN on-premises server offers highly accurate secondary analysis in a fraction of time compared with a traditional CPU-based system.
- Analyze and store data locally
- Supports varying levels of command line interface
- Replace up to 30 traditional compute instances
- Fully process a 34× whole human genome in \~30 minutes. (1)
- One unit supports two NovaSeq 6000 Systems running at full capacity
|
| DRAGEN analysis on Illumina Connected Analytics | Couples the accuracy and speed of the DRAGEN with the ability to customize analysis pipeline to operationalize informatics on a secure platform. |
| DRAGEN on BaseSpace Sequence Hub (BSSH) | Push button analysis capability in an intuitive, easy-to-use interface with compliance, and storage features of BaseSpace Sequence Hub and Amazon Web Services (AWS). |
| DRAGEN onboard NovaSeq X Series | - Flexibly runs multiple secondary analysis pipelines in parallel.
- Performs up to four simultaneous applications per flow cell in a single run.
- Brings up to 5x lossless data compression, and analysis with supported applications
- Provides savings on analysis, which over five years can exceed the price of the sequencer
|
| DRAGEN onboard NextSeq 1000 and NextSeq 2000 Systems | - Provides access to select DRAGEN analysis informatics pipelines
- Enables users to generate results in as little as two hours
- Uses intuitive pipeline algorithms to reduce reliance on external informatics experts
|
| DRAGEN onboard MiSeq i100 Series | Intuitive, ultra-rapid analysis including DRAGEN BCL convert, DRAGEN Library QC, DRAGEN small WGS and DRAGEN Microbial Enrichment Plus.
- Rapid results with comprehensive secondary analysis generated in two hours or less (2)
- Highly efficient workflow with a single user touchpoint to VCF and/or html report and no intermediate file transfers
- Exceptionally easy with an intuitive interface for non-expert users
|
| DRAGEN on AWS, Azure | DRAGEN supports the FPGA enabled instance types of AWS, Azure. Rpm installers and the Kernel driver can be installed on images managed by the user, and DRAGEN can be run by purchasing a license. |
| DRAGEN on AWS and Azure Marketplace | Pre-configured Amazon Machine Images (AMI) and Azure Virtual Machines with DRAGEN installed can be accessed from the respective marketplace offerings in a Pay-As-You-Use model. |
| DRAGEN on GCP | DRAGEN is made available on the Google Cloud Platform. Pre-configured instances with DRAGEN installed can be accessed through the GCP application interface. Limited availability. Please reach out to your Illumina representative for access. |
> (1) HG002 from PrecisionFDA truth challenge V2 run with DRAGEN analysis v4.0 on DRAGEN server v4, all callers
> (2) When run according to sample recommendations
# DRAGEN v4.5
# Getting Started
DRAGEN provides tests you can run to make sure that your DRAGEN system is properly installed and configured. Before running the tests, make sure that the DRAGEN server has adequate power and cooling, and is connected to a network that is fast enough to move your data to and from the machine with adequate performance.
Please refer to the [Server Site Prep & Installation Guide](https://support.illumina.com/downloads/illumina-dragen-server-site-prep-guide.html) when installing a new system.
## On-premises Installation
The software can be installed on an on-premises server by executing the .run installer for the desired version. Installers are made available for all releases at the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/downloads.html).
Installation procedure:
* Download the desired installer from the support website and unzip the package
* The archive integrity can be checked using: `./ --check`
* Install the appropriate release based on your Linux OS with the command: `sudo sh `
The .run file includes a script that administers un-installation of an existing software, integrity checking of the package and files, installation of the new DRAGEN software version. The DRAGEN software is installed in part by use of the Linux RPM Package Manager (rpm). Several rpm packages comprise the installation of a single DRAGEN software version. The RPM packages also configure the system for dragen, like raised user `ulimits`, and the .run script starts services needed for functionality, such as the Licensing daemon `dragen_licd`, and the hugepages daemon, `dragend_hp`.
> NOTE: Root privileges are required for the installation.
### Single Version Installation
Up to DRAGEN Software v4.2, only one version of the DRAGEN software can be installed at a time. Executing the .run file will remove any existing installed version and (re)install the new version.
After installation, the application and associated files are available at `/opt/edico`.
The single version installer will add `/opt/edico` to the Linux $PATH, so that the user can just call `dragen` without specifying the full path.
### Multi-Version Installation
Starting with DRAGEN Software v4.3 and later, multiple compatible versions of the DRAGEN software can be installed at a time. Executing the .run file will add the new version to the system.
After installation, the application files are available at `/opt/dragen/{version}/bin` and FPGA files are located at `/opt/bitstream/{bitstream version}`.
The multi-version installer will NOT add `/opt/dragen/{version}/bin` to the Linux $PATH, since multiple versions can be present at a given time. User should manage the desired paths to the specific version they want to run. When this guide provides command line examples, it will assume that the Linux $PATH is set to correct dragen version, and we will just refer to `dragen `
Notes on multi-version installation:
* Installers released for DRAGEN v4.2 and earlier are single version packages
* Single version packages and multi-version packages can not be mixed
* Installation of a prior single version package will remove all the multi-version packages
* Installation of a multi-version package will remove any installed single version package
* After installing a multi-version package, see a list of installed versions at any time by running `/usr/bin/dragen_versions`
* To remove any multi-version package, call `yum remove` on its Path
* Adding PATH="/opt/dragen/{version}/bin:$PATH" to the last line of .bashrc file avoids the need to set the path upon each server login
Example:
```
$ dragen_versions
The output format of this command may change. Use --json for machine readable output.
Dragen Version Size (MB) Install Date Path
4.3.2 1378.03 2024-03-10 18:26:17 /opt/dragen/4.3.2
4.4.3 1381.41 2024-03-18 20:56:39 /opt/dragen/4.4.3
4.3.5 1379.25 2024-03-11 15:20:24 /opt/dragen/4.3.5
Bitstream Version Size (MB) Install Date Path
07.031.732 (0x18101306) 598.95 2024-03-10 18:26:03 /opt/bitstream/07.031.732
07.031.745 (0x18101306) 598.95 2024-03-18 20:56:18 /opt/bitstream/07.031.745
To remove a dragen version, call `yum remove` on its Path.
```
### Location of `dragen` and resource files
| DRAGEN Version | on-premises server | cloud instance |
| --------------- | ----------------------- | -------------- |
| 4.3 and later | `/opt/dragen/{version}` | `/opt/edico/` |
| 4.2 and earlier | `/opt/edico/` | `/opt/edico/` |
Throughout this guide we will refer to `` which will be either of the locations above
## Licensing
DRAGEN requires license(s) for most functionality, please refer to the [Licensing Reference Section](/dragen-v4.5/reference/licensing) for guidance on how to install and/or review your current licenses.
## Running the System Check
After turning on the server, you can make sure that your DRAGEN server is functioning properly by running `/self_test/self_test.sh`, which does the following:
* Automatically indexes chromosome M from the hg19 reference genome
* Loads the reference genome and index
* Maps and aligns a set of reads
* Saves the aligned reads in a BAM file
* Asserts that the alignments exactly match the expected results
Each server ships with the test input FASTQ data for this script, which is located in `/self_test`. The system check takes approximately 25--30 minutes.
The following example shows how to run the script and shows the output from a successful test.
```
$ /opt/dragen/4.3.4/self_test/self_test.sh
#############################################################
Logging to /var/log/dragen/self_test.1714627157_160164.0.details.log
Using dragen executables in /opt/dragen/4.3.4/bin
Using board(s): 0
#############################################################
Running tests for board 0 (u200)
Using scratch directory /tmp/self_test.4BO0pfPST9/0
-------------------------------------------------------------
Board 0 test 1, FPGA MEMORY TEST
Loading DIAG bitstream
Running fpga memory test, this will take ~13 minutes
Board 0 test 1, FPGA MEMORY TEST: PASS
-------------------------------------------------------------
Board 0 test 2, BAR REGISTER ACCESS
Board 0 test 2, BAR REGISTER ACCESS: PASS
-------------------------------------------------------------
Board 0 test 3, FPGA TEMP REG ACCESS
FPGA Temperature: 27C (Max Temp: 36C, Min Temp: 22C)
Board 0 test 3, FPGA TEMP REG ACCESS: PASS
-------------------------------------------------------------
Board 0 test 4, BOARD SERIAL # REG ACCESS
Serial Number: 2130069BM05V
Board 0 test 4, BOARD SERIAL # REG ACCESS: PASS
-------------------------------------------------------------
Board 0 test 5, DRAGEN GENOME LICENSE
Board 0 test 5, DRAGEN GENOME LICENSE: PASS
-------------------------------------------------------------
Board 0 test 6, CPLD DATE TEST
cpld date is n/a
Board 0 test 6, CPLD DATE TEST: PASS
-------------------------------------------------------------
Board 0 test 7, ENCRYPTION KEY EXISTENCE TEST
Board 0 test 7, ENCRYPTION KEY EXISTENCE TEST: PASS
-------------------------------------------------------------
Board 0 test 8, PARTIAL RECONFIGURATION
DNA-MAPPER: ok
RNA-MAPPER: ok
HMM: ok
ZIP: ok
UNZIP: ok
DIAG: ok
Board 0 test 8, PARTIAL RECONFIGURATION: PASS
-------------------------------------------------------------
Board 0 test 9, HASH TABLE GENERATION
Board 0 test 9, HASH TABLE GENERATION: PASS
-------------------------------------------------------------
Board 0 test 10, MAP AND ALIGNER
running mapper aligner: ok
unmapped input records percentages: ok
md5sum check dbam sorted: pass
Board 0 test 10, MAP AND ALIGNER: PASS
-------------------------------------------------------------
Board 0 test 11, VARIANT CALLER E2E
running variant caller: ok
md5sum check dbam sorted: ok
md5sum check VCF: ok
Board 0 test 11, VARIANT CALLER E2E: PASS
#############################################################
SELF TEST COMPLETED
SELF TEST RESULT : PASS
#############################################################
Log file at /var/log/dragen/self_test.1714627157_160164.0.details.log
```
If the output BAM file does not match expected results, then the last line of the above text is as follows:
`SELF TEST RESULT : FAIL`
If you experience a FAIL result after running this test script immediately after turning on your DRAGEN server, contact Illumina Technical Support.
## Running Your Own Test
When you are satisfied that your DRAGEN system is performing as expected, you are ready to run some of your own data through the machine, as follows:
* Load the reference table for the reference genome
* Determine location of input and output files
* Process input data
### Loading the Reference Genome
Before a reference genome can be used with DRAGEN, it must be converted from FASTA format into a custom binary format for use with the DRAGEN hardware. For more information, see [Prepare a Reference Genome](/dragen-v4.5/product-guides/dragen-v4.5/dragen-reference-support/prepare-a-reference-genome).
The reference hash table specified on the command line is automatically loaded onto the board the first time you process data with a pipeline. You can manually load the hash table for your reference genome by using the following command:
`dragen -r `
Make sure that the reference hash table directory is on the fast file IO drive.
The default location for the hash table for hg19 is as follows.
`/staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149`
The command to load reference genome hg19 from the default location is as follows.
`dragen -r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149`
This command loads the binary reference genome into memory on the DRAGEN board, where it is used for processing any number of input data sets. You do not need to reload the reference genome unless you restart the system or need to switch to a different reference genome. It can take up to a minute to load a reference genome.
DRAGEN checks whether the specified reference genome is already resident on the board. If it is, then the upload of the reference genome is automatically skipped. You can force reloading of the same reference genome using the `force-load-reference (-l)` command line option.
The command to load the reference genome prints the software and hardware versions to standard output. For example:
```
DRAGEN Host Software Version 01.001.035.01.00.30.6682 and
Bio-IT Processor Version 0x1001036
```
After the reference genome has been loaded, the following message is printed to standard output:
```
DRAGEN finished normally
```
### Determine Input and Output File Locations
The DRAGEN Pipeline is very fast, which requires careful planning for the locations of the input and output files. If the input or output files are on a slow file system, then the overall performance of the system is limited by the throughput of that file system. It is recommended that inputs and outputs are streamed directly from/to a mounted external storage system.
The DRAGEN system is preconfigured with at least one fast file system consisting of a set of fast SSD disks grouped with RAID-0 for performance. This file system is mounted at `/staging`. This name was chosen to emphasize the fact that this area was built to be large and fast, but is not redundant. Failure of any of the file system's constituent disks leads to the loss of all data stored there.
During processing, DRAGEN generates and reads back temporary files. With DRAGEN, it is highly recommended to always direct temporary files to the fast SSD (or `/staging`) by using the `--intermediate-results-dir` option. If the `--intermediate-results-dir` option is not provided, temporary files are written to the `--output-directory`. DRAGEN recommends streaming inputs and outputs using an mounted external storage system.
### Process Your Input Data
To analyze FASTQ data, use the dragen command. For example, the following command can be used to analyze a single-ended FASTQ file:
```
dragen \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-1 /staging/test/data/SRA056922.fastq \
--output-directory /staging/test/output \
--output-file-prefix SRA056922_dragen \
--RGID DRAGEN_RGID \
--RGSM DRAGEN_RGSM
```
For detailed information on the command line options, see [DRAGEN Host Software](/dragen-v4.5/product-guides/dragen-v4.5/dragen-host-software).
For recommended command lines in typical use cases, see [DRAGEN Recipes](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes).
# DRAGEN Host Software
You use the DRAGEN host software program *dragen* to build and load reference genomes, and then to analyze sequencing data by decompressing the data, mapping, aligning, sorting, duplicate marking with optional removal, and variant calling.
Invoke the software using the *dragen* command. The command line options are described in the following sections.
Command line options can also be set in a configuration file. For more information on configuration files, see [Configuration Files](#configuration-files) . If an option is set in the configuration file and is also specified on the command-line, the command line option overrides the configuration file.
## Command-line Options
The following are examples of frequently used command lines:
* Build Reference/Hash Table
```
dragen --build-hash-table true --ht-reference \
--output-directory [options]
```
* Run Map/Align and Variant Caller (\*.fastq to \*.vcf)
```
dragen -r --output-directory \
--output-file-prefix [options] -1 \
[-2 ] --RGID --RGSM --enable-variant-caller true
```
* Run Map/Align (\*.fastq to \*.bam)
```
dragen -r --output-directory \
--output-file-prefix [options] \
-1 [-2 ] \
--RGID --RGSM
```
* Run Variant Caller Only (\*.bam to \*.vcf)
```
dragen -r --output-directory \
--output-file-prefix [options] -b \
--enable-map-align false \
--enable-variant-caller true
```
* Re-map and Run Variant Caller (\*.bam to \*.vcf)
```
dragen -r --output-directory \
--output-file-prefix [options] -b \
--enable-map-align true \
--enable-variant-caller true
```
* Run BCL Converter (BCL to \*.fastq)
```
dragen --bcl-conversion-only true --bcl-input-directory \
--output-directory
```
* Run RNA Map/Align (\*.fastq to \*.bam)
```
dragen -r --output-directory \
--output-file-prefix [options] -1 \
[-2 ] --enable-rna true
```
For recommended command lines in typical use cases, see [DRAGEN Recipes](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes).
### Reference Genome Options
Before you can use the DRAGEN system for aligning reads, you must load a reference genome and its associated hash tables onto the PCIe card. For information on preprocessing a reference genome's FASTA files into the native DRAGEN binary reference and hash table formats, see [Prepare a Reference Genome](/dragen-v4.5/product-guides/dragen-v4.5/dragen-reference-support/prepare-a-reference-genome). You must also specify the directory containing the preprocessed binary reference and hash tables with the `-r [or --ref-dir]` option. This argument is always required.
Use the following command to load the reference genome and hash tables to DRAGEN card memory separately from processing reads.
`dragen -r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149`
Use the `-l (--force-load-reference)` option to force the reference genome to load even if it is already loaded.
`dragen -l -r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149`
The time needed to load the reference genome depends on the size of the reference, but for typical recommended settings, it takes approximately 30--60 seconds.
### Operating Modes
DRAGEN has two primary modes of operation, as follows:
* Mapper/aligner
* Variant caller
DRAGEN is capable of performing each mode independently or as an end-to-end solution. DRAGEN also allows you to enable and disable decompression, sorting, duplicate marking, and compression along the DRAGEN pipeline.
* **Full pipeline mode** To execute full pipeline mode, set `--enable-variant-caller` to `true` and provide input as unmapped reads in \*.fastq, \*.bam, or \*.cram formats. DRAGEN performs decompression, mapping, aligning, sorting, and optional duplicate marking and feeds directly into the variant caller to produce a VCF file. In this mode, DRAGEN uses parallel stages throughout the pipeline to drastically reduce the overall run time.
* **Map/align mode** Map/align mode is enabled by default. Input is unmapped reads in \*.fastq, \*.bam, or \*.cram format. DRAGEN produces an aligned and sorted BAM or CRAM file. To mark duplicate reads at the same time, set `‑-enable‑duplicate‑marking` to `true`.
* **Variant caller mode** To execute variant caller mode, set the `--enable-variant-caller` option to true, and set `--enable-map-align` option to false. The input must be a mapped and aligned BAM/CRAM file. DRAGEN produces a VCF file. DRAGEN will force-enable re-sorting of the BAM, because a number of read statistics and estimates are required for the Variant Caller to operate effectively. Setting `--enable-sort` to `false` will be overridden. BAM files cannot be duplicate marked in the DRAGEN pipeline prior to variant calling if they have not already been marked. Use the end-to-end mode of operation to take advantage of the mark-duplicates feature.
* **RNA-Seq data** To enable processing of RNA-Seq--based data, set `--enable-rna` to `true`. DRAGEN uses the RNA spliced aligner during the mapper/aligner stage. DRAGEN dynamically switches between the required modes of operation..
* **Bisulfite MethylSeq data** To enable processing of Bisulfite MethylSeq data, set the `--enable-methylation-calling` option to true. DRAGEN automates the processing of data for Lister (directional) and Cokus (nondirectional) protocols to generate a single BAM with bismark-compatible tags. Alternatively, you can run DRAGEN in a mode that produces a separate BAM file for each combination of the C->T and G->A converted reads and references. To enable this mode of processing, you need to build a set of reference hash tables with `--ht-methylated` enabled, and run DRAGEN with the appropriate `‑‑methylation-protocol` setting.
### Output Options
The following command line options for output are mandatory:
* `--output-directory `—Specifies the output directory for generated files.
* `--output-file-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. The user can control the output format from the map/align stage with the `--output-format ` option. If the output file exists, the software 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.
#### 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.
DRAGEN can also annotate additional information about alignments in a ZS:Z tag. 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. |
| `ZS:Z:NRD` | Alignment is to an auto-added decoy contig (not present in input FASTA). |
| `ZS:Z:PAI` | Alignment is to an insertion encoded in a population based alternate contig (not present in input FASTA). |
By default, DRAGEN writes a ZS:Z:PAI tag in the output BAM for alignments that map completely inside insertions encoded in population based alternate contigs. To write ZS:Z alignment status tags for all other types described above, set `--generate-zs-tags` to true (false by default). 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).
To generate SA:Z tags, set `--generate-sa-tags` to true (the default). These 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 by default for DNA, true for RNA). The pair score is used in DRAGEN for computing MAPQ and can be used to check how well alignment candidate pairs 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 (this is the default). To generate the mate mapping quality (in the MQ:i) tag, set `--generate-mq-tags` to true (this 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 (default is false) and set `--generate-q2-tags` to true (default is false) respectively. Please note that when enabled, R2:Z and Q2:Z tags are emitted only for improperly paired read alignments with fragment length atleast 1000 bp. Also, our methylation pipelines currently do not support the output of mate alignment tags.
DRAGEN also outputs a graph alignment tag ga:Z `--generate-ga-tags` (true by default for DNA, false for RNA) when applicable. This tag is used to describe the best alt contig alignment which improved the score of a primary-contig alignment at its liftover position. It can also be used to describe read alignments to alt contigs for which there is no liftover and the primary alignment is unmapped. For example, cases when the read maps best to an alt contig describing a novel long-insertion that is not present in the reference. In addition, read alignments that have been marked as unmapped because they map to auto-detected decoy contigs not present in the original user-provided FASTA also have their alignments described in the ga tag.
The ga tag uses the same format as the SA tag used to describe supplementary alignments.
#### CRAM Output
When CRAM is selected as output, DRAGEN generates a CRAM file with the following features:
* CRAM format V3.0 is produced by default, V3.1 can be enabled by using the option --cram-version 3.1
* The CRAM is lossless. Lossy compression is never employed and not optional
* Quality score compression is lossless. Read names are preserved
* Only the GZIP compression algorithm is employed for maximum compatibility. bgzip, lzma not employed. rANS is used for quality scores
* All input BAM tags are preserved
* The reference used to compress the CRAM file, is the DRAGEN Hash Table provided during the map/align run. When decompressing the CRAM with a FASTA file and 3rd party tools, the FASTA that was used to generate the Hash Table must be used. Refer to the Reference Files table in [Illumina DRAGEN Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html) to find the correct FASTA file.
* A CRAM index is produced in .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 | 2000 | 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 use non-referenced based encoding |
| 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 |
| cram\_version | 3.0 | Default is CRAM v3.0. |
### Input Options
DRAGEN can process reads in FASTQ format or BAM/CRAM format. DRAGEN supports the following compression options for FASTQ input files.
* Uncompressed
* gzip or bgzip compression
* ORA compression. To use ORA compression, you must provide an ORA reference and reference directory. See ORA Compression and Decompression.
If your input FASTQ files are gzipped, DRAGEN automatically decompresses the files using hardware-accelerated decompression, and then streams the reads into the mapper. If your files end in \*.ora, DRAGEN automatically decompresses the files using ORA decompression, and then streams the reads into the mapper. The same FASTQ command-line options apply for all compression formats.
#### FASTQ Input Files
FASTQ input files can be single-ended or paired-end, as shown in the following examples.
* Single-ended in one FASTQ file (-1 option)
```
dragen -r -1 \
--output-directory -output-file-prefix \
--RGID --RGSM
```
* Paired-end in two matched FASTQ files(-1 and -2 options)
```
dragen -r -1 -2 \
--output-directory --output-file-prefix \
--RGID --RGSM
```
* Paired-end in a single interleaved FASTQ file(`--interleaved (-i)` option)
```
dragen -r -1 -i \
--RGID --RGSM
```
Both bcl2fastq and the DRAGEN BCL command use a common file naming convention, as follows:
`_S<#>___.fastq.gz`
Older versions of bcl2fastq and DRAGEN could segment FASTQ samples into multiple files to limit file size or to decrease the time to generate them.
For Example:
```
RDRS182520_S1_L001_R1_001.fastq.gz
RDRS182520_S1_L001_R1_002.fastq.gz
...
RDRS182520_S1_L001_R1_008.fastq.gz
```
These files do not need to be concatenated to be processed together by DRAGEN. To map/align any sample, provide the first file in the series (`-1 _001.fastq`). DRAGEN reads all segment files in the sample consecutively for both of the FASTQ file sequences specified using the -1 and -2 options for paired-end input and for compressed fastq.gz files. To turn the behavior off, set `‑‑enable-auto-multifile` to false on the command line.
DRAGEN can also optionally read multiple files by the sample name given in the file name, which can be used to combine samples that have been distributed across multiple BCL lanes or flow cells. To enable this feature, set the `--combine-samples-by-name` option to true
If the FASTQ files specified on the command-line use the Casava 1.8 file naming convention shown above and additional files in the same directory share that sample name, those files and all their segments are processed automatically. Note that sample name, read number, and file extension must match. Index barcode and lane number can differ.
To avoid impacting system performance, input files must be located on a fast file system.
**Note** The `--combine-samples-by-name` option is not functional since dragen v4.3. It is recommended to use the fastq-list input option instead.
#### Multiple FASTQ Input Files
To process multiple FASTQ input files as one sample, it is recommended that you use the `--fastq-list ` option to specify the name of a CSV file containing the list of FASTQ files, instead of using the `--combine-samples-by-name` option.
For example:
```
dragen -r --fastq-list \
-fastq-list-sample-id -output-directory
--output-file-prefix
```
Using a CSV file avoids having to concatenate the FASTQ files, for cases where there are multiple FASTQ files for a sample such as top-up scenarios or where FASTQ files are split across lanes. It also allows you to name the FASTQ input files, input from multiple subdirectories, and add BAM tags specified explicitly for each read group. DRAGEN automatically generates a CSV file of the correct format during BCL conversion to FASTQ. The CSV file is named `fastq_list.csv` and contains an entry for each FASTQ file or paired-end file pair produced during the run.
**FASTQ CSV File Format**
The first line of the CSV file specifies the title of each column, and is followed by one or more data lines. All lines in the CSV file must contain the same number of comma-separated values and should not contain white space or other extraneous characters.
Column titles are case-sensitive. The following column titles are required:
* RGID--Read Group
* RGSM--Sample ID
* RGLB--Library
* Lane--Flow cell lane
* Read1File--Full path to a valid FASTQ input file
* Read2File--Full path to a valid FASTQ input file. Required for paired-end input. If not using paired-end input, leave empty.
Each FASTQ file referenced in the CSV list can be referenced only once. All values in the Read2File column must be either nonempty and reference valid files, or they must all be empty.
When generating a BAM file using fastq-list input, one read group is generated per unique RGID value. The BAM header contains RG tags for the following read groups:
* ID (from RGID)
* SM (from RGSM)
* LB (from RGLB)
You can specify additional tags for each read group by adding a column title. The column title must be only four upper-case characters and begin with RG. For example, to add a PU (platform unit) tag, add a column named RGPU and specify the value for each read group in this column. All column titles must be unique.
A fastq-list file can contain files for more than one sample. If a fastq-list file contains only one unique RGSM entry, then no additional options need to be specified, and DRAGEN processes all files listed in the fastq-list file. If there is more than one unique RGSM entry in a fastq-list file, `--fastq-list-sample-id ` must be used in addition to `--fastq-list ` to process only a specific sample from the CSV file. Only the entries in the fastq-list file with an RGSM value that match the specified SampleID are processed.
* Independent processing and output for multiple individual samples in one run is not supported.
* To process all listed files together as one sample, regardless of the RGSM value, the option `--fastq-list-all-samples=true` can be used instead of `--fastq-list-sample-id`.
Note
For a single run, only one BAM and VCF output file are produced because all input read groups are expected to belong to the same sample. To process multiple samples independently from one BCL conversion run, DRAGEN must be run multiple times using different values for the \`--fastq-list-sample-id\` option.
There is no option to specify groupings or subsets of RGSM values for more complex filtering, but the fastq-list file can be modified to achieve the same effect.
The following is an example FASTQ list CSV file with the required columns:
```
RGID,RGSM,RGLB,Lane,Read1File,Read2File
CACACTGA.1,RDSR181520,UnknownLibrary,1,/staging/RDSR181520_S1_L001_R1_001.fastq,
/staging/RDSR181520_S1_L001_R2_001.fastq
AGAACGGA.1,RDSR181521,UnknownLibrary,1,/staging/RDSR181521_S2_L001_R1_001.fastq,
/staging/RDSR181521_S2_L001_R2_001.fastq
TAAGTGCC.1,RDSR181522,UnknownLibrary,1,/staging/RDSR181522_S3_L001_R1_001.fastq,
/staging/RDSR181522_S3_L001_R2_001.fastq
AGACTGAG.1,RDSR181523,UnknownLibrary,1,/staging/RDSR181523_S4_L001_R1_001.fastq,
/staging/RDSR181523_S4_L001_R2_001.fastq
```
If you use the `--tumor-fastq-list` option for somatic input, use the `--tumor-fastq-list-sample-id SampleID>` option to specify the sample ID for the corresponding FASTQ list, as shown in the following example:
```
dragen -r --tumor-fastq-list \
--tumor-fastq-list-sample-id \
--output-directory \
--output-file-prefix --fastq-list \
--fastq-list-sample-id
```
**Tumor-Normal Pairs Input**
If using fastq\_lists or tumor\_fastq\_lists comprising of multiple samples (RGSMs) in somatic mode, you can use a loop to iterate through the two lists to create tumor-normal pairs for testing. Create a \*.txt file with the RGSM of each normal sample to be tested (one per line), and then create a separate \*.txt file with the RGSM of the tumor samples to be tested. Make sure that the tumor sample RGSM is listed in the same order as the corresponding normal samples and to include a blank line after the last sample.
You can use the following example script to perform testing in somatic mode. Each iteration takes one entry from the tumor samples list and one entry from the normal samples list (from top to bottom) to create a tumor-normal pair as input for the DRAGEN run.
```
#!/bin/bash
HT="/staging/HT/"
tumor_fastq_list="/staging/inputs/tumor_fastq_list.csv"
normal_fastq_list="/staging/inputs/normal_fastq_list.csv"
tumor_samples_list="/staging/inputs/tumor_samples_list.txt"
normal_samples_list="/staging/inputs/normal_samples_list.txt"
while read -u 3 -r tumor_RGSM && read -u 4 -r normal_RGSM; do
output_dir="/staging/results/${tumor_RGSM}_${normal_RGSM}"
mkdir -p ${output_dir}
dragen \
-r ${HT} \
--tumor-fastq-list ${tumor_fastq_list} \
--tumor-fastq-list-sample-id ${tumor_RGSM} \
--fastq-list ${normal_fastq_list} \
--fastq-list-sample-id ${normal_RGSM} \
--output-directory ${output_dir} \
--output-file-prefix ${tumor_RGSM}_${normal_RGSM}
done 3<${tumor_samples_list} 4<${normal_samples_list}
```
```
Sample fastq_list.csv content:
RGPL,RGID,RGSM,RGLB,Lane,Read1File,Read2File
DRAGEN_RGPL,DRAGEN_RGID_N1.1,normal-1,ILLUMINA,1,/staging/inputs/normal-1_S1_L001_R1_001.fastq.gz,/staging/inputs/normal-1_S1_L001_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_N1.2,normal-1,ILLUMINA,2,/staging/inputs/normal-1_S1_L002_R1_001.fastq.gz,/staging/inputs/normal-1_S1_L002_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_N2.1,normal-2,ILLUMINA,1,/staging/inputs/normal-2_S1_L001_R1_001.fastq.gz,/staging/inputs/normal-2_S1_L001_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_N2.2,normal-2,ILLUMINA,2,/staging/inputs/normal-2_S1_L002_R1_001.fastq.gz,/staging/inputs/normal-2_S1_L002_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_N3.1,normal-3,ILLUMINA,1,/staging/inputs/normal-3_S1_L001_R1_001.fastq.gz,/staging/inputs/normal-3_S1_L001_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_N3.2,normal-3,ILLUMINA,2,/staging/inputs/normal-3_S1_L002_R1_001.fastq.gz,/staging/inputs/normal-3_S1_L002_R2_001.fastq.gz
```
The following are examples of the FASTQ lists and samples lists used as input for the script.
```
Sample tumor_fastq_list.csv content:
RGPL,RGID,RGSM,RGLB,Lane,Read1File,Read2File
DRAGEN_RGPL,DRAGEN_RGID_T1.1,tumor-1,ILLUMINA,1,/staging/inputs/tumor-1_S1_L001_R1_001.fastq.gz,/staging/inputs/tumor-1_S1_L001_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_T1.2,tumor-1,ILLUMINA,2,/staging/inputs/tumor-1_S1_L002_R1_001.fastq.gz,/staging/inputs/tumor-1_S1_L002_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_T2.1,tumor-2,ILLUMINA,1,/staging/inputs/tumor-2_S1_L001_R1_001.fastq.gz,/staging/inputs/tumor-2_S1_L001_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_T2.2,tumor-2,ILLUMINA,2,/staging/inputs/tumor-2_S1_L002_R1_001.fastq.gz,/staging/inputs/tumor-2_S1_L002_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_T3.1,tumor-3,ILLUMINA,1,/staging/inputs/tumor-3_S1_L001_R1_001.fastq.gz,/staging/inputs/tumor-3_S1_L001_R2_001.fastq.gz
DRAGEN_RGPL,DRAGEN_RGID_T3.2,tumor-3,ILLUMINA,2,/staging/inputs/tumor-3_S1_L002_R1_001.fastq.gz,/staging/inputs/tumor-3_S1_L002_R2_001.fastq.gz
```
```
Sample normal_samples_list content
normal-1
normal-2
normal-3
```
```
Sample tumor_samples_list content
tumor-1
tumor-2
tumor-3
```
#### FASTQ ORA Input Files
You can use the same options as the other FASTQ input file types for ORA files. To use the ORA file, replace the FASTQ file name with the ORA file name and specify the ORA reference directory using `--ora-reference`.
See ORA Compression and Decompression for more information on ORA reference files.
The following command represents paired-end in two matched ORA FASTQ files (-1 and -2 options).
```
dragen -r -1 -2 \
--ora-reference \
--output-directory --output-file-prefix \
--RGID --RGSM
```
#### BAM Input Files
BAM files can be used as input to the mapper/aligner. By default, `--enable-map-align` is true. When a BAM file input is provided with map/align enabled, DRAGEN ignores any alignment or duplicate marking information contained in the input file, reads are re-mapped and the new alignments are fed downstream to the variant callers. Any existing flags in the input BAM are erased when reads are re-mapped. BAM re-mapping is supported for multiple BAM inputs at a time, such as in paired tumor-normal input to somatic variant calling. Outputting the re-mapped BAM(s) can be enabled by setting `--enable-map-align-output=true`.
Alternatively, existing alignments in the BAM file can be used as input to the variant callers by setting the `--enable-map-align` option to false.
If the input file contains paired-end reads, it is important to specify that the input data should be sorted so that pairs can be processed together. Other pipelines would require you to re-sort the input data set by read name. DRAGEN vastly increases the speed of this operation by pairing the input reads, and sending them on to the mapper/aligner when pairs are identified. Use the `--pair-by-name` option to enable or disable this feature (the default is true).
Specify single-ended input in one BAM file with the (`-b`) and `--pair-by-name=false` options, as follows:
```
dragen -r -b --output-directory \
--output-file-prefix --pair-by-name false
```
Specify paired-end input in one BAM file with the (`-b`) and `\--pair-by-name=true` options, as follows:
```
dragen -r -b --output-directory \
--output-file-prefix --pair-by-name true
```
#### CRAM Input
You can use CRAM files as input to the DRAGEN mapper/aligner and variant caller. The DRAGEN functionality available when using CRAM input is the same as when using BAM input. Supported CRAM input file formats are v3.0 and v3.1.
By default, the CRAM compressor and decompressor uses the DRAGEN reference specified with the `--ref-dir` option. CRAM compression is reference based, and the reference used for compression is not part of the CRAM file. Therefore, the CRAM input file must have been created with the same reference than what is provided to DRAGEN for the analysis.
DRAGEN supports the re-alignment of a CRAM input that was created with a different reference in one step. Re-aligning a CRAM file that was created with a different reference requires use of the `--cram-reference` option. This option will make the CRAM decompressor use the specified reference.
* `--cram-reference` can be either a fasta file, or a DRAGEN hash table folder.
* If pointing to a fasta file, the fasta .fai index file must be present next to the fasta file
* CRAM output will always be compressed using the `--ref-dir` reference
*Example: CRAM was created with hg19, re-analysis with hg38*
```
dragen -r --cram-input --output-directory \
--output-file-prefix --cram-reference
```
```
dragen -r --cram-input --output-directory \
--output-file-prefix --cram-reference
```
The following options are used for providing a CRAM input to either mapper/aligner or variant caller:
* `--cram-input`--The name and path for the CRAM file
* `--cram-input`--One usage example is paired-end input in a single CRAM file. In addition, set the `--pair-by-name option` to true.
```
dragen -r --cram-input --output-directory \
--output-file-prefix --pair-by-name true
```
**Multiple BAM or CRAM Input Files**
To provide multiple BAM input files, you can use the `--bam-list ` option to specify the name of a CSV file containing the list of BAM files. For example:
```
dragen -r --bam-list \
--output-directory --output-file-prefix
```
To provide multiple CRAM input files, you can use the `--cram-list ` option.
**BAM or CRAM CSV Input File Format**
The first line of the CSV file specifies the header containing the title for each column and each subsequent line is a data line. All lines in the CSV file must contain the same number of comma-separated values and should not contain white space or any other extraneous characters.
An example BAM CSV file:
```
BamFile
/path/to/bam/one
/path/to/bam/two
```
Column titles are case sensitive. The following column titles are required:
* BamFile -- path to BAM file
Please note that only the "BamFile" column is supported as this time. Extra fields may be specified in the CSV file but they will not be processed by DRAGEN.
CRAM CSV input follows the same format above, with "CramFile" as the column title instead.
Restrictions and Limitations:
DRAGEN bam-list and cram-list are intended to mirror manually merging BAM or CRAM files via a utility such as samtools or MergeSamFiles (Picard). As a result, using bam-list or cram-list is analogous to having a single merged BAM or CRAM input file. Please note that some callers (i.e. DRAGEN variant calling) are unable to process a bam-list or cram-list that is composed of input files containing multiple samples.
In the case where identical read group IDs appear across multiple files and you want to treat them as distinct read groups, you can use the `--prepend-filename-to-rgid=true` option to distinguish between read groups.
If enabled, the resulting output BAM or CRAM file will contain all read groups from the input BAM or CRAM files passed in the CSV list file.
**Tumor-Normal Pairs Input**
You can also use `--tumor-bam-list ` or `--tumor-cram-list ` when running with tumor-only or tumor-normal inputs to DRAGEN. The CSV file has the same format as the options described above.
#### BCL Input Files
BCL is the output format of Illumina sequencing systems. Under limited circumstances, DRAGEN can read directly from BCL for map-align operations, saving the time needed for conversion to FASTQ.
DRAGEN can read directly from BCL in the following circumstances:
* Only one lane is input as part of a run (specified on the command-line).
* The lane has only a single sample specified in the SampleSheet.csv file. When converting BCL to FASTQ is required, DRAGEN provides a BCL to FASTQ converter (see DRAGEN BCL Data Conversion).
The following example command is for BCL input with only one lane of input:
```
dragen --bcl-input-dir --bcl-only-lane -r \
--output-directory --output-file-prefix
```
For additional BCL conversion options, see Input File Types.
#### Handling of N bases
One of the techniques that DRAGEN uses to optimize handling sequences can lead to the overwriting the base quality score assigned to N base calls.
When you use the `--fastq-n-quality` and `--fastq-offset` options, the base quality scores are overwritten with a fixed base quality. The default values for these options are 2 and 33 to match the Illumina minimum quality of 35 (ASCII character ‘#’).
#### Read Names for Paired-End Reads
By a common convention, read names can include suffixes, such as `/1` or `/2`), which indicate the end of a pair the read represents. For BAM input using the `--pair-by-name` option, DRAGEN ignores these suffixes to find matching pair names. By default, DRAGEN uses the forward slash character as the delimiter for these suffixes and ignores the `/1` and `/2` when comparing names. By default, DRAGEN strips these suffixes from the original read names.
DRAGEN has the following options to control how suffixes are used:
* To change the delimiter character, for suffixes, use the `--pair-suffix-delimiter` option. Valid values for this option include forward-slash (/), dot (.), and colon (:).
* To preserve the entire name, including the suffixes, set `--strip-input-qname-suffixes` to false.
* To append a new set of suffixes to all read names, set `--append-read-index-to-name` to true. The delimiter is determined by the `--pair-suffix-delimiter` option. By default, the delimiter is a slash, so `/1` and `/2` are added to the names.
#### Gene Annotation Input Files
When processing RNA-Seq data, you can supply a gene annotations file by using the `--annotation-file` option. Providing this file improves the accuracy of the mapping and aligning stage (see \[Input Files]{.underline}). The file should conform to the GTF/GFF format specification and should list annotated transcripts that match the reference genome being mapped against. The similar GFF3 format is currently not supported, due to inconsistent contig naming between GENCODE and Ensembl. See the RNA user guide section for more details on potential issues and workarounds.
DRAGEN can take the SJ.out.tab file (see \[SJ.out.tab]{.underline}) as an annotations file to help guide the aligner in a two-pass mode of operation.
### Networked Streaming
#### AWS S3, Azure Blob Storage, and AWS Presigned URL Input Streaming
DRAGEN can stream input files directly from an AWS S3 bucket, Azure Blob storage account, or by using AWS presigned URLs (presigned URLs are not supported for Azure Blob storage at this time). With streaming, input files are not required to be downloaded locally prior to being processed. The files are streamed over the network directly into the DRAGEN processor.
Input streaming is most beneficial for large input files. DRAGEN supports input streaming for BAMs and compressed FASTQ files. For FASTQ files, input streaming can be used in all the configurations, including single-end FASTQs, paired-end FASTQs, and FASTQ lists.
Input streaming is supported for the following use cases:
* Mapping/aligning of FASTQ and BAM.
* Germline and somatic small variant calling from BAM (without remapping).
* Configuration files, including your [DRAGEN Cloud Credentials](/dragen-v4.5/reference/licensing/cloud_licensing#providing-credentials-via-license-credentials-file).
For other file types that are significantly smaller in size, download them locally before running the analysis.
**Streaming FASTQ Input Using AWS S3**
```
dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-1 s3://s3-bucket-name/path/to/object_1.fastq.gz \
-2 s3://s3-bucket-name/path/to/object_2.fastq.gz \
--RGID object_ID \
--RGSM sample_name \
--output-directory /staging/examples/ \
--output-file-prefix streaming
```
**Streaming FASTQ Input Using Azure Blob Storage Account**
```
AZ_ACCOUNT_NAME="storage-account-name" AZ_ACCOUNT_KEY="" dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-1 https://storage-account-name.blob.core.windows.net/path/to/object_1.fastq.gz \
-2 https://storage-account-name.blob.core.windows.net/path/to/object_2.fastq.gz \
--RGID object_ID \
--RGSM sample_name \
--output-directory /staging/examples/ \
--output-file-prefix streaming
```
**Streaming FASTQ Input Using Presigned URLs (for AWS only)**
```
dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-1 https://bucket-name.amazonaws.com/path/to/object_1.fastq.gz?querystring \
-2 https://bucket-name.amazonaws.com/path/to/object_2.fastq.gz?querystring \
--RGID object_ID \
--RGSM sample_name \
--output-directory /staging/examples/ \
--output-file-prefix streaming
```
**Streaming BAM Input Using AWS S3**
```
dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-b s3://s3-bucket-name/path/to/object_1.bam \
--output-directory /staging/examples/ \
--output-file-prefix streaming
```
**Streaming BAM Input Using Azure Blob Storage Account**
```
AZ_ACCOUNT_NAME="storage-account-name" AZ_ACCOUNT_KEY="" dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-b https://storage-account-name.blob.core.windows.net/path/to/object_1.bam \
--output-directory /staging/examples/ \
--output-file-prefix streaming
```
**Streaming BAM Input Using Presigned URLs (for AWS only)**
```
dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-b https://bucket-name.amazonaws.com/path/to/object_1.bam?querystring \
--output-directory /staging/examples/ \
--output-file-prefix streaming
```
#### Azure Blob Storage Output Streaming
DRAGEN can stream its output to an Azure Blob Storage Account Container. Output streaming is beneficial for large output files and for sharing results.
**Streaming output to Azure Blob Storage Account**
```
AZ_ACCOUNT_NAME="storage-account-name" AZ_ACCOUNT_KEY="" dragen -f \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-1 SRA056922.fastq \
--RGID object_ID \
--RGSM sample_name \
--output-directory https://storage-account-name.blob.core.windows.net/path/to/output \
--intermediate-results-dir /staging/examples \
--output-file-prefix streaming
```
#### Security and Permissions
To stream input files from cloud storage or write output to Azure Blob Storage, you must have permission to access the remote files.
**AWS S3 (input streaming only)**
S3 requires AWS authentication and credentials. The authentication should already be set up on the instance you are running, for example, via IAM policies. S3 output streaming is not supported.
**Azure Blob Storage Account**
Azure requires authentication and environment variables. DRAGEN supports two cases: (1) Using managed identities and (2) Storage account access keys.
To use managed identities you must run DRAGEN on an Azure instance. The instance must have `Contributor` permissions (read/write) on the Storage Account it wants to read and write to. If the instance has a single managed identity, only the `AZ_ACCOUNT_NAME=` environment variable is required. For multiple managed identities, you must also provide the `AZR_IDENT_CLIENT_ID=` environment variable, with the client id of the identity that can access your storage bucket. This can be found on the Azure Portal.
With storage account access keys, DRAGEN can write to an Azure bucket both on and off Azure instances. For this use case, find the [Storage Account Access Key](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json\&tabs=azure-portal) and set the environment variables `AZ_ACCOUNT_NAME=` and `AZ_ACCOUNT_KEY=`.
**Presigned URL (AWS only)**
An AWS presigned URL most likely has a query string attached to it, which provides the authentication credentials or necessary tokens to grant permission to the S3 bucket (e.g., `https://bucket-name.amazonaws.com/path/to/folder?querystring`). Currently, streaming input to DRAGEN Azure presigned URLs is not supported.
### Sample Sex
Use the `--sample-sex` command line option to control the sex karyotype input used in downstream components, such as variant callers. If a sample sex karyotype input is not specified using the command line, the sex karyotype is automatically determined. The sex karyotype input is converted to a reference sex karyotype for use in variant calling. Other components might support sex karyotype input. Refer to the corresponding section for the component you are using.
The `--sample-sex` option supports the following values. Values are not case-sensitive.
* `none`: No sex karyotype input. Components use a default reference sex karyotype.
* `auto`: The sex karyotype is estimated by the Ploidy Estimator. If using CNV calling, sex karyotype is determined using a separate sex estimation module. If DRAGEN cannot estimate the sex karyotype, then components do not have a sex karyotype input. This behavior is then the same as `none`. `auto` is the default value.
* `female`: Sex karyotype input is XX.
* `male`: Sex karyotype input is XY.
The following example command lines use `--sample-sex` to specify the sex karyotype.
```
--sample-sex FEMALE
--sample-sex MALE
--sample-sex NONE
```
If the value is `none`, `female`, or `male`, the Ploidy Estimator could still run and produce output, but variant callers will not use any estimated sex karyotype that is different than the sex karyotype provided via the command-line.
The sex karyotype input is converted to the reference sex karyotype for the different components as follows. See the relevant component section for more information on how `--sample-sex` is used.
#### Reference Sex Karyotype
| Sex Karyotype Input | CNV Caller | DRAGEN-STR | Ploidy Caller | Small Variant Caller | SV Caller |
| ------------------- | ---------: | ---------: | ------------: | -------------------: | --------: |
| X0 | XX | XY | XX | XXYY | XX |
| XX | XX | XX | XX | XX | XX |
| XXX | XX | XX | XX | XXYY | XX |
| XXXX | XX | XX | XX | XXYY | XX |
| XXXXX | XX | XX | XX | XXYY | XX |
| XY | XY | XY | XY | XY | XY |
| XXY | XY | XX | XY | XXYY | XY |
| XXXY | XY | XX | XY | XXYY | XY |
| XXXXY | XY | XX | XY | XXYY | XY |
| XYY | XY | XY | XY | XXYY | XY |
| XXYY | XY | XX | XY | XXYY | XY |
| XXXYY | XY | XX | XY | XXYY | XY |
| XYYY | XY | XY | XY | XXYY | XY |
| XXYYY | XY | XX | XY | XXYY | XY |
| XYYYY | XY | XY | XY | XXYY | XY |
| None | XX/XY | XX | XX/XY | XXYY | XXYY |
* For sex karyotype input of None, CNV/Ploidy Caller independently check the coverage ratio of X and Y to determine the reference sex karyotype. Detection of minimal Y coverage will yield XY, otherwise XX.
### Preservation or Stripping of BQSR Tags
The Picard Base Quality Score Recalibration (BQSR) tool produces output BAM files that include tags BI and BD. BQSR calculates these tags relative to the exact sequence for a read. If a BAM file with BI and BD tags is used as input to mapper/aligner with hard clipping enabled, the BI and/or BD tags can become invalid.
The recommendation is to strip these tags when using BAM files as input. To remove the BI and BD tags, set the `--preserve-bqsr-tags` option to false. If you preserve the tags, DRAGEN warns you to disable hard clipping.
### Read Group Options
DRAGEN assumes that all the reads in a given FASTQ belong to the same read group. DRAGEN creates a single @RG read group descriptor in the header of the output BAM file, with the ability to specify the following standard BAM attributes:
| Attribute | Argument | Description |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID | `--RGID` | Read group identifier. If you include any of the read group parameters, RGID is required. It is the value written into each output BAM record. |
| LB | `--RGLB` | Library. |
| PL | `--RGPL` | Platform/technology used to produce the reads. The BAM standard allows for values CAPILLARY, LS454, ILLUMINA, SOLID, HELICOS, IONTORRENT and PACBIO. |
| PU | `--RGPU` | Platform unit, eg, flowcell-barcode.lane. |
| SM | `--RGSM` | Sample. |
| CN | `--RGCN` | Name of the sequencing center that produced the read. |
| DS | `--RGDS` | Description. |
| DT | `--RGDT` | Date the run was produced. |
| PI | `--RGPI` | Predicted mean insert size. |
If any of these arguments are present, DRAGEN adds an RG tag to all the output records to indicate that they are members of a read group. The following example shows a command line that includes read group parameters:
```
dragen --RGID 1 --RGCN Broad --RGLB Solexa-135852 \
--RGPL Illumina --RGPU 1 --RGSM NA12878 \
-r /staging/human/reference/hg19/hg19.fa.k_21.f_16.m_149 \
-1 SRA056922.fastq --output-directory /staging/tmp/ \
--output-file-prefix rg_example
```
When using the `--fastq-list` option to input multiple read groups, BAM tags (and others) are specified for each read group by adding columns to the `fastq_list.csv` file. Each column heading consists of four capital letters and each begins with 'RG'. For each column, each read group's values for that column are propagated to the output BAM file in an identically named tag.
### License Options
To suppress the license status message at the end of the run, use the `--lic-no-print` option. The following shows an example of the license status message:
```
LICENSE_MSG| =====================================================
LICENSE_MSG| License report
LICENSE_MSG| Genome status [ACxxxxxxxxxxx] : used 1263.9 Gbases
since 2018-Feb-15 (1263886160894 bases, unlimited)
LICENSE_MSG| Genome bases [ACxxxxxxxxxxx] : 202000000
LICENSE_MSG| Genome bases [total] : 202000000
```
## Autogenerated MD5SUM for BAM and CRAM Output Files
An MD5SUM file is generated automatically for BAM and CRAM output files. The MD5SUM file has the same name as the output file, with an .md5sum extension appended (eg, whole\_genome\_run\_123.bam.md5sum). The MD5SUM file is a single-line text file that contains the md5sum of the output file, which exactly matches the output of the Linux md5sum command.
The MD5SUM calculation is performed as the output file is written, so there is no measurable performance impact (compared to the Linux md5sum command, which can take several minutes for a 30x BAM).
## Configuration Files
Command line options can be stored in a configuration file. The location of the default configuration file is `/config/dragen-user-defaults.cfg`. You can override this file by using the `--config-file (-c)` option to specify a different file. The configuration file used for a given run supplies the default settings for that run, any of which can be overridden by command line options.
The recommended approach is to use the dragen-user-defaults.cfg file as a template to create default settings for different use cases. Copy dragen-user-defaults.cfg, rename the copy, then modify the new file for the specific use-case. Best practice is to put options that rarely change into the configuration file and to specify options that vary from run to run on the command line.
## Licensing
DRAGEN utilizes quota based licensing for a majority of features. More information can be found in the [Licensing Reference Section](/dragen-v4.5/reference/licensing).
# DRAGEN Secondary Analysis
The DRAGEN secondary analysis software utilizes a highly reconfigurable Field Programmable Gate Array (FPGA) card and is available on a preconfigured DRAGEN server that can be seamlessly integrated into bioinformatics workflows. The platform can be loaded with highly optimized algorithms for many different NGS secondary analysis pipelines, including the following:
* Whole genome
* Exome
* RNA-Seq
* Methylome
* Cancer
All user interaction is accomplished via DRAGEN software that runs on the host server and manages all communication with the FPGA card. This user guide summarizes the technical aspects of the system and provides detailed information for all DRAGEN command line options. If you are working with DRAGEN for the first time, Illumina recommends that you first read the *Getting Started section*, which provides a short introduction to DRAGEN, including running a test of the server, generating a reference genome, and running example commands.
## DNA Pipeline
DRAGEN DNA Pipeline
The DRAGEN DNA Pipeline massively accelerates the secondary analysis of NGS data. For example, the time taken to process an entire human genome at 30x coverage is reduced from approximately 10 hours (using the current industry standard, BWA-MEM+GATK-HC software) to approximately 20 minutes. Time scales linearly with coverage depth.
These pipelines harness the tremendous power of the DRAGEN server and include highly optimized algorithms for mapping, aligning, sorting, duplicate marking, and haplotype variant calling. They also use platform features such as hardware-accelerated compression and optimized BCL conversion, together with the full set of platform tools.
Unlike all other secondary analysis methods, DRAGEN DNA Applications do not reduce accuracy to achieve speed improvements. Accuracy for both SNPs and INDELs is improved over that of BWA-MEM+GATK-HC in side-by-side comparisons.
In addition to haplotype variant calling, the pipeline supports calling of copy number and structural variants as well as detection of repeat expansions.
## RNA Pipeline
DRAGEN secondary anaylsis includes an RNA-seq (splicing-aware) aligner, as well as RNA-specific analysis components for gene expression quantification and gene fusion detection.
The DRAGEN RNA Pipeline shares many components with the DNA Pipeline. Mapping of short seed sequences from RNA-Seq reads is performed similarly to mapping DNA reads. In addition, splice junctions (the joining of noncontiguous exons in RNA transcripts) near the mapped seeds are detected and incorporated into the full read alignments.
DRAGEN secondary analysis uses hardware accelerated algorithms to map and align RNA-Seq--based reads faster and more accurately than popular software tools. For instance, it can align 100 million paired-end RNA-Seq--based reads in about three minutes. With simulated benchmark RNA-Seq data sets, its splice junction sensitivity and specificity are unsurpassed.
## Methylation Pipeline
The DRAGEN Methylation Pipeline provides support for automating the processing of bisulfite sequencing data to generate a BAM with the tags required for methylation analysis and reports detailing the locations with methylated cytosines.
# DRAGEN Apps
# DRAGEN Germline Enrichment Platform Core App
DRAGEN Germline Enrichment is an accurate and efficient end-to-end (FASTQ to VCF) secondary analysis solution for whole exome and targeted panel NGS data; it can be used for both germline and somatic variant calling. This app takes input files in FASTQ, ORA, BAM, and CRAM format. Files may be decompressed, go through Map/Align/Sort, and go through variant calling.
Before launching the app in [Platform Core](https://ica.illumina.com) the corresponding bundle containing the pipeline must be linked to your project. Follow the steps on the [Platform Core help site](https://help.ica.illumina.com/home/h-bundles#linking-an-existing-bundle-to-a-project) to link the DRAGEN bundle corresponding to the version and region you want to use (e.g. 'DRAGEN 4.5').
## In-run PON support for CNV and Targeted Caller
Version 4.4.4 of the DRAGEN Germline Enrichment App introduced support for automatic generation of an in-run PON for both CNV calling and the Targeted Caller. An in-run PON is required for Targeted Caller from WES data (see [Targeted Caller | Exome calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller#exome-calling-using-in-run-pon)), and is the preferred replacement for a pre-built PON for CNV calling (see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals)).
Use the following steps to run the DRAGEN Germline Enrichment App using an in-run PON:
1. In your project go to 'Pipelines' and search for 'DRAGEN\_Germline\_Enrichment'. Click on the DRAGEN Germline Enrichment pipeline corresponding to the version you want to use.
2. Click 'Start Analysis'
3. Under 'General' section enter the name for the analysis under the 'User reference' field.
4. Complete the 'Pricing' section.
5. Select FASTQs/BAMs/CRAMs for all samples in the sequencing run. At least 5 samples are required for CNV and at least 30 samples are required for Targeted Caller.
6. Click '+' in the 'Reference' field and select the Illumina DRAGEN References version corresponding to the DRAGEN version being used. The correct reference version can be found on the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html). For example, for DRAGEN 4.4 select 'Illumina DRAGEN v11 References'.
7. For human samples, select one of the supported pangenome reference TAR files containing 'graph' in the name and click 'Add'. Note that Targeted Caller only supports hg38, hg19 and hs37d5.
8. Click '+' in the 'Target BED File' field and select 'Illumina Enrichment BEDs' and then select the reference build selected previously.
9. Select the bed file corresponding to the library prep kit used. If the Illumina CS/PGx Custom Enrichment Research Panel was used, select 'Illumina\_Custom\_Enrichment\_Panel\_v2\_DRAGEN\_Targeted\_Calling.*\*.bed'
10. Do not select files for the 'CNV Panel of Normals' or 'CNV Combined Counts' fields. An in-run PON will be built instead.
11. In the 'Settings | Variant Calling Options' section select the 'true' radio button for the 'Enable CNV calling' field.
12. Select the 'true' radio button for the 'CNV Enable In-Run Panel of Normals' field.
13. If the Illumina CS/PGx Custom Enrichment Research Panel was used go to the 'Settings | Additional Options' section and select the 'true' radio button for the 'Enable Targeted Calling' field.
14. In the field 'Excluded Sample for In-Run Panel of Normals' list the name of any samples from the sequencing run that should not be included in the PON. Examples of samples that can be listed here include:
1. Samples that have not met QC requirements.
2. Related samples from a large pedigree consisting of more than \~6% of the total number of PON samples (e.g. more than quad for PON of size 50).
3. Samples that are known to not be copy-neutral in certain target regions of interest and would otherwise make up a large portion of the total PON samples.
15. The 'Samples Per Node' field defaults to 5. This value can be increased to reduce the cost overhead for spinning up more nodes, but will increase the total runtime. Decreasing this value will increase the cost overhead, but decrease the total runtime.
# DRAGEN Enrichment BSSH App
DRAGEN Enrichment is an accurate and efficient end-to-end (FASTQ to VCF) secondary analysis solution for whole exome and targeted panel NGS data; it can be used for both germline and somatic variant calling. This app takes input files in FASTQ, BAM, and CRAM formats. Files may be decompressed, go through Map/Align/Sort, and go through variant calling.
## In-run PON support for Germline CNV and Targeted Caller
Version 4.4.4 of the DRAGEN Enrichment BSSH App introduced support for automatic generation of an in-run PON for both CNV calling and the Targeted Caller. An in-run PON is required for Targeted Caller from WES data (see [Targeted Caller | Exome calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller#exome-calling-using-in-run-pon)), and is the preferred replacement for a pre-built PON for CNV calling (see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals)).
Use the following steps to run the DRAGEN Enrichment BSSH App on Germline WES data using an in-run PON:
1. Go to version 4.4.4 or later of the [DRAGEN Enrichment BSSH App](https://www.illumina.com/products/by-type/informatics-products/basespace-sequence-hub/apps/dragen-enrichment.html) on BaseSpace and click 'Launch Application'.
2. Set the Analysis Name and output Project.
3. Select FASTQs/BAMs/CRAMs for all samples in the sequencing run. At least 5 samples are required for CNV and at least 30 samples are required for Targeted Caller. Input file types cannot be mixed.
4. Make sure 'Variant Caller Mode' is 'Germline' and select a reference. For human samples, select one of the supported pangenome references. Note that Targeted Caller only supports hg38, hg19 and hs37d5.
5. Select the 'Targeted Regions' corresponding to the enrichment protocol for the sequencing run. For Targeted Caller the 'Illumina CS/PGx Custom Enrichment Research Panel' must be used.
6. Expand the 'CNV' section and check the box 'Enable CNV'. For data generated using the Illumina CS/PGx Custom Enrichment Research Panel, check the box 'Enable Targeted Calling'. 'Enable CNV' must be checked before checking the 'Enable Targeted Calling'.
7. Check the box 'Enable In-Run Panel of Normals'.
8. In the field 'In-Run Panel of Normals Excluded Samples' list any samples from the sequencing run that should not be included in the PON. Examples of samples that can be listed here include:
1. Samples that have not met QC requirements.
2. Related samples from a large pedigree consisting of more than \~6% of the total number of PON samples (e.g. more than quad for PON of size 50).
3. Samples that are known to not be copy-neutral in certain target regions of interest and would otherwise make up a large portion of the total PON samples.
9. Expand the 'Advanced Settings' section and set the 'Samples Per Node' field to 5. This value can be increased to reduce the cost overhead for spinning up more nodes, but will increase the total runtime. Decreasing this value will increase the cost overhead, but decrease the total runtime.
10. Click 'Launch Application'.
# DRAGEN Germline Enrichment from BCLs BSSH App
[DRAGEN Germline Enrichment from BCLs](https://www.illumina.com/products/by-type/informatics-products/basespace-sequence-hub/apps/dragen-germline-enrichment-from-bcls.html) provides accurate and efficient end-to-end (BCL to VCF) germline variant calling of whole exome and targeted panel NGS data. This app takes sequencing output in BCL format, converts them to FASTQs and then performs mapping and variant calling.
## In-run PON support for Germline CNV and Targeted Caller
An in-run PON is required for Targeted Caller from WES data (see [Targeted Caller | Exome calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller#exome-calling-using-in-run-pon)), and is the preferred replacement for a pre-built PON for CNV calling (see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals)). Given samples from a single sequencing run, the DRAGEN Germline Enrichment from BCLs app will generate the required PON files and use them to analyze each sample in the run. The analysis workflow may be started from a planned run using the Run Planning tool in BSSH or from an existing sequencing run by launching the DRAGEN Germline Enrichment from BCLs app on BSSH. The DRAGEN Germline Enrichment from BCls app does not allow any samples from the sequencing run to be excluded. As a workaround, the DRAGEN BCL Convert Application can be used through Run Planning tool to generate FASTQs and the FASTQs can be used with either the [DRAGEN Germline Enrichment Platform Core app](/dragen-v4.5/product-guides/dragen-v4.5/dragen-apps/dragen-germline-enrichment-platform-core-app) or the [DRAGEN Enrichment BSSH app](/dragen-v4.5/product-guides/dragen-v4.5/dragen-apps/dragen-enrichment-bssh-app).
## DRAGEN Germline Enrichment from BCls through Run Planning Tool
A new run can be configured in BaseSpace Sequence Hub using the Run Planning tool. Follow the steps for your sequencing system described on the [Basespace Sequence Hub Help Center | Plan Runs](https://help.basespace.illumina.com/sequence/plan-runs) page.
During the configuration stage, use the following steps to configure the run for DRAGEN Germline Enrichment:
1. In the 'Application' field select the desired version under 'DRAGEN Germline Enrichment'
2. Select the appropriate 'Library Prep Kit' for the samples being sequenced. If the Illumina CS/PGx Custom Enrichment Research Panel was used with Exome 2.5 then select 'Illumina DNA Prep with Exome 2.5 Enrichment'.
3. Select the 'Index Adapter Kit' for the samples being sequenced.
4. Click 'Next'.
5. Complete the [Analysis Settings](#analysis-settings) section.
6. Click 'Next'.
7. Click 'Save as Planned'.
## DRAGEN Germline Enrichment from BCLs from existing run
The DRAGEN Germline Enrichment from BCLs app can run from an existing sequencing run containing BCLs using the steps below.
1. Go to the [BaseSpace Sequence Hub Dashboard](https://basespace.illumina.com/dashboard) and click on the 'Apps' tab.
2. In the search bar enter 'DRAGEN Germline Enrichment From BCLs' and click on the app.
3. Make sure the version selected is 4.4.4 or newer and click 'Launch Application'
4. Select the sequencing run containing BCLs
5. If the Sample Sheet in the selected sequencing run is invalid or outdated there may be validation errors. In this case an 'Override Sample Sheet' must be selected. The 'Override Sample Sheet' can be exported from a run created using the [Run Planning tool](#dragen-germline-enrichment-from-bcls-from-existing-run) as described above. In the final step of the Run Planning tool, instead of clicking 'Save as Planned', click 'Export' to generate the Override Sample Sheet. Note that the Sample Sheet must first be uploaded to a project on BSSH before it can be selected in the app.
6. Click 'Edit' in the 'Configuration: DRAGEN Germline Enrichment' section.
7. Complete the [Analysis Settings](#analysis-settings) section.
8. Click 'Next'.
9. Click 'Requeue' to start the app.
### Analysis Settings
Follow the steps below to configure the analysis settings:
1. Select the 'Reference TAR'. For human samples, select one of the supported pangenome references. Note that Targeted Caller only supports hg38, hg19 and hs37d5.
2. Select the 'Panel BED'. If the Illumina CS/PGx Custom Enrichment Research Panel was used, select 'Illumina\_Custom\_Enrichment\_Panel\_v2\_DRAGEN\_Targeted\_Calling.*\*.bed'
3. Under 'DRAGEN copy number and targeted calling settings' select the 'In-Run' radio button for the 'CNV Baseline Source' field.
4. If the Illumina CS/PGx Custom Enrichment Research Panel was used select the 'Yes' radio button for the 'Enable targeted paralog calling' field.
# DRAGEN Recipes
### Overview
The following sub-pages contain recommended command line options for specific DRAGEN pipelines. For an overview of DRAGEN command line parsing, also see [Multicaller Workflows](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/multi-caller)
#### Germline Pipelines
* [DNA Germline Amplicon](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-germline-amplicon)
* [DNA Germline Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-germline-panel)
* [DNA Germline WES](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-germline-wes)
* [DNA Germline WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-germline-wgs)
* [5 Base DNA Germline Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-germline-panel)
* [5 Base DNA Germline WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-germline-wgs)
#### Germline with UMI Pipelines
* [DNA Germline Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-germline-panel-umi)
* [DNA Germline WES UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-germline-wes-umi)
* [5 Base DNA Germline Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-germline-panel-umi)
#### RNA and scRNA Pipelines
* [Illumina scRNA](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/illumina-scrna)
* [Illumina scRNA Perturb seq](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/illumina-scrna-perturb-seq)
* [Other scRNA prep](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/other-scrna-prep)
* [RNA Amplicon](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/rna-amplicon)
* [RNA Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/rna-panel)
* [RNA WTS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/rna-wts)
#### Somatic Pipelines
* [DNA Somatic Tumor-Normal Heme WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-heme-wgs)
* [DNA Somatic Tumor-Normal MRD](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-mrd)
* [DNA Somatic Tumor-Normal Solid Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-solid-panel)
* [DNA Somatic Tumor-Normal Solid WES](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-solid-wes)
* [DNA Somatic Tumor-Normal Solid WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-solid-wgs)
* [DNA Somatic Tumor-Only Heme WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-heme-wgs)
* [DNA Somatic Tumor-Only Solid Amplicon](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-amplicon)
* [DNA Somatic Tumor-Only Solid Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-panel)
* [DNA Somatic Tumor-Only Solid WES](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-wes)
* [DNA Somatic Tumor-Only Solid WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-wgs)
* [DNA Somatic Tumor-Only ctDNA Amplicon](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-ctdna-amplicon)
* [5 Base DNA Somatic Tumor-Normal Solid Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-somatic-tumor-normal-solid-panel)
* [5 Base DNA Somatic Tumor-Normal Solid WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-somatic-tumor-normal-solid-wgs)
* [5 Base DNA Somatic Tumor-Only Solid Panel](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-somatic-tumor-only-solid-panel)
* [5 Base DNA Somatic Tumor-Only Solid WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-somatic-tumor-only-solid-wgs)
#### Somatic with UMI Pipelines
* [DNA Somatic Tumor-Normal Solid Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-solid-panel-umi)
* [DNA Somatic Tumor-Normal Solid WES UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-solid-wes-umi)
* [DNA Somatic Tumor-Normal Solid WGS UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-normal-solid-wgs-umi)
* [DNA Somatic Tumor-Only Solid Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-panel-umi)
* [DNA Somatic Tumor-Only Solid WES UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-wes-umi)
* [DNA Somatic Tumor-Only Solid WGS UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-solid-wgs-umi)
* [DNA Somatic Tumor-Only ctDNA Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/dna-somatic-tumor-only-ctdna-panel-umi)
* [5 Base DNA Somatic Tumor-Only Solid Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-somatic-tumor-only-solid-panel-umi)
* [5 Base DNA Somatic Tumor-Only ctDNA Panel UMI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/5-base-dna-somatic-tumor-only-ctdna-panel-umi)
#### TruPath Pipelines
* [Illumina TruPath Genome WGS](/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/illumina-trupath-genome-wgs)
# DNA Germline Amplicon
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
--enable-duplicate-marking false #default=false
# Amplicon
--enable-dna-amplicon true
--amplicon-target-bed $PATH
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED #Optional. Auto-generated based on amplicon target bed.
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
# CNV
--enable-cnv true
--cnv-combined-counts $PATH #CNV PON. Required for amplicon CNV calling on CASE samples.
--cnv-target-bed $PATH #Optional. Auto-generated based on amplicon target bed.
--cnv-filter-qual $NUM #CNV filter quality. Adjust CNV filter quality thresholds according to the user’s validation study.
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ----------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Duplicate Marking
| Option | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking false` | The Amplicon Pipeline disables duplicate marking. In amplicon assays, fragments originate from a limited number of unique start and end positions, making conventional duplicate detection inappropriate. |
### SNV
DRAGEN amplicon does not employ machine learning based variant recalibration (DRAGEN-ML).
| 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) |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### CNV
Amplicon CNV requires PON input. In PON mode, the DRAGEN CNV Pipeline is broken down into two distinct stages. The target counts stage is performed on each sample (case and normals), to bin the alignments. The normalization and call detection stage is then performed with the case sample against the panel of normals to determine the events.
| Option | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cnv-segmentation-mode $SEG_MODE` | Option to override the default segmentation algorithm. By default, `bed` is used for standard panels and `hslm` for Pillar panels with a pre-built PON. |
| `--amplicon-cnv-use-default-pon false` | We recommend including in-run normal samples—matched in sample type and library preparation—in the same sequencing run to serve as the PON. If generating a custom PON is not feasible, for Pillar panels, the pre-packaged panel-specific PON can be used as a fallback. To enable this, set the option to true. |
| `--cnv-segmentation-bed $PATH` | You can bypass segmentation by specifying a cnv-segmentation-bed and using cnv-segmentation-mode=bed. If bed segmentation mode is used, the segmentation bed is auto-generated from amplicon target bed by default |
| `--cnv-filter-qual $NUM` | QUAL value at which to hard filter CNV VCF. You can adjust CNV filter quality thresholds according to the your validation study |
### In-run PON
For CNV PON requirements and generation options see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals).
**Step 1. Generate CNV target counts of individual samples from the sequencing run.**
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 pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# CNV
--enable-cnv true
--enable-dna-amplicon true
--amplicon-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 pangenome 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.
# DNA Germline Panel
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
--sv-exome true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON. See 'In-run PON' section below.
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### SNV
DRAGEN SNV VC employs machine learning based variant recalibration (DRAGEN-ML). It processes read and other contextual evidence to remove false positives, recover false negatives and reduce zygosity errors. No additional setup is required. DRAGEN-ML is enabled by default as needed, when running the germline SNV VC on hg19 or hg38.
Note that we do not recommend changing the default QUAL thresholds of 3 for DRAGEN-ML and 10 for DRAGEN without ML. These values differ from each other because DRAGEN-ML improves the calibration of QUAL scores, leading to a change in the scoring range.
| 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### 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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
### In-run PON
For CNV PON requirements and generation options see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals).
**Step 1. Generate CNV target counts of individual samples from the sequencing run.**
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 pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--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 pangenome 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.
# DNA Germline Panel 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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
--sv-exome true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON. See 'In-run PON' section below.
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### 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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/unique-molecular-identifiers#umi-options).
### SNV
DRAGEN SNV VC employs machine learning based variant recalibration (DRAGEN-ML). It processes read and other contextual evidence to remove false positives, recover false negatives and reduce zygosity errors. No additional setup is required. DRAGEN-ML is enabled by default as needed, when running the germline SNV VC on hg19 or hg38.
Note that we do not recommend changing the default QUAL thresholds of 3 for DRAGEN-ML and 10 for DRAGEN without ML. These values differ from each other because DRAGEN-ML improves the calibration of QUAL scores, leading to a change in the scoring range.
| 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### 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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
### In-run PON
For CNV PON requirements and generation options see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals).
**Step 1. Generate CNV target counts of individual samples from the sequencing run.**
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 pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--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 pangenome 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.
# DNA Germline WES
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
--sv-exome true
--sv-target-bed $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF #activates ASCN caller
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON. See 'In-run PON' section below.
# HLA genotyper
--enable-hla true
--hla-exome true #Set HLA output to 3 field resolution (coding sequence only)
# Targeted caller (only if using the Illumina CS/PGx Custom Enrichment Research Panel)
--enable-targeted true
--targeted-pon $PATH #Targeted PON. See 'In-run PON' section below.
--targeted-systematic-noise $PATH #Targeted systematic noise file
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### SNV
DRAGEN SNV VC employs machine learning based variant recalibration (DRAGEN-ML). It processes read and other contextual evidence to remove false positives, recover false negatives and reduce zygosity errors. No additional setup is required. DRAGEN-ML is enabled by default as needed, when running the germline SNV VC on hg19 or hg38.
Note that we do not recommend changing the default QUAL thresholds of 3 for DRAGEN-ML and 10 for DRAGEN without ML. These values differ from each other because DRAGEN-ML improves the calibration of QUAL scores, leading to a change in the scoring range.
| 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### 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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF to enable AOH detection through allele-specific CN calling (ASCN). |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default true). |
| `--cnv-enable-mosaic-calling true` | Enable MOSAIC-calling mode (default true). |
### In-run PON
For CNV PON requirements and generation options see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals).
For Targeted Caller PON requirements and generation options see [Targeted Caller | Exome calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller#exome-calling-using-in-run-pon).
CNV and Targeted Caller require separate PON files, but the intermediate counts files can be generated in the same DRAGEN command line invocation. Follow the steps below to generate the CNV and Targeted Caller PON files. Note that Targeted Caller is only supported with the Illumina CS/PGx Custom Enrichment Research Panel.
**Step 1. Generate CNV target counts and Targeted exome counts of individual samples from the sequencing run.**
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 pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# CNV
--enable-cnv true
--cnv-target-bed $PATH
# Targeted caller (only if using the Illumina CS/PGx Custom Enrichment Research Panel)
--targeted-generate-exome-counts true
```
**Step 2. CNV combined counts file generation.**
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome 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.
**Step 3. Targeted Caller PON file generation.**
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--targeted-pon-counts-list $TARGETED_PON_COUNTS_LIST
```
`$TARGETED_PON_COUNTS_LIST` is a text file with one line for each path to a Targeted Caller exome counts file generated in step 1 (`.targeted.exome.counts.json.gz`). Individual exome counts files are merged into a single `.targeted.pon.json.gz` PON file in the output directory. The PON file is used for each case sample run of DRAGEN Targeted Caller using the `--targeted-pon` option.
### Targeted Caller
A systematic noise file corresponding to one of the pre-built pangenome references can be downloaded from the \[DRAGEN Software Support Site page]).
# DNA Germline 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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
--sv-exome true
--sv-target-bed $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF #activates ASCN caller
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON. See 'In-run PON' section below.
# HLA genotyper
--enable-hla true
--hla-exome true #Set HLA output to 3 field resolution (coding sequence only)
# Targeted caller (only if using the Illumina CS/PGx Custom Enrichment Research Panel)
--enable-targeted true
--targeted-pon $PATH #Targeted PON. See 'In-run PON' section below.
--targeted-systematic-noise $PATH #Targeted systematic noise file
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### 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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/unique-molecular-identifiers#umi-options).
### SNV
DRAGEN SNV VC employs machine learning based variant recalibration (DRAGEN-ML). It processes read and other contextual evidence to remove false positives, recover false negatives and reduce zygosity errors. No additional setup is required. DRAGEN-ML is enabled by default as needed, when running the germline SNV VC on hg19 or hg38.
Note that we do not recommend changing the default QUAL thresholds of 3 for DRAGEN-ML and 10 for DRAGEN without ML. These values differ from each other because DRAGEN-ML improves the calibration of QUAL scores, leading to a change in the scoring range.
| 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### 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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF to enable AOH detection through allele-specific CN calling (ASCN). |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default true). |
| `--cnv-enable-mosaic-calling true` | Enable MOSAIC-calling mode (default true). |
### In-run PON
For CNV PON requirements and generation options see [CNV Preprocessing | Panel of Normals](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#panel-of-normals).
For Targeted Caller PON requirements and generation options see [Targeted Caller | Exome calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller#exome-calling-using-in-run-pon).
CNV and Targeted Caller require separate PON files, but the intermediate counts files can be generated in the same DRAGEN command line invocation. Follow the steps below to generate the CNV and Targeted Caller PON files. Note that Targeted Caller is only supported with the Illumina CS/PGx Custom Enrichment Research Panel.
**Step 1. Generate CNV target counts and Targeted exome counts of individual samples from the sequencing run.**
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 pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# CNV
--enable-cnv true
--cnv-target-bed $PATH
# Targeted caller (only if using the Illumina CS/PGx Custom Enrichment Research Panel)
--targeted-generate-exome-counts true
```
**Step 2. CNV combined counts file generation.**
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome 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.
**Step 3. Targeted Caller PON file generation.**
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
--targeted-pon-counts-list $TARGETED_PON_COUNTS_LIST
```
`$TARGETED_PON_COUNTS_LIST` is a text file with one line for each path to a Targeted Caller exome counts file generated in step 1 (`.targeted.exome.counts.json.gz`). Individual exome counts files are merged into a single `.targeted.pon.json.gz` PON file in the output directory. The PON file is used for each case sample run of DRAGEN Targeted Caller using the `--targeted-pon` option.
### Targeted Caller
A systematic noise file corresponding to one of the pre-built pangenome references can be downloaded from the \[DRAGEN Software Support Site page]).
# DNA Germline WGS
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF #activates ASCN caller
--cnv-enable-self-normalization true
# HLA genotyper
--enable-hla true
# Targeted caller
--enable-targeted true
# Star allele
--enable-star-allele true
# PGX
--enable-pgx true #PGX
# Short tandem repeats
--repeat-genotype-enable true
# Multi-Region Joint Detection (MRJD)
--enable-mrjd true
--mrjd-enable-high-sensitivity-mode true
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### SNV
DRAGEN SNV VC employs machine learning based variant recalibration (DRAGEN-ML). It processes read and other contextual evidence to remove false positives, recover false negatives and reduce zygosity errors. No additional setup is required. DRAGEN-ML is enabled by default as needed, when running the germline SNV VC on hg19 or hg38.
Note that we do not recommend changing the default QUAL thresholds of 3 for DRAGEN-ML and 10 for DRAGEN without ML. These values differ from each other because DRAGEN-ML improves the calibration of QUAL scores, leading to a change in the scoring range.
| 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### 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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF to enable AOH detection through allele-specific CN calling (ASCN). |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default true). |
| `--cnv-enable-mosaic-calling true` | Enable MOSAIC-calling mode (default true). |
### Multi-Region Joint Detection (MRJD)
| Option | Description |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-mrjd` | If set to true, MRJD is enabled for the DRAGEN pipeline. |
| `--mrjd-enable-high-sensitivity-mode` | If set to true, MRJD high sensitivity mode is enabled for the DRAGEN pipeline. See the MRJD section in the user guide for information on variant types reported in MRJD default mode and high-sensitivity mode (default=false). |
For futher details refer to [MRJD](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/multi-region-joint-detection).
# DNA Somatic Tumor-Normal Heme WGS
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.
```
/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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Recommended
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--heme-sv true
--sv-systematic-noise $PATH #Optional
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# DUX4
--enable-dux4-caller true
# CNV
--heme-cnv true
--cnv-use-somatic-vc-baf true
--cnv-enable-self-normalization true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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) |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
| `--heme-cnv true` | Configures DRAGEN to use CNV settings for HEME. |
| `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| 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. |
| `--heme-sv true` | Configures DRAGEN to use SV settings for Liquid Tumors (e.g., AML/MLL). |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/sv-calling).
### DUX4
| Option | Description |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--dux4-skip-sanity-check true` | Bypass the requirements checks if the input datasets don't comply with parameters listed in prerequisites |
For more information, see [DUX4-rearrangement Calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/dux4-rearrangement-caller).
## 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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--vc-detect-systematic-noise=true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](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.
#### 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, Panels or Amplicon. 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
--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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Normal MRD
> **For conceptual background and pipeline overview, see** [**DRAGEN MRD Pipeline Overview**](/dragen-v4.5/product-guides/dragen-v4.5/mrd)
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.
## Step 0: Fastq generation
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--output-directory $OUTPUT_DIR
--sample-sheet $SAMPLE_SHEET
--bcl-input-directory $RUN_FOLDER
--bcl-conversion-only true
--strict-mode true
# if using ora compression (.fastq.ora) rather than gzip (.fastq.gz)
--ora-reference $ORA_REFERENCE
--fastq-compression-format dragen
```
BCL conversion is optional if FASTQ data already exists. If starting from BCL files, this step must be completed before running the MRD pipeline to ensure sample-specific FASTQs are available as input.
## Step 1: Read alignment and targeted variant calling
### Step 1A: Read alignment and targeted germline variant calling (FFPE)
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN linear hashtable
--validate-pangenome-reference false #required
--output-directory $OUTPUT
--intermediate-results-dir $PATH
--output-file-prefix $PREFIX
--events-log-file $EVENTS_LOG_FILE
--watchdog-active-timeout 1800
--watchdog-idle-timeout 1800
# Inputs (e.g. FQ list)
--fastq-list $PATH
--fastq-list-sample-id $STRING
# Mapper
--enable-map-align true #optional for BAM/CRAM input
--enable-map-align-output true #optionally save the output BAM
--enable-duplicate-marking true #default=true
--enable-targeted false
--Aligner.hard-clips 7 #for FFPE samples only, uses hard clipping for all alignment types
# Small variant caller
--enable-variant-caller true #targeted germline calling for ~37K SNP sites with high population allele frequencies (typically close to 50% VAF)
--vc-target-bed $COMMON_GERMLINE_TARGET_BED
# QC
--gc-metrics-enable true
--qc-coverage-ignore-overlaps false #de-duplicated conventional coverage is output rather than molecular coverage
--qc-cross-cont-vcf $QC_CROSS_CONTAMINATION_VCF
# ORA
--ora-reference $ORA_REFERENCE
```
### Step 1B: Read alignment and targeted germline variant calling (BC/Plasma)
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN linear hashtable
--validate-pangenome-reference false #required
--output-directory $OUTPUT
--intermediate-results-dir $PATH
--output-file-prefix $PREFIX
--events-log-file $EVENTS_LOG_FILE
--watchdog-active-timeout 1800
--watchdog-idle-timeout 1800
# Inputs (e.g. FQ list)
--fastq-list $PATH
--fastq-list-sample-id $STRING
# Mapper
--enable-map-align true #optional for BAM/CRAM input
--enable-map-align-output true #optionally save the output BAM
--enable-duplicate-marking true #default=true
--enable-targeted false
# Small variant caller
--enable-variant-caller true #targeted germline calling for ~37K SNP sites with high population allele frequencies (typically close to 50% VAF)
--vc-target-bed $COMMON_GERMLINE_TARGET_BED
# QC
--gc-metrics-enable true
--qc-coverage-ignore-overlaps false #de-duplicated conventional coverage is output rather than molecular coverage
--qc-cross-cont-vcf $QC_CROSS_CONTAMINATION_VCF
# ORA
--ora-reference $ORA_REFERENCE
```
### Read alignment and targeted variant calling notes
For consistency, use the linear reference. For FFPE samples, use `--Aligner.hard-clips=7` to use hard clipping for all alignment types; omit this parameter for Buffy Coat or Plasma samples.
## Step 2: Fingerprint generation + QC
### Step 2A: Fingerprint generation and FFPE normal-aware contamination QC
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN linear hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH
--output-file-prefix $PREFIX
--events-log-file $EVENTS_LOG_FILE
# Inputs (BAM files from Step 1)
--bam-input $BUFFY_COAT_BAM
--tumor-bam-input $FFPE_BAM
# M/A
--enable-map-align false
--enable-map-align-output false
# Small variant caller
--enable-variant-caller true
--vc-enable-germline-tagging true
--vc-target-bed $HIGH_CONFIDENCE_REGIONS
--vc-systematic-noise $VC_SYSTEMATIC_NOISE
--vc-germline-tagging-db-files $VC_GERMLINE_TAGGING_DB_FILES
# FP
--mrd-fingerprint true
# QC
--qc-somatic-contam-vcf $QC_SOMATIC_CONTAMINATION_VCF
```
### Fingerprint generation notes
For the DRAGEN MRD pipeline (similar to all somatic runs) it is recommended to use the linear hashtable. DRAGEN hashtables can be downloaded from [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
It is recommended to use `--vc-target-bed $BED` or `--vc-excluded-regions-bed $BED` to limit fingerprint calls to high-confidence regions. Construct a BED file covering only easily mapped regions, excluding ALU or highly repetitive regions where recurring noise tends to be more frequent.
Use a systematic noise file to further reduce false positives. Prebuilt systematic noise BED files can be downloaded from [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html):
| Prebuilt 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) |
For more information see [SNV systematic noise](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode#systematic-noise-filtering). To download germline annotation files, refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana).
### FFPE normal-aware contamination QC notes
It is recommended to use `--qc-somatic-contam-vcf` for FFPE normal-aware contamination detection. The somatic contamination VCF files are bundled with every DRAGEN installation at `/opt/dragen//resources/qc/`. For the hg38 reference, use `somatic_sample_cross_contamination_resource_hg38.vcf.gz`.
For samples not run in matched Tumor/Normal mode (i.e., BC and Plasma samples in Step 1B), a germline contamination VCF file can be passed to `--qc-cross-cont-vcf`. These files are also located at `/opt/dragen//resources/qc/`. For the hg38 reference, use `sample_cross_contamination_resource_hg38.vcf.gz`.
### Step 2B: FFPE/BC sample matching QC
```
/opt/dragen/$VERSION/bin/dragen
--ref-dir $REF_DIR
--output-directory $OUTPUT_DIR
--output-file-prefix $SAMPLE_ID
--events-log-file $EVENTS_LOG_FILE
# Inputs
--checkfingerprint-expected-vcf $BUFFY_COAT_TARGETED_GERMLINE_VCF
--checkfingerprint-observed-vcf $FFPE_TARGETED_GERMLINE_VCF
# QC
--enable-checkfingerprint true
```
## Step 3: MRD detection
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR
--output-directory $OUTPUT_DIR
--output-file-prefix $SAMPLE_ID
--events-log-file $EVENTS_LOG_FILE
# Inputs
--bam-input $PLASMA_BAM
--mrd-probes-file $FINGERPRINT_VCF
# M/A
--enable-map-align false
--enable-map-align-output false
--enable-sort false
# MRD
--enable-mrd true
```
### MRD detection notes
The command line parameters that control MRD detect are:
| Parameter Name | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `--enable-mrd` | Enables MRD detect. Default = "false". |
| `--mrd-probes-file` | Path to the individual's tumor fingerprint VCF file |
| `--mrd-score-threshold` | Threshold used to determine the presence/absence of residual cancer DNA in the plasma. Default = 4.0. |
The MRD detect module generates an output summary file using the standard DRAGEN output directory and prefix: .mrd\_summary.json. The file is a valid JSON file that contains an array of JSON objects. DRAGEN supports running one sample at a time, so the array will be of length one.
The output JSON will include the following two fields of interest:
* Run\[1].TumorEstimate.illumina.eVAF
* Run\[1].TumorEstimate.illumina.score
The "eVAF" (estimated Variant Allele Frequency) is the allele-level fraction of detected variants in the plasma sample, reflecting ctDNA burden. See [Interpreting eVAF](/dragen-v4.5/product-guides/dragen-v4.5/mrd#interpreting-evaf) for details.
The "score" can be used to determine presence/absence of residual cancer DNA in the plasma. A higher score indicates that the presence of cancer DNA is more likely. The exact threshold score that is used to indicate a positive ctDNA status may depend on sample quality and coverage, and can be optimized for a specific pipeline. It is expected that this threshold will typically be between 4 - 7.
## Step 4: Plasma QC
### Step 4A: Plasma/BC sample matching QC
```
/opt/dragen/$VERSION/bin/dragen
--ref-dir $REF_DIR #path to DRAGEN linear hashtable
--validate-pangenome-reference false #required
--output-directory $OUTPUT
--output-file-prefix $PREFIX
--events-log-file $EVENTS_LOG_FILE
# Inputs
--checkfingerprint-expected-vcf $BUFFY_COAT_TARGETED_GERMLINE_VCF
--checkfingerprint-observed-vcf $PLASMA_TARGETED_GERMLINE_VCF
# QC
--enable-checkfingerprint true
```
### Step 4B: Plasma contamination QC
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR
--output-directory $OUTPUT_DIR
--output-file-prefix $SAMPLE_ID
--events-log-file $EVENTS_LOG_FILE
# Inputs
--bam-input $PLASMA_BAM
# M/A
--enable-map-align false
--enable-map-align-output false
--enable-sort false
# MRD
--enable-mrd true
--mrd-probes-file $COMMON_GERMLINE_VCF
--mrd-blocklist $BUFFY_COAT_TARGETED_GERMLINE_VCF
```
### Plasma QC notes
Similar to the MRD detection step, the output JSON will include the following field of interest:
```
Run[1].TumorEstimate.illumina.eVAF
```
The "eVAF" (estimated Variant Allele Frequency) is the observed allele fraction. For the plasma contamination QC workflow, the inferred foreign DNA fraction is approximately 2\*eVAF (since signal is measured at loci with population allele frequencies close to 50%). See [Interpreting eVAF in plasma contamination QC](/dragen-v4.5/product-guides/dragen-v4.5/mrd#interpreting-evaf-in-plasma-contamination-qc) and [Interpreting eVAF](/dragen-v4.5/product-guides/dragen-v4.5/mrd#interpreting-evaf) for details.
# DNA Somatic Tumor-Normal Solid Panel
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
--enable-duplicate-marking true #default=true
# 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-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-enable-solid true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### 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. |
### 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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-locus-node-target-file` | Specifies a BED file containing a set of regions to call. All SVs with **at least one** breakend within the specified regions will be called. |
| `--sv-target-bed` | (Optional) Specifies a BED file containing the set of regions to call. SVs with **both** breakends within the specified regions will be called. Use this option in place of `sv-locus-node-target-file` for higher specificity. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--vc-detect-systematic-noise=true
--vc-target-bed $VC_TARGET_BED #Region assessed in assay
--vc-target-bed-padding 500
--vc-emit-ref-confidence BP_RESOLUTION
--vc-enable-vcf-output true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_PATH
--intermediate-results-dir $PATH
--output-directory $PATH
--output-file-prefix $STRING
```
For panels we create GVCF files. Gather the full paths to the small variant caller hard filtered GVCFs (not VCFs) from step 1 and create an input file `${GVCF_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 ${GVCF_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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
--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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Normal Solid Panel 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'].
# 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-enable-umi-solid true #>= 1% VAF
# SV
--enable-sv true
--sv-enable-solid true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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](/dragen-v4.5/product-guides/dragen-v4.5/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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-locus-node-target-file` | Specifies a BED file containing a set of regions to call. All SVs with **at least one** breakend within the specified regions will be called. |
| `--sv-target-bed` | (Optional) Specifies a BED file containing the set of regions to call. SVs with **both** breakends within the specified regions will be called. Use this option in place of `sv-locus-node-target-file` for higher specificity. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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-emit-ref-confidence BP_RESOLUTION
--vc-enable-vcf-output true
--vc-enable-umi-solid true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_PATH
--intermediate-results-dir $PATH
--output-directory $PATH
--output-file-prefix $STRING
```
For panels we create GVCF files. Gather the full paths to the small variant caller hard filtered GVCFs (not VCFs) from step 1 and create an input file `${GVCF_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 ${GVCF_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Normal Solid WES
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
--enable-duplicate-marking true #default=true
# 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-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-exome true
--sv-target-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 $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
--hla-exome true #Set HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
| `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--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 $NIRVANA_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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
--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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# 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'].
# 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-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-exome true
--sv-target-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 $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
--hla-exome true #Set HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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](/dragen-v4.5/product-guides/dragen-v4.5/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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
| `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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 $NIRVANA_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Normal Solid WGS
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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Recommended
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-systematic-noise $PATH #Optional
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# CNV
--enable-cnv true
--cnv-use-somatic-vc-baf true
--cnv-enable-self-normalization true
# HRD Scoring
--enable-hrd true #requires CNV
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
| `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--vc-detect-systematic-noise=true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](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.
#### 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, Panels or Amplicon. 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
--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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Normal Solid WGS 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'].
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Recommended
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-systematic-noise $PATH #Optional
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# CNV
--enable-cnv true
--cnv-use-somatic-vc-baf true
--cnv-enable-self-normalization true
# HRD Scoring
--enable-hrd true #requires CNV
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# TMB
--enable-tmb true
# HLA genotyper
--enable-hla true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #recommended
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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](/dragen-v4.5/product-guides/dragen-v4.5/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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
| `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](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.
#### 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, Panels or Amplicon. 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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only Heme WGS
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.
```
/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
# 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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Required
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--heme-sv true
--sv-systematic-noise $PATH #Recommended
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# DUX4
--enable-dux4-caller true
# CNV
--heme-cnv true
--cnv-population-b-allele-vcf $POP_VCF
--cnv-enable-self-normalization true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
--vc-germline-tag-hotspots false #When germline tagging is enabled, disable it only for somatic hotspot variants
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 3. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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) |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
| `--heme-cnv true` | Configures DRAGEN to use CNV settings for HEME. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| Option | Recommended Value for Liquid Tumors (e.g. AML/MLL) |
| ----------------------------------- | ----------------------------------------------------------------------- |
| `--heme-sv true` | Configures DRAGEN to use SV settings for Liquid Tumors (e.g., AML/MLL). |
| `--sv-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/sv-calling).
### DUX4
| Option | Description |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--dux4-skip-sanity-check true` | Bypass the requirements checks if the input datasets don't comply with parameters listed in prerequisites |
For more information, see [DUX4-rearrangement Calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/dux4-rearrangement-caller).
## 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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--vc-detect-systematic-noise=true
--vc-enable-germline-tagging=true
--vc-germline-tag-hotspots=false #When germline tagging is enabled, disable it only for somatic hotspot variants
--variant-annotation-data $NIRVANA_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 [Platform Core](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.
#### 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, Panels or Amplicon. 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
--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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
# DNA Somatic Tumor-Only Solid Amplicon
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.
```
/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
# 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
# Amplicon
--enable-dna-amplicon true
--amplicon-target-bed $PATH
--enable-duplicate-marking false #default=false
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED #Optional. Auto-generated based on amplicon target bed.
--vc-systematic-noise $PATH #optional for SNV systematic noise.
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
# CNV
--enable-cnv true
--cnv-combined-counts $PATH #CNV PON. Required for amplicon CNV calling on CASE samples.
--cnv-target-bed $PATH #Optional. Auto-generated based on amplicon target bed.
--cnv-filter-qual $NUM #CNV filter quality. Adjust CNV filter quality thresholds according to the user’s validation study.
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
--amplicon-enable-msi true
```
## Notes and additional options
### Pillar Amplicon Specific Settings
To support the varied designs of amplicon panels and the specific requirements of different analysis types (e.g., SNV, CNV, SV, MSI, RNA fusion, RNA splice variants, and RNA 3'/5' imbalance ratio), panel-specific parameter settings have been integrated into the command-line options. Each supported Pillar panel has a dedicated option, and the details for these DNA panels are listed in the table below:
| **Panel Name** | **Short Name** | **Panel Code** | **Sample Type** | **Default variant caller enabled** | **Command Line Options** |
| :---------------------------------: | :-------------------: | :------------: | :-------------: | :--------------------------------: | :-------------------------------: |
| oncoReveal BRCA1 & BRCA2 plus CNV | BRCA CNV | BR283 | DNA | SNV, CNV | --amplicon-enable-dna-brca |
| oncoReveal Lymphoid | Lymphoid | P-LYM-01 | DNA | SNV, SV | --amplicon-enable-dna-lymphoid |
| oncoReveal Essential MPN | MPN | MY7 | DNA | SNV | --amplicon-enable-dna-mpn |
| oncoReveal Multi-Cancer v4 with CNV | Multi-Cancer with CNV | HS341 | DNA | SNV, CNV | --amplicon-enable-dna-multicancer |
| oncoReveal Myeloid | Myeloid | MY766 | DNA | SNV, SV | --amplicon-enable-dna-myeloid |
| oncoReveal Nexus 21 Gene | Nexus | P-CMC-01 | DNA | SNV, SV | --amplicon-enable-dna-nexus |
| oncoReveal Solid Tumor v2 | Solid Tumor v2 | P-ST-02 | DNA | SNV | --amplicon-enable-dna-solidtumor |
For more detail on the amplicon pipeline, please refer to [DRAGEN Amplicon Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-amplicon-pipeline)
### 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ----------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Amplicon post-alignment processing
| Option | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--amplicon-primer-length INT` | If an alignment starts inside the primer region of the amplicon target, the alignment is assigned to the amplicon. |
| `--amplicon-allow-partial-target true` | In order to detect deletion events that are close to the target boundaries, we now require only one of the reads to start in the primer region (Default=true) |
For more detail on the amplicon post-alignment processing, please refer to [DRAGEN Amplicon Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-amplicon-pipeline)
### Duplicate Marking
| Option | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking false` | The Amplicon Pipeline disables duplicate marking. In amplicon assays, fragments originate from a limited number of unique start and end positions, making conventional duplicate detection inappropriate. |
### 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-target-vaf $FLOAT` | The default is 0.03 (3%) |
| `--vc-af-call-threshold $FLOAT` | If the AF filter is enabled using --vc-enable-af-filter=true, the option sets the allele frequency call threshold for nuclear chromosomes to emit a call in the VCF. The default value is 0.01. |
| `--vc-af-filter-threshold $FLOAT` | If the AF filter is enabled using --vc-enable-af-filter=true, the option sets the allele frequency filter threshold for nuclear chromosomes to mark emitted VCF calls as filtered. The default value is 0.05. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### CNV
Amplicon CNV requires PON input. In PON mode, the DRAGEN CNV Pipeline is broken down into two distinct stages. The target counts stage is performed on each sample (case and normals), to bin the alignments. The normalization and call detection stage is then performed with the case sample against the panel of normals to determine the events.
| Option | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cnv-segmentation-mode $SEG_MODE` | Option to override the default segmentation algorithm. By default, `bed` is used for standard panels and `hslm` for Pillar panels with a pre-built PON. |
| `--amplicon-cnv-use-default-pon false` | We recommend including in-run normal samples—matched in sample type and library preparation—in the same sequencing run to serve as the PON. If generating a custom PON is not feasible, for Pillar panels, the pre-packaged panel-specific PON can be used as a fallback. To enable this, set the option to true. |
| `--cnv-segmentation-bed $PATH` | You can bypass segmentation by specifying a cnv-segmentation-bed and using cnv-segmentation-mode=bed. If bed segmentation mode is used, the segmentation bed is auto-generated from amplicon target bed by default |
| `--cnv-filter-qual $NUM` | QUAL value at which to hard filter CNV VCF. You can adjust CNV filter quality thresholds according to the your validation study |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Default as amplicon target bed. |
| `--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` | Optional systematic noise BEDPE file containing the set of noisy paired regions. |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
DRAGEN has pre-built systematic noise files for Pillar panels. These files are packaged directly with DRAGEN.
#### 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
--vc-detect-systematic-noise=true
--enable-dna-amplicon true
--amplicon-target-bed $PATH
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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
--enable-dna-amplicon true
--amplicon-target-bed $PATH
--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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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
--enable-dna-amplicon true
--amplicon-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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only Solid Panel
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
# 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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-enable-solid true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### 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. |
### 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 3. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-locus-node-target-file` | Specifies a BED file containing a set of regions to call. All SVs with **at least one** breakend within the specified regions will be called. |
| `--sv-target-bed` | (Optional) Specifies a BED file containing the set of regions to call. SVs with **both** breakends within the specified regions will be called. Use this option in place of `sv-locus-node-target-file` for higher specificity. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--vc-detect-systematic-noise=true
--vc-target-bed $VC_TARGET_BED #Region assessed in assay
--vc-target-bed-padding 500
--vc-emit-ref-confidence BP_RESOLUTION
--vc-enable-vcf-output true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_PATH
--intermediate-results-dir $PATH
--output-directory $PATH
--output-file-prefix $STRING
```
For panels we create GVCF files. Gather the full paths to the small variant caller hard filtered GVCFs (not VCFs) from step 1 and create an input file `${GVCF_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 ${GVCF_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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
--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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only Solid Panel 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
# 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
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-enable-umi-solid true #>= 1% VAF
# SV
--enable-sv true
--sv-enable-solid true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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-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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-locus-node-target-file` | Specifies a BED file containing a set of regions to call. All SVs with **at least one** breakend within the specified regions will be called. |
| `--sv-target-bed` | (Optional) Specifies a BED file containing the set of regions to call. SVs with **both** breakends within the specified regions will be called. Use this option in place of `sv-locus-node-target-file` for higher specificity. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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-emit-ref-confidence BP_RESOLUTION
--vc-enable-vcf-output true
--vc-enable-umi-solid true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_PATH
--intermediate-results-dir $PATH
--output-directory $PATH
--output-file-prefix $STRING
```
For panels we create GVCF files. Gather the full paths to the small variant caller hard filtered GVCFs (not VCFs) from step 1 and create an input file `${GVCF_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 ${GVCF_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only Solid WES
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
# 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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-exome true
--sv-target-bed $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# HRD Scoring
--enable-hrd true #requires CNV
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
--hla-exome true #Set HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 3. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--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 $NIRVANA_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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
--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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only 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
# 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
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-exome true
--sv-target-bed $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# HRD Scoring
--enable-hrd true #requires CNV
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
--hla-exome true #Set HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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-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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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 $NIRVANA_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only Solid WGS
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
# 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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-systematic-noise $PATH #Recommended
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF
--cnv-enable-self-normalization true
# HRD Scoring
--enable-hrd true #requires CNV
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 3. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| Option | Recommended Value for Liquid Tumors (e.g. AML/MLL) |
| ----------------------------------- | -------------------------------------------------- |
| `--sv-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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
--vc-detect-systematic-noise=true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](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.
#### 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, Panels or Amplicon. 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
--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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only Solid WGS 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
# 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
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-target-vaf $NUM #Default = 0.03 (>= 3% VAF)
# SV
--enable-sv true
--sv-systematic-noise $PATH #Recommended
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF
--cnv-enable-self-normalization true
# HRD Scoring
--enable-hrd true #requires CNV
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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-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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
| `--cnv-enable-cyto-output true` | Enable Cytogenomics-compatible output (default false). |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum 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.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| Option | Recommended Value for Liquid Tumors (e.g. AML/MLL) |
| ----------------------------------- | -------------------------------------------------- |
| `--sv-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](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.
#### 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, Panels or Amplicon. 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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only ctDNA Amplicon
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.
```
/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
# 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
# Amplicon
--enable-dna-amplicon true
--amplicon-target-bed $PATH
--enable-duplicate-marking false #default=false
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED #Optional. Auto-generated based on amplicon target bed.
--vc-systematic-noise $PATH #optional for SNV systematic noise.
--vc-target-vaf $NUM #Default = 0.001 (>= 0.1% VAF)
# SV
--enable-sv true
# CNV
--enable-cnv true
--cnv-combined-counts $PATH #CNV PON. Required for amplicon CNV calling on CASE samples.
--cnv-target-bed $PATH #Optional. Auto-generated based on amplicon target bed.
--cnv-filter-qual $NUM #CNV filter quality. Adjust CNV filter quality thresholds according to the user’s validation study.
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
--amplicon-enable-msi true
```
## Notes and additional options
### Pillar Amplicon Specific Settings
To support the varied designs of amplicon panels and the specific requirements of different analysis types (e.g., SNV, CNV, SV, MSI, RNA fusion, RNA splice variants, and RNA 3'/5' imbalance ratio), panel-specific parameter settings have been integrated into the command-line options. Each supported Pillar panel has a dedicated option, and the details for these DNA panels are listed in the table below:
| **Panel Name** | **Short Name** | **Panel Code** | **Sample Type** | **Default variant caller enabled** | **Command Line Options** |
| :----------------------: | :------------: | :------------: | :-------------: | :--------------------------------: | :-------------------------------: |
| oncoReveal Core LBx | Core LBx | P-LBX-01 | cfDNA | SNV, CNV, MSI | --amplicon-enable-cfdna-core |
| oncoReveal Essential LBx | Essential LBx | P-LBX-04 | cfDNA | SNV, CNV, MSI | --amplicon-enable-cfdna-essential |
For more detail on the amplicon pipeline, please refer to [DRAGEN Amplicon Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-amplicon-pipeline)
### 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ----------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Amplicon post-alignment processing
| Option | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--amplicon-primer-length INT` | If an alignment starts inside the primer region of the amplicon target, the alignment is assigned to the amplicon. |
| `--amplicon-allow-partial-target true` | In order to detect deletion events that are close to the target boundaries, we now require only one of the reads to start in the primer region (Default=true) |
For more detail on the amplicon post-alignment processing, please refer to [DRAGEN Amplicon Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-amplicon-pipeline)
### Duplicate Marking
| Option | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking false` | The Amplicon Pipeline disables duplicate marking. In amplicon assays, fragments originate from a limited number of unique start and end positions, making conventional duplicate detection inappropriate. |
### 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-target-vaf $FLOAT` | For ctDNA, the default is 0.001 (0.1%). |
| `--vc-af-call-threshold $FLOAT` | If the AF filter is enabled using --vc-enable-af-filter=true, the option sets the allele frequency call threshold for nuclear chromosomes to emit a call in the VCF. For ctDNA, the default is 0.001. |
| `--vc-af-filter-threshold $FLOAT` | If the AF filter is enabled using --vc-enable-af-filter=true, the option sets the allele frequency filter threshold for nuclear chromosomes to mark emitted VCF calls as filtered. For ctDNA, the default is 0.003. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### CNV
Amplicon CNV requires PON input. In PON mode, the DRAGEN CNV Pipeline is broken down into two distinct stages. The target counts stage is performed on each sample (case and normals), to bin the alignments. The normalization and call detection stage is then performed with the case sample against the panel of normals to determine the events.
| Option | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--cnv-segmentation-mode $SEG_MODE` | Option to override the default segmentation algorithm. By default, `bed` is used for standard panels and `hslm` for Pillar panels with a pre-built PON. |
| `--amplicon-cnv-use-default-pon false` | We recommend including in-run normal samples—matched in sample type and library preparation—in the same sequencing run to serve as the PON. If generating a custom PON is not feasible, for Pillar panels, the pre-packaged panel-specific PON can be used as a fallback. To enable this, set the option to true. |
| `--cnv-segmentation-bed $PATH` | You can bypass segmentation by specifying a cnv-segmentation-bed and using cnv-segmentation-mode=bed. If bed segmentation mode is used, the segmentation bed is auto-generated from amplicon target bed by default |
| `--cnv-filter-qual $NUM` | QUAL value at which to hard filter CNV VCF. You can adjust CNV filter quality thresholds according to the your validation study |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Default as amplicon target bed. |
| `--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` | Optional systematic noise BEDPE file containing the set of noisy paired regions. |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
DRAGEN has pre-built systematic noise files for Pillar panels. These files are packaged directly with DRAGEN.
#### 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
--vc-detect-systematic-noise=true
--enable-dna-amplicon true
--amplicon-target-bed $PATH
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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
--enable-dna-amplicon true
--amplicon-target-bed $PATH
--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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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
--enable-dna-amplicon true
--amplicon-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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# DNA Somatic Tumor-Only ctDNA Panel 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.
```
/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
# 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
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-enable-umi-liquid true #>= 0.1% VAF
# SV
--enable-sv true
--sv-enable-liquid true
--sv-locus-node-target-file $SV_TARGET_BED
# CNV
--enable-cnv true
--cnv-target-bed $PATH
--cnv-combined-counts $PATH #CNV PON
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
# TMB
--enable-tmb true
--vc-callability-tumor-thresh 1000
--tmb-vaf-threshold 0.002
--tmb-enable-proxi-filter true #Optional for Tumor-Only
# HLA genotyper
--enable-hla true
--hla-as-filter-min-threshold 29.0 #panel specific setting
--hla-as-filter-ratio-threshold 0.85 #panel specific setting
--hla-exome true #If panel contains only coding regions. Sets HLA output to 3 field resolution (coding sequence only)
# Microsatellite Instability (MSI)
--enable-msi true
--msi-microsatellites-file $PATH
--msi-ref-normal-input $PATH #required
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/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-emit-ref-confidence GVCF` | To enable gVCF output. |
| `--vc-enable-vcf-output` | To enable VCF file output during a gVCF run, set to true. The default value is false. |
| `--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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 2. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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](/dragen-v4.5/product-guides/dragen-v4.5/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). |
| `--hla-exome` | Output HLA alleles at 3-field resolution (default 4-field resolution) for panels targeting only coding sequences or WES. |
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. 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-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF. This option can be used when a matched normal sample is not available and analysis must be performed in tumor-only mode. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### TMB
The Tumor-Normal pipeline is more effective than the Tumor-Only pipeline at removing or tagging germline variants. The Tumor-Only may subsequently report somewhat elevated TMB values. The TMB proxi filter is an optional setting on top of the regular database germline filter. It will aggressively filter additional germline variants based on allele frequencies.
| Option | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| `--tmb-vaf-threshold FLOAT` | Variant minimum allele frequency for usable variants. Default=0.05. Set to 0.002 for ctDNA. |
| `--vc-callability-tumor-thresh` | Required read coverage to use a site. Default=50. Set to 1000 for ctDNA. |
See the user guide: [TMB Germline Variants](https://help.dragen.illumina.com/dragen-v4.5/product-guides/dragen-v4.5/dragen-recipes/pages/gNnLZydItf4mjzOt19Ly#id-4.-support-for-germline-variants).
### MSI
Microsatellite sites and PON files can be downloaded here: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
For more information on MSI calling, see [MSI](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-locus-node-target-file` | Specifies a BED file containing a set of regions to call. All SVs with **at least one** breakend within the specified regions will be called. |
| `--sv-target-bed` | (Optional) Specifies a BED file containing the set of regions to call. SVs with **both** breakends within the specified regions will be called. Use this option in place of `sv-locus-node-target-file` for higher specificity. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. 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.
#### Prebuilt
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-emit-ref-confidence BP_RESOLUTION
--vc-enable-vcf-output true
--vc-enable-umi-liquid true
--vc-enable-germline-tagging=true
--variant-annotation-data $NIRVANA_PATH
--intermediate-results-dir $PATH
--output-directory $PATH
--output-file-prefix $STRING
```
For panels we create GVCF files. Gather the full paths to the small variant caller hard filtered GVCFs (not VCFs) from step 1 and create an input file `${GVCF_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 ${GVCF_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 [Platform Core](https://www.illumina.com/products/by-type/informatics-products/connected-analytics.html).
### SV Systematic Noise
SV systematic noise files have not been tested with WES, enrichment and amplicon panels. It is considered an experimental mode for these assays.
#### Custom
Custom systematic noise files can be generated for WES, Panels or Amplicon. 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 [Platform Core](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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-reference#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.
### MSI baseline file (PON)
It is recommended to use a baseline file that matches the sample type (FF/FFPE), assay type (WGS/WES/Panel) and genome build (hg19/hg38) of the samples being analyzed. If matched normals are available, it is recommended to include them in the baselines.
For MSI baseline generation, see [Baseline microsatellite repeat distribution](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/biomarkers/biomarker-msi#baseline-microsatellite-repeat-distribution). It is required that non-tumor inputs are used for baseline generation.
**Step 1. Generate MSI baselines for individual 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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# MSI
--enable-msi true
--msi-generate-baseline true
--msi-microsatellites-file $MICROSATELLITE_LIST#see 'Product Files' for available files
```
**Step 2. Combine MSI baselines to a single file.**
```
touch combined_msi_baseline.dist
sed 's/$/ $SAMPLEID $OUTPUT/$PREFIX.microsat_normal.dist | grep -v '#' >> combined_msi_baseline.dist
```
The combined MSI baseline files can then be used for each case sample run of DRAGEN MSI using `--msi-ref-normal-input combined_msi_baseline.dist`.
# Illumina TruPath Genome WGS
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--fastq-list $PATH #see 'Input Options'
--fastq-list-sample-id $STRING
# Illumina TruPath Genome
--enable-proximity true
# 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
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-phasing-min-fragments 0
# SV
--enable-sv true
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF #activates ASCN caller
--cnv-enable-self-normalization true
# Targeted caller
--enable-targeted true
# Short tandem repeats
--repeat-genotype-enable true
# Multi-Region Joint Detection (MRJD)
--enable-mrjd true
```
## Notes and additional options
### Hashtable
See: [Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html)
### Input options
TruPath Genome Prep only supports fastq list and fastq input. For BCL input, first create FASTQs using [BCL conversion](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-population-b-allele-vcf $POP_VCF` | Specify a population SNP VCF to enable AOH detection through allele-specific CN calling (ASCN). |
# Illumina scRNA
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.
```
/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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# Mapper
--enable-rna true
--annotation-file $GTF #GTF or GFF3 format
--enable-map-align true #required for RNA/scRNA
--enable-map-align-output true #optionally save the output BAM
--enable-sort true #default=true
# Illumina Single Cell Prep
--scrna-enable-pipseq-mode true
--single-cell-threshold ratio #['fixed', 'ratio', inflection']
```
## Notes and additional options
### Hashtable
For DRAGEN RNA/scRNA 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | -------------------------------------------------------------- |
| `--enable-map-align true` | For RNA/scRNA pipelines, map-align should always be turned on. |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Illumina single-cell RNA Prep PIPseq options
PIPseq mode batch option automatically sets the barcode/BI source, the barcode and binning index positions and the barcode sequence list options.
By default the barcode/BI is obtained from read 1 and the transcript is obtained from read 2.
To change the barcode or binning index positions, use `--scrna-barcode-position` and `--scrna-umi-position`. These settings should be provided in the form `_` for each barcode. Connect multiple barcode sequence positions with a '+'.
For example, a library with the cell-barcode split into three blocks of 9 bp separated by fixed linker sequences and an 8 bp BI would be set using: `--scrna-barcode-position 0_8+21_29+43_51`, and `--scrna-umi-position 52_59`.
The following table lists some optional settings:
| Option | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--scrna-enable-pipseq-mode` | Option to enable Illumina PIPseq mode. |
| `--scrna-barcode-position` | See example above or refer to [Illumina scRNA PIPseq](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina). |
| `--scrna-umi-position` | See example above or refer to [Illumina scRNA PIPseq](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina). |
| `--single-cell-threshold` | Cell filtering can be set to \['fixed', 'ratio', or 'inflection']. |
| `--scrna-barcode-sequence-list` | A known barcode sequence list can be optionally provided. |
| `--umi-source` | Optionally override the default barcode/BI source, valid option include \['read1', 'read2', 'qname', 'fastq']. |
For more details on Illumina single cell prep pipeline options, refer to the [Illumina scRNA PIPseq Pipeline User Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina)
# Illumina scRNA Perturb seq
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.
```
/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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# Mapper
--enable-rna true
--annotation-file $GTF #GTF or GFF3 format
--enable-map-align true #required for RNA/scRNA
--enable-map-align-output true #optionally save the output BAM
--enable-sort true #default=true
# Illumina Single Cell Perturb-seq
--scrna-enable-pipseq-mode true
--single-cell-threshold ratio #['fixed', 'ratio', inflection']
--scrna-enable-pipseq-crispr-mode true
--scrna-feature-barcode-groups $FEATURE_RGIDS
--scrna-feature-barcode-reference $FEATURE_REF_CSV
```
## Notes and additional options
### Hashtable
For DRAGEN RNA/scRNA 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | -------------------------------------------------------------- |
| `--enable-map-align true` | For RNA/scRNA pipelines, map-align should always be turned on. |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Illumina single-cell RNA Prep Perturb-seq options
PIPseq mode batch option automatically sets the barcode/BI source, the barcode and binning index positions and the barcode sequence list options.
By default the barcode/BI is obtained from read 1 and the transcript is obtained from read 2.
PIPseq CRISPR mode option configures DRAGEN to automatically process CRISPR feature reads.
CRISPR mode enables feature counting, transforming of CRISPR cell-barcodes to match transcript barcodes, guide RNA calling, and additional metrics.
CRISPR mode requires a feature barcode reference CSV file to be provided with the CRISPR 'hook' and 'grab' sequences and positions. Refer to [Illumina scRNA CRISPR Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina#crispr-mode) for details.
CRISPR mode also requires the feature barcode groups to be provided, i.e., the RGIDs of the CRISPR input FASTQs (multiple read groups should be comma-separated).
To change the barcode or binning index positions, use `--scrna-barcode-position` and `--scrna-umi-position`. These settings should be provided in the form `_` for each barcode. Connect multiple barcode sequence positions with a '+'.
For example, a library with the cell-barcode split into three blocks of 9 bp separated by fixed linker sequences and an 8 bp BI would be set using: `--scrna-barcode-position 0_8+21_29+43_51`, and `--scrna-umi-position 52_59`.
The following table lists some optional settings:
| Option | Description |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--scrna-enable-pipseq-mode` | Option to enable Illumina PIPseq mode. |
| `--scrna-barcode-position` | See example above or refer to [Illumina scRNA PIPseq](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina). |
| `--scrna-umi-position` | See example above or refer to [Illumina scRNA PIPseq](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina). |
| `--scrna-enable-pipseq-crispr-mode` | Option to enable Illumina PIPseq CRISPR mode. |
| `--scrna-feature-barcode-groups` | Comma-separated list of CRISPR read groups (RGID strings), required in PIPseq CRISPR mode. |
| `--scrna-feature-barcode-reference` | CSV-file of feature barcode reference sequences. Refer to [Illumina scRNA CRISPR Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina#crispr-mode). |
| `--single-cell-threshold` | Cell filtering can be set to \['fixed', 'ratio', or 'inflection']. |
| `--scrna-barcode-sequence-list` | A known barcode sequence list can be optionally provided. |
| `--umi-source` | Optionally override the default barcode/BI source, valid option include \['read1', 'read2', 'qname', 'fastq']. |
For more details on Illumina single cell perturb-seq pipeline options, refer to the [Illumina scRNA CRISPR Mode User Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-illumina#crispr-mode)
# Other scRNA prep
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.
```
/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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# Mapper
--enable-rna true
--annotation-file $GTF #GTF or GFF3 format
--enable-map-align true #required for RNA/scRNA
--enable-map-align-output true #optionally save the output BAM
--enable-sort true #default=true
# Other Single Cell Prep
--enable-single-cell-rna true
--umi-source qname #default='qname'
--scrna-barcode-position $BARCODE_POS #see notes
--scrna-umi-position $UMI_POS #see notes
--scrna-barcode-sequence-list $PATH
--single-cell-threshold ratio #['fixed', 'ratio', inflection']
--single-cell-threshold-filterby umi #['umi', 'read']
```
## Notes and additional options
### Hashtable
For DRAGEN RNA/scRNA 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | -------------------------------------------------------------- |
| `--enable-map-align true` | For RNA/scRNA pipelines, map-align should always be turned on. |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Other single-cell RNA Prep options
To change the barcode or binning index positions, use `--scrna-barcode-position` and `--scrna-umi-position`. These settings should be provided in the form `_` for each barcode. Connect multiple barcode sequence positions with a '+'.
For example, a library with the cell-barcode split into three blocks of 9 bp separated by fixed linker sequences and an 8 bp BI would be set using: `--scrna-barcode-position 0_8+21_29+43_51`, and `--scrna-umi-position 52_59`.
The following table lists some optional settings:
| Option | Description |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--enable-single-cell-rna true` | Option to enable single-cell rna mode. |
| `--scrna-barcode-position` | See example above or refer to [scRNA](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-other). |
| `--scrna-umi-position` | See example above or refer to [scRNA](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-other). |
| `--single-cell-threshold` | Cell filtering can be set to \['fixed', 'ratio', or 'inflection']. |
| `--scrna-barcode-sequence-list` | A known barcode sequence list can be optionally provided. |
| `--umi-source` | Optionally override the default barcode/BI source, valid option include \['read1', 'read2', 'qname', 'fastq']. |
For more details on single-cell RNA options, refer to the [DRAGEN Single-Cell RNA User Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-single-cell-pipeline/dragen-scrna-other).
# RNA Amplicon
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.
```
/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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# Mapper
--enable-rna true
--annotation-file $GTF #GTF or GFF3 format
--enable-map-align true #required for RNA/scRNA
--enable-map-align-output true #optionally save the output BAM
--enable-sort true #default=true
# Amplicon
--enable-rna-amplicon true
--amplicon-target-bed $PATH
--amplicon-enable-imbalance-ratio true #optional for panels that support 3'/5' imbalance-ratio
--enable-duplicate-marking false #default=false
# RNA Splice Variants
--enable-rna-splice-variant true
# RNA Gene Fusions
--enable-rna-gene-fusion true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## Notes and additional options
### Hashtable
For DRAGEN RNA/scRNA 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)
### RNA Amplicon
To enable RNA amplicon, set:
* `--enable-rna-amplicon true`, and
* `--amplicon-target-bed $PATH`.
If RNA amplicon mode is enabled and the amplicon bed file already includes the gene name, then it is not required to set the enriched option (rna-enriched-regions or rna-enriched-genes), since DRAGEN will read the enriched genes names from the amplicon BED file (fifth column).
#### Pillar Specific Amplicon Settings
To support the varied designs of amplicon panels and the specific requirements of different analysis types (e.g., SNV, CNV, SV, MSI, RNA fusion, RNA splice variants, and RNA 3'/5' imbalance ratio), panel-specific parameter settings have been integrated into the command-line options. Each supported Pillar panel has a dedicated option, and the details for these RNA panels are listed in the table below:
| **Panel Name** | **Short Name** | **Panel Code** | **Sample Type** | **Default variant caller enabled** | **Command Line Options** |
| :-----------------------------------: | :----------------------: | :------------: | :-------------: | :-------------------------------------------------------: | :-------------------------------: |
| oncoReveal Heme | Heme | P-HFU-01 | RNA | RNA fusion | --amplicon-enable-rna-heme |
| oncoReveal Fusion LBx | Fusion LBx | P-LBX-03 | cfRNA | RNA fusion, RNA splice-variant | --amplicon-enable-cfrna-lbxfusion |
| oncoReveal Multi-Cancer RNA Fusion v2 | Multi-Cancer with Fusion | SF-V2 | RNA | RNA fusion, RNA splice-variant, RNA 3'/5' imbalance-ratio | --amplicon-enable-rna-multicancer |
For more detail on the amplicon pipeline, please refer to [DRAGEN Amplicon Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-amplicon-pipeline)
### Input options
DRAGEN input sources include: fastq list, fastq, bam, or cram. For BCL input, first create FASTQs using [BCL conversion](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | -------------------------------------------------------------- |
| `--enable-map-align true` | For RNA/scRNA pipelines, map-align should always be turned on. |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Duplicate Marking
| Option | Description |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking false` | The Amplicon Pipeline disables duplicate marking. In amplicon assays, fragments originate from a limited number of unique start and end positions, making conventional duplicate detection inappropriate. |
### RNA Variant Calling
| Option | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--vc-target-bed $PATH` | Restrict the variants called to a target bed. A bed file specifying the gene-coding regions should be provided to avoid calling erroneous variants in unenriched or noncoding regions due to noisy reads. |
### RNA Splice
| Option | Description |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--rna-splice-variant-normals $PATH` | Optional list of normal splice variants that will be used to filter false positive calls. The file should be a tab separated file with the following first four columns: (1) contig name, (2) first base of the splice junction (1-based), (3) last base of the splice junction (1-based), (4) strand (0: undefined, 1: +, 2: -). |
| `--rna-splice-variant-knowns $PATH` | File with a list of expected splice junctions, these will be passed |
| `--rna-splice-variant-fusion-genes $PATH` | List of hotspot genes that may contain spliced fusions |
### RNA Fusion
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--rna-gf-restrict-genes` | Ignore genes that are not protein coding for gene fusions (Default=true) |
| `--rna-gf-enable-post-filters` | Enable stringent post-filtering of RNA gene fusion candidates by quality flags to reduce false positives (Default=false) |
| `--rna-gf-output-fusion-sequence` | Output assembled gene fusion sequence in fusion\_candidates.final file (Default=true) |
| `--rna-gf-report-intronic` | Report fusion calls with intronic breakpoints (Default=true) |
| `--rna-gf-report-antisense` | Report fusion calls with antisense and intronic breakpoints (Default=false) |
| `--rna-gf-report-intergenic` | Report fusion calls with intergenic, antisense and intronic breakpoints (Default=false) |
| `--rna-gf-report-read-through` | Report read-through fusion calls (Default=false) |
| `--rna-gf-ptd-genes` | List of gene names where we allow PTD/ITD associated self fusions |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
# RNA Panel
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.
```
/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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# Mapper
--enable-rna true
--annotation-file $GTF #GTF or GFF3 format
--enable-map-align true #required for RNA/scRNA
--enable-map-align-output true #optionally save the output BAM
--enable-sort true #default=true
--rna-enriched-genes $PATH #for RNA panels
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# RNA Quantification
--enable-rna-quantification true
--rna-library-type A #see 'RNA Quant'
--rna-quantification-gc-bias true
# RNA Splice Variants
--enable-rna-splice-variant true
# RNA Gene Fusions
--enable-rna-gene-fusion true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## Notes and additional options
### Hashtable
For DRAGEN RNA/scRNA 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | -------------------------------------------------------------- |
| `--enable-map-align true` | For RNA/scRNA pipelines, map-align should always be turned on. |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### RNA Variant Calling
| Option | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--vc-target-bed $PATH` | Restrict the variants called to a target bed. A bed file specifying the gene-coding regions should be provided to avoid calling erroneous variants in unenriched or noncoding regions due to noisy reads. |
### RNA Quant
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--rna-library-type` | Set the library according to the read orientations. Set to 'A' to auto detect the correct read orientation. Alternatively select 'IU', 'ISR', 'ISF', 'U', 'SR', or 'SF'. |
### RNA Splice
| Option | Description |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--rna-splice-variant-normals $PATH` | Optional list of normal splice variants that will be used to filter false positive calls. The file should be a tab separated file with the following first four columns: (1) contig name, (2) first base of the splice junction (1-based), (3) last base of the splice junction (1-based), (4) strand (0: undefined, 1: +, 2: -). |
| `--rna-splice-variant-knowns $PATH` | File with a list of expected splice junctions, these will be passed |
| `--rna-splice-variant-fusion-genes $PATH` | List of hotspot genes that may contain spliced fusions |
### RNA Fusion
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--rna-gf-restrict-genes` | Ignore genes that are not protein coding for gene fusions (Default=true) |
| `--rna-gf-enable-post-filters` | Enable stringent post-filtering of RNA gene fusion candidates by quality flags to reduce false positives (Default=false) |
| `--rna-gf-output-fusion-sequence` | Output assembled gene fusion sequence in fusion\_candidates.final file (Default=true) |
| `--rna-gf-report-intronic` | Report fusion calls with intronic breakpoints (Default=true) |
| `--rna-gf-report-antisense` | Report fusion calls with antisense and intronic breakpoints (Default=false) |
| `--rna-gf-report-intergenic` | Report fusion calls with intergenic, antisense and intronic breakpoints (Default=false) |
| `--rna-gf-report-read-through` | Report read-through fusion calls (Default=false) |
| `--rna-gf-ptd-genes` | List of gene names where we allow PTD/ITD associated self fusions |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
# RNA WTS
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.
```
/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
--fastq-list $PATH #see 'Input Options' for FQ, BAM or CRAM
--fastq-list-sample-id $STRING
# Mapper
--enable-rna true
--annotation-file $GTF #GTF or GFF3 format
--enable-map-align true #required for RNA/scRNA
--enable-map-align-output true #optionally save the output BAM
--enable-sort true #default=true
--enable-duplicate-marking true #default=true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# RNA Quantification
--enable-rna-quantification true
--rna-library-type A #see 'RNA Quant'
--rna-quantification-gc-bias true
# RNA Splice Variants
--enable-rna-splice-variant true
# RNA Gene Fusions
--enable-rna-gene-fusion true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## Notes and additional options
### Hashtable
For DRAGEN RNA/scRNA 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | -------------------------------------------------------------- |
| `--enable-map-align true` | For RNA/scRNA pipelines, map-align should always be turned on. |
| `--enable-map-align-output true` | Optionally save the output BAM (default=false). |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### RNA Variant Calling
| Option | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--vc-target-bed $PATH` | Restrict the variants called to a target bed. A bed file specifying the gene-coding regions should be provided to avoid calling erroneous variants in unenriched or noncoding regions due to noisy reads. |
### RNA Quant
| Option | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--rna-library-type` | Set the library according to the read orientations. Set to 'A' to auto detect the correct read orientation. Alternatively select 'IU', 'ISR', 'ISF', 'U', 'SR', or 'SF'. |
### RNA Splice
| Option | Description |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--rna-splice-variant-normals $PATH` | Optional list of normal splice variants that will be used to filter false positive calls. The file should be a tab separated file with the following first four columns: (1) contig name, (2) first base of the splice junction (1-based), (3) last base of the splice junction (1-based), (4) strand (0: undefined, 1: +, 2: -). |
| `--rna-splice-variant-knowns $PATH` | File with a list of expected splice junctions, these will be passed |
| `--rna-splice-variant-fusion-genes $PATH` | List of hotspot genes that may contain spliced fusions |
### RNA Fusion
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--rna-gf-restrict-genes` | Ignore genes that are not protein coding for gene fusions (Default=true) |
| `--rna-gf-enable-post-filters` | Enable stringent post-filtering of RNA gene fusion candidates by quality flags to reduce false positives (Default=false) |
| `--rna-gf-output-fusion-sequence` | Output assembled gene fusion sequence in fusion\_candidates.final file (Default=true) |
| `--rna-gf-report-intronic` | Report fusion calls with intronic breakpoints (Default=true) |
| `--rna-gf-report-antisense` | Report fusion calls with antisense and intronic breakpoints (Default=false) |
| `--rna-gf-report-intergenic` | Report fusion calls with intergenic, antisense and intronic breakpoints (Default=false) |
| `--rna-gf-report-read-through` | Report read-through fusion calls (Default=false) |
| `--rna-gf-ptd-genes` | List of gene names where we allow PTD/ITD associated self fusions |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
# 5 Base DNA Germline Panel
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
--enable-duplicate-marking true #default=true
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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) |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
# 5 Base DNA Germline Panel 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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### UMI
| Option | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/unique-molecular-identifiers#umi-options).
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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) |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
# 5 Base DNA Germline WGS
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.
```
/opt/dragen/$VERSION/bin/dragen #DRAGEN install path
--ref-dir $REF_DIR #path to DRAGEN pangenome hashtable
--output-directory $OUTPUT
--intermediate-results-dir $PATH #e.g. SSD /staging
--output-file-prefix $PREFIX
# Inputs
--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
--enable-duplicate-marking true #default=true
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
# SV
--enable-sv true
# CNV
--enable-cnv true
--cnv-enable-self-normalization true
```
## Notes and additional options
### Hashtable
For DRAGEN germline runs, it is recommended to use the pangenome 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--fastq-list $PATH
--fastq-list-sample-id $STRING
```
FQ Input
```
--fastq-file1 $PATH
--fastq-file2 $PATH
--RGSM $STRING
--RGID $STRING
```
BAM Input
```
--bam-input $PATH
```
CRAM Input
```
--cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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) |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
# 5 Base DNA Somatic Tumor-Normal Solid Panel
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
--enable-duplicate-marking true #default=true
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# 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
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### 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. |
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
## 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-built systematic noise files for WGS, WES and for Pillar Amplicons. These files should also be used in 5-Base workflows. The 5-Base workflows have not been tested with custom noise files.
#### Prebuilt
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 |
# 5 Base DNA Somatic Tumor-Normal Solid WGS
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
--enable-duplicate-marking true #default=true
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Recommended
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
# SV
--enable-sv true
--sv-systematic-noise $PATH #Optional
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# CNV
--enable-cnv true
--cnv-use-somatic-vc-baf true
--cnv-enable-self-normalization true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--enable-variant-annotation true
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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 17.5. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
| `--cnv-normal-cnv-vcf $CNV_NORMAL_VCF` | Specify germline CNVs from the matched normal sample. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| 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](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. These files should also be used in 5-Base workflows. The 5-Base workflows have not been tested with custom noise files.
#### Prebuilt
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 |
# 5 Base DNA Somatic Tumor-Only Solid Panel
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
# 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
--enable-duplicate-marking true #default=true
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
| `--enable-positional-collapsing true` | Alternative to `--enable-duplicate-marking=true`. Instead of discarding duplicate reads, DRAGEN can optionally perform positional collapsing, merging them into higher-quality consensus reads. This is beneficial for small panels without UMIs and coverage between 300X and 1000X. However, it's slower than standard duplicate marking and less effective on samples with coverage lower than 300X. For very high coverage (1000X+), avoid it due to potential read collisions. For high-sensitivity panels with 1000X+ coverage, consider using UMIs. |
### 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. |
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 3. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
## 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-built systematic noise files for WGS, WES and for Pillar Amplicons. These files should also be used in 5-Base workflows. The 5-Base workflows have not been tested with custom noise files.
#### Prebuilt
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 |
# 5 Base DNA Somatic Tumor-Only Solid Panel 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
# 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
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
--vc-enable-umi-solid true #>= 1% VAF
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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-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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/unique-molecular-identifiers#umi-options).
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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-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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
## 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-built systematic noise files for WGS, WES and for Pillar Amplicons. These files should also be used in 5-Base workflows. The 5-Base workflows have not been tested with custom noise files.
#### Prebuilt
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 |
# 5 Base DNA Somatic Tumor-Only Solid WGS
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
# 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
--enable-duplicate-marking true #default=true
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-systematic-noise $PATH #Required
--vc-excluded-regions-bed $BED #FFPE: optionally mask ALUs
# SV
--enable-sv true
--sv-systematic-noise $PATH #Recommended
--enable-oncovirus-detection true #Optional
--oncovirus-detection-db $PATH #Optional
# CNV
--enable-cnv true
--cnv-population-b-allele-vcf $POP_VCF
--cnv-enable-self-normalization true
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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. |
### Duplicate Marking
| Option | Description |
| --------------------------------- | ------------------------------------------------------------------------------- |
| `--enable-duplicate-marking true` | By default, DRAGEN marks duplicate reads and exclude them from variant calling. |
### 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. |
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 3. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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) |
Clinical applications require maximum confidence in variant calls to prevent false positive diagnoses. High-specificity mode reduces false positives with some loss in sensitivity.
| High Specificity Option | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| `--vc-high-specificity true` | Apply aggressive filters in the small variant caller to boost specificity, with some loss in sensitivity. |
For more detail on the small variant caller in somatic mode please refer to [Somatic Mode](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### 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` | Specify a segmentation bed file to add pre-defined segments to be called. |
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
### SV
| Option | Description |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sv-target-bed` | Specifies a BED file containing the set of regions to call. Optionally gzip or bgzip format. |
| `--sv-exclusion-bed` | (Optional) Specifies a BED file containing the set of regions to exclude for the SV calling. Optionally 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, enrichment and amplicon 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. |
| `--enable-oncovirus-detection` | Set to enable detection of oncoviral integration. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| `--oncovirus-detection-db` | Specifies the directory containing oncovirus detection resource files. See [Oncovirus Detection](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/oncovirus-detection) for more information. |
| Option | Recommended Value for Liquid Tumors (e.g. AML/MLL) |
| ----------------------------------- | -------------------------------------------------- |
| `--sv-min-scored-variant-size $INT` | 100000 |
For more information, see [Structural Variant Calling](/dragen-v4.5/product-guides/dragen-v4.5/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-built systematic noise files for WGS, WES and for Pillar Amplicons. These files should also be used in 5-Base workflows. The 5-Base workflows have not been tested with custom noise files.
#### Prebuilt
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 |
# 5 Base DNA Somatic Tumor-Only ctDNA Panel 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.
```
/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
# 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
# 5-Base
--methylation-conversion illumina
--methylation-generate-cytosine-report true
--methylation-compress-cx-report true
# Small variant caller
--enable-variant-caller true
--vc-target-bed $VC_TARGET_BED
--vc-systematic-noise $PATH #Required
--vc-enable-umi-liquid true #>= 0.1% VAF
# Annotation
--variant-annotation-data $NIRVANA_PATH
--vc-enable-germline-tagging true
```
## 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](/dragen-v4.5/product-guides/dragen-v4.5/bcl-conversion).
FQ list Input
```
--tumor-fastq-list $PATH
--tumor-fastq-list-sample-id $STRING
```
FQ Input
```
--tumor-fastq1 $PATH
--tumor-fastq2 $PATH
--RGSM-tumor $STRING
--RGID-tumor $STRING
```
BAM Input
```
--tumor-bam-input $PATH
```
CRAM Input
```
--tumor-cram-input $PATH
```
### Mapping and Aligning
| Option | Description |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--enable-map-align true` | Optionally disable map & align (default=true). |
| `--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-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. Most pipelines perform better with a setting of 1. A setting of 2 may potentially be relevant for samples with ultra deep coverage (e.g., ctDNA). (Default since DRAGEN V4.5 is 1) |
| `--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](/dragen-v4.5/product-guides/dragen-v4.5/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. |
For more information see: [UMI Options](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/unique-molecular-identifiers#umi-options).
### 5-Base Methylation
| Option | Description |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--methylation-conversion STRING` | Library conversion for methylation analysis. Options: `none`, `c_t`, `mc_t`, `illumina` (default=none). |
| `--methylation-protocol STRING` | Library protocol for methylation analysis. Options: `none`, `directional`, `non-directional`, `directional-complement`, `pbat`. The default value for `methylation-conversion=illumina` is `directional`, otherwise it is `none`. |
| `--methylation-mapq-threshold INT` | Only reads with MAPQ greater or equal than the threshold will be included in methyl-seq analysis (default=0). |
| `--methylation-generate-mbias-report true` | Whether to generate a per-sequencer-cycle methylation bias report (default=true). |
| `--mbias-report-include-overlaps` | Calculate methylation stats for overlapping bases between mates (default=false). |
| `--methylation-generate-cytosine-report true` | Whether to generate a genome-wide cytosine methylation CX\_report file (default=false). |
| `--methylation-compress-cx-report true` | Set to true to enable compression of the CX\_report (default=true). |
| `--methylation-keep-ref-cytosine true` | Set to true to keep all reference cytosines in the CX\_report file, even if they don't appear in the input reads (default=false). |
| `--enable-cpg-methylated-mapping true` | Enable methylated mapping with base conversions restricted to CpG context (default=true). When false, runs DRAGEN Methylation 3-base map/align instead. |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in VCF files (default=c). |
| `--methylation-report-to-vcf` | Specify methylation type (none, cg, or c) which is reported in gVCF files (default=cg). |
For more information see: [5-Base Pipeline](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline).
### 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.). When working with panels it is recommended that a custom systematic noise file be created for each assay. |
| `--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-sq-filter-threshold $NUM` | Threshold for sensitivity-specificity tradeoff using SQ score. The pipeline specific default threshold is 2. 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-specificity tradeoff using AQ score for non-hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 60. 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-specificity tradeoff using AQ score for hotspot variants. This is only used when supplying a systematic noise file. Pipeline specific default value = 20. 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](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/somatic-mode)
### Annotation
For instructions on how to download the Nirvana annotation database, please refer to [Nirvana](/dragen-v4.5/product-guides/dragen-v4.5/nirvana)
## 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-built systematic noise files for WGS, WES and for Pillar Amplicons. These files should also be used in 5-Base workflows. The 5-Base workflows have not been tested with custom noise files.
#### Prebuilt
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 |
# DRAGEN Germline Accuracy
This section contains comprehensive accuracy metrics for DRAGEN's germline variant calling.
## Available components
* Standard SBS
* [Small Variants](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/small_variants_accuracy) — SNPs and indels detection accuracy across HG001-HG007 samples
* [Multi-Region Joint Detection](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/mrjd_accuracy) — MRJD performance in high-homology paralogous regions
* [Copy Number Variation](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/copy_number_variation_accuracy) — CNV calling performance metrics
* [HLA Genotyping](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/hla_genotyping_accuracy) — HLA Class I and II genotyping accuracy
* [Targeted Callers](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/targeted_callers_accuracy) — Performance for specialized variant callers
* [Ploidy Estimator](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/ploidy_estimator_accuracy) — Ploidy estimation accuracy
* [Structural Variants](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/structural_variants_accuracy) — SV and MEI detection metrics
* [Tandem Repeats](/dragen-v4.5/product-guides/dragen-v4.5/germline/standard-sbs/tandem_repeats_accuracy) — STR expansion detection and classification accuracy
* TruPath
* [Small Variants](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-trupath/small_variants_accuracy) — HMW and SMW small-variant accuracy from weekly Anaconda runs
* [Copy Number Variation](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-trupath/cnv_accuracy) — TruPath CNV accuracy from the generic Anaconda metrics config
* [Structural Variants](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-trupath/structural_variants_accuracy) — TruPath HMW and SMW SV accuracy from Truvari metrics
* [Tandem Repeats](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-trupath/tandem_repeats_accuracy) — TruPath STR refine-regions and swimplot summaries
* [Multi-Region Joint Detection](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-trupath/mrjd_accuracy) — MRJD concordance across paralogous regions in the TruPath cohort
* Illumina 5-base
* [Small Variants](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-5-base/small_variants_accuracy) — SNPs and indels detection accuracy for 5-base assay
* [Copy Number Variation](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-5-base/copy_number_variation_accuracy) — CNV calling performance metrics
* [Structural Variants](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-5-base/structural_variants_accuracy) — SV detection accuracy for 5-base assay
* [Methylation](/dragen-v4.5/product-guides/dragen-v4.5/germline/illumina-5-base/methylation_accuracy) — DNA methylation detection accuracy
## Reference
**DRAGEN Version**: 4.5.4 | **Reference Genome**: GRCh38
# Standard SBS
# WGS Small Variants
Generated on **2026-05-07**
## Small variants
The DRAGEN Germline Small Variant Caller takes mapped and aligned DNA reads as input and calls SNPs and indels through a combination of column-wise detection and local de novo assembly of haplotypes. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling).
**DRAGEN**: DRAGEN 4.4.6 vs 4.5.4 | **Truthset**: GIAB/NIST high-confidence, GIAB/NIST v4.2.1 | **Reference**: GRCh38
Results reported for HG001-HG007 sequenced with NSX 1.3 with 10B flow cell downsampled at 35x raw coverage.
SNPs table (click to expand)
| Sample | Version | Recall | Precision | F1-score | FN | FP |
| ------ | ------- | ------ | --------- | -------- | ---- | ---- |
| HG001 | 4.4.6 | 1.000 | 0.999 | 0.999 | 1336 | 2634 |
| HG001 | 4.5.4 | 1.000 | 1.000 | 1.000 | 721 | 1658 |
| HG002 | 4.4.6 | 0.999 | 1.000 | 0.999 | 2896 | 1749 |
| HG002 | 4.5.4 | 0.999 | 1.000 | 1.000 | 2198 | 1026 |
| HG003 | 4.4.6 | 0.999 | 0.999 | 0.999 | 3511 | 3005 |
| HG003 | 4.5.4 | 0.999 | 0.999 | 0.999 | 2936 | 2338 |
| HG004 | 4.4.6 | 0.999 | 0.999 | 0.999 | 3748 | 2584 |
| HG004 | 4.5.4 | 0.999 | 1.000 | 0.999 | 2963 | 1803 |
| HG005 | 4.4.6 | 0.999 | 0.999 | 0.999 | 3023 | 2047 |
| HG005 | 4.5.4 | 0.999 | 1.000 | 0.999 | 2413 | 1369 |
| HG006 | 4.4.6 | 0.999 | 0.999 | 0.999 | 3103 | 2408 |
| HG006 | 4.5.4 | 0.999 | 1.000 | 0.999 | 2484 | 1699 |
| HG007 | 4.4.6 | 0.999 | 0.999 | 0.999 | 3467 | 2327 |
| HG007 | 4.5.4 | 0.999 | 1.000 | 0.999 | 2955 | 1602 |
Indels table (click to expand)
| Sample | Version | Recall | Precision | F1-score | FN | FP |
| ------ | ------- | ------ | --------- | -------- | ---- | ---- |
| HG001 | 4.4.6 | 0.996 | 0.997 | 0.997 | 1867 | 1437 |
| HG001 | 4.5.4 | 0.996 | 0.997 | 0.997 | 1849 | 1231 |
| HG002 | 4.4.6 | 0.996 | 0.997 | 0.997 | 2101 | 1421 |
| HG002 | 4.5.4 | 0.996 | 0.998 | 0.997 | 1998 | 1229 |
| HG003 | 4.4.6 | 0.996 | 0.997 | 0.997 | 1852 | 1420 |
| HG003 | 4.5.4 | 0.997 | 0.998 | 0.997 | 1789 | 1164 |
| HG004 | 4.4.6 | 0.996 | 0.997 | 0.997 | 1898 | 1384 |
| HG004 | 4.5.4 | 0.996 | 0.998 | 0.997 | 1877 | 1226 |
| HG005 | 4.4.6 | 0.998 | 0.998 | 0.998 | 897 | 670 |
| HG005 | 4.5.4 | 0.998 | 0.999 | 0.998 | 810 | 554 |
| HG006 | 4.4.6 | 0.997 | 0.998 | 0.998 | 1147 | 838 |
| HG006 | 4.5.4 | 0.997 | 0.998 | 0.998 | 1116 | 741 |
| HG007 | 4.4.6 | 0.997 | 0.998 | 0.998 | 1246 | 868 |
| HG007 | 4.5.4 | 0.997 | 0.998 | 0.998 | 1161 | 762 |
**HG002 T2TQ100 performance**
**DRAGEN**: 4.4.6 vs 4.5.4 | **Truthset**: T2TQ100-v1.1-v0.019 | **Reference**: GRCh38
HG002 T2TQ100-v1.1-v0.019 small variants comparison (click to expand)
| Version | SNPs FN | SNPs FP | SNPs FP+FN | Indels FN | Indels FP | Indels FP+FN |
| ------- | ------- | ------- | ---------- | --------- | --------- | ------------ |
| 4.4.6 | 21571 | 8752 | 30323 | 40208 | 23681 | 63889 |
| 4.5.4 | 16490 | 5764 | 22254 | 36945 | 19661 | 56606 |
**A legacy of continuous innovation and improving accuracy in each version.**
Historical HG002 benchmarked releases using the HG002 small variants NIST v4.2.1 truthset show FP+FN dropping from 41,244 in DRAGEN 3.4.5 to 4,364 in DRAGEN 4.5.4.
Historical version trend table (click to expand)
| Version | FP+FN |
| ------- | ------ |
| 3.4.5 | 41,244 |
| 3.5.7 | 40,056 |
| 3.6.3 | 39,046 |
| 3.7.5 | 21,479 |
| 3.8.4 | 20,402 |
| 3.9.3 | 19,052 |
| 3.10.4 | 12,851 |
| 4.0.3 | 12,815 |
| 4.2.4 | 11,163 |
| 4.3.3 | 6,615 |
| 4.4.6 | 5,955 |
| 4.5.4 | 4,364 |
**Mosaic detection**
Non-cancer post-zygotic mosaic variants have typical allele fraction (AFs) lower than 50% and therefore more challenging to find with the default small variant caller that has been optimized to detect germline variants with typical AFs of 0%, 50% or 100%. The Mosaic variant caller has been designed to address this gap by training a dedicated machine learning model trained on lowAF variants. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/mosaic-detection).
**DRAGEN**: DRAGEN 4.5.4 vs 4.4.6 | **Truthset**: HG002 NIST Mosaic v1.0 | **Reference**: GRCh38 Results reported for HG002 sample [fastqs](https://ftp-trace.ncbi.nlm.nih.gov/ReferenceSamples/giab/data/AshkenazimTrio/HG002_NA24385_son/NIST_HiSeq_HG002_Homogeneity-10953946/HG002_HiSeq300x_fastq/) sequenced with HiSeq2500 at 300x available from NIST.
HG002 mosaic small variants comparison (click to expand)
| Version | SNPs FN | SNPs FP | SNPs TP | SNPs FP+FN | Indels FN | Indels FP | Indels TP | Indels FP+FN |
| ------- | ------- | ------- | ------- | ---------- | --------- | --------- | --------- | ------------ |
| 4.4.6 | 0 | 318 | 85 | 318 | 0 | 196 | 0 | 196 |
| 4.5.4 | 0 | 311 | 85 | 311 | 0 | 185 | 0 | 185 |
# WGS Copy Number Variation
Generated on **2026-05-13**
## Copy Number Variation
The DRAGEN Copy Number Variant (CNV) Pipeline can call CNV events using next-generation sequencing (NGS) data. This pipeline supports multiple applications in a single interface via the DRAGEN Host Software, including processing of whole-genome sequencing (WGS) data and whole-exome sequencing (WES) data. For more information, refer to the [DRAGEN user guide for germline CNV calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-germline).
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: HG002 NIST CNV v0.6 | **Reference**: GRCh38
Standard WGS CNV table (click to expand)
| Subtype | Recall | Precision | F1-score |
| --------- | ------ | --------- | -------- |
| 1kb-10kb | 0.968 | 0.977 | 0.973 |
| 10kb-50kb | 0.950 | 0.952 | 0.951 |
| >50kb | 1.000 | 1.000 | 1.000 |
### Cytogenomics Modality
Conventional cytogenomics methodologies typically focus on larger alterations than the ones provided by NGS analyses. The Cytogenomics modality for the CNV caller allows the user to visualize variants at different resolutions, aiming at providing a more flexible workspace for different use cases. For more information, refer to [DRAGEN manual](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-germline#cytogenomics-modality).
Cytogenomics CNV summary table (click to expand)
| Group | TP | FN | Recall |
| ------------ | --- | -- | ------ |
| DEL 25kb-1Mb | 15 | 1 | 0.938 |
| DEL >=1Mb | 46 | 1 | 0.979 |
| DUP 50kb-1Mb | 10 | 0 | 1.000 |
| DUP >=1Mb | 29 | 1 | 0.967 |
| AOH >=500kb | 43 | 0 | 1.000 |
| TOTAL | 143 | 3 | 0.979 |
# WGS Structural Variants
Generated on **2026-05-07**
## Structural Variants
The DRAGEN Structural Variant (SV) caller identifies large insertions, deletions and genomic arrangements from mapped DNA reads. For details, refer to the [DRAGEN user guide for structural variant calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/sv-calling).
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: HG002 T2TQ100-v1.1-v0.018 on Truvari v4.2.2 | **Reference**: GRCh38
SV WGS historical comparison table (click to expand)
| Method | Recall | Precision | F1-score |
| ------------ | ------ | --------- | -------- |
| DRAGEN 4.5.4 | 0.880 | 0.969 | 0.922 |
| DRAGEN 4.4 | 0.807 | 0.963 | 0.878 |
| DRAGEN 4.3 | 0.511 | 0.953 | 0.665 |
**Comparison with previous DRAGEN versions**
**Mobile Element Insertions**
The general purpose SV routine can detect Mobile Element Insertions (MEIs) with assembled inserted sequences like other regular insertions. If missed by the general purpose SV routine, MEIs will be rescued by the MEI specific routine based on similarity between assembled contigs and known sequences in the MEI catalog.
Recall for **HG002 NIST v0.6 MEI** (Wittyer v0.5.4.1):
SV MEI historical comparison table (click to expand)
| Method | Recall |
| ------------ | ------ |
| DRAGEN 4.5.4 | 0.985 |
| DRAGEN 4.4 | 0.906 |
| DRAGEN 4.3 | 0.885 |
**Comparison with previous DRAGEN versions**
# WGS HLA Genotyping
Generated on **2026-05-07**
## HLA Genotyping
DRAGEN includes a dedicated genotyper for genotyping the Human Leukocyte Antigen (HLA) genes. This typer is capable of matching to established HLA alleles from the IMGT Database as well as calling novel alleles. For WGS data or panels covering the entire HLA genes, DRAGEN can output HLA types at full resolution. For more information, refer to [DRAGEN manual](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/hla-typing).
Assessment based on 47 samples with long read truth calls. 3- and 4-field resolution for HLA Class I accuracy is not supported in DRAGEN 4.4.
HLA Class I Accuracy Table
**2-field comparison**
| Gene | Field resolution | DRAGEN version | Accuracy | 2-field improvement (4.5.4 - 4.4) |
| ---- | ---------------- | -------------- | -------- | --------------------------------- |
| A | 2-field | 4.4 | 98.94% | |
| B | 2-field | 4.4 | 96.81% | |
| C | 2-field | 4.4 | 98.94% | |
| All | 2-field | 4.4 | 98.23% | |
| A | 2-field | 4.5.4 | 98.94% | +0.00 pp |
| B | 2-field | 4.5.4 | 98.94% | +2.13 pp |
| C | 2-field | 4.5.4 | 100.00% | +1.06 pp |
| All | 2-field | 4.5.4 | 99.29% | +1.06 pp |
**Other field resolutions**
| Gene | Field resolution | DRAGEN version | Accuracy |
| ---- | ---------------- | -------------- | -------- |
| A | 3-field | 4.5.4 | 98.94% |
| B | 3-field | 4.5.4 | 96.81% |
| C | 3-field | 4.5.4 | 100.00% |
| All | 3-field | 4.5.4 | 98.58% |
| A | 4-field | 4.5.4 | 94.68% |
| B | 4-field | 4.5.4 | 92.55% |
| C | 4-field | 4.5.4 | 93.62% |
| All | 4-field | 4.5.4 | 93.62% |
HLA Class II Accuracy Table
| Gene | Field resolution | DRAGEN version | Accuracy |
| ---- | ---------------- | -------------- | -------- |
| DPA1 | 2-field | 4.5.4 | 94.05% |
| DPB1 | 2-field | 4.5.4 | 98.81% |
| DQA1 | 2-field | 4.5.4 | 99.40% |
| DQB1 | 2-field | 4.5.4 | 100.00% |
| DRB1 | 2-field | 4.5.4 | 93.45% |
| All | 2-field | 4.5.4 | 97.14% |
| DPA1 | 3-field | 4.5.4 | 91.67% |
| DPB1 | 3-field | 4.5.4 | 98.21% |
| DQA1 | 3-field | 4.5.4 | 98.81% |
| DQB1 | 3-field | 4.5.4 | 92.26% |
| DRB1 | 3-field | 4.5.4 | 93.45% |
| All | 3-field | 4.5.4 | 94.88% |
| DPA1 | 4-field | 4.5.4 | 87.50% |
| DPB1 | 4-field | 4.5.4 | 93.45% |
| DQA1 | 4-field | 4.5.4 | 89.29% |
| DQB1 | 4-field | 4.5.4 | 83.33% |
| DRB1 | 4-field | 4.5.4 | 75.00% |
| All | 4-field | 4.5.4 | 85.71% |
# WGS Targeted Callers
Generated on **2026-05-07**
## Targeted Callers
Repetitive regions in the human genome pose a challenge for general variant calling approaches which typically cannot make use of potentially misplaced MAPQ0 reads. Furthermore, high sequence homology of some genes with a pseudogene paralog can lead to a wide variety of common structural variants (SVs) in the population, requiring specialized targeted calling approaches. DRAGEN supports targeted calling for a number of genes/targets as described in subsequent target-specific sections. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller).
**DRAGEN**: DRAGEN 4.5.4 | **Assay**: WGS
**Performance summary**
**Targeted caller concordance summary (WGS)**
| Target | Concordant | Total | Concordance |
| -------------------- | ---------- | ----- | ----------- |
| CYP2D6 | 211 | 212 | 99.5% |
| SMN1 | 247 | 250 | 98.8% |
| SMN2 | 244 | 250 | 97.6% |
| GBA | 24 | 24 | 100.0% |
| CYP2B6 (GeT-RM) | 70 | 76 | 92.1% |
| CYP2B6 (PacBio HiFi) | 123 | 125 | 98.4% |
| CYP21A2 | 82 | 84 | 97.6% |
| HBA1/2 | 244 | 247 | 98.8% |
| RHD/RHCE | 41 | 42 | 97.6% |
**CYP2D6**
Concordant across 211 out of 212 (99.5%) WGS samples with calls from GeT-RM and long read sequencing data.
**CYP2D6 concordance by star allele type**
| Star Allele Type | Number of Samples | Concordance |
| ----------------- | ----------------- | --------------- |
| without SV | 90 | 89 (98.9%) |
| deletion | 15 | 15 (100%) |
| duplication | 12 | 12 (100%) |
| fusion/conversion | 26 | 26 (100%) |
| **Total** | **143** | **142 (99.3%)** |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/cyp2d6-calling) | [Cyrius: accurate CYP2D6 genotyping using WGS data](https://www.illumina.com/science/genomics-research/articles/cyrius-cyp2d6-genotyping-wgs-data.html)
**SMN1/2**
Concordant across 247/250 (98.8%) WGS samples for SMN1 and 244/250 (97.6%) WGS samples for SMN2, compared against digital PCR and MLPA.
**SMN1 concordance by copy number**
| SMN1 CN | Total Samples | Concordant |
| --------- | ------------- | --------------- |
| 0 | 42 | 42 (100%) |
| 1 | 23 | 23 (100%) |
| 2 | 96 | 94 (97.9%) |
| 3 | 68 | 68 (100%) |
| 4 | 20 | 20 (100%) |
| 6 | 1 | 0 (0%) |
| **Total** | **250** | **247 (98.8%)** |
**SMN2 concordance by copy number**
| SMN2 CN | Total Samples | Concordant |
| --------- | ------------- | --------------- |
| 0 | 26 | 26 (100%) |
| 1 | 73 | 71 (97.3%) |
| 2 | 92 | 89 (96.7%) |
| 3 | 54 | 54 (100%) |
| 4 | 5 | 4 (80%) |
| **Total** | **250** | **244 (97.6%)** |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/smn-calling) | [SMA carrier screening from WGS data](https://www.illumina.com/science/genomics-research/articles/sma-carrier-screening-wgs-data.html)
**GBA**
Concordant across 24/24 (100%) WGS samples compared against digital PCR and long read sequencing data.
**GBA concordance by variant type**
| Copy Number Change | Recombinant Variant | Total Samples | Concordant |
| ------------------ | ------------------- | ------------- | ------------- |
| Gain | None | 10 | 10 (100%) |
| Loss | None | 2 | 2 (100%) |
| Loss | RecNciI | 1 | 1 (100%) |
| Loss | A495P | 1 | 1 (100%) |
| Neutral | L483P | 7 | 7 (100%) |
| Neutral | c.1263del | 1 | 1 (100%) |
| Neutral | c.1263del+RecTL | 2 | 2 (100%) |
| **Total** | | **24** | **24 (100%)** |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/gba-calling) | [GBA gene for Gaucher and Parkinson disease research](https://www.illumina.com/science/genomics-research/articles/using-dragen-for-gaucher-and-parkinson-disease-research--resolvi.html)
**CYP2B6**
Concordance against calls from GeT-RM and long read sequencing data. Concordance is based on metabolizer status when multiple genotypes are reported. Two discordant samples in the PacBio comparison are due to a novel star allele (\*U1) resulting in multiple possible genotypes.
**CYP2B6 concordance by reference source**
| Star Allele Genotype Source | Number of Samples | DRAGEN Concordance |
| --------------------------- | ----------------- | ------------------ |
| GeT-RM | 76 | 70 (92.1%) |
| PacBio HiFi reads | 125 | 123 (98.4%) |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/cyp2b6-calling)
**CYP21A2**
Concordant across 82/84 (97.6%) WGS samples across three benchmark sets with calls from long-range PCR, MLPA and long read sequencing.
**CYP21A2 concordance by benchmark set**
| Benchmark Set | Total Samples | Concordant |
| ------------- | ------------- | -------------- |
| Internal | 14 | 13 (92.9%) |
| 1KGP | 66 | 65 (98.5%) |
| Coriell | 4 | 4 (100%) |
| **Total** | **84** | **82 (97.6%)** |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/cyp21a2-calling) | [CYP21A2 blog](https://www.illumina.com/science/genomics-research/articles/CYP21A2.html)
**HBA1/2**
Concordant across 244/247 (98.8%) WGS samples compared against long read sequencing data.
**HBA1/2 WGS concordance by genotype**
| HBA Genotype | Total Samples | Concordant |
| ------------ | ------------- | --------------- |
| aa/aa | 202 | 199 (98.5%) |
| -α3.7/aa | 31 | 31 (100%) |
| --/aa | 4 | 4 (100%) |
| -α3.7/-α3.7 | 4 | 4 (100%) |
| αααα3.7/aa | 3 | 3 (100%) |
| -α4.2/aa | 2 | 2 (100%) |
| αααα4.2/aa | 1 | 1 (100%) |
| **Total** | **247** | **244 (98.8%)** |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/hba-calling) | [HBA targeted caller](https://www.illumina.com/science/genomics-research/articles/HBA-targeted-caller.html)
**LPA**
LPA copy number is assessed via allele-specific KIV-2 repeat quantification. Accuracy was evaluated by trio/duo-based inheritance analysis and comparison against Bionano optical mapping.
**Figure**: **(A)** Trio-based phased KIV-2 copy number comparison in 120 offspring vs best-matching parental call. **(B)** Duo-based comparison in 153 offspring. **(C)** Total copy number vs Bionano optical mapping (n=145). **(D)** Allelic copy number vs Bionano optical mapping (n=145). Pearson's r and P-value shown per panel.
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/lpa-calling) | [KIV-2 copy number variants for cardiovascular disease risk](https://www.illumina.com/science/genomics-research/articles/using-whole-genome-sequencing-to-evaluate-copy-number-variants-o.html)
**RHD/RHCE**
Concordant across 41/42 (97.6%) WGS samples compared against long read sequencing data.
**RHD/RHCE concordance by gene conversion status**
| RHCE\*CE-D(2)-CE Gene Conversion | Total Samples | Concordant |
| -------------------------------- | ------------- | -------------- |
| Not present | 24 | 24 (100%) |
| Heterozygous | 10 | 9 (90%) |
| Homozygous | 8 | 8 (100%) |
| **Total** | **42** | **41 (97.6%)** |
**References:** [DRAGEN Product Guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/targeted-caller/rh-calling)
**Star Allele Caller**
The Star Allele Caller identifies the genotypes and metabolism status of the following PGx genes that are included in FDA's PGx recommendations or have CPIC Level A designation: CACNA1S, CFTR, CYP2C19, CYP2C9, CYP3A4, CYP3A5, CYP4F2, IFNL3, RYR1, NUDT15, SLCO1B1, TPMT, UGT1A1, VKORC1, DPYD, G6PD, MT-RNR1, BCHE, ABCG2, NAT2, F5 and UGT2B17. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/star-allele-caller).
| Sample source | # samples | Compare against | Genes tested | Concordance\* |
| ------------------ | --------- | --------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------- |
| 1K genomes project | 3201 | PharmCAT (from DRAGEN gVCF) | DPYD, CACNA1S, UGT1A1, TPMT, CYP3A5, CFTR, CYP2C19, CYP2C9, SLCO1B1, NUDT15, VKORC1, CYP4F2, RYR1, IFNL3 | 100% |
| Coriell | 96 | PharmCAT (from DRAGEN gVCF) | DPYD, CACNA1S, UGT1A1, TPMT, CYP3A5, CFTR, CYP2C19, CYP2C9, SLCO1B1, NUDT15, VKORC1, CYP4F2, RYR1, IFNL3 | 100% |
| Coriell | 96 | GeT-RM (using orthogonal methods) | CYP2C19, CYP2C9, CYP3A5, CYP4F2, TPMT | 94%\* |
| 1K genomes project | 100 | Aldy (from BWA/GATK BAM) | G6PD, CFTR, IFNL3, TPMT, VKORC1 | 100% |
\* *Truth set from 2016; 6% calls from outdated star allele definition.*
# WGS Multi-Region Joint Detection
Generated on **2026-05-11** Revised on **2026-06-07**
## Multi-Region Joint Detection
DRAGEN Multi-Region Joint Detection (MRJD) is a *de novo* germline small variant caller for paralogous regions. For standard short-read sequencing data, MRJD covers six clinically relevant genes: *NEB*, *TTN*, *SMN1/2*, *PMS2*, *STRC*, and *IKBKG*. MRJD is compatible with the hg38, hg19, and GRCh37 reference genomes. The table below lists the hg38 region coordinates covered by MRJD. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/multi-region-joint-detection).
hg38 region coordinates covered by MRJD (click to expand)
| Chromosome | Start | End | Description |
| ---------- | --------- | --------- | ----------------- |
| chr2 | 151578759 | 151588523 | NEB exon 98-105 |
| chr2 | 151589318 | 151599076 | NEB exon 90-97 |
| chr2 | 151599871 | 151609628 | NEB exon 82-89 |
| chr2 | 178653238 | 178654995 | TTN exon 172-180 |
| chr2 | 178657498 | 178659255 | TTN exon 181-189 |
| chr2 | 178661759 | 178663516 | TTN exon 190-198 |
| chr5 | 70049522 | 70077596 | SMN2 |
| chr5 | 70924940 | 70953013 | SMN1 |
| chr7 | 5970924 | 5980896 | PMS2 exon 13-15 |
| chr7 | 5980968 | 5987689 | PMS2 exon 11-12 |
| chr7 | 6737007 | 6743712 | PMS2CL exon 2-3 |
| chr7 | 6743880 | 6753867 | PMS2CL exon 4-6 |
| chr15 | 43599563 | 43602630 | STRC exon 24-29 |
| chr15 | 43602982 | 43611000 | STRC exon 14-23 |
| chr15 | 43611040 | 43618800 | STRC exon 1-13 |
| chr15 | 43699379 | 43702452 | STRCP1 exon 23-28 |
| chr15 | 43702488 | 43710472 | STRCP1 exon 13-22 |
| chr15 | 43710502 | 43718262 | STRCP1 exon 1-12 |
| chrX | 154555884 | 154565047 | IKBKG exon 3-10 |
| chrX | 154639390 | 154648553 | IKBKGP1 |
### MRJD performance on cell line samples
We benchmarked MRJD variant calling performance in the *PMS2* high-homology region using 147 cell line samples from the Illumina Polaris 1 diversity panel¹. Ground truth was established using orthogonal small variant calls derived from long-range PCR data. MRJD high sensitivity mode achieves aggregated recall of approximately 99.7% for SNVs and 97.1% for indels. The lower indel recall likely reflects the higher indel error rate of long-range PCR data. To address this limitation, we performed a concordance analysis against a long-read-based approach² using a separate set of 147 cell line samples representing diverse ancestries from the 1000 Genomes Project. Aggregated recall against the long-read-based approach exceeds 99% for both SNVs and indels.
The high recall of MRJD high sensitivity mode is achieved by reporting all possible variants across paralogous regions, which lowers precision. To measure the spurious call rate, we compared merged orthogonal variant calls in both *PMS2* and *PMS2CL* against MRJD high sensitivity mode calls in *PMS2* alone. The spurious call rate is below 0.7%, indicating that nearly all reported alleles are present in the samples but are reported at both locations by MRJD high sensitivity mode (ambiguous placement).
We further benchmarked MRJD performance across all six genes covered by MRJD. The results are shown in Figure 1. MRJD high sensitivity mode achieves aggregated recall between 96.5% and 100% for both SNVs and indels across all six genes, which is significantly higher than the recall from MRJD default mode.
Figure 1. Aggregated SNV and indel performance across the six genes covered by MRJD, comparing MRJD default mode and MRJD high sensitivity mode on more than 100 diverse cell line samples from the 1000 Genomes Project. Orthogonal small variant calls were derived from a long-read-based approach. Benchmark statistics were generated using RTG Tools ploidy-squash mode. All perfect homopolymers > 6 bp and imperfect homopolymers > 10 bp were excluded from the analysis.
*For details on MRJD calling in high sensitivity mode, refer to the* [*DRAGEN user guide*](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling/multi-region-joint-detection#high-sensitivity-mode)*.*
### Non-cell-line validation
We also validated MRJD performance on 22 non-cell-line samples from Broad Clinical Labs and Tempus AI. MRJD detected all expected clinically relevant small variants in these samples.
Table 1: MRJD high sensitivity mode results on 22 non-cell-line samples with potentially clinically relevant variants. All listed variants were orthogonally confirmed and localized to *PMS2*, *PMS2CL*, or *NEB*. Results were provided by Broad Clinical Labs and Tempus AI.
### References
¹Gould GM, Gauman PV, Theilmann MR, et al. Detecting clinically actionable variants in the 3′ exons of *PMS2* via a reflex workflow based on equivalent hybrid capture of the gene and its pseudogene. *BMC Med Genet.* 2018;19(1):176. doi:10.1186/s12881-018-0691-9
²Chen X, Harting J, Farrow E, et al. Comprehensive *SMN1* and *SMN2* profiling for spinal muscular atrophy analysis using long-read PacBio HiFi sequencing. *Am J Hum Genet.* 2023;110(2):240-250. doi:10.1016/j.ajhg.2023.01.001
# WGS Ploidy Estimator
Generated on **2026-05-07**
## Ploidy Estimator
The Ploidy Estimator uses reads from the mapper/aligner to calculate the sequencing depth of coverage for each autosome and allosome in the human genome. The sex karyotype of the sample is then estimated using the ratios of the median sex chromosome coverages to the median autosomal coverage. The sex karyotype is estimated based on the range the ratios fall in. If the ratios are outside all expected ranges, then the Ploidy Estimator does not determine a sex karyotype. 100% recall and precision were achieved across all chromosomes in 21 samples with various triploid and sex chromosome aneuploidies as well as 2 normal samples. Accuracy was assessed using PASS calls from the ploidy.vcf. For more see [DRAGEN documentation](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/ploidy-calling/ploidy-estimator).
**Example: HG00142 trisomy event**
HG00142 is reported in Polaris whole chromosome events as an example with chromosome-level copy number gains consistent with trisomy.
HG00142 chromosome-level ploidy metrics (click to expand)
| CHROM | median | mad | z-score |
| ----- | ------ | --- | ------- |
| chr11 | 130.4 | 9.6 | 169.4 |
| chr13 | 129.6 | 9.7 | 144.9 |
Source: Polaris whole chromosome trisomy events, sample HG00142.
# WGS Tandem Repeats
Short tandem repeats (STRs) are regions of the genome consisting of repetitions of short DNA segments called repeat units. STRs can expand to lengths beyond the normal range and cause mutations called repeat expansions. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/repeat-expansions).
DRAGEN-STR ships with two STR catalogs. The *default* catalog contains a restricted number of well-studied loci whose expansion is linked with various diseases. The *expanded* catalog contains \~174,000 highly-polymorphic STR loci located in and around genes, and is more suitable for whole-genome explorations.
## STR size genotyping accuracy in the expanded catalog
Accuracy on the expanded catalog loci was evaluated against the GIAB tandem repeat benchmark (v1.0) (1), using Truvari (2) for variant comparison.
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: HG002 GIABTR v1.0 | **Reference**: GRCh38
Standard WGS STR table (click to expand)
| Subtype | Recall | Precision | F1-score | FN | FP |
| ------- | ------ | --------- | -------- | ---- | --- |
| STR | 0.9617 | 0.9871 | 0.9742 | 2007 | 664 |
## Classification of samples with known pathogenic STR expansions
We sequenced 40 Coriell cell lines with known STR expansions and compared DRAGEN's STR classification against orthogonal validation methods. The swimplot shows long-allele size distributions in repeat-count units. Dots are colored by [STRipy database](https://www.stripy.org/database) range classification (normal/intermediate/pathogenic) according to each locus thresholds and orthogonally validated size prediction. Shaded regions and classification thresholds from Ibañez K. et al., Lancet Neurology 21, 234–245 (2022).
STR classification metrics table (click to expand)
| Subtype | Recall | Precision | F1-score |
| ----------------------------------- | ------ | --------- | -------- |
| STR Classification Accuracy Metrics | 0.9824 | 1.0000 | 0.9911 |
STR lengths distribution across 20 loci for 40 Coriell samples with pathogenic STRs. Shaded regions show normal, intermediate, and pathogenic ranges (STRipy database, motif-length scaled). Dots are colored by classification.
#### References
1.
2.
# Illumina TruPath
# TruPath Small Variants
Generated on **2026-08-03**
## TruPath small variants
This page reports TruPath small-variant accuracy for High Molecular Weight (HMW) and Small Molecular Weight (SMW). The DRAGEN Germline Small Variant Caller takes mapped and aligned DNA reads as input and calls SNPs and indels through a combination of column-wise detection and local de novo assembly of haplotypes. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling).
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: GIAB/NIST high-confidence, GIAB/NIST v4.2.1 | **Reference**: GRCh38
### HMW (High Molecular Weight)
| Sample | SNP FN | SNP FP | SNP FP+FN | Indel FN | Indel FP | Indel FP+FN |
| ------ | ------ | ------ | --------- | -------- | -------- | ----------- |
| HG001 | 305 | 1727 | 2032 | 587 | 557 | 1144 |
| HG002 | 1145 | 1305 | 2450 | 588 | 439 | 1027 |
| HG003 | 4588 | 3805 | 8393 | 1798 | 1379 | 3177 |
| HG004 | 1390 | 1494 | 2884 | 774 | 636 | 1410 |
| HG005 | 1144 | 1249 | 2393 | 272 | 277 | 549 |
| HG006 | 1467 | 2094 | 3561 | 390 | 361 | 751 |
| HG007 | 1671 | 1518 | 3189 | 430 | 303 | 733 |
### SMW (Standard Molecular Weight)
| Sample | SNP FN | SNP FP | SNP FP+FN | Indel FN | Indel FP | Indel FP+FN |
| ------ | ------ | ------ | --------- | -------- | -------- | ----------- |
| HG001 | 350 | 1520 | 1870 | 708 | 514 | 1222 |
| HG002 | 1368 | 1233 | 2601 | 730 | 555 | 1285 |
| HG003 | 2987 | 3087 | 6074 | 1362 | 1010 | 2372 |
| HG004 | 1641 | 1318 | 2959 | 726 | 567 | 1293 |
| HG005 | 1557 | 1106 | 2663 | 371 | 321 | 692 |
| HG006 | 1707 | 1875 | 3582 | 403 | 337 | 740 |
| HG007 | 2086 | 1360 | 3446 | 492 | 328 | 820 |
### HMW (High Molecular Weight) vs SMW (Standard Molecular Weight) side-by-side FP+FN plot
# TruPath Copy Number Variation
Generated on **2026-06-10**
## Copy Number Variation
The DRAGEN Copy Number Variant (CNV) Pipeline can call CNV events using next-generation sequencing (NGS) data. This pipeline supports multiple applications in a single interface via the DRAGEN Host Software, including processing of whole-genome sequencing (WGS) data and whole-exome sequencing (WES) data. For more information, refer to the [DRAGEN user guide for germline CNV calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-germline).
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: HG002 NIST CNV v0.6 | **Reference**: GRCh38
TruPath CNV summary (click to expand)
| Subtype | Recall | Precision | F1-score |
| --------- | ------ | --------- | -------- |
| 1kb-10kb | 0.953 | 0.988 | 0.970 |
| 10kb-50kb | 0.929 | 0.968 | 0.948 |
| >50kb | 1.000 | 1.000 | 1.000 |
# TruPath Structural Variants
Generated on **2026-07-09**
## Structural Variants
The DRAGEN Structural Variant (SV) caller identifies large insertions, deletions and genomic arrangements from mapped DNA reads. For details, refer to the [DRAGEN user guide for structural variant calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/sv-calling).
**DRAGEN**: DRAGEN 07.031.818.4.5.3 | **Truthset**: HG002 T2TQ100-v1.1-v0.018, Truvari v4.2.2, Refined Regions | **Reference**: GRCh38
TruPath SV refine-variant table (click to expand)
| Molecule | Recall | Precision | F1-score | FN | FP |
| -------- | ------ | --------- | -------- | ---- | --- |
| HMW | 0.9500 | 0.9921 | 0.9706 | 7 | 1 |
| SMW | 0.9331 | 0.9707 | 0.9515 | 1495 | 578 |
# TruPath Tandem Repeats
Generated on **2026-08-05**
## Short Tandem Repeats (STR)
Short tandem repeats (STRs) are regions of the genome consisting of repetitions of short DNA segments called repeat units. STRs can expand to lengths beyond the normal range and cause mutations called repeat expansions. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/repeat-expansions).
DRAGEN-STR ships with two STR catalogs. The *default* catalog contains a restricted number of well-studied loci whose expansion is linked with various diseases. The *expanded* catalog contains \~174,000 highly-polymorphic STR loci located in and around genes, and is more suitable for whole-genome explorations.
### STR size genotyping accuracy in the expanded catalog
Accuracy on the expanded catalog loci was evaluated against the GIAB tandem repeat benchmark (v6.26), using Truvari (2) for variant comparison.
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: HG002 GIABTR v6.26 Truvari 4.2.2 Refine Variant | **Reference**: GRCh38
TruPath STR table (click to expand)
| Subtype | Recall | Precision | F1-score | FN | FP |
| ------- | ------ | --------- | -------- | ---- | --- |
| STR | 0.9611 | 0.9854 | 0.9731 | 2035 | 749 |
### Classification of samples with known pathogenic STR expansions
We sequenced 40 Coriell cell lines with known STR expansions and compared DRAGEN's STR classification against orthogonal validation methods. The swimplot shows long-allele size distributions in repeat-count units. Dots are colored by [STRipy database](https://www.stripy.org/database) range classification (normal/intermediate/pathogenic) according to each locus thresholds and orthogonally validated size prediction. Shaded regions and classification thresholds from Ibañez K. et al., Lancet Neurology 21, 234–245 (2022).
STR classification metrics table (click to expand)
| Calls | Recall | Precision | F1-score |
| ----- | ------ | --------- | -------- |
| 2470 | 0.9824 | 1.0000 | 0.9911 |
STR lengths distribution across 20 loci for 40 Coriell samples with pathogenic STRs. Shaded regions show normal, intermediate, and pathogenic ranges (STRipy database, motif-length scaled). Dots are colored by classification.
**References**
1.
2.
# TruPath Multi-Region Joint Detection
Generated on **2026-07-30**
## MRJD
DRAGEN Multi-region Joint Detection (MRJD) performance for the TruPath 14-cell-line cohort is summarized below. The MRJD results are benchmarked against orthogonal long-read-derived results generated using PacBio HiFi followed by Paraphase.
**Total Concordance for Unplaced (mean across the TruPath 14-cell-line cohort)**
| Paralogous gene or region | Disease relevance | HMW DNA mean concordance | Standard DNA mean concordance |
| ------------------------- | --------------------------------------- | ------------------------ | ----------------------------- |
| PMS2 | Lynch syndrome | 0.988 | 0.987 |
| SMN1-SMN2 | Spinal muscular atrophy | 0.933 | 0.927 |
| NCF1 | Chronic granulomatous disease | 0.969 | 0.970 |
| CYP21A2 (RCCX region) | Congenital adrenal hyperplasia | 0.999 | 1.000 |
| TNXB (RCCX region) | Ehlers-Danlos syndrome | 0.999 | 1.000 |
| STRC | Recessive nonsyndromic hearing loss | 0.980 | 0.979 |
| CYP2D6 | Pharmacogenetics | 0.977 | 0.978 |
| CYP11B1-CYP11B2 | Glucocorticoid-remediable aldosteronism | 0.998 | 0.998 |
| GBA-GBAP1 | Gaucher disease | 0.985 | 0.984 |
| CFHR1-CFHR2-CFHR3-CFHR4 | Atypical hemolytic uremic syndrome | N/A | N/A |
| SP18 | Type I interferonopathy | N/A | N/A |
Values are derived from region-level unplaced total concordance metrics aggregated across the TruPath 14-cell-line cohort.
# Illumina 5-base
# 5-base Small Variants
**Currently, Illumina 5-base supports only PCR prep** The DRAGEN Germline Small Variant Caller takes mapped and aligned DNA reads as input and calls SNPs and indels through a combination of column-wise detection and local de novo assembly of haplotypes. For more information, refer to the [DRAGEN user guide](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/small-variant-calling).
#### HG002 performance
**DRAGEN**: 4.5.4 | **Truthset**: GIAB/NIST high-confidence | **Reference**: GRCh38
HG002 NIST small variants summary (click to expand)
| Variant | Recall | Precision | F1-score | FN | FP | FP+FN |
| ------- | -------- | --------- | -------- | ---- | ---- | ----- |
| SNP | 0.998561 | 0.999357 | 0.998959 | 4848 | 2164 | 7012 |
| INDEL | 0.982097 | 0.990685 | 0.986372 | 9357 | 4826 | 14183 |
**T2TQ100-v1.1-v0.019**
**DRAGEN**: 4.5.4 | **Truthset**: T2TQ100-v1.1-v0.019 | **Reference**: GRCh38
HG002 T2TQ100-v1.1-v0.019 small variants summary (click to expand)
| Variant | Recall | Precision | F1-score | FN | FP | FP+FN |
| ------- | -------- | --------- | -------- | ----- | ----- | ----- |
| SNP | 0.99155 | 0.996665 | 0.994101 | 30872 | 12124 | 42996 |
| INDEL | 0.892639 | 0.992973 | 0.940137 | 56919 | 5462 | 62381 |
# 5-base Methylation
**Currently, Illumina 5-base supports only PCR prep**
The epigenetic methylation of cytosine bases in DNA can have a dramatic effect on gene expression. Bisulfite sequencing is the most canonical method for detecting epigenetic methylation patterns at single-base resolution through converting all unmethylated cytosines to thymine. These libraries inform methylation but have low base diversity which precludes accurate genomic interrogations. Novel Illumina 5-base assay converts methylated cytosine to thymine, retaining high complexity, and is capable of simultaneous variant calling and DNA methylation levels detection. [For more information refer to DRAGEN 5-base manual](/dragen-v4.5/product-guides/dragen-v4.5/dragen-5-base/dragen-5base-pipeline)
**DRAGEN**: DRAGEN 4.5.4 | **Truthsets**: Methylated pUC19 and unmethylated λ-phage
Illumina 5-base accurately and specifically converts methylated control DNA.
| Method | Unmethylated λ | Methylated pUC19 |
| --------- | :------------: | :--------------: |
| BiSulfite | 0.5% | 95.0% |
| EM-Seq | 0.4% | 96.4% |
| 5-base | 0.9% | 94.7% |
# 5-base Copy Number Variation
**Currently, Illumina 5-base supports only PCR prep**
The DRAGEN Copy Number Variant (CNV) Pipeline can call CNV events using next-generation sequencing (NGS) data. This pipeline supports multiple applications in a single interface via the DRAGEN Host Software, including processing of whole-genome sequencing (WGS) data and targeted sequencing data. For more information, refer to the [DRAGEN user guide for germline CNV calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/cnv-overview/cnv-germline).
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: CNV NIST v0.6 (HG002) | **Reference**: GRCh38
HG002 5-base CNV summary (Wittyer event-level bins, Deletion+CopyNumberLoss, click to expand)
| Subtype | Recall | Precision | F1-score |
| --------- | ------ | --------- | -------- |
| 1kb-10kb | 0.955 | 0.983 | 0.969 |
| 10kb-50kb | 0.964 | 0.966 | 0.965 |
| >50kb | 1.000 | 1.000 | 1.000 |
# 5-base Structural Variants
**Currently, Illumina 5-base supports only PCR prep**
The DRAGEN Structural Variant (SV) caller identifies large insertions, deletions and genomic arrangements from mapped DNA reads. For details, refer to the [DRAGEN user guide for structural variant calling](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/sv-calling).
**DRAGEN**: DRAGEN 4.5.4 | **Truthset**: SV T2TQ100-v1.1 v0.019 (HG002) | **Reference**: GRCh38
SV 5-base accuracy table (click to expand)
| Method | Recall | Precision | F1-score |
| ---------------------------- | ------ | --------- | -------- |
| DRAGEN 4.5.4 (RefineVariant) | 0.6770 | 0.9794 | 0.8006 |
# DRAGEN Reference Support
DRAGEN supports the construction of reference hash tables for both human and non-human reference genomes. The reference autodetect feature of DRAGEN is able to recognize the reference hash tables build on the four Human reference genomes: hg19 (`hg19`), GRCh37/hs37d5 (`hs37d5`), GRCh38/hs38d1(`hg38`), and T2T-CHM13v2.0 (`chm13`).
DRAGEN supports pangenome reference hash tables which extend the reference genomes with alternative variant paths from a sample cohort used to construct the pangenome reference. A pangenome-based reference improves the mapping accuracy of Illumina reads in the “Difficult-to-Map Regions” of the genome and the downstream variant calling.
Pre-built human references are available for download at [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
The pangenome is the recommended reference for germline human analyses. The accuracy achieved with pangenome references are highlighted in the plot below.
In the following tables we summarize the reference support for each DRAGEN component and the recommended reference type for each component.
| Pipeline | hg19 | hs37d5 | hg38 | chm13 | Recommended (Human) | Recommended (Non-Human) |
| -------------------------- | --------- | --------- | ---- | --------- | ------------------- | ----------------------- |
| **Germline** | Yes | Yes | Yes | *Note1\** | Pangenome | Linear |
| **Somatic** | Yes | Yes | Yes | *Note2\** | Linear | Linear |
| **RNA** | Yes | Yes | Yes | *Note1\** | Linear | Linear |
| **Methyl 5-base Germline** | Yes | Yes | Yes | No | Pangenome | Linear |
| **Methyl 5-base Somatic** | Yes | Yes | Yes | No | Linear | Linear |
| **Methyl TruSeq** | Yes | Yes | Yes | No | Linear | Linear |
| **scRNA** | Yes | Yes | Yes | *Note1\** | Linear | Linear |
| **TruPath** | *Note3\** | *Note3\** | Yes | No | Pangenome | Linear |
| **Annotation** | Yes | Yes | Yes | No | Pangenome | Linear |
*Note1\* DRAGEN™ supports the component execution; however, the component's accuracy has not been established. Validated only for SNV. Accuracy not validated for CNV, SV, Joint Genotyping, HLA, gVCFGenotyper, RNA and scRNA. Not supported for STR, Targeted Callers, MRJD*
*Note2\* DRAGEN™ supports the component execution; however, the component's accuracy has not been established.*
*Note3\* Experimental use only. The component's functionality and accuracy has not been established with this reference.*
### Component availability per pipeline
| Pipeline | Components |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| Germline | SNV, CNV, SV, STR, Targeted Callers, MRJD, RNA, De Novo, Joint Genotyping, Biomarkers (HLA), gVCF genotyper |
| Somatic | SNV, UMI SNV, CNV, SV |
| Methylation | 5-base, TruSeq DNA Methyl, TruSeq Methyl Capture |
| Single cell | RNA, ATAC |
| TruPath | SNV, CNV, SV, STR, Targeted Callers, MRJD |
| Annotation | Nirvana |
By default, DRAGEN will error out if a linear reference is provided when running a component for which a pangenome reference is recommended as listed in the above table. If you are sure that a linear reference is desired, the error can be suppressed by setting `--validate-pangenome-reference=false`.
See [Prepare a Reference Genome](/dragen-v4.5/product-guides/dragen-v4.5/dragen-reference-support/prepare-a-reference-genome) for how to build a custom reference genome.
# Prepare a Reference Genome
Before a reference genome can be used with DRAGEN, it must be converted from FASTA format into a custom binary format for use with the DRAGEN hardware. The options used in this preprocessing step offer tradeoffs between performance and mapping quality.
Pre-built DRAGEN reference genomes are available for download in the Illumina customer portal. If you find that performance and mapping quality with these are adequate, there is a good chance that you can simply work with these supplied reference genomes. Depending on your read lengths and other particular aspects of your application, you may be able to improve mapping quality and/or performance by tuning the reference preprocessing options.
## Hash Table Background
The DRAGEN mapper extracts many overlapping seeds (subsequences or K-mers) from each read, and looks up those seeds in a hash table residing in memory on its PCIe card, to identify locations in the reference genome where the seeds match. Hash tables are ideal for extremely fast lookups of exact matches. The DRAGEN hash table must be constructed from a chosen reference genome using the `--build-hash-table option`, which extracts many overlapping seeds from the reference genome, populates them into records in the hash table, and saves the hash table as a binary file.
### Automatic Reference Detection
DRAGEN will attempt to detect the provided reference in order to automatically apply recommended resources and settings. There are four human references that DRAGEN can detect: hg38, hg19, hs37d5, and chm13v2. DRAGEN is able to detect references that contain a subset of the primary contigs from one of these references, as long as the names and lengths of the detected contigs are consistent with the names and lengths from the standarad assemblies of these references.
In detail, automatic reference detection operates as follows:
We define a primary contig of a human genome to be an autosome (1-22) or sex chromosome (X,Y). Let F be the input fasta. For each reference genome R in hg38, hg19, hs37d5, and chm13v2, DRAGEN checks if there are any contigs in F that have the same name and length as a primary contig in R, and that there are no contigs in F that have the same name as a contig in R, but with different length. If these conditions hold for exactly one of hg38, hg19, hs37d5, and chm13v2, then that reference is detected and resources may be applied automatically.
The DRAGEN hash table builder will automatically apply decoy contigs and mask bed files to detected reference. Other pipelines may also apply automatic resources. For example variant callers may apply machine learning models and target bed files.
#### Naming Conventions
In order for DRAGEN to correctly detect the provided reference, it is important to use the standard naming conventions for each of the four human assemblies that DRAGEN detects:
| Assembly | Autosome and Sex Chromosome Names |
| ------------------- | --------------------------------- |
| hg38, hg19, chm13v2 | chr1-chr22, chrX, chrY |
| hs37d5 | 1-22, X, Y |
### Reference Seed Interval
The size of the DRAGEN hash table is proportionate to the number of seeds populated from the reference genome. The default is to populate a seed starting at every position in the reference genome, ie, roughly 3 billion seeds from a human genome. This default requires at least 32 GB of memory on the DRAGEN PCIe board.
To operate on larger, nonhuman genomes or to reduce hash table congestion, it is possible to populate less than all reference seeds using the `--ht-ref-seed-interval` option to specify an average reference interval. The default interval for 100% population is `--ht-ref-seed-interval 1`, and 50% population is specified with `--ht-ref-seed-interval 2`. The population interval does not need to be an integer. For example, `--ht-ref-seed-interval 1.2` indicates 83.3% population, with mostly 1-base and some 2-base intervals to achieve a 1.2 base interval on average.
### Hash Table Occupancy
It is characteristic of hash tables that they are allocated a certain size, but always retain some empty records, so they are less than 100% occupied. A healthy amount of empty space is important for quick access to the DRAGEN hash table. Approximately 90% occupancy is a good upper bound. Empty space is important because records are pseudo-randomly placed in the hash table, resulting in an abnormally high number of records in some places. These congested regions can get quite large as the percentage of empty space approaches zero, and queries by the DRAGEN mapper for some seeds can become increasingly slow.
### Hash Table / Seed Length
The hash table is populated with reference seeds of a single common length. This primary seed length is controlled with the `--ht-seed-len` option, which defaults to 21.
The longest primary seed supported is 27 bases when the table is 8 GB to 31.5 GB in size. Generally, longer seeds are better for run time performance, and shorter seeds are better for mapping quality (success rate and accuracy). A longer seed is more likely to be unique in the reference genome, facilitating fast mapping without needing to check many alternative locations. But a longer seed is also more likely to overlap a deviation from the reference (variant or sequencing error), which prevents successful mapping by an exact match of that seed (although another seed from the read may still map), and there are fewer long seed positions available in each read.
Longer seeds are more appropriate for longer reads, because there are more seed positions available to avoid deviations.
Seed Length Recommendations
| Value for `--ht-seed-len` | Read Length |
| ------------------------- | --------------------- |
| 21 | 100 bp to 150 bp |
| 17 to 19 | shorter reads (36 bp) |
| 27 | 250+ bp |
### Hash Table / Seed Extensions
Due to repetitive sequences, some seeds of any given length match many locations in the reference genome. DRAGEN uses a unique mechanism called seed extension to successfully map such high-frequency seeds. When the software determines that a primary seed occurs at many reference locations, it extends the seed by some number of bases at both ends, to some greater length that is more unique in the reference.
For example, a 21-base primary seed may be extended by 7 bases at each end to a 35-base extended seed. A 21-base primary seed may match 100 places in the reference. But 35-base extensions of these 100 seed positions may divide into 40 groups of 1-3 identical 35-base seeds. Iterative seed extensions are also supported, and are automatically generated when a large set of identical primary seeds contains various subsets that are best resolved by different extension lengths.
The maximum extended seed length, by default equal to the primary seed length plus 128, can be controlled with the `--ht-max-ext-seed-len` option. For example, for short reads, it is advisable to set the maximum extended seed shorter than the read length, because extensions longer than the whole read can never match.
It is also possible to tune how aggressively seeds are extended using the following options (advanced usage):
`--ht-cost-coeff-seed-len`
`--ht-cost-coeff-seed-freq`
`--ht-cost-penalty`
`--ht-cost-penalty-incr`
There is a tradeoff between extension length and hit frequency. Faster mapping can be achieved using longer seed extensions to reduce seed hit frequencies, or more accurate mapping can be achieved by avoiding seed extensions or keeping extensions short, while tolerating the higher hit frequencies that result. Shorter extensions can benefit mapping quality both by fitting seeds better between SNPs, and by finding more candidate mapping locations at which to score alignments. The default extension settings along with default seed frequency settings, lean aggressively toward mapping accuracy, with relatively short seed extensions and high hit frequencies.
The defaults for the seed frequency options are as follows:
| Option | Default |
| --------------------------- | ------- |
| `--ht-cost-coeff-seed-len` | 1 |
| `--ht-cost-coeff-seed-freq` | 0.5 |
| `--ht-cost-penalty` | 0 |
| `--ht-cost-penalty-incr` | 0.7 |
| `--ht-max-seed-freq` | 16 |
| `--ht-target-seed-freq` | 4 |
### Seed Frequency Limit and Target
One primary or extended seed can match multiple places in the reference genome. All such matches are populated into the hash table, and retrieved when the DRAGEN mapper looks up a corresponding seed extracted from a read. The multiple reference positions are then considered and compared to generate aligned mapper output. However, the DRAGEN software enforces a limit on the number of matches, or frequency, of each seed, which is controlled with the `--ht-max-seed-freq option`. By default, the frequency limit is 16. In practice, when the software encounters a seed with higher frequency, it extends it to a sufficiently long secondary seed that the frequency of any particular extended seed pattern falls within the limit. However, if a maximum seed extension would still exceed the limit, the seed is rejected, and not populated into the hash table. Instead, a single High Frequency record is populated.
This seed frequency limit does not tend to impact DRAGEN mapping quality notably, for two reasons. First, because seeds are rejected only when extension fails, only extremely high-frequency primary seeds, typically with many thousands of matches are rejected. Such seeds are not very useful for mapping. Second, there are other seed positions to check in a given read. If another seed position is unique enough to return one or more matches, the read can still be properly mapped. However, if all seed positions were rejected as high frequency, often this means that the entire read matches similarly well in many reference positions, so even if the read were mapped it would be an arbitrary choice, with very low or zero MAPQ.
Thus, the default frequency limit of 16 for `--ht-max-seed-freq` works well. However, it may be decreased or increased, up to a maximum of 256. A higher frequency limit tends to marginally increase the number of reads mapped (especially for short reads), but commonly the additional mapped reads have very low or zero MAPQ. This also tends to slow down DRAGEN mapping, because correspondingly large numbers of possible mappings are occasionally considered.
In addition to a frequency limit, a target seed frequency can be specified with `--ht-target-seed-freq` option. This target frequency is used when extensions are generated for high frequency primary seeds. Extension lengths are chosen with a preference toward extended seed frequencies near the target. The default of 4 for `--ht-target-seed-freq` means that the software is biased toward generating shorter seed extensions than necessary to map seeds uniquely.
### References with ALT contigs
When building a reference hash table from a fasta with ALT contigs, it may be desired to mask certain regions of high similarity, or to establish a liftover realtionships between primary and alternate contigs. The recommended approach is masking, as described in the Map-Align section. When hg19 or hg38 alt contigs are detected, the hash table builder will require a liftover file or a bed file to mask the alt contigs. If non are provided, a mask bed file from `/resources/ht_builder/` will be used automaticaly.
### Masked References
DRAGEN has adopted a masked approach to handle native reference ALT contigs, where strategic regions are masked to increased accuracy. The hash table builder will build the mapper hash table as if the regions that were specified in the argument for `ht-mask-bed` were masked with N's. The hash table builder will only allow setting one of `ht-mask-bed` or `ht-alt-liftover`. Each line in the bed file is expected to contain a contig name, start position (0-based), and end position (1-based), seperated by a single tab or space. Lines that start with # are ignored by the hash table builder to allow commenting. Any line with a contig name that is not found in the input fasta is skipped and logged to the DRAGEN log file. Likewise, lines that describe empty intervals are skipped. If all lines are skipped this way, the hash table builder will issue an error and abort, unless the mask bed file was automatically applied (see Automatic masking). The hash table builder will always issue an error and abort if an interval described in the BED file is outside of the range of the corresponding contig in the fasta. Lines that are not skipped are written to a file called mask.bed that will be present in the hash table output directory, and whose digest will appear in hash\_table.cfg. This file is used when a reference is loaded to the FPGA card to dynamically mask reference.bin.
### Automatic masking
When running from a fasta for which hg38 or hg19 is detected (See Automatic Reference Detection), and no argument for `ht-mask-bed` or `ht-alt-liftover` was provided, the hash table builder will automatically apply the corresponding bed file for the detected reference from `/resources/ht_builder/`. Note that the hash table builder will identify alt contigs by name. So when running from an input fasta that contains alt contig with standard names but modified base content, it is recommended to suppress automatic masking by setting `ht-suppress-mask=true` or by passing a custom mask bed file to `ht-mask-bed`.
### Handling Decoy Contigs
The behavior of DRAGEN with respect to the handling of decoy contigs in the reference has changed since version 2.6.
Starting with DRAGEN 3.x, DRAGEN's hash table builder automatically detects the absence of the decoy contigs from the reference and adds it to the FASTA file, prior to building the hash table. The decoys file is found at `/resources/ht_builder/hs_decoys.fa.gz`. If the reference is missing the decoy contigs, then the reads which map to the decoy contigs are artificially marked as unmapped in the output BAM (because the original reference does not have the decoy contig). This results in an artificially lower mapping rate, however, the accuracy of variant calling is improved thanks to removing false positive caused by decoy reads.
Illumina recommends using this feature by default. However, you can to set the `--ht-suppress-decoys` option to true to suppress adding these decoys to the hash table.
The table below describes the difference in behavior between older DRAGEN versions (2.6 and earlier) and DRAGEN 3.x versions with respect to the handling of decoy contigs in the hash table builder:
| DRAGEN Behavior | DRAGEN 2.6 and earlier versions | DRAGEN 3.0 and later versions |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reference does not include the decoy contigs (eg, hg19) | Decoy reads mismap elsewhere in the genome due to the lack of contigs in the reference.
Artificially higher mapping rate.
False positive calls in noisy regions to which the decoy contigs are mismapped.
| DRAGEN automatically detects the absence of the decoy contig from the reference and adds it to the FASTA file.
Artificially lower mapping rate because decoy reads which map to the decoy contigs are artificially marked as unmapped in the output BAM (because the original reference does not have the decoy contig).
False positive calls are avoided thanks to adding the decoy contigs under the hood. Therefore this helps variant calling.
|
| Reference includes the decoy contigs (eg, hs37d5) | Decoy reads map to the decoy contigs.
High mapping rate.
No false positive calls caused by decoy reads because decoy reads map to the right place
| Decoy reads map to the decoy contigs.
High mapping rate.
No false positive calls caused by decoy reads because decoy reads map to the right place
|
## Prepare a Pangenome Reference
DRAGEN analysis is capable of mapping on a pangenome hash table. The pangenome hash table introduces alternate graph paths to the linear reference hash table to represent more broadly the allelic diversity of the population over the whole genome or in specific regions defined in a bed file. Gain on accuracy from this methodology has been described in scientific blogs available on the [Illumina Genomics Research Hub site](https://www.illumina.com/science/genomics-research.html). Mutigenome hash tables for CHM13\_v2, hg38, hg19 and hs37d5 assemblies are available on the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
See [DRAGEN Multigenome Mapper](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/dna-map-align#dragen-multigenome-mapper) for information on the multigenome mapping method.
It is possible to build a custom pangenome reference in order to:
* customize the released pangenome hash table with custom bed files or hash table builder options. A set of bed files are available in the resource files on the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
* generate a population-specific-pangenome hash table from pangenome msVCF generated from the BSSH app.
* generate a human or non-human pangenome hash table from customer-provided msVCF.
The input files required are a single multi-sample VCF file containing the set of population variants, and optionally bed files restricting graph to some region. The generated files, including hash\_table.cmp and associated files in the specified output directory, can then be used as the reference hash table for the DRAGEN mapper. DRAGEN software supports the tool on human reference with files available on the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html). For non-human, the user provides the required resource files.
### Usage
To enable the pangenome hash table builder, example command usage is :
`dragen --build-hash-table true (required) --ht-graph-msvcf-file (required) --ht-graph-extra-kmer-bed < graph.bed> (optional) --ht-mask-bed (optional) --ht-graph-exclusion-bed (optional) --output-directory (required) [options]`
### Inputs
#### Set of population variants, in a multi-sample VCF (msVCF)
The custom pangenome hash table builder tool uses a set of population variants provided by the user to generate a pangenome hash table. The variants must be specified in VCF format, in a single multi-sample VCF (msVCF) file containing the variants for a set of individuals. This multi-sample VCF file must have specific formatting described below.
#### Specific msVCF input formatting
The custom pangenome hash table builder tool only supports msVCF file input respecting the format described below:
* msVCF compliant with 4.2 VCF format specification
* with variants positionally sorted in the same contig order as the main FASTA reference genome provided in --ht-reference
* records shall include diploid or haploid GT calls
* supports multi-allelic variants merged in multi-line or separated in multiple lines
* with the following FILTER codes, non-PASS records are ignored:
* \##FILTER=\
* with the following FORMAT field :
* \##FORMAT=\
* for better results, we recommend variants to be left-aligned.
* maximum number of recommended samples in the msVCF is 256. Higher number may lead to very high memory usage at hash table creation.
> Note: INFO/FORMAT subfields must be defined in the header. Events with undefined subfields are ignored.
To build a high-performance custom genome it is highly recommended to use long read sequencing data. We recommend using external tools such as Whatshap () to generate phased input. DRAGEN analysis leverages the phasing information to reconstruct population haplotypes.
#### Reference genome
A reference genome in FASTA format must be provided. Reference genomes are available to download from the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
> Note: the reference genome provided as input must be the same as the one used to generate the input phased msVCF. If the msVCF contains variants from regions not present in the fasta file, the pangenome reference builder will stop with an error.
#### Exclusion bed file (optional)
This bed file is used to filter out regions of the msVCF file. Variants that fall within intervals defined in the "Graph exclusion bed" file will be ignored and not used in any part of the pangenome reference builder. The result will be the same as if the input msVCF did not contain any variants in the regions defined in the exclusion bed. The file is optional, by default every variants in the msVCF file will be used. Exclusion bed files are available to download from [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
A custom exclusion bed file can also be provided given the following format: tab delimited with first three columns being: contig name, start position, end position. Any line with a contig name that is not found in the input FASTA is skipped. Any lines that describe empty intervals are skipped.
> Note: records of the exclusion bed file provided must be from the same build as the reference genome used to build the pangenome reference.
#### Extra kmer bed file (optional)
This file is used to define regions in the genome where extra seeds will be indexed in the hash table. By default, only seed extracted from the primary reference will be extracted and saved in the reference hash table for mapping. This option will additionally generate seeds from population variants in the defined regions. It is recommended to include the expected difficult regions in this bed file. Extra-kmer-bed files are available to download from [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html) for the human hg38, hg19, hs37d5, and chm13 references.
An Extra-kmer-bed bed file can also be provided given the following format: tab delimited with first three columns being: contig name, start position, end position. Any line with a contig name that is not found in the input FASTA is skipped. Any lines that describe empty intervals are skipped.
> Note: records of the Extra-kmer-bed file provided must be from the same build as the reference genome used to build the graph reference.
#### Mask bed file (recommended)
A mask bed file must be provided in order to mask certain regions of high similarity between primary and alternate contigs present in the main genome FASTA. Mask bed files are available to download from the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
A custom mask bed file can also be provided given the following format: tab delimited with first three columns being: contig name, start position, end position. Any line with a contig name that is not found in the input FASTA is skipped. Any lines that describe empty intervals are skipped.
> Note: records of the mask bed file provided must be from the same build as the reference genome used to build the graph reference.
### Command line options
| Option | Required | Description |
| ------------------------- | -------------------- | ------------------------------------------------------------------------ |
| --build-hash-table | Yes | Set to true |
| --ht-graph-msvcf-file | Yes | Path to the multi-sample VCF file containing population variants |
| --ht-reference | Yes | Path to the reference genome FASTA file. |
| --ht-graph-extra-kmer-bed | No | Path to the extra kmer bed file |
| --ht-mask-bed | No (but recommended) | Path to the mask bed file |
| --ht-graph-exclusion-bed | No | Path to the exclusion bed file |
| --output-directory | Yes | Specify the directory where all related hash table files will be written |
> Note: The custom graph reference hash table end to end pipeline will return an error if options --ht-alt-liftover or --ht-allow-mask-and-liftover are specified.
### Output
The hash table builder generates the following outputs:
| File | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| reference.bin | The reference sequences, encoded in 4 bits per base. Four-bit codes are used, so the size in bytes is roughly half the reference genome size. In between reference sequences, N are trimmed and padding is automatically inserted. For example, hg19 has 3,137,161,264 bases in 93 sequences. This is encoded in 1,526,285,312 bytes = 1.46 GB, where 1 GB means 1 GiB or 2^30^ bytes. |
| hash\_table.cmp | Compressed hash table. The hash table is decompressed and used by the DRAGEN mapper to look up primary seeds with length specified by the `--ht-seed-len` option and extended seeds of various lengths. |
| hash\_table.cfg | A list of parameters and attributes for the generated hash table, in a text format. This file provides key information about the reference genome and hash table. |
| hash\_table.cfg.bin | A binary version of hash\_table.cfg used to configure the DRAGEN hardware. |
| hash\_table\_stats.txt | A text file listing extensive internal statistics on the constructed hash including the hash table occupancy percentages. This table is for information purposes. It is not used by other tools. |
| mask.bed | Present only for masked hash tables. A tab delimeted bed file that describes the masked regions. Contains all lines from the input bed file that are not comment lines, lines that describe empty intervals, or lines with contig names that were not found in the input fasta. |
## Prepare a linear Reference
### Usage
Use the `--build-hash-table` option to transform a reference FASTA into the hash table for DRAGEN mapping. It takes as input a FASTA file (multiple reference sequences being concatenated) and a preexisting output directory. Build command usage is as follows:
```
dragen --build-hash-table true [options] --ht-reference
--output-directory
```
### Input
The `--ht-reference` and `--output-directory` options are required for building a hash table. The `--ht‑reference` option specifies the path to the reference FASTA file, while `--output-directory` specifies a preexisting directory where the hash table output files are written. Illumina recommends organizing various hash table builds into different folders. As a best practice, folder names should include any nondefault parameter settings used to generate the contained hash table. The sequence names in the reference FASTA file must be unique.
### Command line options
| Option | Required | Description |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| --build-hash-table | Yes | Set to true |
| --ht-reference | Yes | Path to the reference genome FASTA file. |
| --ht-mask-bed | No (but recommended) | Path to the mask bed file. If not provided, the DRAGEN software automatically applies BED files for hg38 and hg19 from `/resources/ht_builder`. |
| --output-directory | Yes | Specify the directory where all related hash table files will be written |
#### Liftover Based ALT-Aware Hash Tables
While masking is the recommended approach to dealing with ALT contigs, DRAGEN also supports a liftover based method. To enable liftover based ALT-aware mapping in DRAGEN, build the hash table with a liftover file by using the `--ht-alt-liftover` option. The hash table builder classifies each reference sequence as primary or alternate based on the liftover file, and packs primaries before alternates in reference.bin. SAM liftover files for hg38DH and hg19 are in the `/resources/ht_builder` folder.
**Custom Liftover Files**
Custom liftover files can be used in place of those provided with DRAGEN. Liftover files must be SAM format, but no SAM header is required. SEQ and QUAL fields can be omitted ('\*'). Each alignment record should have an alternate haplotype reference sequence name as QNAME, indicating the RNAME and POS of its liftover alignment in a destination (normally primary assembly) reference sequence.
Reverse-complemented alignments are indicated by bit 0x10 in FLAG. Records flagged unmapped (0x4) or secondary (0x100) are ignored. The CIGAR may include hard or soft clipping, leaving parts of the ALT contig unaligned.
A single reference sequence cannot serve as both an ALT contig (appearing in QNAME) and a liftover destination (appearing in RNAME). Multiple ALT contigs can align to the same primary assembly location. Multiple alignments can also be provided for a single ALT contig (extras optionally be flagged 0x800 supplementary), such as to align one portion forward and another portion reverse-complemented. However, each base of the ALT contig only receives one liftover image, according to the first alignment record with an M CIGAR operation covering that base.
SAM records with QNAME missing from the reference genome are ignored, so that the same liftover file may be used for various reference subsets, but an error occurs if any alignment has its QNAME present but its RNAME absent.
## Options for advanced users
### Primary Seed Length
The `--ht-seed-len` option specifies the initial length in nucleotides of seeds from the reference genome to populate into the hash table. At run time, the mapper extracts seeds of this same length from each read, and looks for exact matches (unless seed editing is enabled) in the hash table.
The maximum primary seed length is a function of hash table size. The limit is k=27 for table sizes from 16 GB to 64 GB, covering typical sizes for whole human genome, or k=26 for sizes from 4 GB to 16 GB.
The minimum primary seed length depends mainly on the reference genome size and complexity. It needs to be long enough to resolve most reference positions uniquely. For whole human genome references, hash table construction typically fails with k < 16. The lower bound may be smaller for shorter genomes, or higher for less complex (more repetitive) genomes. The uniqueness threshold of `--ht-seed-len 16` for the 3.1Gbp human genome can be understood intuitively because log4(3.1 G) ≈ 16, so it requires at least 16 choices from 4 nucleotides to distinguish 3.1 G reference positions.
#### Accuracy Considerations
For read mapping to succeed, at least one primary seed must match exactly (or with a single SNP when edited seeds are used). Shorter seeds are more likely to map successfully to the reference, because they are less likely to overlap variants or sequencing errors, and because more of them fit in each read. So for mapping accuracy, shorter seeds are mainly better.
However, very short seeds can sometimes reduce mapping accuracy. Very short seeds often map to multiple reference positions, and lead the mapper to consider more false mapping locations. Due to imperfect modeling of mutations and errors by Smith-Waterman alignment scoring and other heuristics, occasionally these noise matches may be reported. Run time quality filters such as `--Aligner.aln_min_score` can control the accuracy issues with very short seeds.
#### Speed Considerations
Shorter seeds tend to slow down mapping, because they map to more reference locations, resulting in more work such as Smith-Waterman alignments to determine the best result. This effect is most pronounced when primary seed length approaches the reference genome's uniqueness threshold, eg, K=16 for whole human genome.
#### Application Considerations
**Read Length**---Generally, shorter seeds are appropriate for shorter reads, and longer seeds for longer reads. Within a short read, a few mismatch positions (variants or sequencing errors) can chop the read into only short segments matching the reference, so that only a short seed can fit between the differences and match the reference exactly. For example, in a 36 bp read, just one SNP in the middle can block seeds longer than 18 bp from matching the reference. By contrast, in a 250 bp read, it takes 15 SNPs to exceed a 0.01% chance of blocking even 27 bp seeds.
**Paired Ends**---The use of paired end reads can make longer seeds yield good mapping accuracy. DRAGEN uses paired end information to improve mapping accuracy, including with rescue scans that search the expected reference window when only one mate has seeds mapping to a given reference region. Thus, paired end reads have essentially twice the opportunity for an exact matching seed to find their correct alignments.
**Variant or Error Rate**---When read differences from the reference are more frequent, shorter seeds may be required to fit between the difference positions in a given read and match the reference exactly.
**Mapping Percentage Requirement**---If the application requires a high percentage of reads to be mapped somewhere (even at low MAPQ), short seeds may be helpful. Some reads that do not match the reference well anywhere are more likely to map using short seeds to find partial matches to the reference.
### Maximum Seed Length
The `--ht-max-ext-seed-len` option limits the length of extended seeds populated into the hash table. Primary seeds (length specified by `--ht-seed-len`) that match many reference positions can be extended to achieve more unique matching, which may be required to map seeds within the maximum hit frequency (`--ht-max-seed-freq`).
Given a primary seed length k, the maximum seed length can be configured between k and k+128. The default is the upper bound, k+128.
#### When to Limit Seed Extension
The `--ht-max-ext-seed-len` option is recommended for short reads, eg, less than 50 bp. In such cases, it is helpful to limit seed extension to the read length minus a small margin, such as 1-4 bp. For example, with 36 bp reads, setting `--ht-max-ext-seed-len` to 35 might be appropriate. This ensures that the hash table builder does not plan a seed extension longer than the read causing seed extension and mapping to fail at run time, for seeds that could have fit within the read with shorter extensions.
While seed extension can be similarly limited for longer reads, eg, setting `--ht-max-ext-seed-len` to 99 for 100 bp reads, there is little utility in this because seeds are extended conservatively in any event. Even with the default k+128 limit, individual seeds are only extended to the lengths required to fit under the maximum hit frequency (`--ht-max-seed-freq`), and at most a few bases longer to approach the target hit frequency (`‑‑ht‑target-seed-freq`), or to avoid taking too many incremental extension steps.
### Maximum Hit Frequency
The `--ht-max-seed-freq` option sets a firm limit on the number of seed hits (reference genome locations) that can be populated for any primary or extended seed. If a given primary seed maps to more reference positions than this limit, it must be extended long enough that the extended seeds subdivide into smaller groups of identical seeds under the limit. If, even at the maximum extended seed length (`--ht-max-ext-seed-len`), a group of identical reference seeds is larger than this limit, their reference positions are not populated into the hash table. Instead, a single High Frequency record is populated.
The maximum hit frequency can be configured from 1 to 256. However, if this value is too low, hash table construction can fail because too many seed extensions are needed. The practical minimum for a whole human genome reference, other options being default, is 8.
#### Accuracy Considerations
Generally, a higher maximum hit frequency leads to more successful mapping. There are two reasons for this. First, a higher limit rejects fewer reference positions that cannot map under it. Second, a higher limit allows seed extensions to be shorter, improving the odds of exact seed matching without overlapping variants or sequencing errors.
However, as with very short seeds, allowing high hit counts can sometimes hurt mapping accuracy. Most of the seed hits in a large group are not to the true mapping location, and occasionally one of these noise hits may be reported due to imperfect scoring models. Also, the mapper limits the total number of reference positions it considers, and allowing very high hit counts can potentially crowd out the actual best match from consideration.
#### Speed Considerations
Higher maximum hit frequencies slow down read mapping, because seed mapping finds more reference locations, resulting in more work, such as Smith-Waterman alignments, to determine the best result.
### Pangenome Reference
The DRAGEN Software enables the user to build a custom pangenome hash table from a set of population variants. The population variants are specified in a single multi-sample VCF file.
* `--ht-graph-msvcf-file: Input file containing list of population variants, in multi-sample VCF format.`
This replaces the previous options that were previously used to build a graph Reference that are now deprecated.
List of deprecated options :
* `--ht-pop-alt-contigs: Population based alternate contigs FASTA.`
* `--ht-pop-alt-liftover: Liftover SAM file of population alternate contigs.`
* `--ht-pop-snps: Population based SNPs VCF`
### ALT-Contigs
The following options control building hash tables from references with ALT-contigs. See References with ALT contigs for more information.
* `--ht-mask-bed`: Set a custom BED file that defines which regions to mask. If not provided, the DRAGEN software automatically applies BED files for hg38 and hg19 from `/resources/ht_builder`.
* `--ht-alt-liftover`: Set a liftover file to build a liftover based ALT-aware hash table. SAM liftover files for hg38DH and hg19 are provided in `/resources/ht_builder`.
* `--ht-allow-mask-and-liftover`: Allow the use of both `--ht-mask-bed` and `--ht-alt-liftover` together.
* `--ht-suppress-mask`: Suppress automatic detection of the default mask bed files when building the hash table.
### Decoy Contigs
* `--ht-decoys` The DRAGEN software automatically detects the use of hg19 and hg38 references and adds decoys to the hash table when they are not found in the FASTA file. Use the `--ht-decoys` option to specify the path to a decoys file. The default is `/resources/ht_builder/hs_decoys.fa.gz`.
* `--ht-suppress-decoys`: Suppress automatic detection of the default decoys file when building the hash table.
### Processing Options
* `--ht-num-threads` The `--ht-num-threads` option determines the maximum number of worker CPU threads that are used to speed up hash table construction. The default for this option is 8, with a maximum of 32 threads allowed. If your server supports execution of more threads, it is recommended that you use the maximum. For example, the DRAGEN servers contain 24 cores that have hyperthreading enabled, so a value of 32 should be used. When using a higher value, adjust `--ht-max-table-chunks` needs to be adjusted as well. The servers have 128 GB of memory available.
* `--ht-max-table-chunks` The `--ht-max-table-chunks` option controls the memory footprint during hash table construction by limiting the number of \~1 GB hash table chunks that reside in memory simultaneously. Each additional chunk consumes roughly twice its size (\~2 GB) in system memory during construction. The hash table is divided into power-of-two independent chunks, of a fixed chunk size, X, which depends on the hash table size, in the range 0.5 GB < X ≤ 1 GB. For example, a 24 GB hash table contains 32 independent 0.75 GB chunks that can be constructed by parallel threads with enough memory and a 16 GB hash table contains 16 independent 1 GB chunks. The default is `--ht-max-table-chunks` equal to `--ht-num-threads`, but with a minimum default `--ht-max-table-chunks` of 8. It makes sense to have these two options match, because building one hash table chunk requires one chunk space in memory and one thread to work on it. Nevertheless, there are build-speed advantages to raising `--ht-max-table-chunks` higher than `--ht-num-threads`, or to raising `--ht-num-threads` higher than `--ht-max-table-chunks`.
### Size Options
* `--ht-mem-limit` Memory Limit. The `--ht-mem-limit` option controls the generated hash table size by specifying the DRAGEN card memory available for both the hash table and the encoded reference genome. The `‑‑ht‑mem-limit` option defaults to 32 GB when the reference genome approaches WHG size, or to a generous size for smaller references. Normally there is little reason to override these defaults.
* `--ht-size` Hash Table Size. This option specifies the hash table size to generate, rather than calculating an appropriate table size from the reference genome size and the available memory (option `--ht-mem-limit`). Using default table sizing is recommended and using `--ht-mem-limit` is the next best choice.
### Seed Population Options
* `--ht-ref-seed-interval` Seed Interval. The `--ht-ref-seed-interval` option defines the step size between positions of seeds in the reference genome populated into the hash table. An interval of 1 (default) means that every seed position is populated, 2 means 50% of positions are populated, etc. Noninteger values are supported, eg, 2.5 yields 40% populated. Seeds from a whole human reference are easily 100% populated with 32 GB memory on DRAGEN boards. If a substantially larger reference genome is used, change this option.
* `--ht-soft-seed-freq-cap` and `--ht-max-dec-factor` Soft Frequency Cap and Maximum Decimation Factor for Seed Thinning. Seed thinning is an experimental technique to improve mapping performance in high-frequency regions. When primary seeds have higher frequency than the cap indicated by the `--ht-soft-seed-freq-cap option`, only a fraction of seed positions are populated to stay under the cap. The `--ht-max-dec-factor` option specifies a maximum factor by which seeds can be thinned. For example, `--ht-max-dec-factor 3` retains at least 1/3 of the original seeds. `--ht-max-dec-factor 1` disables any thinning. Seeds are decimated in careful patterns to prevent leaving any long gaps unpopulated. The idea is that seed thinning can achieve mapped seed coverage in high frequency reference regions where the maximum hit frequency would otherwise have been exceeded. Seed thinning can also keep seed extensions shorter, which is also good for successful mapping. Based on testing to date, seed thinning has not proven to be superior to other accuracy optimization methods.
* `--ht-rand-hit-hifreq` and `--ht-rand-hit-extend` Random Sample Hit with HIFREQ Record and EXTEND Record. Whenever a HIFREQ or EXTEND record is populated into the hash table, it stands in place of a large set of reference hits for a certain seed. Optionally, the hash table builder can choose a random representative of that set, and populate that HIT record alongside the HIFREQ or EXTEND record. Random sample hits provide alternative alignments that are very useful in estimating MAPQ accurately for the alignments that are reported. They are never used outside of this context for reporting alignment positions, because that would result in biased coverage of locations that happened to be selected during hash table construction. To include a sample hit, set `--ht-rand-hit-hifreq` to 1. The `--ht-rand-hit-extend` option is a minimum pre-extension hit count to include a sample hit, or zero to disable. Modifying these options is not recommended.
### Seed Extension Control
DRAGEN seed extension is dynamic, applied as needed for particular K-mers that map to too many reference locations. Seeds are incrementally extended in steps of 2--14 bases (always even) from a primary seed length to a fully extended length. The bases are appended symmetrically in each extension step, determining the next extension increment if any.
There is a potentially complex seed extension tree associated with each high frequency primary seed. Each full tree is generated during hash table construction and a path from the root is traced by iterative extension steps during seed mapping. The hash table builder employs a dynamic programming algorithm to search the space of all possible seed extension trees for an optimal one, using a cost function that balances mapping accuracy and speed. The following options define that cost function:
* `--ht-target-seed-freq` Target Hit Frequency. The `--ht-target-seed-freq` option defines the ideal number of hits per seed for which seed extension should aim. Higher values lead to fewer and shorter final seed extensions, because shorter seeds tend to match more reference positions.
* `--ht-cost-coeff-seed-len` Cost Coefficient for Seed Length The `--ht-cost-coeff-seed-len` option assigns the cost component for each base by which a seed is extended. Additional bases are considered a cost because longer seeds risk overlapping variants or sequencing errors and losing their correct mappings. Higher values lead to shorter final seed extensions.
* `--ht-cost-coeff-seed-freq` Cost Coefficient for Hit Frequency. The `--ht-cost-coeff-seed-freq` option assigns the cost component for the difference between the target hit frequency and the number of hits populated for a single seed. Higher values result primarily in high-frequency seeds being extended further to bring their frequencies down toward the target.
* `--ht-cost-penalty` Cost Penalty for Seed Extension. The `--ht-cost-penalty` option assigns a flat cost for extending beyond the primary seed length. A higher value results in fewer seeds being extended at all. Current testing shows that zero (0) is appropriate for this parameter.
* `--ht-cost-penalty-incr` Cost Increment for Extension Step. The `--ht-cost-penalty-incr` option assigns a recurring cost for each incremental seed extension step taken from primary to final extended seed length. More steps are considered a higher cost because extending in many small steps requires more hash table space for intermediate EXTEND records, and takes substantially more run time to execute the extensions. A higher value results in seed extension trees with fewer nodes, reaching from the root primary seed length to leaf extended seed lengths in fewer, larger steps.
## Pipeline Specific Hash Tables
### RNA-Seq
When building a hash table, DRAGEN configures the options for DNA analysis by default. To run RNA-Seq data, you must build an RNA-Seq hash table by setting `--ht-build-rna-hashtable` to true. If running RNA-Seq alignment, use the original `--output-directory` instead of the automatically generated subdirectory.
### CNV
If using the CNV pipeline, set `--ht-build-cnv-hashtable` to true. The command generates an additional Kmer hash map that is used in the CNV algorithm. Illumina recommends to always use the `--ht-build-cnv-hashtable` option, so you can perform CNV calling with the same hash table used for mapping and aligning.
### Methylation
To run the methylation pipeline, you must build a methylation-specific hash table. DRAGEN can build a single-pass or legacy multi-pass methylation hash table. Methylation runs using a single-pass hash table are completed faster than the legacy multipass hash tables. Single-pass hash tables are recommended for building methylation tables and running analyses.
| Hash Table Type | Hash Table Commands |
| --------------- | ----------------------------------------------------------------- |
| single-pass | `--ht-methylated-combined=true` `--ht-seed-len 27` |
| multi-pass | `--ht-methylated=true` `--ht-seed-len 27` `--ht-max-seed-freq 16` |
#### Single-pass
The following is an example of a single-pass hash table build. The example generates a combined hash table in your reference index folder under the methyl\_converted subdirectory.
`dragen --build-hash-table true \ --output-directory $REFDIR \ --ht-reference $FASTA \ --ht-num-threads 40 \ --ht-methylated-combined=true \ --ht-seed-len 27`
#### Multipass
Multi-pass methylation mapping requires building two special hash tables with reference bases converted from C to T in one table and G to A in the other table. The conversions are performed automatically when using the `--ht-methylated` command line option. The converted hash tables are generated in two subdirectories under the folder specified using the `--output-directory` command line option. The subdirectories are named CT\_converted and GA\_converted, corresponding with the base conversions. When using the hash tables for methylated alignment runs, make sure to refer to the `--output-directory` folder, not the subdirectories.
The base conversions remove a significant amount of information from the hash tables. You might need to use different hash table parameters than in a conventional hash table build. The following options are recommended for building hash tables for mammalian species.
`dragen --build-hash-table=true --output-directory $REFDIR --ht-reference $FASTA --ht-max-seed-freq 16 --ht-seed-len 27 --ht-num-threads 40 --ht-methylated=true`
## HLA
To run the HLA caller, an HLA-specific anchored reference hash table must be built. Set `--ht-build-hla-hashtable` to true. The command will create a `anchored_hla` subdirectory inside the `--output-directory`. The HLA-specific reference subdirectory can be built at the same time as the primary reference construction.
An HLA resource file is packaged with DRAGEN and located at the following path after installation: `/resources/hla/HLA_resource.v1.fasta.gz`. This file is used by default when building the HLA-specific anchored hash table. A custom file can be specified with `--ht-hla-reference`. See the HLA section for more information [Using Custom HLA Reference Files](/dragen-v4.5/product-guides/dragen-v4.5/dragen-dna-pipeline/hla-typing#using-custom-hla-reference-files)
# DRAGEN DNA Pipeline
The DRAGEN DNA Pipeline accelerates the secondary analysis of NGS data by harnessing the tremendous power available on the DRAGEN Platform. The pipeline includes highly optimized algorithms for mapping, aligning, sorting, duplicate marking, and haplotype variant calling. In addition to haplotype variant calling, the pipeline supports calling of copy number and structural variants as well as detection of repeat expansions and targeted calls.
# DNA Mapping
### DNA Mapping
#### Seed Density Option
The *seed-density* option controls how many (normally overlapping) primary seeds from each read the mapper looks up in its hash table for exact matches. The maximum density value of 1.0 generates a seed starting at every position in the read, ie, (L-K+1) K-base seeds from an L-base read.
Seed density must be between 0.0 and 1.0. Internally, an available seed pattern equal or close to the requested density is selected. The sparsest pattern is one seed per 32 positions, or density 0.03125.
* **Accuracy Considerations**--Generally, denser seed lookup patterns improve mapping accuracy. However, for modestly long reads (eg, 50 bp+) and low sequencer error rates, there is little to be gained beyond the default 50% seed lookup density.
* **Speed Considerations**--Denser seed lookup patterns generally slow down mapping, and sparser seed patterns speed it up. However, when the seed mapping stage can run faster than the aligning stage, a sparser seed pattern does not make the mapper much faster.
**Relationship to Reference Seed Interval**
Functionally, a denser or sparser seed lookup pattern has an impact very similar to a shorter or longer reference seed interval (build hash table option `--ht-ref-seed-interval`). Populating 100% of reference seed positions and looking up 50% of read seed positions has the same effect as populating 50% of reference seed positions and looking up 100% of read seed positions. Either way, the expected density of seed hits is 50%.
More generally, the expected density of seed hits is the product of the reference seed density (the inverse of the reference seed interval) and the seed lookup density. For example, if 50% of reference seeds are populated and 33.3% (1/3) of read seed positions are looked up, then the expected seed hit density should be 16.7% (1/6).
DRAGEN automatically adjusts its precise seed lookup pattern to ensure it does not systematically miss the seed positions populated from the reference. For example, the mapper does not look up seeds matching only odd positions in the reference when only even positions are populated in the hash table, even if the reference seed interval is 2 and seed-density is 0.5.
#### Map Orientations Option
The `--Mapper.map-orientations` option is used in mapping reads for bisulfite methylation analysis. It is set automatically based on the value set for `‑‑methylation-protocol`.
The `--Mapper.map-orientations` option can restrict the orientation of read mapping to only forward in the reference genome, or only reverse-complemented. The valid values for `--map-orientations` are as follows.
* 0--Either orientation (default)
* 1--Only forward mapping
* 2--Only reverse-complemented mapping
If mapping orientations are restricted and paired end reads are used, the expected pair orientation can only be FR, not FF or RF.
#### Seed-Editing Options
Although DRAGEN primarily maps reads by finding exact reference matches to short seeds, it can also map seeds differing from the reference by one nucleotide by also looking up single-SNP edited seeds. Seed editing is usually not necessary with longer reads (100 bp+), because longer reads have a high probability of containing at least one exact seed match. This is especially true when paired ends are used, because a seed match from either mate can successfully align the pair. But seed editing can, for example, be useful to increase mapping accuracy for short single-ended reads, with some cost in increased mapping time. The following options control seed editing:
Seed Editing Options
| Command-Line Option Name | Configuration File Option Name |
| --------------------------- | ------------------------------ |
| `--Mappper.seed-density` | seed-density |
| `-Mapper.edit-mode` | edit-mode |
| `--Mapper.edit-seed-num` | edit-seed-num |
| `--Mapper.edit-read-len` | edit-read-len |
| `--Mapper.edit-chain-limit` | edit-chain-limit |
**edit-mode and edit-chain-limit**
The edit-mode and edit-chain-limit options control when seed editing is used. The following four edit-mode values are available:
| Mode | Description |
| ---- | ------------------------ |
| 0 | No editing (default) |
| 1 | Chain length test |
| 2 | Paired chain length test |
| 3 | Full seed editing |
Edit mode 0 requires all seeds to match exactly. Mode 3 is the most expensive because every seed that fails to match the reference exactly is edited. Modes 1 and 2 employ heuristics to look up edited seeds only for reads most likely to be salvaged to accurate mapping.
The main heuristic in edit modes 1 and 2 is a seed chain length test. Exact seeds are mapped to the reference in a first pass over a given read, and the matching seeds are grouped into chains of similarly aligning seeds. If the longest seed chain (in the read) exceeds a threshold edit-chain-limit, the read is judged not to require seed editing, because there is already a promising mapping position.
Edit mode 1 triggers seed editing for a given read using the seed chain length test. If no seed chain exceeds `edit-chain-limit` (including if no exact seeds match), then a second seed mapping pass is attempted using edited seeds. Edit mode 2 further optimizes the heuristic for paired-end reads. If either mate has an exact seed chain longer than `edit-chain-limit`, then seed editing is disabled for the pair, because a rescue scan is likely to recover the mate alignment based on seed matches from one read. Edit mode 2 is the same as mode 1 for single-ended reads.
**edit-seed-num and edit-read-len**
For edit modes 1 and 2, when the heuristic triggers seed editing, these options control how many seed positions are edited in the second pass over the read. Although exact seed mapping can use a densely overlapping seed pattern, such as seeds starting at 50% or 100% of read positions, most of the value of seed editing can be obtained by editing a much sparser pattern of seeds, even a nonoverlapping pattern. Generally, if a user application can afford to spend some additional amount of mapping time on seed editing, a greater increase in mapping accuracy can be obtained for the same time cost by editing seeds in sparse patterns for a large number of reads, than by editing seeds in dense patterns for a small number of reads.
Whenever seed editing is triggered, these two options request edit-seed-num seed editing positions, distributed evenly over the first edit-read-len bases of the read. For example, with 21-base seeds, edit-seed-num=6 and edit-read-len=100, edited seeds can begin at offsets {0, 16, 32, 48, 64, 80} from the 5' end, consecutive seeds overlapping by 5 bases. Because sequencing technologies often yield better base qualities nearer the (5') beginning of each read, this can focus seed editing where it is most likely to succeed. When a particular read is shorter than `edit-read-len`, fewer seeds are edited.
Seed editing is more expensive when the reference seed interval (build hash table option ‑-ht‑ref-seed-interval) is greater than 1. For edit modes 1 and 2, additional seed editing positions are automatically generated to avoid missing the populated reference seed positions. For edit mode 3, the time cost can increase dramatically because query seeds matching unpopulated reference positions typically miss and trigger editing.
### DNA Aligning
#### Smith-Waterman Alignment Scoring Settings
The first stage of mapping is to generate seeds from the read and look for exact matches in the reference genome. These results are then refined by running full Smith-Waterman alignments on the locations with the highest density of seed matches. This well-documented algorithm works by comparing each position of the read against all the candidate positions of the reference. These comparisons correspond to a matrix of potential alignments between read and reference. For each of these candidate alignment positions, Smith-Waterman generates scores that are used to evaluate whether the best alignment passing through that matrix cell reaches it by a nucleotide match or mismatch (diagonal movement), a deletion (horizontal movement), or an insertion (vertical movement). A match between read and reference provides a bonus, on the score, and a mismatch or indel imposes a penalty. The overall highest scoring path through the matrix is the alignment chosen.
The specific values chosen for scores in this algorithm indicate how to balance, for an alignment with multiple possible interpretations, the possibility of an indel as opposed to one or more SNPs, or the preference for an alignment without clipping. The default DRAGEN scoring values are reasonable for aligning moderate length reads to a whole human reference genome for variant calling applications. But any set of Smith-Waterman scoring parameters represents an imprecise model of genomic mutation and sequencing errors, and differently tuned alignment scoring values can be more appropriate for some applications.
The following alignment options control Smith-Waterman Alignment:
| Command-Line Option Name | Configuration File Option Name |
| --------------------------- | ------------------------------ |
| `--Aligner.global` | `global` |
| `--Aligner.match-score` | `match-score` |
| `--Aligner.match-n-score` | `match-n-score` |
| `--Aligner.mismatch-pen` | `mismatch-pen` |
| `--Aligner.gap-open-pen` | `gap-open-pen` |
| `--Aligner.gap-ext-pen` | `gap-ext-pen` |
| `--Aligner.unclip-score` | `unclip-score` |
| `--Aligner.no-unclip-score` | `no-unclip-score` |
| `--Aligner.aln-min-score` | `aln-min-score` |
| `--Aligner.min-score-coeff` | `min-score-coeff` |
* **global** The `global` option (value can be 0 or 1) controls whether alignment is forced to be end-to-end in the read. When set to 1, alignments are always end-to-end, as in the Needleman-Wunsch global alignment algorithm (although not end-to-end in the reference), and alignment scores can be positive or negative. When set to 0, alignments can be clipped at either or both ends of the read, as in the Smith-Waterman local alignment algorithm, and alignment scores are nonnegative. Generally, `global=0` is preferred for longer reads, so significant read segments after a break of some kind (large indel, structural variant, chimeric read, and so forth) can be clipped without severely decreasing the alignment score. Setting global=1 might not have the desired effect with longer reads because insertions at or near the ends of a read can function as pseudoclipping. Also, with global=0, multiple (chimeric) alignments can be reported when various portions of a read match widely separated reference positions. Using `global=1` is sometimes preferable with short reads, which are unlikely to overlap structural breaks, unable to support chimeric alignments, and are suspected of incorrect mapping if they cannot align well end-to-end. Consider using the unclip-score option, or increasing it, instead ofsetting global=1, to make a soft preference for unclipped alignments.
* **match-score** The `match-score` option specifies the score for a read nucleotide matching a reference nucleotide (A, C, G, or T), or matching a reference 2–3 nucleotide IUPAC-IUB code. Its value is an unsigned integer, from 0 to 15. match\_score=0 can only be used when global=1. A higher match score results in longer alignments, and fewer long insertions.
* **match-n-score** The `match-n-score` option specifies the score for an aligned position where the read position and/or the reference position is an N code. This option is a signed integer, from -16 to 15.
* **mismatch-pen** The `mismatch-pen` option is the penalty (negative score) for a read nucleotide mismatching any reference nucleotide or IUPAC-IUB code, except N. This option is an unsigned integer, from 0 to 63. A higher mismatch penalty results in alignments with more insertions, deletions, and clipping to avoid SNPs.
* **gap-open-pen** The `gap-open-pen` option is the penalty (negative score) for opening a gap (ie, an insertion or deletion). This value is only for a 0-base gap. It is always added to the gap length times gap-ext-pen. This option is an unsigned integer, from 0 to 127. A higher gap open penalty causes fewer insertions and deletions of any length in alignment CIGARs, with clipping or alignment through SNPs used instead.
* **gap-ext-pen** The `gap-ext-pen` option is the penalty (negative score) for extending a gap (ie, an insertion or deletion) by one base. This option is an unsigned integer, from 0 to 15. A higher gap extension penalty causes fewer long insertions and deletions in alignment CIGARs, with short indels, clipping, or alignment through SNPs used instead.
* **unclip-score** The `unclip-score` option is the score bonus for an alignment reaching the beginning or end of the read. An end-to-end alignment receives twice this bonus. This option is an unsigned integer, from 0 to 127. A higher unclipped bonus causes alignment to reach the beginning and/or end of a read more often, where this can be done without too many SNPs or indels. A nonzero unclip-score is useful when global=0 to make a soft preference for unclipped alignments. Unclipped bonuses have little effect on alignments when global=1, because end-to-end alignments are forced anyway (although 2 × unclip-score does add to every alignment score unless no-unclip-score = 1). Note that, especially with longer reads, setting unclip-score much higher than gap-open-pen can have the undesirable effect of insertions at or near one end of a read being utilized as pseudoclipping, as happens with global=1
* **no-unclip-score** The `no-unclip-score` option can be 0 or 1. The default is 1. When no-unclip-score is set to 1, any unclipped bonus (unclip-score) contributing to an alignment is removed from the alignment score before further processing, such as comparison with aln-min-score, comparison with other alignment scores, and reporting in AS or XS tags. However, the unclipped bonus still affects the best-scoring alignment found by Smith-Waterman alignment to a given reference segment, biasing toward unclipped alignments When unclip-score > 0 causes a Smith-Waterman local alignment to extend out to one or both ends of the read, the alignment score stays the same or increases if no-unclip-score=0, whereas it stays the same or decreases if no-unclip-score=1. The default, no-unclip-score=1, is recommended when global=1, because every alignment is end-to-end, and there is no need to add the same bonus to every alignment. When changing no-unclip-score, consider whether aln-min-score should be adjusted. When no-unclip-score=0, unclipped bonuses are included in alignment scores compared to the aln-min-score floor, so the subset of alignments filtered out by aln-min-score can change significantly with no-unclip-score.
* **aln-min-score** The `aln-min-score` option specifies a minimum acceptable alignment score. Any alignment results scoring lower are discarded. Increasing or decreasing aln-min-score can reduce or increase the percentage of reads mapped. This option is a signed integer (negative alignment scores are possible with global=0). aln-min-score also affects MAPQ estimates. The primary contributor to MAPQ calculation is the difference between the best and second-best alignment scores. A read's best alignment score is saved in the AS SAM tag, and the second-best score (if available) is saved in the XS tag. aln-min-score serves as the suboptimal alignment score if nothing higher was found except the best score. Therefore, increasing aln-min-score can decrease reported MAPQ for some low-scoring alignments. You can use the min-score-coeff option to adjust aln-min-score as a function of read length.
* **min-score-coeff** The `min-score-coeff` option makes adjustments to `aln-min-score` per read base. When using the `min-score-coeff` and `aln-min-score` options together, you can define the minimum alignment score for each read as an affine function of read lengths. The minimum score for an N-base read is calculated as follows: `(min-score-coeff)\*N+(aln-min-score)` The `min-score-coeff` option is an integer ranging from –64 to 63.999. If the value is 0, then the minimum alignment score is fixed at aln-min-score for all read length. You can use positive values for `min-score-coeff` to allow shorter reads to match with lower alignment scores, but require longer reads to achieve higher scores.
#### Paired-End Options
DRAGEN can process paired-end data passed via a pair of FASTQ files or in a single interleaved FASTQ file. The hardware maps the two ends separately, and then determines a set of alignments that seem most likely to form a pair in the expected orientation and having roughly the expected insert size. The alignments for the two ends are evaluated for the quality of their pairing, with larger penalties for insert sizes far from the expected size. The following options control processing of paired-end data:
* **Reorientation** The `pe-orientation` option specifies the expected paired-end orientation. Only pairs with this orientation can be flagged as proper pairs. Valid values are as follows:
* 0--FR (default)
* 1--RF
* 2--FF
* **unpaired-pen** For paired end reads, best mapping positions are determined jointly for each pair, according to the largest pair score found, considering the various combinations of alignments for each mate. A pair score is the sum of the two alignment scores minus a pairing penalty, which estimates the unlikelihood of insert lengths further from the mean insert than this aligned pair. The `unpaired-pen` option specifies how much alignment pair scores should be penalized when the two alignments are not in properly paired position or orientation. This option also serves as the maximum pairing penalty for properly paired alignments with extreme insert lengths. The unpaired-pen option is specified in Phred scale, according to its potential impact on MAPQ. Internally, it is scaled into alignment score space based on Smith-Waterman scoring parameters.
* **pe-max-penalty**
The `pe-max-penalty` option limits how much the estimated MAPQ for one read can increase because its mate aligned nearby. A paired alignment is never assigned MAPQ higher than the MAPQ that it would have received mapping single-ended, plus this value. By default, pe-max-penalty = mapq-max = 255, effectively disabling this limit. The key difference between `unpaired-pen` and `pe-max-penalty` is that `unpaired-pen` affects calculated pair scores and thus which alignments are selected and pe-max-penalty affects only reported MAPQ for paired alignments.
#### Mean Insert Size Detection
When working with paired-end data, DRAGEN must choose among the highest-quality alignments for the two ends to try to choose likely pairs. To make this choice, DRAGEN uses a skew normal insert model to evaluate the likelihood that a pair of alignments constitutes a pair. This model is based on the observation that common library preparation methods have insert-size distributions that are sometimes close to normal, but also sometimes clearly asymmetric, often skewing toward longer insert sizes. The skew normal insert model is used only for the DNA mode.
If you know the statistics of your library prep for an input file (and the file consists of a single read group), you can specify the characteristics of the insert-length distribution: mean, standard deviation, shape (or skewness) and three quartiles. These characteristics can be specified with the `Aligner.pe-stat-mean-insert`, `Aligner.pe-stat-stddev-insert`, `Aligner.pe-stat-shape-insert`, `Aligner.pe-stat-quartiles-insert`, and `Aligner.pe-stat-mean-read-len` options. However, it is typically preferable to allow DRAGEN to detect these characteristics automatically.
Dragen automatically samples the insert-length distribution. When the software starts execution, it runs a sample of up to 2,000,000 pairs through the aligner, calculates the distribution, and then uses the resulting statistics for evaluating all pairs in the input set.
The DRAGEN host software reports the statistics in its stdout log in a report, as follows:
```
Initial paired-end statistics detected for read group RGID, based on 39042 high quality pairs for FR orientation
Quartiles (25 50 75) = 398 409 420
Mean = 410.192
Standard deviation = 14.1254
NOTE: DRAGEN's insert estimates include corrections for clipping (so they are not identical to TLEN)
Skew-normal insert distribution applied:
Position (xi) = 424.084
Scale (omega) = 19.8719
Shape (alpha) = -1.88125
To rerun with identical insert stats, specify:
--Aligner.pe-stat-mean-insert=424.084
--Aligner.pe-stat-stddev-insert=19.8719
--Aligner.pe-stat-shape-insert=-1.88125
--Aligner.pe-stat-quartiles-insert="398 409 420"
--Aligner.pe-stat-mean-read-len=101
```
Note that the `Mean`, `Standard deviation` and `Quartiles` reported above are the sample mean, standard deviation and quartiles calculated from the initial sample of up to 2,000,000 pairs, assuming a normal distribution. The sample mean and standard deviation are used to fit the parameters of a skew-normal distribution. A skew-normal distribution is defined by starting with an underlying normal distribution (whose mean we call `position` or `xi` and standard deviation we call `scale` or `omega`) and folding a varying portion of the probability mass from one side of the mean (e.g., left side) to the other (e.g., right) side. The portion folded varies smoothly, from 0% at the original mean, approaching 100% from the left tail to the right tail. A `shape` parameter which we call `alpha` controls how rapidly the folded fraction increases, and at `alpha=0` there is no folding and the distribution remains normal.
In the standard output, we also include the command line options needed to reproduce the DRAGEN run with the same insert stat settings. Note that when specifying stats on the command line, the skew-normal `xi` value should be used for `Aligner.pe-stat-mean-insert`. The `omega` value should be used for `Aligner.pe-stat-stddev-insert`, and the `alpha` value should be used for `Aligner.pe-stat-shape-insert`. If `Aligner-pe-stat-shape-insert` is not specified on the command line, a default value of 0 is assumed.
The insert length distribution for each sample is written to fragment\_length\_hist.csv. Each sample starts with the following lines
```
#Sample: sample name
FragmentLength,Count
```
These lines are followed by the histogram for the first \~2M read pairs for DNA (\~100K read pairs for RNA). The histogram counts are aggregated across all read groups sharing the same sample id (`RGSM` field).
When the number of sample pairs is very small, there is not enough information to characterize the distribution with high confidence. In this case, DRAGEN applies default statistics that specify a very wide insert distribution, which tends to admit pairs of alignments as proper pairs, even if they may lie tens of thousands of bases apart. In this situation, DRAGEN outputs a message, as follows:
```
WARNING: Less than 28 high quality pairs found - standard deviation is
calculated from the small samples formula
```
The small samples formula calculates standard deviation as follows:
```
if samples < 3 then
standard deviation = 10000
else if samples < 28 then
standard deviation = 25 * (standard deviation + 1) / (samples - 2)
end if
if standard deviation < 12 then
standard deviation = 12
end if
```
The default model is "standard deviation = 10000". If the first 2M reads are unmapped or if all pairs are improper pairs, then the standard deviation is set to 10000 and the mean and quartiles are set to 0. Note that the minimum value for standard deviation is 12, which is independent of the number of samples. Also, in the DNA mode when we have fewer than 1000 high quality alignments we revert to the normal distribution based insert model, because of insufficient number of samples to accurately estimate the parameters of the skew normal distribution.
For RNA-Seq data, the insert size distribution is not normal due to pairs containing introns. The DRAGEN software estimates the distribution using a kernel density estimator to fit a long tail to the samples. This estimate leads to a more accurate mean and standard deviation for RNA-Seq data and proper pairing.
DRAGEN writes detected paired-end stats into a tab-delimited log file in the output directory called .insert-stats.tab. This file contains the statistical distribution of detected insert sizes for each read group, including quartiles, mean, standard deviation, shape, minimum, and maximum. The information matches the standard-out report above. Additionally, the log file includes the minimum and maximum insert limits that DRAGEN applied for rescue scans. Note that the reported mean and standard deviation in this tab-limited log file are the `xi` and `omega` parameters of the skew-normal distribution.
#### Rescue Scans
For paired-end reads, where a seed hit is found for one mate but not the other, rescue scans hunt for missing mate alignments within a rescue radius of the mean insert length. Normally, the DRAGEN host software sets the rescue radius to 2.5 standard deviations of the empirical insert distribution. But in cases where the insert standard deviation is large compared to the read length, the rescue radius is restricted to limit mapping slowdowns. In this case, a warning message is displayed, as follows:
```
Rescue radius = 220
Effective rescue sigmas = 0.5
WARNING: Default rescue sigmas value of 2.5 was overridden by host software!
The user may wish to set rescue sigmas value explicitly with --Aligner.rescue-sigmas
```
Although the user can ignore this warning, or specify an intermediate rescue radius to maintain mapping speed, it is recommended to use 2.5 sigmas for the rescue radius to maintain mapping sensitivity. To disable rescue scanning, set max-rescues to 0.
#### Output Options
DRAGEN can track multiple independent alignments for each read. These alignments include the optimal (primary) one, as well as those mapping different subsegments of the read, (chimeric/supplementary), and sub-optimal (secondary) mappings of the read to different areas of the reference.
For DNA alignment by default, DRAGEN can emit one primary alignment for each read, up to three chimeric alignments (Aligner.supp-aligns=3), and no secondary alignments (Aligner.sec-aligns=0). The maximum user-specified value for supp-aligns or sec-aligns is 4095.
You can use the following configuration options to control how many of each type of alignment to include in DRAGEN output.
* **mapq-max** The `mapq-max` option specifies a ceiling on the estimated MAPQ that can be reported for any alignment, from 0 to 255. If the calculated MAPQ is higher, this value is reported instead. The default is 60.
* **supp-aligns**, **sec-aligns** The `supp-aligns` and `sec-aligns` options restrict the maximum number of supplementary (ie, chimeric and SAM FLAG 0x800) alignments and secondary (ie, suboptimal and SAM FLAG 0x100) alignments, respectively, that can be reported for each read. A maximum of 4095 supplementary alignments and 4095 secondary alignments can be reported for any read, in addition to a primary alignment. High settings for these two options impact speed so it is advisable to increase only as needed.
* **sec-phred-delta** The `sec-phred-delta` option controls which secondary alignments are emitted based on the alignment score relative to the primary reported alignment. Only secondary alignments with likelihood within this Phred value of the primary are reported.
* **sec-aligns-hard** The `sec-aligns-hard` option suppresses the output of all secondary alignments if there are more secondary alignments than can be emitted. Set sec-aligns-hard to 1 to force the read to be unmapped when not all secondary alignments can be output.
* **supp-as-sec** When the `supp-as-sec` option is set to 1, then supplementary (chimeric) alignments are reported with SAM FLAG 0x100 instead of 0x800. The default is 0. The supp-as-sec option provides compatibility with tools that do not support FLAG 0x800.
* **hard-clips** The hard-clips option is used as a field of 3 bits, with values ranging from 0 to 7. The bits specify alignments, as follows:
* Bit 0--primary alignments
* Bit 1--supplementary alignments
* Bit 2--secondary alignments
Each bit determines whether local alignments of that type are reported with hard clipping (1) or soft clipping (0). The default is 6, meaning primary alignments use soft clipping and supplementary and secondary alignments use hard clipping.
### Mapping with ALT-contigs
The GRCh38 human reference contains many more alternate haplotypes (ALT contigs) than previous versions of the reference. Generally, including ALT contigs in the mapping reference improves mapping and variant calling specificity, because misalignments are eliminated for reads matching an ALT contig but scoring poorly against the primary assembly. However, mapping with GRCh38's ALT contigs without special treatment can substantially degrade variant calling sensitivity in corresponding regions, because many reads align equally well to an ALT contig and to the corresponding position in the primary assembly.
#### Masked Based ALT-awareness
The recomeneded and default approach for dealing with ALT-contigs in DRAGEN is masking regions of ALT contigs of high similarity to their corresponding primary contig. This approach is more accurate than liftover based ALT-awarness because there are many places where the "correct" or most useful liftover between a long ALT haplotype and the primary assembly is ambiguous. Incorrect liftover can produce dense clusters of mismapped reads and false variant calls. The base masking approach has the benefits of using ALT contigs without the negative consequences.
Masked hash tables are built from a standard hg18 or hg38 FASTA that contains ALT contigs. The hash table builder will automatically mask regions of the ALT contigs with Ns.
#### Liftover Based ALT-awarness
With liftover based ALT-awareness, the mapper and aligner are aware of the liftover relationship between ALT contig positions and corresponding primary assembly positions. Seed matches within ALT contigs are used to obtain corresponding primary assembly alignments, even if the latter score poorly. Liftover groups are formed, each containing a primary assembly alignment candidate, and zero or more ALT alignment candidates that lift to the same location. Each liftover group is scored according to its best-matching alignments, taking properly paired alignments into account. The winning liftover group provides its primary assembly representative as the primary output alignment, with MAPQ calculated based on the score difference to the second-best liftover group. Emitting primary alignments within the primary assembly maintains normal aligned coverage and facilitates variant calling there. If the --Aligner.en-alt-hap-aln option is set to 1 and --Aligner.supp-aligns is greater than 0, then corresponding alternate haplotype alignments can also be output, flagged as supplementary alignments.
DRAGEN requires ALT-Aware hash tables for any hg19 or GRCh38 reference where ALT contigs are detected. To disable this requirement in DRAGEN, set the --ht-alt-aware-validate option to false.
The following is a comparison of alternative options for dealing with alternate haplotypes.
* Mapping without ALT contigs in the reference:
* False-positive variant calls result when reads matching an alternate haplotype misalign somewhere else.
* Poor mapping and variant calling sensitivity where reads matching an ALT contig differ greatly from the primary assembly.
* Mapping with ALT contigs but no ALT awareness:
* False-positive variant calls from misaligned reads matching ALT contigs are eliminated.
* Low or zero aligned coverage in primary assembly regions covered by alternate haplotypes, due to some reads mapping to ALT contigs.
* Low or zero MAPQ in regions covered by alternate haplotypes, where they are similar or identical to the primary assembly.
* Variant calling sensitivity is dramatically reduced throughout regions covered by alternate haplotypes.
* Mapping with ALT contigs and ALT awareness:
* False-positive variant calls from misaligned reads matching ALT contigs are eliminated.
* Normal aligned coverage in regions covered by alternate haplotypes because primary alignments are to the primary assembly.
* Normal MAPQs are assigned because alignment candidates in alternative haplotypes are not considered in competition.
* Good mapping and variant calling sensitivity where reads matching an ALT contig differ greatly from the primary assembly.
### DRAGEN Multigenome Mapper
The Multigenome Mapper in DRAGEN significantly improves the accuracy of mapping Illumina reads, particularly in challenging regions such as segmental duplications and other difficult to map regions. This advanced method leverages population haplotypes from pangenome references to incorporate additional variant information, constructing alternative haplotype paths that improve reads mapping. By offering these alternate paths, the Multigenome Mapper enables reads containing population-specific variants to align directly to their most likely genomic locations, reducing mapping ambiguity. This improved mapping also results in improved variant calling accuracy.
When given a set of population variants (VCF) or haplotypes, the pangenome reference modification is categorized in the following types:
* Alternate contigs represent population haplotypes. Alt-contigs can have a single variant or a combination of nearby phased variants.
* Ambiguous codes (IUPAC codes) to represent SNPs. To improve alignment, it edits the reference FASTA with isolated population SNPs.
* Haplotype database. An additional haplotype database is built and used to augment the reference FASTA with population variants. A multigenome based mapper algorithm is used to score read alignment according to the variants in this database.
The DRAGEN pangenome hashtables are available to download from the [DRAGEN Software Support Site page](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html).
# Read Trimming
DRAGEN can remove artifacts from reads using hardware accelerated read trimming. Hardware accelerated read trimming is available on U200 and cloud systems, as part of the DRAGEN mapper and adds no additional run time. DRAGEN provides multiple independent trimming filters that target different types of artifacts or use cases. You can enable and configure the artifacts or use cases independently to tailor the read-trimming to your analysis. Read trimming uses two different modes, hard-trimming and soft-trimming.
To enable hard-trimming mode, use `--read-trimmers`. In hard-trimming mode, potential artifacts are removed from input reads. Reads that are trimmed to fewer than 20 bases are filtered and replaced with a placeholder read that uses 10 N bases. DRAGEN assigns the filtered reads a 0x200 flag set.
DRAGEN contains a novel lossless soft-trimming mode. In soft-trimming mode, reads are mapped as though they had been trimmed, but no bases are removed. To enable the trimmer in soft mode, use `--soft-read-trimmers`.
Soft-trimming suppresses systematic mismapping of reads that contain trimmable artifacts, without actually losing the trimmed bases in aligned output. Soft-trimming prevents reads with trimmable artifacts, such as Poly-G artifacts, from being mapped to reference G homopolymers, or prevents adapter sequences from being mapped to the matching reference loci. Soft-trimming might map reads to different positions in the reference than they would have been if not using soft-trimming. When using soft-trimmed, DRAGEN does not filter reads and does not map reads with bases that would have been trimmed entirely.
Soft-trimming for Poly-G artifacts is enabled by default on supported systems.
## Read Trimming Tools
### Fixed-Length Trimming
Fixed-length trimming removes a fixed number of bases from the 5' end of each read. If you are analyzing sequencing data from an amplicon of fixed size and expect the read-length to consistently exceed the length of quality sequence data, you can use the expected number in fixed-length trimming.
### Poly-G Trimming
Poly-G artifacts appear on two-channel sequencing systems when the dark base G is called after synthesis has terminated. As a result, DRAGEN calls several erroneous high-confidence G bases on the ends of affected reads. For contaminated samples, many affected reads can be mapped to reference regions with high G content. The affected reads can cause problems for processing downstream.
### Quality Trimming
Base quality can degrade over the length of a read toward the 5' end and separate from any artifacts from early termination of synthesis. The lower quality bases can affect mapping and alignment results, and might lead to incorrect variant or methylation calls downstream. The quality trimming tool calculates a rolling average of the base quality inward from the 5' end and removes the minimum number of bases, so the average number of bases is above the threshold specified using `--trim-min-quality`.
### Adapter Trimming
Problems during library preparation, or libraries with smaller inserts can result in the synthesis of high quality reads containing sequence from the adapters used. If not removed before analysis, noninsert bases can reduce mapping efficiency and downstream accuracy. The adapter trimming tool uses the adapter sequences from the input FASTA file, and then removes all hits greater than a specified size. Adapter trimming allows for a 10% mismatch. For 3' adapters, trimming is from the first matching adapter base to the end of the read. For 5' adapters, trimming is from the first (3') matching adapter base to the beginning (5') of the read.
### Ambiguous Base Trimming
If quality trimming is not feasible due to reduced yield or other limitations, an alternative option is to remove only explicitly ambiguous bases from the ends of read. If enabled the ambiguous base trimmer applies a simple exact-match search to both ends of all processed reads, regardless of mate-pair status.
### Minimum Length Trimming
You can maximize trimmer sensitivity, by using the minimum length trimming tool to remove a fixed number of bases from each read after the trimmer tools above have run. For example, if you would like to remove 5 bp from each read, a 7 bp adapter hit could be missed if five of the bases are removed first. To mitigate this issue, DRAGEN provides an optional minimum trim-length filter.
### Maximum Length Trimming
If using libraries of fixed-size inserts, such as small PCR amplicons, it is more convenient to specify a length that all reads should be trimmed to rather than the number of bases to remove. You can use the maximum length trimming tool.
### PolyA Tail Trimming
If using RNA libraries, reads overlapping the poly-A tail of the transcripts may contain long poly-A/poly-T sequences at the end of the reads which may result in incorrect alignment. The poly-A trimmer mitigates this by trimming the poly-A tail from the end of the read. See additional description in [RNA alignment](/dragen-v4.5/product-guides/dragen-v4.5/dragen-rna-pipeline/rna-alignment#polya-trimming) section.
## Read Trimming Metrics
The trimmer generates a metrics file titled `\