Illumina Connected Software is becoming Illumina BioInsight Platform. For this and other updates, you can
read more here
Ctrlk
Illumina KnowledgeIllumina SupportSign In
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Getting Started with DRAGEN

Overview

Illumina Connected Annotations is bundled with DRAGEN and provides comprehensive variant annotation capabilities. You can annotate VCF files either:

  • Automatically through DRAGEN pipeline parameters

  • Manually using the standalone Illumina Connected Annotations tool

Key Requirements

Before annotating variants, you must:

  1. Configure credentials for premium data sources

  2. Download annotation data files

  3. Specify the data location when running DRAGEN or the standalone tool

Installation Paths

The annotation binaries location depends on your DRAGEN environment:

Environment
Nirvana Path
Resource Path

On-Premise

/opt/dragen/<DRAGEN_VERSION>/share/nirvana/

/opt/dragen/<DRAGEN_VERSION>/resources/annotation/

Cloud

/opt/edico/share/nirvana/

/opt/edico/resources/annotation/

Available binaries:

  • Nirvana: Illumina Connected Annotations tool

  • DataManager: Annotation data download manager

Platform Compatibility

Nirvana and DataManager are compatible with CentOS 7, Oracle 8, and other modern Linux distributions using x64 processors.

Automated Setup Script

For a streamlined setup experience, use the Annotation Setup script (download below) which automates all the configuration steps:

32KB
annotation_setup.sh
Open

Features:

  • Interactive mode: Step-by-step guidance for credential setup and data download

  • CLI mode: Fully automated for scripting and CI/CD pipelines

  • Automatic credential detection: Uses environment variables or prompts for credentials

  • Multi-download support: Download multiple assemblies and annotation types in one run

  • Dry-run mode: Preview commands without downloading (use --dry-run)

Quick Start Reference

On-Premise DRAGEN

Cloud DRAGEN

Alternative Cloud Option

If you already have a DRAGEN --lic-credentials file, you can use it directly:

Detailed Instructions

Step 1: Configure Credentials

To access premium annotation data sources, you need to provide credentials. The system supports multiple authentication methods and will automatically search for credentials in several locations.

Supported Authentication Methods

The annotation tools support the following authentication methods:

Authentication Method
Use Case
Environment Variables
Command-Line Options

DRAGEN Serial Number

On-premise DRAGEN servers

DRAGEN_SERIAL_NUMBER

--credentials-file

DRAGEN API Key

DRAGEN cloud/platform deployments

DRAGEN_API_KEY_VALUE DRAGEN_API_KEY_FILE (path)

--api-key-file --credentials-file

BYOL Credentials

Cloud DRAGEN users

NIRVANA_API_KEY + NIRVANA_API_SECRET DRAGEN_LICENSE_CREDENTIALS_FILE (path)

--lic-credentials --credentials-file

Credential Priority

If multiple authentication methods are configured, the system will use them in this priority order:

  1. DRAGEN Serial Number

  2. BYOL Credentials (ApiKey/ApiSecret)

  3. DRAGEN API Key

You only need to provide one authentication method.

Credential Configuration Options

You can configure credentials using any of these methods:

Option 1: Default credentials directory

Option 2: Explicit file paths

Option 3: Environment variables

Option 1: Default Credentials Directory

Automatically look for credentials in ~/.ilmnAnnotations/ directory:

File Name
Purpose
Format

credentials.json

Main credentials file (all auth types)

JSON

dragen_api_key.txt

DRAGEN API key only

Plain text

dragen_credentials.txt

BYOL credentials (ApiKey/ApiSecret)

Key-value pairs

Option 2: Explicit File Paths

You can specify credential file locations using command-line arguments:

Tool
Argument
Description

DataManager

--credentials-file <path> or -l <path>

Path to credentials.json

DataManager

--api-key-file <path>

Path to raw API key file

DataManager

--lic-credentials <path>

Path to license credentials file (key-value format)

Option 3: Environment Variables

Set environment variables for automatic credential detection:

Environment Variable
Description
Example

MY_ILLUMINA_API_KEY

MyIllumina API key

your-api-key

DRAGEN_SERIAL_NUMBER

DRAGEN serial number

ABCD1234

DRAGEN_API_KEY_VALUE

DRAGEN API key value

your-dragen-api-key

DRAGEN_API_KEY_FILE

Path to DRAGEN API key file

/path/to/api_key.txt

NIRVANA_API_KEY

BYOL API key (user_id)

your-user-id

NIRVANA_API_SECRET

BYOL API secret (password)

your-password

DRAGEN_LICENSE_CREDENTIALS_FILE

Path to DRAGEN license credentials

/path/to/dragen_credentials.txt

Examples:

Credentials File Formats

Format 1: credentials.json (Recommended)

The credentials.json file supports all authentication methods in a single file:

On-Premise DRAGEN:

Cloud DRAGEN (BYOL):

MyIllumina Platform:

Basic, without access to premium data:

All supported fields:

Format 2: dragen_api_key.txt

A plain text file containing only the DRAGEN API key:

Format 3: dragen_credentials.txt

A key-value pair file for BYOL credentials:

Setting Up Credentials by Environment

On-Premise DRAGEN

Required credential: DRAGEN Serial Number

Obtaining your DRAGEN serial number:

If you have a single DRAGEN version:

If you have multiple DRAGEN versions:

Creating credentials.json:

Or using environment variable:

Cloud DRAGEN

Cloud users do not have a DRAGEN serial number. Active DRAGEN cloud users are automatically eligible for premium resources using BYOL credentials or DRAGEN API keys.

Required credentials: BYOL ApiKey/ApiSecret or DRAGEN API Key

Method 1: Using DRAGEN API Key

If you have a DRAGEN API key, you can use it directly:

Or set as an environment variable:

Method 2: Use existing --lic-credentials file directly

If you run DRAGEN with --lic-credentials <file>, you can use the same file directly with DataManager and Nirvana:

Using the license credentials file:

Optional: Convert to credentials.json (if you prefer the JSON format):

Troubleshooting

If you encounter authentication errors:

  1. Verify credentials are in the correct format

  2. Check file permissions (credentials files should be readable)

  3. Ensure at least one authentication method is configured

  4. Try specifying the credentials file path explicitly with --credentials-file

Step 2: Download Annotation Data

Use the DataManager tool to download required annotation data sources.

For complete DataManager documentation, see the DataManager guide.

Available Annotation Configurations

Configuration files are located in the resources directory (see Installation Paths above):

Configuration File
Assembly
Use Case
DRAGEN Parameter

all_annotations_GRCh37.json

GRCh37

Full variant annotation

--enable-variant-annotation true

all_annotations_GRCh38.json

GRCh38

Full variant annotation

--enable-variant-annotation true

germline_tagging_annotations_GRCh37.json

GRCh37

Germline tagging

--vc-enable-germline-tagging true

germline_tagging_annotations_GRCh38.json

GRCh38

Germline tagging

--vc-enable-germline-tagging true

tmb_annotations_GRCh37.json

GRCh37

Tumor Mutational Burden

--enable-tmb true

tmb_annotations_GRCh38.json

GRCh38

Tumor Mutational Burden

--enable-tmb true

Important Notes

  • TMB annotation files include germline tagging data. If you download TMB annotations, you don't need to separately download germline tagging annotations.

  • Running DRAGEN with --enable-tmb true requires TMB annotation data.

  • Running DRAGEN with --vc-enable-germline-tagging true requires germline tagging annotation data.

  • Missing required data will cause DRAGEN to fail with an error. :::

Download Commands

Parameters:

  • <assembly>: GRCh37 or GRCh38

  • <path/to/credentials.json>: Path to your credentials file from Step 1

  • <path/to/data/directory>: Destination directory for annotation files

  • <config_file.json>: One of the configuration files listed above

Storage Best Practice

Use the same data directory for all configuration files. This consolidated location will be used with the --variant-annotation-data parameter when running DRAGEN.

Download Example

Example command for full GRCh38 annotations:

Expected output:

Example completion message:

Step 3: Annotate Variants

Once credentials are configured and data is downloaded, you can annotate variants through DRAGEN or the standalone tool.

Option A: Annotate via DRAGEN Pipeline

Add these parameters to your DRAGEN command:

Parameter
Value
Description

--enable-variant-annotation

true

Enables variant annotation

--variant-annotation-data

/path/to/data/directory

Location of downloaded annotation files

--variant-annotation-assembly

GRCh37 or GRCh38

Reference genome assembly (use GRCh37 for hg19)

--annotation-data-config

/path/to/data/versions-config-json

File path to annotation data config (json) file, if this is not set, embedded data config will be used

--variant-annotation-assembly

true

Set Nirvana output format to VCF(optional)

Example:

Option B: Annotate via Standalone Tool

Use the standalone Nirvana tool to annotate existing VCF files.

For complete annotation options, see the Illumina Connected Annotations guide.

Parameters:

Option
Description
Example

-i

Input VCF file (uncompressed or bgzipped)

input.vcf.gz

-o

Output file prefix

output

-c

Cache directory

/data/nirvana_data/Cache

-r

Reference file

/data/nirvana_data/References/Homo_sapiens.GRCh38.Nirvana.dat

--sd

Supplementary annotation directory

/data/nirvana_data/SupplementaryAnnotation/GRCh38

-l

Credentials file

credentials.json

--versions-config

Version configuration file

Path from resources directory

Example output:

Output Formats

JSON Output (Default)

Illumina Connected Annotations produces JSON output by default. This format provides comprehensive annotation information.

Documentation: Illumina Connected Annotations JSON Format

VCF Output (Optional)

Add --output-format vcf to generate VCF output. Note that VCF format has limited annotation capabilities compared to JSON.

Documentation: Illumina Connected Annotations VCF Format

Version History

DRAGEN Version
Annotations Version
AI Annotations
Documentation
Data Utility

4.5

3.27.0

spliceAI, primateAI3D

3.27

Data Manager

4.4

3.25.1

spliceAI, primateAI3D

3.25

Data Manager

4.3

3.23

spliceAI, primateAI3D

3.23

Downloader

3.9, 3.10, 4.0, 4.1, 4.2

3.16.1

spliceAI, primateAI

3.16

Downloader

3.8

3.14

spliceAI, primateAI

3.14

Downloader

3.6, 3.7

3.9.0

spliceAI, primateAI

Not Available

Not Available

3.5

3.6.0

spliceAI, primateAI

Not Available

Not Available

Annotations binaries have been included with DRAGEN since v3.5. Newer versions are backward compatible and can annotate output files from older DRAGEN releases.

PreviousGetting Started with local downloadNextParsing Illumina Connected Annotations JSON

Last updated

Was this helpful?