illumina Dragen v3.9.5 Software User Guide
- June 9, 2024
- illumina
Table of Contents
illumina Dragen v3.9.5 Software
Introduction
These release notes detail the key changes to software components for the Illumina® DRAGEN™ BioIT Platform v3.9.5.
Changes are relative to DRAGEN™ v3.9.3. If you are upgrading from a version prior to DRAGEN™ v3.9.3, please review the release notes for a list of features and bug fixes introduced in subsequent versions.
DRAGEN™ Installers, User Guide and Release Notes are available here:
https://support.illumina.com/sequencing/sequencing_software/dragen-bio-
itplatform.html
The 3.9.5 software package includes:
- Amazon Machine Image (AMI)
- Microsoft Azure Image (VM)
- RPM packages for Centos 7 for Amazon Web Services (AWS)
Deprecated platforms:
- Support for IBM PPC has been deprecated since DRAGEN™ v3.7
- Support for Intel CentOS 6 has been deprecated since DRAGEN™ v3.8
- Support for Ubuntu has been deprecated since DRAGEN™ v3.9
Added Functionality
DRAGEN v3.9.5 now supports Red Hat Enterprise Linux (RHEL) v8 for on-site servers. The .run file includes an RPM installer for el8. The installer now uses the Linux dims service to manage the kernel driver. DRAGEN is tested on Oracle Linux Server release 8.4.
Issues Resolved
Issues that are fixed in v3.9.5
| Defect ID | Component | Description |
|---|---|---|
| DRAGEN- 14274 | Cloud Infrastructure | Fix for crash with “HW License V2 |
expected” on new cloud instance (AWS and Azure) due to a register access
attempt before fpga image is loaded.
DRAGEN- 14152| All| Fix several security vulnerabilities.
DRAGEN- 14188| SNV VC| Fix hang in MNV detection when GVCF mode is enabled.
DRAGEN- 14258| Cloud Infrastructure| Fix self_test.sh for AWS instances, allow
the license url argument
DRAGEN- 14167| SNV VC, Mito| Fix for missing homref scores in Germline Mito
GVCF. Somatic homref scores are changed to an evidence measurement rather than
a posterior probability, in line with the GQ scores reported for germline
homref. This allows zero-depth positions to get a score of zero.
DRAGEN- 14380| BCL| Fix a BCL conversion crash when config.xml is present in
BaseCalls on aggregated bcl input (HiSeq/MiSeq).
DRAGEN- 14297| Somatic CNV| Fix a CNV hang in somatic mode
SET-1971 DRAGEN- 14493| SNV VC, Mito| Fix for unexpected MT variant calls with
DRAGEN v3.8.4
DRAGEN- 13409| BCL| Fix for bcl-convert producing incorrect demuxing data with
inputs with a Read 1 size of < 25 cycles
DRAGEN- 14430| BCL| BCL fix for Adapter Metrics of R2 being copied from R1
DRAGEN- 14080| Downsampling| Fix to propagate full fastq read names to output
for downsampling feature
DRAGEN- 14179| UMI, HLA| Fix for HLA accuracy degrade when UMI is enabled
DRAGEN- 14034 SET-2030| SNV VC| Fix for watchdog timeout (hang) during SNV
when haplotypes exceed a certain length
DRAGEN-
14460
| Downsampling| Fix inconsistent output orientation for Downsampling
DRAGEN- 14447| scRNA| Fix out-of-bounds exception in scRNA when using fixed
cell threshold
DRAGEN- 14501| SNV VC| Block MNV enabling with force GT due to segmentation
fault (unsupported)
DRAGEN- 14119| scRNA| Fix cell-hashing barcodeSummary.csv output, remove
additional empty column
DRAGEN- 14495| BCL| Fix BCL convert tiles regex validation error on s_1+s_2
DRAGEN- 14538| CRAM| Fix for CRAM index containing invalid span values
---|---|---
DRAGEN- 14522| Infrastructure| Add bitstream/fpga tests to self_test.sh
DRAGEN- 14479| Cloud Infrastructure| Fix for AMI not working with AWS BATCH /
ECS
DRAGEN- 14168| SNV VC| Fix a crash during Evidence BAM output when MD tags are
enabled
DRAGEN- 14040| Somatic CNV| Support T/N+PON CNV WES when running with SNV or
SV
DRAGEN- 14472| SNV VC, Mito| Fix incorrect callability metric for germline
mito GVCF
DRAGEN- 13753| SNV VC, Somatic| Fix for forced GT calls present in regions
with no coverage and outside of target bed regions in somatic run
DRAGEN- 14744| SNV VC, Somatic| Fix for missing NON_REF GVCF positions in
Somatic GVCF output
DRAGEN- 14781
| Gvcf Genotyper, Joint Genotyper| Fix for missing FT fields in ms-VCF header
when running Joint Genotyper from Gvcf Genotyper input
DRAGEN- 13837| Gvcf Genotyper| Fix for Hail crash on ChrM with Gvcf Genotyper
output, by correcting header SQ entry
DRAGEN- 14799| Trimmer| Make read-trimming option validation stricter, to
resolve potential failure mode
DRAGEN- 14798| Trimmer| Add validation check for ‘cut-end’ trimmer and related
trimming options, to resolve potential failure mode
Known Issues
Known issues of the DRAGEN™ v3.9.5 release
Defect ID| Component| Issue Type| Description| Remedy /
Workaround
---|---|---|---|---
DRAGEN- 14966| CRAM, Alt-
masking
| Bug| CRAM generated with alt-masking HT may not be decodable by 3rd party| Reads which map to regions that are masked may be affected. The workaround is to apply masking to the fasta and use that fasta to decompress the CRAM. The issue is present since alt-masking was introduced in 3.9.3
and will be fixed in DRAGEN v3.10
DRAGEN- 14902| Infrastructure| Usability| DRAGEN hangs on corrupted (truncated) BAM input| Some types of BAM truncation may lead to hang in DRAGEN. User will be
able to quit the hanging job via CRLT+C and fix their input and re-run.
DRAGEN- 14890| SNV VC| Bug| Segmentation fault in MNV| When using the distance bed option to specify combination distances, some bed files lead to a crash in MNV processing. The issue exists in 3.9.3
release. The workaround is to use
| | | | command line option instead of BED file.
DRAGEN- 14794| Metrics| Bug| QC region coverage metrics reports more aligned
reads than WGS coverage metrics| Use the aligned reads from the WGS coverage
metrics
DRAGEN- 14755| RNA| Usability| RNA gene fusion output md5sum difference
between U200 Phase2 and Phase4 servers due to precision| VCF may not be bit
exact match, due to insignificant floating-point differences. The score is
used to filter false fusion candidates. Candidates with a score < 0.5 are
marked as failing whereas candidates with a score
0.5 are marked as passing if they also pass other criteria. Based on this, only candidates which have a score close to 0.5 may be affected by this issue, but the issue is seen only on
very low score values
DRAGEN- 14743| CNV| Usability| Sample excluded from sex genotyper metrics file| A user may include N samples to be used in the panel of normals, for CNV normalization. As part of the algorithm, a sample may be removed from the set if it does not meet certain quality requirements (such as having too many 0 coverage regions). When this happens, the remaining n < N set of samples is used. The remaining n samples will have their Sex Genotype reported in the output cnv_metrics.csv. Known behavior, not a bug. Some users may still be interested in the estimated gender of samples that have been removed, so this will be changed
in DRAGEN v3.10
DRAGEN- 14727| Metrics, Graph Genome| Bug| DRAGEN graph genome
– discrepancy in coverage stats results
| A coverage metric for graph genome is incorrect. This issue is present in
3.9.3 also. No workaround
DRAGEN- 14526| Methylation| Bug| Multi-pass methylation does not report number
of duplicates in mapping metrics.| Duplicates are not reported in metrics for
multi-pass methylation. No workaround.
The metric is calculated now in the new “single-pass” methylation flow, which is the recommended way to run
methylation.
DRAGEN- 14513| FPGA| Usability| Deflate engine error: 0x9080 on stream 1 on
EAGLE server| Very rare intermittent hardware issue on Phase1 server FPGA
leads to crash. Rerun of the sample will succeed.
DRAGEN- 14511| Cloud Infrastructure| Usability| [AZURE] Error in
`/opt/edico/bin/dragen’: corrupted size vs. prev_size: 0x00002b10140015ef|
This crash was encountered once on Azure and has not been reproducible. A re-
run will succeed
DRAGEN- 14390| CRAM| Usability| DRAGEN hits segmentation fault on| When
incorrect reference is used to process CRAM input, the system may crash. This
has been the behavior of
| | | CRAM input mismatched with reference| DRAGEN with CRAM input. Select
correct reference and re-run.
DRAGEN- 14373| Infrastructure| Usability| Trailing whitespace on the dragen
command line cause an error| Trailing whitespace can lead to command line
parsing error, and dragen exits.
DRAGEN- 13977| Infrastructure| Usability| dragen_drv does not compile on linux
kernel 5.8.0| dragen driver does not compile on Ubuntu with on linux kernel
5.8.0
DRAGEN- 13896| CNV| Bug| Panel of Normals filtering applied incorrectly|
Affects CNV panel-of-normals feature, which is still officially supported but
no longer recommended. Will not be fixed.
The feature shall be deprecated.
DRAGEN- 13887| Methylation| Bug| Methylation reporting only assertion failing
during processing| Encountered when using methylation report compression. The
workaround is to disable report compression
DRAGEN- 13818| HT Builder| Usability| Custom reference failing at alignment
due to compression issue| Some small custom references cannot be built by the
hash table builder.
There is no workaround.
SW Installation Procedure
-
Download the desired installer from the Illumina 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
-
Please follow the installer instructions. Server power cycle may be required after installation, depending on the currently installed version. If an updated FPGA shell image needs to load from flash, this is only achieved with power cycle.
o A power cycle is required when upgrading from v3.3.7 or older
o A power cycle is required when downgrading to v3.3.7 or older
o A power cycle is not required when upgrading from a release after v3.3.7 -
Procedure to downgrade to v3.3.7 or older: o Requires the following three steps. The prior .mcs file needs to be flashed manually:
- Install the prior release: sudo sh
- program_flash /opt/edico/bitstream/07/.mcs
- Power cycle