Setting up maxodiff
MaxoDiff can be run from the command-line or as a Web application.
Prerequisites
maxodiff is a Java application. If you want to build maxodiff from source, then the build process described below requires Git and Java Development Kit (JDK) 21 or newer.
Installing maxodiff
Building from sources
To build maxodiff from sources, go the GitHub page of maxodiff, and clone or download the project, then build the executable JAR files from sources with Maven:
We use the Maven Wrapper for building the sources, so installation of Maven prior to build is not required.
Download resources
We can download the resource files needed by maxodiff by running the download command
of the CLI JAR:
The command will download the data files into data folder that will be created in the current working directory.
See the command's documentation for more options.
This command will automatically create the MICA dictionary with the latest downloaded files.
MICA dictionary
To run maxodiff with Phenomizer, we must first generate a file that contains the
most informative common ancestors for pairs of HPO terms. See the class IcMicaDictLoader.
maxodiff uses the Phenomizer algorithm to calculate the differential diagnosis; see the original publication for details: Clinical diagnostics in human genetics with semantic similarity searches in ontologies
To run this algorithm, we require
the information content of the most informative common ancestor (MICA) for
every pair of terms. It is more efficient to precalculate this using the
following command. By default, the command will look for the input files hp.json
and phenotype.hpoa in the datafolder, which is created by the download command.
The file will have been generated automatically by the download command. If you would like to regenerate the file, please enter the following command.
On a modern commodity laptop, this command will require a few minutes to complete. By default, the output file will be created here. Currently, it occupies 117 Mb.Start Maxodiff web app
The web app can be started as:
If a Java heap space error occurs, more memory can be allocated by adding VM options:
By default, the app will serve requests at http://localhost:8080/maxodiff.
Troubleshooting
Connection refused
The error Connection refused might be a sign that you need to set proxy settings.
If ./mvnw clean package produces a connect exception, run export MAVEN_OPTS="-Dhttp.proxyHost=xxx -Dhttp.proxyPort=8080 -Dhttps.proxyHost=xxx -Dhttps.proxyPort=8080" (with your own proxy settings) in advance.
If java -jar maxodiff-cli/target/maxodiff-cli.jar downloadproduces a connect exception, try java -Dhttp.proxyHost=xxx -Dhttp.proxyPort=8080 -Dhttps.proxyHost=xxx -Dhttps.proxyPort=8080 -jar maxodiff-cli/target/maxodiff-cli.jar download (with your own proxy settings) instead.
Running out of memory
If java -jar maxodiff-html/target/maxodiff-html.jar stalls for a long time at Loading Maxodiff resources from xxx before failing, try giving java more heap space (in this example 12GB) with -Xmx12G, i.e. java -Xmx12G -jar maxodiff-html/target/maxodiff-html.jar.
Port already in use
If you try to start the Webserver and see an error like this:
***************************
APPLICATION FAILED TO START
***************************
Description:
Web server failed to start. Port 8080 was already in use.
Then enter the following (adjust the port if needed)
This will indicate the process id of the process (