> For the complete documentation index, see [llms.txt](https://help.bioinsight.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.bioinsight.illumina.com/annotation/introduction/getting-started.md). # Getting Started with local download DRAGEN Annotation is written in C# using [.NET Core](https://www.microsoft.com/net/download/core) runtime environment, which is compatible with Windows, Linux, Mac OS X, and Docker images. Once .NET Core has been downloaded, all you need to do is obtain the source code, compile it, and download the data files. {% hint style="info" %} DRAGEN Annotation requires .NET8.0. Ensure that you have the required runtime installed from the [.NET Core downloads](https://www.microsoft.com/net/download/core) page. {% endhint %} {% hint style="info" %} Refer to the [Prerequisite](/annotation/introduction/prerequisite.md) section for instructions on generating the credential file required to run DRAGEN Annotation. {% endhint %} ### Getting DRAGEN Annotation #### Latest Release Please visit [DRAGEN Annotation](https://developer.illumina.com/illumina-connected-annotations) to obtain the latest release. Place the downloaded ZIP file in the `IlluminaConnectedAnnotations` folder. ```bash mkdir -p IlluminaConnectedAnnotations/Data cd IlluminaConnectedAnnotations unzip IlluminaConnectedAnnotations-3.25.0-0-g101034c3-net6.0.zip ``` #### Quick Start To get started right away, run the script to unzip the DRAGEN Annotation build, download annotation data, and annotate a test file: {% file src="/files/ffxkttwIuIWyFeT17RA9" %} ```bash bash ./TestIlluminaConnectedAnnotations.sh IlluminaConnectedAnnotationsBuild.zip ``` This script has been verified to work on Windows (using Git Bash or WSL), Linux, and Mac OS X. #### Docker Obtain the docker image as a ZIP file (e.g. IlluminaConnectedAnnotations-3.25.0-0-g101034c3-net6.0-docker.tar.gz), and load it as follows: ```bash docker load < IlluminaConnectedAnnotations-3.25.0-0-g101034c3-net6.0-docker.tar.gz ``` To build your own Docker image, download the DRAGEN Annotation ZIP file, Dockerfile, and image creation script: {% file src="/files/fy2IvbnMLbbglxwb3oTR" %} {% file src="/files/Zab1Xjae8zP4oYBe89P8" %} Place both files (`create_docker_image.sh` and `Dockerfile`) in the same directory. In the terminal, navigate to the directory containing the scripts and execute the following commands: ```bash chmod +x create_docker_image.sh ./create_docker_image.sh [path to zip file] [image tag] ``` After you run the script, the docker image will be available in your local machine with image name `illumina-connected-annotations:[image tag specified]`. Use these instructions to run the legacy `IlluminaConnectedAnnotations` Docker image: {% file src="/files/t5giF92URZbxPwLj92r6" %} ```bash docker run --rm -it -v local/data/folder:/scratch illumina-connected-annotations:v3.25.0 Annotator -c /scratch/Cache/ \ -r /scratch/References/Homo_sapiens.GRCh37.Nirvana.dat \ --sd /scratch/SupplementaryAnnotation/GRCh37 \ -i /scratch/HiSeq.10000.vcf.gz -o /scratch/HiSeq ``` {% hint style="warning" %} Running DRAGEN Annotation in Docker has a performance penalty. Data files are accessed through a Docker volume. {% endhint %} {% hint style="info" %} For convenience, the user is encouraged to create aliases for the docker commands. For example: ```bash alias IlluminaConnectedAnnotations="docker run --rm -it -v local/data/folder:/scratch illumina-connected-annotations:v3.25.0 IlluminaConnectedAnnotations" ``` {% endhint %} ### Downloading the data files Refer to [Prerequisite](/annotation/introduction/prerequisite.md) for details on creating an Illumina API key for DRAGEN Annotation and its utilities. To download the latest data sources (or update the ones that you already have), use the following commands to automate the download from S3: ```bash dotnet DataManager.dll make-config -r GRCh37 dotnet DataManager.dll download \ -r GRCh37 \ --dir Data ``` Refer to [Data Manager](/annotation/utilities/data-manager.md) for more details on managing data sources and their versions. **Glitches in the Matrix** Every once in a while, the download process may encounter issues due to network interruptions or insufficient disk space. The DataManager will perform md5sum checks against the downloaded files to ensure file integrity and completeness. If you see that a file was marked `Mismatched checksum` in the Download Summary, try resolving any potential causes and run the DataManager again. {% hint style="info" %} From time to time, you can re-run the DataManager to obtain the latest annotation files. It will only download files that have changed since the last download. {% endhint %} ### Download a test VCF file Here's a toy VCF file you can play around with: {% file src="/files/t5giF92URZbxPwLj92r6" %} ```bash curl -O https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/files/HiSeq.10000.vcf.gz ``` ### Running DRAGEN Annotation Once you have downloaded the data sets, use the following command to annotate your VCF: ```bash dotnet Annotator.dll \ -c Data/Cache \ --sd Data/SupplementaryAnnotation/GRCh37 \ -r Data/References/Homo_sapiens.GRCh37.Nirvana.dat \ -i HiSeq.10000.vcf.gz \ -o HiSeq.10000 ``` * the `-c` argument specifies the cache directory * the `--sd` argument specifies the supplementary annotation directory * the `-r` argument specifies the compressed reference path * the `-i` argument specifies the input VCF path * the `-o` argument specifies the output filename prefix When running DRAGEN Annotation, performance metrics appear for each input VCF chromosome: ```bash --------------------------------------------------------------------------- Illumina Connected Annotations (c) 2024 Illumina, Inc. 3.25.0 --------------------------------------------------------------------------- Initialization Time Positions/s --------------------------------------------------------------------------- Cache 00:00:00.0 SA Position Scan 00:00:00.0 153,634 Reference Preload Annotation Variants/s --------------------------------------------------------------------------- chr1 00:00:00.2 00:00:00.8 11,873 Summary Time Percent --------------------------------------------------------------------------- Initialization 00:00:00.0 1.5 % Preload 00:00:00.2 4.9 % Annotation 00:00:00.8 18.5 % Time: 00:00:04.4 ``` The output will be a JSON file called `HiSeq.10000.json.gz`. Here's the full JSON file: {% file src="/files/lTZdv9bRRUuPWH9hA7RX" %} ### The DRAGEN Annotation command line The full command line options can be viewed by using the `-h` option or no options ```bash dotnet Annotator.dll --------------------------------------------------------------------------- Illumina Connected Annotations (c) 2024 Illumina, Inc. 3.25.0 --------------------------------------------------------------------------- USAGE: dotnet Annotator.dll -i -c --sd -r -o Annotates a set of variants OPTIONS: --cache, -c input cache directory --in, -i input VCF path --tsv input VCF path --out, -o output file path --ref, -r input compressed reference sequence path --sd input supplementary annotation directory --sources, -s annotation data sources to be used (comma separated list of supported tags) --credentials-file, -l File path to user credentials, default is set to ~ /.ilmnAnnotations/credentials.json --versions-config Annotation version config file. By default, it will use file ~/.ilmnAnnotation/assembly_ annotation_config.json --ignore-license-error ignore error due to invalid license and skip related data sources --force-mt forces to annotate mitochondrial variants --legacy-vids enables support for legacy VIDs --enable-dq report DQ from VCF samples field --enable-bidirectional-fusions enables support for bidirectional gene fusions --disable-junction-preservation disable junction preserving functional annotation --str user provided STR annotation TSV file --vcf-info additional vcf info field keys (comma separated) desired in the output --vcf-sample-info additional vcf format field keys (comma separated) desired in the output --sa-cutoff Any SV larger than or equal to this value will not have any supplementary annotations --simple-nomenclature-cutoff-length Any SV larger than or equal to this value will not have any simple nomenclature annotation. Default is 1000. --output-format output file format, available options: json, vcf. --help, -h displays the help menu --version, -v displays the version ##### Supported Annotation Sources ##### Basic Tier: DECIPHER, GME, GERP, DANN, REVEL, ClinGen, gnomAD, phyloP, TOPMed, DGV, 1000 Genomes, CliinVar, dbSNP, FusionCatcher, MITOMAP, MultiZ100Way Professional Tier: PrimateAI(GRCh37), PrimateAI-3D(GRCh38), SpliceAI, COSMIC, OMIM. ##### Contact ##### Professional content licensing, feedback and technical support: annotation_support@illumina.com. ``` #### Specifying annotation sources By default, DRAGEN Annotation uses all available data sources. You can customize sources and versions with `--versions-config`. An example of a versions-config json file is shown below: ```json { "Ensembl": { "GeneModels": "110" }, "GenomeAssembly": { "GenomeAssembly": "GRCh37.p13" }, "HGNC": { "GeneModels": "20240603" }, "RefSeq": { "GeneModels": "105.20220307" }, "clinvar": { "SmallVariant": "99999999" }, "gnomad": { "LowComplexityRegions": "2.1", "SmallVariant": "2.1" } } ``` If an unknown source is specified, a warning message will be displayed. ```bash dotnet Annotator.dll \ -c Data/Cache/GRCh37 \ --sd Data/SupplementaryAnnotation/GRCh37 \ -r Data/References/Homo_sapiens.GRCh37.Nirvana.dat \ -i HiSeq.10000.vcf.gz \ -o HiSeq.10000 \ --versions-config /Users/bob/.ilmnAnnotations/customised_GRCh37_annotation_config.json --------------------------------------------------------------------------- Illumina Connected Annotations (c) 2024 Illumina, Inc. 3.25.0 --------------------------------------------------------------------------- Some requested data sources are not loaded. Data Source Type Status Comments --------------------------------------------------------------------------- GenomeAssembly GenomeAssembly Loaded GRCh37.p13 RefSeq GeneModels Loaded 105.20220307 Ensembl GeneModels Loaded 110 HGNC GeneModels Loaded 20240603 gnomad SmallVariant Loaded 2.1 gnomad LowComplexityRegions Loaded 2.1 clinvar SmallVariant Skipped Version 99999999 not available Initialization Time Positions/s --------------------------------------------------------------------------- SA Position Scan 00:00:00.3 307,966 .... .. ``` The list of available values is compiled from the files provided (using `-c` and `--sd` options). --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.bioinsight.illumina.com/annotation/introduction/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.