Jannovar

Functional variant file annotation in Java. Jannovar provides a program for the annotation of VCF files and also exposes its functionality through a library API.

Also see the Quickstart section in the Jannovar manual.

In Brief

• Language/Platform: Java >=8
• License: BSD 3-Clause
• Version: see Github side bar for current release
• Availability:
  • Java command line tool jannovar-cli
  • Java libraries exposing most of jannovar-cli's functionality.

Databases

As of Jannovar version v0.36, we provide pre-built databases via Zenodo.

You can obtain pre-built databases Zenodo as shown from the following table. In the case that you need is missing, please start a Github discussion.

Note: RefSeq* = RefSeq with curated / NM_ transcript only and excluding XM_ transcripts that are based on gene predictions.

Note that files are compatible with both the NCBI and the UCSC genomes. E.g., the files for hg19 are compatible with the UCSC hg19 FASTA file and the GRCh37 files (e.g., hs37/hs37d5).

Database Compatibility

Jannovar database .ser files are compatible within a given version range with respect to the Jannovar version. The following table lists the compatibility.

Developer Guidelines

Style

• Java code should follow IntelliJ default formatting and the Ctrl+Alt+l formatter. Eclipse users please use Eclipse Code Formatter. Enable the "wrap at right margin" option for JavaDoc.
• For all other text, use .editorconfig.

Building Transcript Databases

For building Jannovar transcript database files (with .ser extension), you will need files from various sources. These include the actual transcript databases from RefSeq, ENSEMBL, UCSC etc. But you will also helper files for mapping between gene names and symbols from HGNC and information regarding contig sequence identifiers from NCBI. It turned out that the upstream locations are unstable so we resolved in uploading the files to Zenodo as this offers stable identifiers. At the same time, this create challenges in versioning as, e.g., UCSC regularly publishes updates without giving out versions.

Downloading Raw Data Files

The script ./utils/download-raw.sh contains scripts to download raw data files from the original "upstream" locations. The files will go into ./data (ignored via .gitignore). The top level file directory is ./data/raw/bwa.3430-N1-DNA1-WGS1.bam.7z/ which contains the raw data files for building the database of name ${database}, in variant ${_variant} (e.g., refseq_curated) that for a given release and genome build. Everything below this will follow specific requirements of the given data base. The download-raw.sh script may also directly download data from Zenodo where applicable.

The script ./utils/gen-zenodo-raw.sh will prepare the previously downloaded raw data for upload to Zenodo. The files will go to ./data/zenodo-raw. Zenodo does not support folders so we fall back to introducing -- as flat file separators. Note well that uploading files twice to Zenodo just takes space on their storage systems and we don't have any mechanism in place to remove duplicates.

Building Databases

The script ./utils/build-dbs.sh will generate the databases for the current Jannovar version. The files will go into ./data/jannovar-data-${jannovar_version}. These files can also go to Zenodo. For now, we will curate links to the files in the README.md file for each version. Note that not each Jannovar version will require rebuilding the databases. The currently needed latest version is given in JannovarDataSerializer.minVersion. Upload to Zenodo and curation of databases is currently manual work.