Skip to content

Latest commit

 

History

History
106 lines (85 loc) · 5.15 KB

Usage.md

File metadata and controls

106 lines (85 loc) · 5.15 KB
Raw

JPhyloRef Usage

Some example phyloreferences are included as part of the test suite. They can be found in the examples directory, and are tested as part of the test suite included with this package. You can try these out yourself by setting up Apache Maven and running:

$ mvn clean package

This will create target/JPhyloRef-${version}.jar. You can run this using Java. For example, and assuming a version number of 1.1.0-SNAPSHOT, the following command will provide a comprehensive list of command line options for JPhyloRef.

$ java -jar target/JPhyloRef-1.1.0-SNAPSHOT.jar

You can test one of the example files by running:

$ java -jar target/jphyloref-1.1.0-SNAPSHOT.jar test src/test/resources/phylorefs/dummy1.owl > output.txt
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Input: src/test/resources/phylorefs/dummy1.owl
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Found local ontologies: []
(...logs and warnings generated by the Elk reasoner are displayed here...)
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Phyloreferences identified: [<#phyloref0>]
Testing complete:1 successes, 0 failures, 0 failures marked TODO, 0 skipped.

A more detailed description of the test results is written out on the standard output. In this example, this is written to output.txt in the Test Anything Protocol (TAP) format.

1..1
# From file: src/test/resources/phylorefs/dummy1.owl
# Using reasoner: null/0.0.0.0
ok 1 Phyloreference '1'
# Expected nodes: [#phylogeny0_node2]
# Resolved nodes: [#phylogeny0_node2]

This indicates that the phyloreference labeled '1' resolved to node #phylogeny0_node2, which was annotated to indicate that this is where this phyloreference was expected resolve. Thus, it was resolved correctly.

Another example file shows how a resolution error is reported.

$ java -jar target/jphyloref-1.1.0-SNAPSHOT.jar test src/test/resources/phylorefs/failing1.jsonld > output.txt
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Input: src/test/resources/phylorefs/failing1.jsonld
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Found local ontologies: []
(...logs and warnings generated by the Elk reasoner are displayed here...)
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Phyloreferences identified: [<http://example.org/jphyloref#phyloref0>, <http://example.org/jphyloref#phyloref1>, <http://example.org/jphyloref#phyloref2>]
Testing complete:1 successes, 1 failures, 0 failures marked TODO, 1 skipped.

Once again, detailed explanations are available on standard output, here redirected to output.txt:

1..3
# From file: src/test/resources/phylorefs/failing1.jsonld
# Using reasoner: null/0.0.0.0
ok 1 Phyloreference '1'
# Expected nodes: [#phylogeny0_node2]
# Resolved nodes: [#phylogeny0_node2]
not ok 2 Phyloreference '2'
# Expected nodes: [#phylogeny0_node1]
# Resolved nodes: [#phylogeny0_node2]
# Some nodes were resolved but were not expected: [<http://example.org/jphyloref#phylogeny0_node2>]
# Some nodes were expected but were not resolved: [<http://example.org/jphyloref#phylogeny0_node1>]
not ok 3 Phyloreference '4' # SKIP Phyloreference has no expected resolution, and so cannot be tested.
# Expected nodes: []
# It resolved to the following 1 nodes: [<http://example.org/jphyloref#phylogeny0_node2>]

Here we see that one phyloreference ('1') resolved as expected, another ('2') resolved to a node other than the one it was expected to resolve to, and a third ('3') was skipped during testing, as no node had been annotated to indicate that it should resolve to it. However, phyloreference '3' did resolve unexpectedly to a node -- this is noted in the output as a suggestion that this resolution should be looked into.

Instead of testing the phyloreference, we could also ask JPhyloRef for information on which node each phyloreference resolved to:

$ java -jar target/jphyloref-1.1.0-SNAPSHOT.jar resolve src/test/resources/phylorefs/failing1.jsonld > output.json
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Input: src/test/resources/phylorefs/failing1.jsonld
[main] INFO org.phyloref.jphyloref.commands.TestCommand - Found local ontologies: []
(...logs and warnings generated by the Elk reasoner are displayed here...)

In this case, a JSON document is written to standard output (here redirected to output.json), showing which node each phyloreference resolved to.

{"phylorefs":{"#phyloref2":["#phylogeny0_node2"],"#phyloref0":["#phylogeny0_node2"],"#phyloref1":["#phylogeny0_node2"]}}

Real-world example phyloreferences can be found in the phyx.js repository. phyx.js includes a test suite that includes jphyloref.js, a Mocha-based test that uses JPhyloRef to verify that these example phyloreferences resolve as expected.