Setting up LIRICAL

LIRICAL is a desktop Java application that requires several external files to run. This document details how to download these files and prepare to run LIRICAL. LIRICAL requires Exomiser to be installed as a library before it can be compiled and built.

Prerequisites

LIRICAL was written with Java version 17 but will compile under Java 17 or better. If you want to build LIRICAL from source, then the build process described below requires Git and Java Development Kit 17 or better.

Note

The v1 of LIRICAL was written in Java 8 but starting from v2 we require Java 17 or better to take advantage of the novel Java features.

Prebuilt LIRICAL executable

Most users should use the prebuilt LIRICAL executable. LIRICAL is distributed as a ZIP archive that contains the executable JAR file, the libraries, and a few files for running the examples. The archive is available from the Releases section on the GitHub repository.

Assuming the distribution file was downloaded to lirical-cli-2.0.3-SNAPSHOT-distribution.zip, the following will print the help message:

unzip lirical-cli-2.0.3-SNAPSHOT-distribution.zip
java -jar lirical-cli-2.0.3-SNAPSHOT/lirical-cli-2.0.3-SNAPSHOT.jar --help

Building from sources

Alternatively, LIRICAL can also be built from sources. Assuming JDK 17 or better is available in the environment, the build is as simple as running:

git clone https://github.com/TheJacksonLaboratory/LIRICAL.git
cd LIRICAL
./mvnw -Prelease package

The code first clones LIRICAL repository and then runs the amazing Maven Wrapper for building the application, so prior installation of Maven is not required.

During the build, Maven compiles the LIRICAL code into an executable Java archive (JAR) file and assembles the entire application into the distribution ZIP archive. The archive is stored at lirical-cli/target subdirectory and it is the same archive that you can obtain from Github releases.

Note

Building from sources is not necessary for a typical LIRICAL use. Use the Prebuilt LIRICAL executable unless you really really need to build the app yourself.

Building to use as a library

In some rare cases, LIRICAL code needs to be available as a library to another applications. To make LIRICAL ready for use as a library, we need to run:

git clone https://github.com/TheJacksonLaboratory/LIRICAL.git
cd LIRICAL
./mvnw -Prelease install

This is almost the same as building from sources done in the previous section. However, running install instead of package will copy the LIRICAL JARs into the local Maven repository, making it available for other applications.

Note

Building to use as a library is not necessary for a typical LIRICAL use. Use the Prebuilt LIRICAL executable unless you really, really, really need to use LIRICAL as a library.

Set up alias

In general, Java command line applications are invoked as java -jar executable.jar. However, such incantation is a bit too verbose and we can shorten it a bit by defining an alias.

Let’s define a command alias for LIRICAL. Assuming the distribution ZIP was unpacked into phenopacket-tools-cli-2.0.3-SNAPSHOT directory, run the following to set up and check the command alias:

alias lirical="java -jar $(pwd)/lirical-cli-2.0.3-SNAPSHOT/lirical-cli-2.0.3-SNAPSHOT.jar"
lirical --help

Note

From now on, we will use the lirical alias instead of the longer form.

Exomiser database files

LIRICAL uses data files from the Exomiser to annotate the VCF file and support variant interpretation. We recommend that always the latest version of these files be used. The Exomiser data files can be obtained from the Exomiser download site. You may need to scroll (right hand side) to see the subdirectory latest, which includes the current version of these files. Download either 2302_hg19.zip (for the hg19/GRCh37 genome assembly) or 2302_hg38.zip for the hg38/GRCh38 assembly). Of course, the datafile you use should match the assembly used to align and call the exome/genome data you want to analyze with LIRICAL.

Note

LIRICAL was tested for compatibility with 2302 Exomiser data version.

Unpack the ZIP file, e.g.:

unzip 2302_hg19.zip

LIRICAL uses the variant database file that is present in the data folder. The database file is named as <release>_<genome-build>_variants.mv.db, where

  • release is the release identifier (e.g. 2302)

  • genome-build is the identifier of the genome build (e.g. hg38)

Remember the path, since it will be needed to run LIRICAL with exome/genome data. We will use the CLI options:

  • -e19 | --exomiser-hg19 /some/path/2302_hg19_variants.mv.db, or

  • -e38 | --exomiser-hg38 /some/path/2302_hg19_variants.mv.db

to set path to the Exomiser variant database.

Note

The -e option that used to point to Exomiser data directory in the previous LIRICAL has been deprecated and will not work in v2.

LIRICAL data files

LIRICAL requires some additional files to run.

  1. hp.json. The main Human Phenotype Ontology file

  2. phenotype.hpoa The main annotation file with all HPO disease models

  3. hgnc_complete_set.txt A text file from HUGO Gene Nomenclature Committee (HGNC) with information about human genes

  4. mim2gene_medgen A file from the NCBI medgen project with OMIM-derived links between genes and diseases

  5. Jannovar transcript annotation files with definitions of transcripts and genes:

  • hg19_refseq.ser

  • hg19_ucsc.ser

  • hg38_refseq.ser

  • hg38_ucsc.ser

LIRICAL offers a convenience function to download all files to a local directory. By default, LIRICAL will download all files into a newly created subdirectory called data in the current working directory. You can change this default with the -d or --data options (If you change this, then you will need to pass the location of your directory to all other LIRICAL commands using the -d flag).

Download the files into the data folder located next to the LIRICAL JAR file by running:

cd lirical-cli-2.0.3-SNAPSHOT
lirical download

This will ensure LIRICAL finds the data folder automatically (see below).

Note

We assume the LIRICAL alias was set as described in the Set up alias section.

LIRICAL will not download the files if they are already present unless the --overwrite argument is passed. For instance, the following command would download the four files to a directory called datafiles and would overwrite any previously downloaded files:

lirical download -d datafiles --overwrite

If desired, you can download these files on your own but you need to place them all in the same directory and provide the path to the directory using the -d | –data option.

The path to the LIRICAL data directory can be provided in two ways:

  1. explicitly, using -d | --data option

  2. implicitly, if the data folder is located next to the LIRICAL JAR file