JPhyloRef is a Java-based command line tool as well as a web service for reasoning with OWL ontologies containing phyloreferences and their accompanying reference phylogenetic trees. JPhyloRef has been published in The Journal of Open Source Software, which should be cited when this tool is reused.
JPhyloRef has two main goals:
- The primary one is to facilitate automated testing that the semantics of the logical definitions imply ("resolve to") the correct nodes in the reference tree as clade ancestors. This is key in supporting quality control for the digitization of clade definitions from natural language text to a structured machine-interpretable representation. It also verifies that one of the theoretical foundational premises of phyloreferences, computational reproducibility, holds in practice.
- The secondary goal is to enable integration with external tools that need to obtain the clade ancestor node(s) resulting from a given ontology of phyloreferences and reference tree(s). When run as part of an automated testing workflow, JPhyloRef reports test results in the cross-platform Test Anything Protocol format. When used to find clade ancestor nodes implied by logical clade definitions, results are returned as a JSON object. JPhyloRef uses the OWL API reference library for reading Web Ontology Language (OWL) ontologies, and for the actual ontology reasoning step it uses an external and configurable OWL reasoner.
JPhyloRef wraps the ELK reasoner and provides three ways in which it can be used to resolve phyloreferences:
java -jar jphyloref.jar resolve input.owl: Resolves phyloreferences in
input.owland returns the nodes they resolve to in a JSON document.
java -jar jphyloref.jar webserver: Starts a webserver that accepts ontologies for reasoning and provides the result as a JSON document.
- Requests should be sent via POST to the
/reasonendpoint as an HTML form submission. The form can contain the ontology as a file upload in the
jsonldFileelement or as a string in the
jsonldelement. We will return a response in JSON with the results of the reasoning or with an error message.
- You can also use the
/versionendpoint to test whether the software is working. It will report on the version of JPhyloRef, OWLAPI and reasoner being used.
- Note that no content is served at
/; you will need to use
/versionto test that the server is running.
- Requests should be sent via POST to the
java -jar jphyloref.jar test input.owl: Test all the phyloreferences in
input.owlby comparing their resolution with the expected resolution recorded in the file.
Detailed usage instructions are included in the JPhyloRef Usage document. Documentation of the source code is included as Javadoc comments, which are also available online at javadoc.io.
Command line options
Many command line options can be used for all included commands:
-jcan be used to interpret the input file as a JSON-LD file rather than an RDF/XML file (resolve or test only).
-hcan be used to set the hostname that the webserver should listen on (webserver only).
--port [port number]or
-pcan be used to set the port that the webserver should listen on (webserver only).
--reasoner [name]can be used to set the reasoner to use. The following reasoners are supported:
- Elk 0.4.3 (
elk) is an OWL 2 EL reasoner. Other reasoners for the OWL-EL profile may work but have not been tested. OWL-DL reasoners have been found to have insufficient performance.
- Elk 0.4.3 (
Development of JPhyloRef takes place in our GitHub repository. This includes an issue tracker for reporting any bugs you find or requesting any features you need. We welcome any pull requests to add additional features, tests or documentation. All new pull requests are tested with a continuous testing workflow.
Build and execution instructions
You will need Java and Apache Maven to build the software from source. We recommend installing these
tools using a package manager, such as Homebrew on macOS. You can use jEnv instead if you want to install
multiple Java versions on the same computer. Installation should set up the
variable; if not, you will need to set it to point at the directory containing your Java installation.
Once you have downloaded the source code to your computer, you can compile and test the code by running
JPhyloRef can be built from source by running
mvn package from the root directory of this repository. This will create a JAR file in the
target/ directory, which can be executed by running,
$ java -jar target/jphyloref-1.2.0-SNAPSHOT.jar test src/test/resources/phylorefs/dummy1.owl
1.2.0 should be replaced by the correct version number -- look for the
Building JPhyloRef N.M.K-SNAPSHOT line in the output from
mvn package, where N.M.K is the version, such as 1.2.0)
You can also download any published version of this software directly from Maven at https://search.maven.org/artifact/org.phyloref/jphyloref.
If you have Coursier installed, you can download and run JPhyloRef in one step by running:
$ coursier launch org.phyloref:jphyloref:1.1.1 -- test input.owl
Hosting a server with Webhook
JPhyloRef can be set up on a SLURM cluster using Webhook, allowing jobs to be executed on a separate computer from the web server.
Publishing to Sonatype OSSRH
To publish this package to the Sonatype OSSRH, we follow the workflow detailed on the Sonatype website. Note that you will need to set up a Maven settings.xml file with your GPG settings in order to sign the package for publication.
Once you're set up, you can run
mvn clean deploy to publish the package
to the OSSRH. If your version number ends in
-SNAPSHOT, this will be
published to the OSSRH Snapshots repository.