# Illumina Connected Annotations ### Illumina Connected Annotations Illumina Connected Annotations, also known as Illumina Annotation Engine (IAE) or Nirvana provides translational research-grade annotation of genomic variants (SNVs, MNVs, insertions, deletions, indels, STRs, gene fusions, and SVs (including CNVs). It 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 The input to Illumina Connected Annotations are VCFs and the output is either a structured JSON representation of all annotation and sample information (as extracted from the VCF) or an annotated VCF. Please note that the annotated VCF only contains a subset of the annotations provided in the JSON output. This tool can handle multi-sample VCFs. #### 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//share/nirvana/` | `/opt/dragen//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. #### Downloading Annotation Data Files Variant annotation in DRAGEN requires additional annotation data files that have to be downloaded prior to running any DRAGEN pipeline that requires variant annotation. To download, please use the DataManager software that is located in `/share/nirvana/DataManager`. Detailed instructions on how to setup annotations is available [here](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/introduction/getting-started-dragen). We highly recommend using the [Automated Script Setup](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/introduction/getting-started-dragen#automated-setup-script). #### Detailed Instructions If you prefer not to use the automated script, please follow the instructions [here](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/introduction/getting-started-dragen#detailed-instructions). #### Annotate Files (via DRAGEN command-line) To automatically annotate output VCFs, please add the following command-line arguments: | 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) | All the command-line arguments shown together: ```bash dragen \ --enable-variant-annotation true \ --variant-annotation-data /data/nirvana_data \ --variant-annotation-assembly GRCh38 \ --annotation-data-config /opt/dragen//resources/annotation/latest_annotations_GRCh38.json \ --variant-annotation-enable-vcf-output true \ [... other DRAGEN parameters ...] ``` #### Annotate Files (via standalone Illumina Connected Annotations) 1. Please note that Illumina Connected Annotations supports uncompressed VCF files and bgzip compressed VCF files. VCF files that have been compressed by standard gzip are not supported. 2. To annotate the file, enter the following command: ```shell //Nirvana \ -i \ -o \ -c /Cache \ -r /References/Homo_sapiens.GRCh38.Nirvana.dat \ --sd /SupplementaryAnnotation/GRCh38 \ -l \ --versions-config /opt/dragen//resources/annotation/all_annotations_GRCh38.json ``` **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 | Using the example above, Annotations generates the following output. ```bash --------------------------------------------------------------------------- Illumina Connected Annotations (c) 2026 Illumina, Inc. 3.27.0 --------------------------------------------------------------------------- Data Source Type Status Comments --------------------------------------------------------------------------- DANN Score Loaded 20200205 DECIPHER StructuralVariant Loaded 201509 Ensembl GeneModels Loaded 112 FusionCatcher GeneFusion Loaded 1.33 GME SmallVariant Loaded 20160618 GenomeAssembly GenomeAssembly Loaded GRCh38.p14 Gerp Score Loaded 20110522 HGNC GeneModels Loaded 20240603 MultiZ100Way Protein Loaded 20171006 PrimateAI SmallVariant Loaded 0.2 PromoterAI SmallVariant Loaded 1.0 REVEL SmallVariant Loaded 20200205 RefSeq GeneModels Loaded GCF_000001405.40-RS_2023_10 TOPMed SmallVariant Loaded freeze_5 clingen Gene Loaded 20240910 clingen StructuralVariant Loaded 20240910 clingen (legacy) StructuralVariant Loaded 20160414 clinvar SmallVariant Loaded 20240902 clinvar StructuralVariant Loaded 20240902 clinvar-preview SmallVariant Loaded 20240902 clinvar-preview StructuralVariant Loaded 20240902 cosmic Gene Loaded 99 cosmic GeneFusion Loaded 99 cosmic SmallVariant Loaded 99 dbSNP SmallVariant Loaded 156 globalAllele SmallVariant Loaded 151 gnomad Gene Loaded 4.1 gnomad LowComplexityRegions Loaded 2.1 gnomad SmallVariant Loaded 4.1 gnomad StructuralVariant Loaded 4.1 gnomad-exome SmallVariant Loaded 4.1 mitomap SmallVariant Loaded 20200819 mitomap StructuralVariant Loaded 20200819 omim Gene Loaded 20240910 oneKg RefMinor Loaded Phase 3 v3plus oneKg SmallVariant Loaded Phase 3 v3plus oneKg StructuralVariant Loaded Phase 3 v5a phylopScore ConservationScore Loaded hg38 phylopScore Score Loaded 1.0 primateAI-3D SmallVariant Loaded 1.0 spliceAI SmallVariant Loaded 1.3 --------------------------------------------------------------------------- Initialization Time Positions/s --------------------------------------------------------------------------- Cache 00:00:03.6 SA initialization 00:00:08.0 VCF Position Scan 00:00:00.0 115,442 Reference SA Loading Annotation Variants/s --------------------------------------------------------------------------- chr1 00:00:00.5 00:00:02.0 4,980 Summary Time Percent --------------------------------------------------------------------------- Initialization 00:00:11.7 84.9 % Annotation 00:00:02.0 14.4 % |--SA Loading 00:00:00.5 4.2 % |--Output writing 00:00:00.3 2.2 % License Check 00:00:00.0 0.0 % Usage Report 00:00:00.0 0.0 % --------------------------------------------------------------------------- Gross Annotation rate: 718.84 positions/sec Peak memory usage: 5.867 GB Time: 00:00:13.8 ``` **Note** For complete annotation options, see the [Illumina Connected Annotations guide](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/introduction/getting-started#the-illumina-connected-annotations-command-line). #### JSON Output File Annotations produces an output file in JSON format. Please refer to [Illumina Connected Annotations JSON](https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/file-formats/illumina-annotator-json-file-format#header) for detailed description of the JSON file. #### Version History Annotations binaries have been included with DRAGEN since v3.5. The table below indicates which version of Annotations binaries were included with different DRAGEN releases, and their AI annotation capabilities. > The Annotations binaries distributed with DRAGEN can not be changed. Newer versions of Annotations are backward compatible, and can therefore annotate output files from older DRAGEN releases. | DRAGEN version(s) | Annotations version | AI annotations | Documentation | Data Utility | | ------------------------ | ------------------- | --------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 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 |