> 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/v3.27/introduction/getting-started.md). # Getting Started with local download Illumina Connected Annotations 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" %} Illumina Connected Annotations 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/v3.27/introduction/prerequisite.md) section for instructions on generating the credential file required to run Illumina Connected Annotations. {% endhint %} ### Getting Illumina Connected Annotations #### Latest Release Please visit [Illumina Connected Annotations](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, the below script may be run to automatically unzip the Illumina Connected Annotations build, download annotation data, and initiate annotation a test file: {% file src="/files/tqDPDO4SrASiR0h56Xlj" %} ```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 Illumina Connected Annotations ZIP file, Dockerfile, docker image creation script (Dockerfile and script below): {% file src="/files/ZyxZQOr0i6v7HtnrJ90Q" %} {% file src="/files/6Z7WBM9tLyOQQcNQAJEK" %} 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]`. We have special instructions for running IlluminaConnectedAnnotations (Here's a toy VCF in case you need it): {% file src="/files/CO27348rdckqRGwHPiSN" %} ```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" %} Please note that there is a noticeable performance penalty when running Illumina Connected Annotations in Docker as our 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/v3.27/introduction/prerequisite.md) for more details on creating Illumina API key to use Illumina Connected 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/v3.27/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/CO27348rdckqRGwHPiSN" %} ```bash curl -O https://illumina.github.io/IlluminaConnectedAnnotationsDocumentation/files/HiSeq.10000.vcf.gz ``` ### Running Illumina Connected Annotations 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 Illumina Connected Annotations, performance metrics are shown as it evaluates each chromosome in the input VCF file: ```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/qNpjD1Clf88Gq6s2uoyq" %} ### The Illumina Connected Annotations 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, Illumina Connected Annotations uses all available data sources. However, you can customize the set of sources and their versions using the `--versions-config` option. 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 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/v3.27/introduction/getting-started.md?ask=&goal= ``` `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.