Run DRAGEN in Bench - Interactive

Introduction

DRAGEN can run in Bench workspaces

• In either FPGA mode (hardware-accelerated) or software mode when using FPGA instances. This can be useful when comparing performance gains by hardware acceleration or to distribute concurrent processes between the FPGA and cpu.

• In software mode when using non-FPGA instances.

To run DRAGEN in software mode, you need to use the DRAGEN --sw-mode parameter.

The DRAGEN command line parameters to specify the location of the licence file are different.

• FPGA mode uses LICENSE_PARAMS=``"--lic-instance-id-location /opt/dragen-licence/instance-identity.protected --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds.lic"

• Software mode uses LICENSE_PARAMS="--sw-mode --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds-sw-mode.lic"

DRAGEN Bench Images

DRAGEN software is provided in specific Bench images with names starting with Dragen. For example (available versions may vary):

• Dragen 4.4.1 - Minimal provides DRAGEN 4.4.1 and SSH access

• Dragen 4.4.6 provides DRAGEN 4.4.6, SSH and JupyterLab.

Prerequisites

Memory

The instance type is selected during workspace creation (Projects > your_project > Bench > Workspaces). The amount of RAM available on the instance is critical. 256GiB RAM is a safe choice to run DRAGEN in production. All FPGA2 instances offer 256GiB or more of RAM.

When running in Software mode, use himem-large (348GiB RAM) or hicpu-large (144 GiB RAM) to ensure enough RAM is available for your runs.

During pipeline development, when typically using small amounts of data, you can try to scale down in instance types to save costs. You can start at hicpu-large and progressively use smaller instances, though you will need at least standard-xlarge. If DRAGEN runs out of available memory, the system is rebooted, losing your currently running commands and interface.

DRAGEN version 4.4.6 and later verify if the system has at least 128GB of memory available. If not enough memory is available, you will encounter an error stating that the Available memory is less than the minimum system memory required 128GB. This can be overridden with the command line parameter dragen --min-memory 0

FPGA-mode

Using an fpga2-medium instance type.

Example

mkdir /data/demo 
cd /data/demo 

# download ref 
wget --progress=dot:giga https://s3.amazonaws.com/stratus-documentation-us-east-1-public/dragen/reference/Homo_sapiens/hg38.fa -O hg38.fa 
# => 0.5min 

# Build ht-ref 
mkdir ref 
dragen --build-hash-table true --ht-reference hg38.fa --output-directory ref 
# => 6.5min 

# run DRAGEN mapper 
FASTQ=/opt/edico/self_test/reads/midsize_chrM.fastq.gz

# Next line is needed to resolve "run the requested pipeline with a pangenome reference, but a linear reference was provided" in DRAGEN (4.4.1 and others). Comment out when encountering unrecognised option '--validate-pangenome-reference=false'.
DRAGEN_VERSION_SPECIFIC_PARAMS="--validate-pangenome-reference=false" 

# License Parameters
LICENSE_PARAMS="--lic-instance-id-location /opt/dragen-licence/instance-identity.protected --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds.lic"

mkdir out
dragen -r ref --output-directory out --output-file-prefix out -1 $FASTQ --enable-variant-caller false --RGID x --RGSM y ${LICENSE_PARAMS} ${DRAGEN_VERSION_SPECIFIC_PARAMS} 
# => 1.5min (10 sec if fpga already programmed)

Software-mode

Using a standard-xlarge instance type.

Software mode is activated with the DRAGEN --sw-mode parameter.

Example

mkdir /data/demo 
cd /data/demo 

# download ref 
wget --progress=dot:giga https://s3.amazonaws.com/stratus-documentation-us-east-1-public/dragen/reference/Homo_sapiens/hg38.fa -O hg38.fa 
# => 0.5min 

# Build ht-ref 
mkdir ref 
dragen --build-hash-table true --ht-reference hg38.fa --output-directory ref 
# => 6.5min 

# run DRAGEN mapper 
FASTQ=/opt/edico/self_test/reads/midsize_chrM.fastq.gz

# Next line is needed to resolve "run the requested pipeline with a pangenome reference, but a linear reference was provided" in DRAGEN (4.4.1 and others). Comment out when encountering ERROR: unrecognised option '--validate-pangenome-reference=false'.
DRAGEN_VERSION_SPECIFIC_PARAMS="--validate-pangenome-reference=false"

# When using DRAGEN 4.4.6 and later, the line above should be extended with --min-memory 0 to skip the memory check.
DRAGEN_VERSION_SPECIFIC_PARAMS="--validate-pangenome-reference=false --min-memory 0" 

# License Parameters
LICENSE_PARAMS="--sw-mode --lic-credentials /opt/dragen-licence/instance-identity.protected/dragen-creds-sw-mode.lic" 

mkdir out 
dragen -r ref --output-directory out --output-file-prefix out -1 $FASTQ --enable-variant-caller false --RGID x --RGSM y ${LICENSE_PARAMS} ${DRAGEN_VERSION_SPECIFIC_PARAMS} 
# => 2min