> For the complete documentation index, see [llms.txt](https://help.connected.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.connected.illumina.com/annotation/v4.0/introduction/getting-started-dragen.md).

# Getting Started with DRAGEN

### Overview

DRAGEN Annotation 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 DRAGEN Annotation tool

{% hint style="info" %}
**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

Please note that we provide a `setup` wizard that guides the user through all these steps.
{% endhint %}

### Installation Paths

The annotation binaries location depends on your DRAGEN environment:

| Environment    | Annotator Path                                |
| -------------- | --------------------------------------------- |
| **On-Premise** | `/opt/dragen/<DRAGEN_VERSION>/share/nirvana/` |
| **Cloud**      | `/opt/edico/share/nirvana/`                   |

**Available binaries:**

* `Annotator`: DRAGEN Annotation tool (includes `setup`, `download`, `annotate`, `list`, and `version-validate` commands)

{% hint style="warning" %}
**Platform Compatibility**

`Annotator` is compatible with CentOS 7, Oracle 8, and other modern Linux distributions using x64 processors.
{% endhint %}

### Automated Setup

The `Annotator setup` command provides an interactive wizard that guides you through configuring credentials, selecting a data catalog, and downloading annotation data — step by step:

```bash
/opt/dragen/<DRAGEN_VERSION>/share/nirvana/Annotator setup
```

See [Command Line Parameters](/annotation/v4.0/software-functionality/command-line-parameters.md#setup) for full details on setup options.

**Credentials File Formats**

Please note that all fields are optional, but it cannot be empty. Some form of credentials are required. The `Annotator setup` wizard can prompt for values and create this file for you.

```json
{
  "MyIlluminaApiKey": "<optional-myillumina-key>",
  "DragenSerialNo": "<optional-serial-number>",
  "ApiKey": "<optional-byol-user-id>",
  "ApiSecret": "<optional-byol-password>",
  "DragenApiKey": "<optional-dragen-api-key>"
}
```

{% hint style="info" %}
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 `--license.credentialsFile`
   {% endhint %}

#### Download Annotation Data

The setup wizard will ask the user if they want to proceed with downloading the data. If the user does not download at that time, they can use the following command to download at a later stage.

Use the `Annotator download` command to download required annotation data sources.

{% hint style="info" %}
For complete documentation, see the [Command Line Parameters](/annotation/v4.0/software-functionality/command-line-parameters.md).
{% endhint %}

**Available Annotation Configurations**

Configuration files are located in the \<annotation-data-directory>/runConfigs:

| Configuration File                           | Use Case                | DRAGEN Parameter                    |
| -------------------------------------------- | ----------------------- | ----------------------------------- |
| `<assembly>.<version>.premium.json`          | Full variant annotation | `--enable-variant-annotation true`  |
| `<assembly>.<version>.germline-tagging.json` | Germline tagging        | `--vc-enable-germline-tagging true` |
| `<assembly>.<version>.methylation.json`      | Methylation annotation  | —                                   |
| `<assembly>.<version>.tmb.json`              | 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.

**Example:**

```bash
dragen \
  --enable-variant-annotation true \
  --variant-annotation-data /data/annotations \
  --variant-annotation-assembly GRCh38 \
  --variant-annotation-run-config /data/annotations/runConfigs/GRCh38.20260501.premium.json \
  --variant-annotation-enable-vcf-output true \
  [... other DRAGEN parameters ...]
```

**Option B: Annotate via Standalone Tool**

Use the standalone `Annotator` tool to annotate existing VCF files:

```bash
dotnet Annotator.dll annotate \
  --config /data/annotations/runConfigs/GRCh38.20260501.premium.json \
  --input.file /data/samples/sample.vcf.gz \
  --output.directory /data/annotations/results
```

See [Command Line Parameters](/annotation/v4.0/software-functionality/command-line-parameters.md#annotate) for the full list of annotation options.

### Output Formats

#### JSON Output (Default)

DRAGEN Annotation produces JSON output by default. This format provides comprehensive annotation information.

**Documentation:** [DRAGEN Annotation JSON Format](/annotation/v4.0/file-formats/illumina-annotator-json-file-format.md)

#### VCF Output (Optional)

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

**Documentation:** [DRAGEN Annotation VCF Format](/annotation/v4.0/file-formats/illumina-annotator-vcf-file-format.md)

### Version History

| DRAGEN Version           | Annotations Version | AI Annotations                    | Documentation                                                                      | Data Utility                                                                                                                                    |
| ------------------------ | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 4.6                      | 4.0.0               | spliceAI, primateAI3D, PromoterAI | 4.0.0                                                                              | Annotator                                                                                                                                       |
| 4.5                      | 3.27.0              | spliceAI, primateAI3D, PromoterAI | [3.27](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/3.27/) | [Data Manager](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/3.27/utilities/data-manager)                                |
| 4.4                      | 3.25.1              | spliceAI, primateAI3D, PromoterAI | [3.25](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/3.25/) | [Data Manager](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/3.25/utilities/data-manager)                                |
| 4.3                      | 3.23                | spliceAI, primateAI3D, PromoterAI | [3.23](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/3.23/) | [Downloader](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/3.23/introduction/getting-started#downloading-the-data-files) |
| 3.9, 3.10, 4.0, 4.1, 4.2 | 3.16.1              | spliceAI, primateAI               | [3.16](https://illumina.github.io/NirvanaDocumentation/3.16/)                      | [Downloader](https://illumina.github.io/NirvanaDocumentation/3.16/introduction/getting-started#downloading-the-data-files)                      |
| 3.8                      | 3.14                | spliceAI, primateAI               | [3.14](https://illumina.github.io/NirvanaDocumentation/3.14/)                      | [Downloader](https://illumina.github.io/NirvanaDocumentation/3.14/introduction/getting-started#downloading-the-data-files)                      |
| 3.6, 3.7                 | 3.9.0               | spliceAI, primateAI               | Not Available                                                                      | Not Available                                                                                                                                   |
| 3.5                      | 3.6.0               | spliceAI, primateAI               | Not Available                                                                      | Not Available                                                                                                                                   |

{% hint style="info" %}
Annotations binaries have been included with DRAGEN since v3.5. Newer versions are backward compatible and can annotate output files from older DRAGEN releases.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.connected.illumina.com/annotation/v4.0/introduction/getting-started-dragen.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.