• The Exomiser
  • Software and Hardware requirements
  • Installation
    • Windows
    • Linux
  • Genomiser data files
  • Usage
  • Troubleshooting
  • Running Exomiser with Docker
    • Working with the distroless image (no shell)
    • Working with the Docker bash images

The Exomiser is a tool to perform genome-wide prioritisation of genomic variants including non-coding and regulatory variants using patient phenotypes as a means of differentiating candidate genes.

To perform an analysis, Exomiser requires the patient's genome/exome in VCF format and their phenotype encoded in HPO terms. The exomiser is also capable of analysing trios/small family genomes, so long as a pedigree in PED format is also provided. See Usage section for info on running an analysis.

The most up-to-date information can be found in the online documentation.

• For exome analysis of a 30,000 variant sample 4GB RAM should suffice.
• For genome analysis of a 4,400,000 variant sample 12GB RAM should suffice.
• Any 64-bit operating system
• Java 21 or above
• At least 50GB free disk space (SSD preferred for best performance)
• An internet connection is not required to run the Exomiser, although network access will be required if accessing a networked database (optional).
• By default the Exomiser is completely self-contained and is able to run on standard consumer laptops.

1. Install 7-Zip (http://www.7-zip.org) for unzipping the archive files. The built-in archiving software has issues extracting the zip files.
2. Download the data and distribution files from https://data.monarchinitiative.org/exomiser/latest
3. Extract the distribution files by right-clicking exomiser-cli-${project.version}-distribution.zip and selecting 7-Zip > Extract Here
4. Extract the data files (e.g. ${phenotype.data.version}_phenotype.zip, ${genome.data.version}_hg19.zip) by right-clicking the archive and selecting 7-Zip > Extract files... 4.1 Extract the files to the exomiser data directory. By default exomiser expects this to be exomiser-cli-${project.version}/data, but this can be changed in the application.properties
5. cd exomiser-cli-${project.version}
6. java -Xms2g -Xmx4g -jar exomiser-cli-${project.version}.jar analyse --analysis examples/test-analysis-exome.yml

The following shell script should work-

# download the distribution (won't take long)
wget https://data.monarchinitiative.org/exomiser/latest/exomiser-cli-${project.version}-distribution.zip
# download the data (this is ~20GB and will take a while)
wget https://data.monarchinitiative.org/exomiser/latest/${genome.data.version}_hg19.zip
wget https://data.monarchinitiative.org/exomiser/latest/${genome.data.version}_hg38.zip
wget https://data.monarchinitiative.org/exomiser/latest/${phenotype.data.version}_phenotype.zip

# unzip the distribution and data files - this will create a directory called 'exomiser-cli-${project.version}' in the current working directory
unzip exomiser-cli-${project.version}-distribution.zip
unzip ${genome.data.version}_*.zip -d exomiser-cli-${project.version}/data

# Check the application.properties are pointing to the correct versions:
#  exomiser.hg19.data-version=${genome.data.version}
#  exomiser.hg38.data-version=${genome.data.version}
#  exomiser.phenotype.data-version=${phenotype.data.version}

# run a test exome analysis
cd exomiser-cli-${project.version}
java -jar exomiser-cli-${project.version}.jar analyse --analysis examples/test-analysis-exome.yml

This script will download, verify and extract the exomiser files and then run the analysis contained in the file 'test-analysis-exome.yml' from the examples sub-directory. This contains a known pathogenic missense variant in the FGFR2 gene.

In order to run the Genomiser you will also need to download the REMM data file from here. Once downloaded you'll need to add the path to the ReMM.v0.3.1.tsv.gz file to the application.properties file. For example if you downloaded the file to the exomiser data directory you could add the entry like this:

exomiser.hg19.remm-path=${exomiser.hg19.data-directory}/ReMM.v0.3.1.tsv.gz

If this step is omitted, the application will throw and error and stop any analysis which defines REMM in the pathogenicitySources section of an analysis yml file.

Having done this, run the analysis like this:

java -Xmx6g -jar exomiser-cli-${project.version}.jar analyse --analysis examples/NA19722_601952_AUTOSOMAL_RECESSIVE_POMP_13_29233225_5UTR_38.yml 

This is an analysis for an autosomal recessive 5'UTR variant located in POMP gene on chromosome 13. The phenotype HPO terms are taken from the clinical synopsis of OMIM #601952 (http://www.omim.org/clinicalSynopsis/601952)

If you want to run Exomiser using data from a different release directory edit the line in application.properties:

exomiser.data-directory=

with

exomiser.data-directory=/full/path/to/alternative/data/directory

If you're running the Exomiser from a different directory to the one the exomiser-cli-${project.version}.jar is located you'll need to add the command

--spring.config.location=/full/path/to/your/exomiser-cli/directory

to the end of your command-line arguments. n.b. the spring.config.location command must be the last argument in the input commands

The Exomiser can be run via simply via a yaml analysis file. The extended cli capability was removed in version 10.0.0 as this was less capable than the yaml scripts and only supported hg19 exome analysis.

Analysis files contain all possible options for running an analysis including the ability to specify variant frequency and pathogenicity data sources and the ability to tweak the order that analysis steps are performed.

See the test-analysis-exome.yml and test-analysis-genome.yml files located in the base install directory for details.

java -Xmx4g -jar exomiser-cli-${project.version}.jar analyse --analysis examples/test-analysis-exome.yml

These files can also be used to run full-genomes however, they will require substantially more RAM to do so. For example a 4.4 million-variant analysis requires approximately 12GB RAM. However, RAM requirements can be greatly reduced by setting the analysisMode option to PASS_ONLY. This will also aid your ability to evaluate the results.

Analyses can be run in batch mode. Simply put the path to each analysis file in the batch file - one file path per line.

java -Xmx4g -jar exomiser-cli-${project.version}.jar batch examples/test-analysis-batch.txt

If you're running the exomiser from a different directory to the one the jar file is located in, you will need to specify the path to the application.properties file in the start-up command. For example:

 java -Xmx4g -jar $path_to_exomiser/exomiser-cli-${project.version}.jar analyse --analysis $path_to_exomiser/examples/test-analysis-exome.yml --spring.config.location=$path_to_exomiser/application.properties

java -jar exomiser-cli-${project.version}.jar --help

If you get the following error message:

Exception in thread "main" java.lang.UnsupportedClassVersionError:
org/monarchinitiative/exomiser/cli/Main : Unsupported major.minor version

You are running an older unsupported version of Java. Exomiser requires Java version 17 or higher. This can be checked by running:

java -version

You should see something like this in response:

openjdk version "11.0.11" 2021-04-20
OpenJDK Runtime Environment (build 11.0.11+9-Ubuntu-0ubuntu2.20.04)
OpenJDK 64-Bit Server VM (build 11.0.11+9-Ubuntu-0ubuntu2.20.04, mixed mode, sharing)

versions lower than 17 (e.g. 1.5, 1.6, 1.7, 1.8, 9, 10, 11...) will not run exomiser, so you will need to install the latest LTS Java version. We recommend using the Eclipse Temurin Java releases which you can find here: https://adoptium.net/

If, when running 'unzip exomiser-cli-${project.version}-distribution.zip', you see the following:

error:  Zip file too big (greater than 4294959102 bytes)
Archive:  exomiser-cli-${project.version}-distribution.zip
warning [exomiser-cli-${project.version}-distribution.zip]:  9940454202 extra bytes at beginning or within zipfile
  (attempting to process anyway)
error [exomiser-cli-${project.version}-distribution.zip]:  start of central directory not found;
  zipfile corrupt.
  (please check that you have transferred or created the zipfile in the
  appropriate BINARY mode and that you have compiled UnZip properly)

Check that your unzip version was compiled with LARGE_FILE_SUPPORT and ZIP64_SUPPORT. This is standard with UnZip 6.00 and can be checked by typing:

unzip -version

This shouldn't be an issue with more recent linux distributions.

Pre-built docker images can be found on docker hub. Here you can find images built for most common architectures as a distroless image or with a bash shell.

The build process will not create a Docker image by default, unless specified. However, if you choose to create a Docker container, you may select either the docker:distroless (no shell) or docker:bash (with shell) profiles.

We employ multi-arch builds as part of our Docker image creation process to ensure compatibility with a wide range of system architectures. To assist you in selecting the appropriate image for your system, we provide a table below that lists the supported architectures for each Docker image.

If a Docker image is not required, we suggest using the following command to build the exomiser-cli without:

mvn clean install

Alternatively, you may provide a Docker repositoryName (e.g. dockerhub username) to push the image directly to your repository. Afterwards you can access the image by pulling it from the Docker hub. To properly specify repository settings during the Maven building process, use the following example:

mvn clean install -P <profileID> -Ddocker.repository=<repositoryName>

It is important to note that if an authentication issue arises, it may be necessary to update the .docker/config.json file to include authentication for https://index.docker.io/v1/. This can be done by providing your base64-encoded Docker credentials.

Docker images are built using jib which does not require a Docker daemon to be running/installed to build an image.

$ docker pull ${docker.registry}/${docker.repository}/exomiser-cli:${project.version}
$ docker images
REPOSITORY                       TAG              IMAGE ID      CREATED         SIZE
${docker.repository}/exomiser-cli           latest           f39698e3f36b  53 years ago   274 MB
${docker.repository}/exomiser-cli           ${project.version} f39698e3f36b  53 years ago   274 MB

Exomiser requires data directory and version configuration. The Docker images include a preconfigured environment variable EXOMISER_DATA_DIRECTORY=/exomiser-data.

Option 1: Set environment variables directly

-e EXOMISER_HG19_DATA_VERSION=2512 \
-e EXOMISER_PHENOTYPE_DATA_VERSION=2512

Option 2: Use an application.properties file Mount your file and point Spring to it: application.properties

-v /path/to/application.properties:/config/application.properties \
-e SPRING_CONFIG_LOCATION=/config/application.properties

Exomiser provides two image types:

• Distroless (default): Minimal security-hardened image without a shell. Tagged as :latest or :${project.version}
• Bash: Includes a shell for interactive use, required for NextFlow. Tagged as :latest-bash or :${project.version}-bash

Both image types require mounting three directories:

-v "/host/path/to/exomiser-data:/exomiser-data"  # Contains unpacked data directories like 2512_hg19
-v "/host/path/to/exomiser-cli/examples/:/examples"            # Analysis files and test data
-v "/host/path/to/results:/results"              # Output directory for results

Example data directory structure:

exomiser-data/
├── 2512_hg19/
└── 2512_phenotype/

Pull the image:

docker pull ${docker.registry}/${docker.repository}/exomiser-cli:${project.version}

Run Exomiser (the exomiser command is the entrypoint, so pass arguments directly):

docker run \
-v "/host/path/to/exomiser-data:/exomiser-data" \
-v "/host/path/to/exomiser-cli/examples/:/examples" \
-v "/host/path/to/results:/results" \
-e EXOMISER_HG19_DATA_VERSION=2512 \
-e EXOMISER_PHENOTYPE_DATA_VERSION=2512 \
${docker.repository}/exomiser-cli:${project.version} \
analyse --analysis /examples/preset-exome-analysis-human-only.yml \
--vcf /examples/Pfeiffer.vcf.gz --assembly hg19 \
--sample /examples/pfeiffer-phenopacket.yml \
--output-directory /results --output-format=PARQUET --output-filename docker-test

Working with the bash image Pull the image:

docker pull ${docker.registry}/${docker.repository}/exomiser-cli:${project.version}-bash

Start an interactive shell:

docker run -it \
 -v "/host/path/to/exomiser-data:/exomiser-data" \
 -v "/host/path/to/exomiser-cli/examples/:/examples" \
 -v "/host/path/to/results:/results" \
 -e EXOMISER_HG19_DATA_VERSION=2512 \
 -e EXOMISER_PHENOTYPE_DATA_VERSION=2512 \
 ${docker.repository}/exomiser-cli:${project.version}-bash

From the bash prompt, run Exomiser:

exomiser analyse --analysis /examples/preset-exome-analysis-human-only.yml \
--vcf /examples/Pfeiffer.vcf.gz --assembly hg19 \
--sample /examples/pfeiffer-phenopacket.yml \
--output-directory /results --output-format=PARQUET --output-filename docker-test

If successful, results will be written to /results/docker-test.parquet.