DRAGEN analysis is available on multiple platforms.

(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 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 . Details here . Accessed March 22, 2023

3. PrecisionFDA Truth Challenge V2: Calling Variants from Short and Long Reads in Difficult-to-Map Regions. . Accessed November 3, 2020.

Applications

DRAGEN analysis offers a large selection of application pipelines.

DRAGEN v4.4 introduces support for DRAGEN server apps. These apps, comprised of Docker images, Nextflow workflows, a CLI shell script, and packaged resource bundles, can be downloaded and installed on the on-premises server. The packaged resource bundles include all the resource files required to run the application, such as the hash table(s), various noise baseline files, bed files.

Server apps make it easy to run complex workflows such as Tumor Normal somatic analysis by simplifying the management of external resources and applying the correct command line parameters for the selected analysis type. The DRAGEN server can support multiple installed server apps and DRAGEN on-prem for command line use at the same time.

We recommend using the BSSH Run Planner tool to minimize errors in creating the sample sheet. For instruments such as NovaSeq X, sample sheets created in the BSSH Run Planer tool is automatically downloaded into the run folder on the instrument.

Local output management

• 📂 Work — (DRAGEN server only) - Contains information and files related to Nextflow execution

• On DRAGEN server, Nextflow logs are contained in the Work folder

Local output management

Common output files for cloud and local pipelines are described in the Analysis Output.

On DRAGEN server, Nextflow logs are contained in the Work folder in a hierarchical folder structure organized by the tasks in the pipeline_trace.txt. These files are prefixed with "." and hidden from normal view.

• 📂 Work — (DRAGEN server only) - Contains information and files related to Nextflow execution

  • 📄 .command.log - Contains Nextflow pipeline step execution log.

  • 📄 .command.out - Contains Nextflow pipeline step standard output log.

  • 📄 .command.err - Contains Nextflow pipeline step standard error log.

  • 📄 .exit.code - Contains Nextflow pipeline step execution exit code.

The pipeline only supports starting from FASTQ, BAM or CRAM in the current release. The sample sheet below only contains the minimally required sections for starting the analysis. It is not a valid sample sheet for other purposes.

Users can visit the Sample Sheet guidelines section to learn additional details on required fields and values as they fill-in their sample information, or download a template from Sample Sheet Template.

[Header],,,,,,,,,,
FileFormatVersion,2,,,,,,,,,
RunName,DRAGEN TN Start From FASTQ Only,,,,,,,,,
InstrumentType,NovaSeq,,,,,,,,,
InstrumentPlatform,NovaSeq,,,,,,,,,

[TN_Data],,,,,,,,,,
Sample_ID,Specimen_Type,Sample_Type,Case_ID,Sample_Description,Sample_Classification
tumorSample,FFPE,DNA,SampleA,Description1,Tumor
normalSample,FFPE,DNA,SampleA,Description2,Normal

Overview

DRAGEN Heme WGS Tumor Only Pipeline, henceforth referred as the Heme Pipeline, is a comprehensive and unbiased whole genome sequencing solution to replace conventional cytogenetic and panel sequencing approaches for detecting all types of mutation using a limited amount of DNA. It can be applied to detect clinically actionable mutations for cancer spanning a wide range of genomic events, e.g., structural variants (SV), Copy Number Alterations (CNA), small variants (SNV/insertion/deletion/delins) and internal tandem duplications (ITD) and DUX4 variants using Heme samples.

The Heme pipeline includes a DNA-only workflow designed to analyze whole genome sequencing data generated on supported instruments. It may be run as a local off-instrument solution installable on a DRAGEN server or accessible through the Illumina Connected Analytics (ICA) cloud environment. The Heme pipeline is for Research Use Only (RUO).

Help

Support Request

For debugging or support request, please include the files from the top level of the analysis output folder, the work directory and the errors directory content, in addition to the MetricsOutput.tsv from the Results folder.

Run Planning

Analysis in the ICA Cloud environment

Prerequisites

The Illumina Connected Insights (ICI) Local platform can be used to interpret and visualize analysis results from a clinical research workflow pipeline on a local DRAGEN server. See .

CRAM input

When CRAM is used as input, the reference genome used to generate the CRAM files is required. This may be provided using the .

Output Folder

• This section only describes output files specific to ICA. are described in the common output files.

• Nextflow output folders differ across platforms.

Overview

The pipeline supports advanced use cases:

• Selected custom parameters may be configured using a configuration file, and associated custom pipeline resource files.

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.

Help

stopping analysis

Pressing Ctrl+C during a DRAGEN step stops the currently running analysis and might cause an FPGA error. To recover from an FPGA error, shut down and restart the server.

Advanced Use Cases

• User may be able to rerun a completed analysis using the "rerun" option in ICA.

• User may be able to use the icav2 client to complete any analysis performed throught the UI.

Copying data to local /staging drive

• Copy the run or FASTQ folder to the DRAGEN server into the staging folder with the following recommended organization: /staging/runs/{RunID}. You can copy the run folder onto the DRAGEN server using Linux commands such as rsync. The sample sheet within the run folder is used unless otherwise specified through the command line.

• Run folder must be intact.

• If the analysis output folder path is different from the default, provide the analysis output folder path.

Analysis output directory

Before running the analysis, confirm that the output directory for the software to write to is empty and does not include results of previous analyses.

Storage Requirements

The DRAGEN server provides an NVMe SSD in the /staging directory to use as the software output directory. Network-attached storage is required for long-term storage.

When running the Heme pipeline, use the default settings or set the -analysisFolder command line option to a directory in /staging to make sure the DRAGEN server processes read and write data on the NVMe SSD.

Before beginning analysis, develop a strategy to copy data from the DRAGEN server to a network‑attached storage. Delete output data on the DRAGEN server as soon as possible.

The following are the run folder output size estimates and the minimum free space requirements for fastq.gz or fastq.ora output format.

When launching the analysis, the software checks that the minimum disk space required is available. If the minimum disk space is not available, the software shows an error message and prevents analysis from starting. If disk space is exhausted during a run, the run shows an error and stops analyzing.

Moving or modifying files during an analysis may cause the analysis to fail or provide incorrect results.

Data streaming from Network Filesystem

Analysis of data stored on network file system may be slow when there are multiple DRAGEN servers reading and writing to the network file system simultaneously. However, it is advisable to use a network filesystem to stream large datasets from NFS when data transfer to local /staging is taking a significant amount of time, especially for NovaSeq X 25B flow cells. Discuss with your system administrator for of the DRAGEN server.

This feature allows users to customize a specific set of DRAGEN command-line options to override the default values pre-defined in the pipeline.

ICA Setup

On the ICA (Illumina Connected Analytics) user interface (UI) to the software, you can specify the Custom Parameters Config File and Custom Resources Directory directly. Supported customizable options are described below.

Examples

heme_custom_param.config Content

custom_resources_Heme_dir Folder Structure on ICA

ℹ️ Note: Custom resource files and the custom configuration file must be uploaded to the same ICA project where the run is created. You can use the icav2 client or other supported methods. See for details.

ICA Input Files UI Example

This feature allows users to customize a specific set of DRAGEN command-line options to override the default values pre-defined in the pipeline.

ICA Setup

On the ICA (Illumina Connected Analytics) user interface (UI) to the software, you can specify the Custom Parameters Config File and Custom Resources Directory directly. Supported customizable options are described below.

Examples

solid_custom_param.config Content

custom_resources_Heme_dir Folder Structure on ICA

ℹ️ Note: Custom resource files and the custom configuration file must be uploaded to the same ICA project where the run is created. You can use the icav2 client or other supported methods. See for details.

ICA Input Files UI Example

Overview

Run on DRAGEN Server

The DRAGEN Heme WGS Tumor Only Pipeline is launched with the bash script called run_Heme_WGS_TO_{version}.sh, which is installed in the /usr/local/bin directory. The bash script is executed on the command line and runs the software using DRAGEN Application Manager. For a full list of command-line options, refer to .

Getting Started

To launch an analysis, you must provide the --inputType and --inputFolder arguments. The --inputType argument can be bcl, fastq, bam, or cram. When starting from a sequencing system run folder containing BCL files, --inputType must be bcl and --inputFolder is the absolute path to the full run folder. When starting from FASTQ, BAM, or CRAM files --inputFolder may also be a comma separated list of folders. If more than one input folder is specified, the --sampleSheet argument must also be provided with the absolute path to a valid Sample Sheet (refer to

Analysis output is written to /staging/DRAGEN_Heme_WGS_Tumor_Only_Pipeline_{version}_Analysis_{datetimestamp} by default. To write to a different output directory, run the bash script with --analysisFolder <FULL_PATH_TO_ANALYSIS_FOLDER>.

The --demultiplexOnly flag runs the pipeline through FASTQ Generation only, and these outputs can be used for splitting a run into smaller batch analyses with --inputType fastq and the --sampleIDs argument.

The Illumina Connected Insights (ICI) platform can be used to interpret and visualize analysis results from the Heme pipeline. Analysis results can be provided to ICI via a manual upload for local analyses and via auto-ingestion for Illuminia Connected Analytics (ICA) analyses.

Automatic Ingestion of Heme Analysis on ICA to ICI

• Access to Illumina Connected Analytics

• Access to Illumina Connected Insights

Refer to the ICI support site page for information on

Overview

Run on DRAGEN Server

The DRAGEN Heme WGS Tumor Only Pipeline is launched with the bash script called run_Solid_WGS_TN_{version}.sh, which is installed in the /usr/local/bin directory. The bash script is executed on the command line and runs the software using DRAGEN Application Manager. For a full list of command-line options, refer to .

Getting Started

To launch an analysis, you must provide the --inputType and --inputFolder arguments. The --inputType argument can be fastq, bam, or cram. The --inputFolder may be the absolute path to the input folder or it may be a comma separated list of path. If more than one input folder is specified, the --sampleSheet argument must also be provided with the absolute path to a valid Sample Sheet (refer to ). If the --sampleSheet argument is not provided, the software checks for a file named SampleSheet.csv in the input folder.

Analysis output is written to /staging/DRAGEN_Solid_WGS_Tumor_Normal_Pipeline_{version}_Analysis_{datetimestamp} by default. To write to a different output directory, run the bash script with --analysisFolder <FULL_PATH_TO_ANALYSIS_FOLDER>.

Analysis on DRAGEN Server

Prerequisites

Quick Start Guide

Table 1. Release Information

Description

Sample Sheet templates for the Heme pipeline for standalone DRAGEN server and ICA manual launch analysis can be found in the table below. For auto-launch compatible sample sheets, use BaseSpace Run Planner.

The Heme pipeline is compatible with several instruments and assay workflows (standard, XP), each of which have implications for the sample sheet.

Quick Start Guide

Table 1. Release Information

Overview

DRAGEN Solid WGS Tumor Normal Pipeline, henceforth referred as the Solid WGS TN Pipeline, is a comprehensive and unbiased whole genome sequencing solution for detection of all types of mutation in matched tumor and normal samples. It can be applied to detect clinically actionable mutations for cancer spanning a wide range of genomic events, e.g., structural variants (SV), copy number alterations (CNA), small variants (SNV/insertion/deletion/delins).

The Solid WGS TN pipeline includes a DNA-only workflow designed to analyze whole genome sequencing data generated on supported instruments. It may be run as a local off-instrument solution installable on a DRAGEN server or accessible through the Illumina Connected Analytics (ICA) cloud environment. The Solid WGS TN pipeline is for Research Use Only (RUO).

The TN pipeline may contain additional user defined fields such as Sex, Tumor Type or Case ID for use with variant interpretation in ICI.

Standard Sample Sheet Requirements

The following sample sheet requirements describe required and optional fields for TN pipeline. It must contain fhe follwing sections.

The analysis fails if the sample sheet requirements are not met.

Demultiplex only option

In order to break up the workflow, one may wish to run the software with the demux only option. The pipeline will perform FASTQ generation with the settings provided by default or as specified in the sample sheet. Then the subsequent analysis may start from FASTQ.

CRAM input

The pipeline may be downloaded and installed on a local DRAGEN server. A download utility may be obtained from the Illumina download site, and the download utility will manage all the dependencies. Once the required installers are downloaded, the software may be installed by running the installers.

Using NFS for data streaming

With the NovaSeq X 25B flow cells, the amount of data is on the order of terabytes, which may take a few hours or more to copy to the /staging folder on the local DRAGEN server. Using NFS storage directly for input and output is recommended in this case.

BSSH Run Planner Setup

On the BSSH Run Planner, custom parameters and custom resource files can also be specified during Run Planning.

Custom resource files must be uploaded to BaseSpace under the same project to be selectable during run planning. Supported customizable options are described in the Custom Configuration Support section of each application.

See for additional details.

Overview

Command line options

For command-line options, refer to Table 1 (below) for details.

Table 1: Shell Script Command-Line Options

CAUTION: Do not run analyses as the root user as it can lead to permissions issues when managing data generated by the software.

Overview

Command line options

For command-line options, refer to Table 1: Shell Script Command-Line Options for details.

Table 1: Shell Script Command-Line Options

CAUTION: Do not run analyses as the root user as it can lead to permissions issues when managing data generated by the software.

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.

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.

Notes and additional options

Hashtable

Requirements

Analysis on ICA requires an account with a valid subscription and a project with the following configuration.

Manual Launch

Overview

The following sub-pages contain recommended command line options for specific DRAGEN pipelines. For an overview of DRAGEN command line parsing, also see

Germline Pipelines

Requirements

Analysis on ICA requires an account with a valid subscription and a project with the following configuration.

Manual Launch

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.

Notes and additional options

Hashtable

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 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.

Installation procedure:

• Download the desired installer from the support website and unzip the package

• The archive integrity can be checked using: ./<dragen .run file> --check

• Install the appropriate release based on your Linux OS with the command: sudo sh <dragen .run file>

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 <options>

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

Example:

Location of dragen and resource files

Throughout this guide we will refer to <INSTALL_PATH> which will be either of the locations above

Licensing

DRAGEN requires license(s) for most functionality, please refer to the 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 <INSTALL_PATH>/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

Each server ships with the test input FASTQ data for this script, which is located in <INSTALL_PATH>/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.

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 .

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 <reference_hash-table_directory>

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:

After the reference genome has been loaded, the following message is printed to standard output:

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:

For detailed information on the command line options, see .

For recommended command lines in typical use cases, see .

Autolaunch requires additional BaseSpace Sequence Hub and sample sheet settings.

BaseSpace Sequence Hub Requirements for ICA Autolaunch

Autolaunch uses the BaseSpace Sequence Hub (BSSH) run planning tool to create and export a v2 format sample sheet to enable streaming of sequencing run data to the project and requires the following additional settings. See Figure 1 below.

• Access to BaseSpace Sequence Hub.

• ICA Run Storage is enabled under BaseSpace Sequence Hub settings.

Refer to the BaseSpace Sequence Hub support site page for information on .

Illumina Cloud Run Planning and Auto-Launch Workflow

Autolaunch requires a v2 format sample sheet with specific parameters that instruct the BSSH project to automatically initiate a Heme pipeline analysis in ICA. Use the run planning option in BaseSpace Sequence Hub to generate the sample sheet. The exported sample sheet is automatically populated with the required fields. Using an invalid sample sheet can result in failed runs and analyses.

Refer to Table 1 below for descriptions of the added fields. Enter the following required run parameters in BaseSpace Sequence Hub Run Planning:

For more information on run planning, refer to the the

Figure 1. BSSH Run Planning Enabled End to End Workflow

The BaseSpace Sequence Hub setting for run monitoring and storage must be selected on the instrument to use Heme pipeline Analysis Software analysis Autolaunch. For information on preparing your instrument for DRAGEN Heme App for Whole-Genome Sequencing Analysis Software Autolaunch, refer to the documentation for your instrument.

1. Use Run Planning in BaseSpace Sequence Hub to create and export a sample sheet.

2. Import the sample sheet to the instrument and start the sequencing run. Data is uploaded to BaseSpace Sequence Hub and then pushed to ICA. You can monitor the run in BaseSpace Sequence Hub.

3. When sequencing and the upload completes, analysis autolaunches in ICA. You can monitor the status of the analysis in BaseSpace Sequence Hub or ICA

4. If necessary, requeue the analysis via the run's Summary page in BaseSpace Sequence Hub. Refer to the BaseSpace Sequence Hub support site page for more information on requeuing an analysis.

Table 1. Additional Sample Sheet Fields for Autolaunch

Autolaunch-compatible sample sheets contain the following fields specific to autolaunch configuration.

The Heme pipeline is a DNA only analysis software based on the DRAGEN Secondary Analysis Software. Even though it includes some of the default settings from the DNA Somatic Tumor-Only Heme WGS DRAGEN recipe, it uses a distinct recipe with different options. A user has the ability to override specific parameters via a custom configuration file.

An example command is provided that highlights the input and output used in DragenCaller step of the Heme Pipeline, which may be found in the log file. Any parameter options not displayed on the command line would be using the default value for the DRAGEN variant caller module. The detailed parameters and default arguments for the individual modules within the DragenCaller step may be found in the replay.json output. See DRAGEN Command Line Options for detailed explanations of the parameters.

Reference Genomes

The Heme pipeline supports two reference genomes for the DRAGEN Map/Aligner - hg38 and hs37d5_chr.

The hs37d5_chr genome is the hg19 reference genome with the Chromosome Y PAR masked. It includes the NC_012920 mitocondria genome. The contigs have the chr prefix added, but without the native alternate loci names.

DRAGEN Map/Aligner

involves aligning sequencing reads derived from DNA libraries to a reference genome prior to variant calling.

The pipeline currently does not support UMI libraries by default. Please use the to generate the collapsed BAM as input, if so desired.

DRAGEN continues to use these final alignments as input for various variant calls such as gene amplification (copy number) calling, small variant calling (SNV, indel, MNV, delin), and DNA library quality control.

Small Variant Calling and Filtering

DRAGEN supports calling SNVs, indels, MNVs, and delins in tumor-only samples by using mapped and aligned DNA reads from a tumor sample as input. Variants are detected via both column wise pileup analysis and local de novo assembly of haplotypes. The de novo haplotypes allow the detection of much larger insertions and deletions than possible through column wise pileup analysis only. DRAGEN insertions and deletions are validated with lengths of at least 0–25 bp and more than 25 bp can be supported. In addition, DRAGEN also uses the de novo assembly to detect SNVs, insertions, and deletions that are co-phased and part of the same haplotypes. Any such co-phased variants that are within a window of 15 bp can then be reassembled into complex variants (MNVs and delins). The tumor-only pipeline produces a VCF file containing both germline and somatic variants that can be further analyzed to identify tumor mutations. The pipeline makes no ploidy assumptions, enabling detection of low-frequency alleles.

DRAGEN small variant calling includes the following steps:

1. Detects regions with sufficient read coverage (callable regions).

2. Detects regions where the reads deviate from the reference and there is a possibility of a germline or somatic call (active regions).

3. Assembles de novograph haplotypes are assembled from reads (haplotype assembly).

4. Extracts possible somatic or germline calls (events) from column wise pileup analysis.

Additional information is available at .

Copy Number Variant Calling

The DRAGEN copy number variant caller performs amplification, reference, and deletion calling for CNV targets within the assay. It counts the coverage of each target interval on the panel, uses a preprocessed panel of normal samples to normalize target counts, corrects for GC coverage bias, and calculates scores of a CNV event from observed coverage and makes copy number calls.

Additional information is available at .

Structural Variant Calling

The DRAGEN Structural Variant (SV) Caller is described . The DUX4 rearrangement caller is described .

Variant Deduplication

The Variant Deduplication is described

Contamination Detection

The contamination analysis step detects foreign human DNA contamination using the SNP error file and pileup file that are generated during the small variant calling and the TMB trace file. The software determines whether a sample has foreign DNA using the contamination score. In contaminated samples, the variant allele frequencies in SNPs shift from the expected values of 0%, 50%, or 100%. The algorithm collects all positions that overlap with common SNPs that have variant allele frequencies of < 25% or > 75%. Then, the algorithm computes the likelihood that the positions are an error or a real mutation. The contamination score is the sum of all the log likelihood scores across the predefined SNP positions with minor allele frequency < 25% in the sample and are not likely due to CNV events.

The larger the contamination score, the more likely there is foreign DNA contamination. A sample is considered to be contaminated if the contamination score is above predefined quality threshold. The contamination score was found to be high in samples with highly rearranged genomes or HRD samples. 1% of HRD samples found to be above the threshold with no evidence for actual contamination.

Annotation

The Illumina Annotation Engine performs annotation of small variants, CNVs, and exon-level CNVs. The inputs are gVCF files and the outputs are annotated JSON files.

The Heme pipeline currently does not support annotation of gVCF files. Please use the to perform tertiary analysis.

Tumor Mutational Burden

Not Supported in the current release. Please use the .

Microsatellite Instability Status

Not supported in the current release. Please use the .

A reusable Nextflow component designed for executing various post-processing tasks at the end of pipeline execustion. It can be used to enhance, transform, or modify outputs in Logs_Intermediates and Results folders, making it versatile for addressing specific requirements.

This component is highly configurable, supporting fine-tuned control of computational resources (CPU, memory), containerization, and output management. Users can integrate custom containers and scripts to implement their own logic for post-processing, all configured through parameters. Externalized process scripts allow for seamless execution of containerized processes.

Key Features

• Customizability: Easily adaptable to different post-processing requirements.

• Reusability: Can be used in multiple pipelines, reducing development effort.

• Data transformation: Can be used to transform or modify output data in various ways.

What you need ?

1. A config file which has Post-Processing parameters and values

2. A bash script , that implements desired functioanlity

3. Any other custom resources/files that will be required by the bash script

4. Docker container having dependencies to run the bash script

Process

1. Upload and configure

2. Modify config file; Set postProcessing_container to the uploaded conatiner

3. Upload all the required files(config, script, reources) to a project directory, e.g., custom-resources, in ICA using the icav2 client.

4. Configure ICA Web-UI on 'Start Analysis' Page:

Config File - <file-name>.config

Configurable Parameters in Config file

Allowed values for postProcessing_cpusMemoryConfig in the config file

Post-Processing : Sample Script (bam2cram.sh)

A Post-Processing bash script is a , which has access to paths/variables defined in the parent Nextflow Process. In our case following directories and subdirectories can accessed from the bash script like {params.analysisDir}/Results , {params.analysisDir}/Logs_Intermediates. Also, the output files generated should be stored into {params.postProcessing.stepName} directory. Note- For BAM to CRAM Conversion , we must upload genome.fa and .fai files to custom resources direcory.

Autolaunch requires additional BaseSpace Sequence Hub and sample sheet settings.

BaseSpace Sequence Hub Requirements for ICA Autolaunch

Autolaunch uses the BaseSpace Sequence Hub (BSSH) run planning tool to create and export a v2 format sample sheet to enable streaming of sequencing run data to the project and requires the following additional settings. See Figure 1 below.

• Access to BaseSpace Sequence Hub.

• ICA Run Storage is enabled under BaseSpace Sequence Hub settings.

Refer to the BaseSpace Sequence Hub support site page for information on .

Illumina Cloud Run Planning and Auto-Launch Workflow

Autolaunch requires a v2 format sample sheet with specific parameters that instruct the BSSH project to automatically initiate a pipeline analysis in ICA. Use the run planning option in BaseSpace Sequence Hub to generate the sample sheet. The exported sample sheet is automatically populated with the required fields. Using an invalid sample sheet can result in failed runs and analyses.

Refer to Table 1 below for descriptions of the added fields. Enter the following required run parameters in BaseSpace Sequence Hub Run Planning:

For more information on run planning, refer to the the

Figure 1. BSSH Run Planning Enabled End to End Workflow

The BaseSpace Sequence Hub setting for run monitoring and storage must be selected on the instrument to use pipeline Analysis Software analysis Autolaunch. For information on preparing your instrument for DRAGEN App for Whole-Genome Sequencing Analysis Software Autolaunch, refer to the documentation for your instrument.

1. Use Run Planning in BaseSpace Sequence Hub to create and export a sample sheet.

2. Import the sample sheet to the instrument and start the sequencing run. Data is uploaded to BaseSpace Sequence Hub and then pushed to ICA. You can monitor the run in BaseSpace Sequence Hub.

3. When sequencing and the upload completes, analysis autolaunches in ICA. You can monitor the status of the analysis in BaseSpace Sequence Hub or ICA

4. If necessary, requeue the analysis via the run's Summary page in BaseSpace Sequence Hub. Refer to the BaseSpace Sequence Hub support site page for more information on requeuing an analysis.

Table 1. Additional Sample Sheet Fields for Autolaunch

Autolaunch-compatible sample sheets contain the following fields specific to autolaunch configuration.

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.

Notes and additional options

Hashtable

For DRAGEN RNA/scRNA runs, it is recommended to use the linear hashtable.

See:

Input options

DRAGEN input sources include: fastq list, fastq, bam, or cram. For BCL input, first create FASTQs using .

FQ list Input

FQ Input

BAM Input

CRAM Input

Mapping and Aligning

Single-cell RNA PIPseq options

PIPseq mode batch option to automatically set the barcode/BI source, the barcode and binning index positions and the barcode sequence list options.

By default the barcode/BI is read 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 <startPos>_<endPos> 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 UMI would be set to: --scrna-barcode-position 0_8+21_29+43_51, and --scrna-umi-position 52_59.

The following table list some optional settings:

For more details on PIPseq pipeline options, refer to the

Analysis Output

When the analysis run completes, the software generates an analysis output in a folder named /staging/DRAGEN_Heme_WGS_Tumor_Only_Pipeline_{version}_Analysis_{datetimestamp}, unless a specific location is specified on the command line. In ICA, analysis output is listed in the Output section of the analysis, where the folder name is a combination of user reference, pipeline name, and a UUID. Within the analysis folder, each analysis step generates a subfolder within the Logs_Intermediates folder.

UI Options

Manual Launch of Heme pipeline Analysis Software Analysis

To manually launch an analysis, configure a Heme pipeline Analysis Software pipeline analysis run in ICA with the following parameters.

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.

DRAGEN Amplicon Pillar Panel 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 RNA panels are listed in the table below:

Overview

A sample sheet is required for each analysis with the pipeline. A sample sheet is a comma-separated value (*.csv) file format used by Illumina instruments, platforms, and analysis pipelines to store settings and data for sequencing and analysis. The pipeline is compatible with the sample sheet v2. For general information on the sample sheet v2, refer to Illumina Connected Software Sample Sheet.

A full sample sheet includes multiple sections, including a [BCLConvert_Settings] section with a list of samples and their index sequences, along with additional information required to run the pipeline in the [{app}_Data] section. For example, the Library Prep Kit is a required field in the sample sheet for the DRAGEN Heme WGS Tumor Only Pipeline. Both Illumina library prep kits or custom library prep kits are supported.

On the other hand, the DRAGEN Solid WTS Tumor Normal Pipeline may only required a minimal sample sheet with only [Header] section and a [TN_Data] section when starting the analysis from FASTQ. This partial sample sheet is not valid when starting analysis from a run folder.

When running analysis on a standalone DRAGEN server or ICA, a valid sample sheet can be created by:

• BaseSpace Run Planner (preferred), see for details.

• Downloading and modifying a sample sheet template following the requirements, see for details.

When running analysis on a standalone DRAGEN server or on ICA, a minimal sample sheet for starting from FASTQ, BAM or CRAM can be created by:

• Modify a sample sheet template following the requirements, see product specific templates for more information.

Note: A minimal sample sheet may be invalid for other purposes. It is always advisable to use a valid sample sheet generated from the BaseSpace Run Planner.

The Run Planning section of this guide is available for specific instructions to plan a run and set up a valid sample sheet for the pipeline when supported.

New Sample Sheet options available in DRAGEN 4.4+ release

Forward orientation for index2

With v2 sample sheet, and DRAGEN 4.4+, it is now required for users to specify index2 orientation in forward orientation only. For additional information, see .

Summary of Valid Settings for Index Orientation

As indicated in the following Table, the index2 orientation is always Forward orientation for simplicity. The two new flags introduced are especially useful when custom LPKs are used and when a consistent index2 orientation is desired for all run folders. The IndexOrientation field is present from BaseSpace run planner generated sample sheet, and indicates that the sample sheet index2/i5 sequences are in Forward orientation.

Look up table for index2 orientations in DRAGEN 4.4+

• Bcl-convert SoftwareVersion must be >=4.4.

• * indicates the situation where the IsReverseComplement flag in the RunInfo.xml is overriden by the RunInfoIndex2ReverseComplement value. NA means that IsReverseComplement flag for the index2 is not present in the RunInfo.xml file.

• ** indicates that legacy run folders may use the two paired flags to ensure that index2 Forward orientation is consistently applied.

Summary of Legacy Settings for index2 orientations

For backward compatibility, when the bcl-convert version specified is less than 4.4, the index2 orientation may vary depending on the instrument. In BaseSpaces run planner generated sample sheet, the IndexOrientation may still indicate Forward, but it is ignored in this situation.

Look up table for index2 orientations in earlier DRAGEN versions

• Bcl-convert SoftwareVersion must be <4.4.

• *indicates the situation where the IsReverseComplement flag in the RunInfo.xml is different depending on the control software version.

Installation Procedure on DRAGEN Server

Downloader

A separate lightweight downloader for Windows, macOS, and Linux operating systems is available at the DRAGEN Installer Download Site.

Choose the downloader appropriate for your platform, when executed it will prompt you to provide a path to download the assets to. The required software packages will be downloaded into the dragen_pipelines directory under the path provided at the prompt. If the path provided was used for a previous execution of the downloader, any incomplete downloads will be resumed, existing files will be checksummed, and any files with invalid checksums will be re-downloaded.

The downloaded directory content may be moved to the installation target DRAGEN server using a USB key with at least 128 GB of free space or by copying to Network Storage which is reachable from the target DRAGEN Server.

Additional download information is available at the download site.

Downloader System Requirements

Expected downloaded content

• 📂 dragen_pipelines

  • dragen-app-manager-1.0.14-1.x86_64-el8-offline.run

  • README

  • 📂 Solid_WGS_TN_4.4.4.53

Installer

Installation Requirements

DRAGEN and DRAGEN Application Manager

The pipeline requires DRAGEN v4.4.4 or higher. If upon installation of the app this version of DRAGEN (or higher) is not installed, the software shall install this version of DRAGEN.

The pipeline also requires DRAGEN Application Manager to be installed, and an installer is included. DRAGEN Application Manager configuration is controlled by the config.toml file located in /etc/dragen-app-manager directory. See for additional information.

Minimum System Operating Requirements

Hardware

• v3 DRAGEN server or v4 DRAGEN server

• mkfifo is enabled on the network-attached storage (NAS).

Software

The software installed by default on the DRAGEN server includes the following items:

• DRAGEN server software. Refer to sample sheet settings for the DRAGEN version number.

• Oracle Linux 8

Storage

• DRAGEN server v3 provides a 6.4 TB NVMe SSD. This SSD is located at the /staging directory and is suitable for storing only one or two runs of the analysis pipeline.

• DRAGEN server v4 provides 12.8 TB via a 2 x 6.4 TB NVMe U.2 SSD configuration.

• Consider the following when making data storage decisions.

  • A NovaSeq 6000 sequencing run that uses an S4 flow cell can produce up to 3 TB of output. ▫ The pipeline can produce an additional 4-6 TB of analysis output. For optimal performance when writing to a non-default directory, specify an analysis folder location on /staging, this ensures that the DRAGEN-related processes read and write data to the DRAGEN Server's high-speed NVMe SSD.

Installation Instructions

• Installing the pipeline requires root privileges.

• Contact Illumina Customer Care to request a link to the Downloader or visit and confirm that the Genome DRAGEN license is enabled for your server.

  • Follow the instructions for DRAGEN license installation provided by Illumina Customer Care or refer to the DRAGEN server documentation.

• Copy the directory structure from the downloader directory to the target DRAGEN server (or a path accessible with sudo privileges)

Run Self-Test Script

The self-test script, present after app installation, checks the following functions:

• All required services are running.

• All resources are in place.

• The analysis workflow image can be launched.

• The pipeline can run successfully on a test dataset.

To run the self-test script, execute:

If the self-test prints a failure message, contact Illumina Technical Support, and provide the output file found in /staging/check_Solid_WGS_TN_{version}_{datetimestamp}.tgz.

When running an analysis on the DRAGEN server via SSH, Illumina recommends that you use a terminal multiplexer utility, which allows you to resume analysis in the event of a disconnection from the DRAGEN server.

Uninstall pipeline

To uninstall the pipeline, run the following command as the root user (or with sudo privileges):

Executing the uninstall script removes the following assets:

• All scripts, including:

  • run_Solid_WGS_TN_{version}.sh

  • check_Solid_WGS_TN_{version}.sh

  • uninstall_Solid_WGS_TN_{version}.sh

If the uninstall script is executed with the -r or --removeResources flag, dependencies of the application being uninstalled will be removed if no other applications depend on them.

You are not required to uninstall DRAGEN Application Manager, Docker, or the DRAGEN server software.

To remove Docker, review the install instructions for your operating system in the Docker documentation

Local App Setup

Overview

This document describes how to use the Custom Configuration Support feature for the pipeline software. This feature allows users to customize a specific set of DRAGEN command-line options to override the default values pre-defined in the pipeline.

Customization with customConfig and customResourceDir

Users can customize pipeline behavior and file inputs using:

• --customConfig : path to a custom configuration file listing customized parameter values.

• --customResourceDir : path to a directory containing custom resource files.

Both options should be used together if file-based overrides are required.

Important note for using File Parameters

• For file parameters (parameters that require a file), users must specify relative paths in the customConfig file. The software will join customResourceDir and the relative path to form the full file path.

• Additionally, the value assigned to a file parameter must be enclosed in single quotes ('').

Examples

Command Line

heme_custom_param.config Content

custom_resources_Heme_dir Folder Structure

customConfig Template (with default value)

Supported Parameters

ℹ️ Note: For CRAM Input Reference Genome, a list of commonly-used human reference FASTA files can be downloaded from the Illumina support site:

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.

Notes and additional options

Hashtable

For DRAGEN germline runs, it is recommended to use the pangenome hashtable.

See:

Input options

DRAGEN input sources include: fastq list, fastq, bam, or cram. For BCL input, first create FASTQs using .

FQ list Input

FQ Input

BAM Input

CRAM Input

Mapping and Aligning

Duplicate Marking

5-Base Methylation

For more information see: .

SNV

For more detail on the small variant caller in somatic mode please refer to

Annotation

For instructions on how to download the Nirvana annotation database, please refer to

UI Options

Manual Launch of pipeline Analysis Software Analysis