OWLKB 2.0 Documentation


About

» Quickjump to API section

OWLKB 2.0 is the Ricordo semantic reasoner server. It provides an API for querying semantic data which is loaded from an ontology. OWLKB is smart enough to know the semantic meanings of the terms in the ontology and to act accordingly.

Simple example: Suppose the ontology says widget X was created at factory Y, and that factory Y only creates blue widgets. A query for "show all blue widgets" will show X even if the ontology does not explicitly say that X is blue: the reasoner is smart enough to deduce the blueness of X from the other two facts.
The original OWLKB 1.0 was programmed by Sarala Wimalaratne. The current version was programmed by Samuel Alexander.

License

        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
      

Quick Nav


Installation

Installation is as follows.

  1. Ensure a java runtime and java compiler are installed.
  2. Use "git clone", or any other means, to copy the repository from http://github.org/semitrivial/owlkb
  3. Within the directory containing the copy of the repository, expand OWLKB's dependencies using "jar -xf dep.jar"
  4. Within the directory containing the copy of the repository, compile OWLKB using "make" (or on Windows: "javac -g Owlkb.java")
  5. Within that directory, run "java Owlkb.java -help" to get help on the command line arguments, or see further below.

Loading an ontology

OWLKB loads ontologies in .owl form; we assume the user has an owlfile on their system. When running OWLKB, one should specify the location of the desired .owl file. This is done using the -file commandline argument.

For example: java Owlkb -file /home/ontologies/ricordo.owl

Commandline arguments

OWLKB can be run with the following commandline arguments.

  • -file <location of file>: Specifies which ontology file OWLKB will load.
  • -port <port number>: Specifies which port OWLKB will listen on (default: 20080).
  • -reasoner <elk or hermit>: Specifies which reasoner OWLKB will use. Currently supported: Elk, HermiT
  • -namespace <base of iri>: Specifies the namespace to be used for classes created with OWLKB.
  • -save <true or false>: Specifies whether or not OWLKB saves new classes to harddrive (default: true).
  • -help: Displays a help screen.

Simple GUI

OWLKB comes with a simple GUI. When OWLKB is running, the GUI can be accessed at http://localhost:20080/gui/ (replace "localhost" with whatever host you're running OWLKB on, and replace "20080" with whatever port your OWLKB is running on, if necessary). For example, the demonstration instance of OWLKB is running on host open-physiology.org on port 20080, so the GUI is at http://open-physiology.org:20080/gui

Please Note

The built-in GUI is mainly just for demonstration purposes. We anticipate OWLKB will mainly be used directly via the API.

KBCaller Java Library

If you are wanting to incorporate OWLKB into your own Java project, we're sorry to say OWLKB is not designed as a library. There's a good reason for this: OWLKB is rather resource-intensive when loaded with a non-trivial ontology. Thus it makes more sense as a separate process than as a library.

Nevertheless, we've created KBCaller.java, a library which abstracts the act of sending an HTTP API request to OWLKB. For details, see KBCaller Documentation.

Mailing List

There is an OWLKB-Questions mailing list, where you can feel free to ask questions, general or technical. The list is located at http://groups.google.co.uk/d/forum/owlkb-questions.


The API

OWLKB launches a server which listens for connections and responds to the following types of requests.

Note: The "eqterms" type of request is special. Unlike the other commands, "eqterms" will actually create a new class and add it to the selected ontology, if no equivalent class already exists. This is one of the main features of OWLKB, creation of so-called composite terms.

subterms

Example: http://localhost:20080/subterms/CHEBI_33709

Finds all subterms of the indicated term. For example, "amino acid" is a subterm of "acid".

parents

Example: http://localhost:20080/parents/CHEBI_33709

Finds all the direct parents (i.e., the direct superclasses) of the indicated term.

children

Example: http://localhost:20080/children/CHEBI_33709

Finds all the direct children (i.e., the direct subclasses) of the indicated term.

siblings

Example: http://localhost:20080/siblings/CHEBI_33709

Finds all siblings of the indicated term. A 'sibling' is defined to be an immediate subterm of an immediate superterm of the indicated term.

subhierarchy

Example: http://localhost:20080/subhierarchy/CHEBI_33709

Finds all subterms of the indicated term, and displays them in a hierarchical format (using JSON).

eqterms

Example:
http://localhost:20080/eqterms/CL_0000548+and+(capable_of+some+GO_0022414)

Finds all terms equivalent to the indicated term. For example, the class of all "animal cells" (CL_0000548) capable of some "reproductive process" (GO_0022414) is equivalent to the class of all "germ line stem cells" (CL_0000039).

» If there are no equivalent terms, a new class is created, defined to be equivalent to the indicated term. The new class is saved to the ontology (unless saving to hard-drive was disabled by command-line argument).

terms

Example:
http://localhost:20080/terms/CL_0000548+and+(capable_of+some+GO_0022414)

Finds all terms and all subterms of the indicated term. Note that unlike "eqterms", this API command will not create a new class if no equivalent classes are found.

instances

Example: http://localhost:20080/instances/TYPE-OF-CLINICAL-CONTEXT

Finds all instances of the indicated class. For example, "IN-VITRO-CCTYPE" might be an instance of "TYPE-OF-CLINICAL-CONTEXT". (This is, of course, only for ontologies that include named individuals; otherwise "instances" will always return the empty result set.)

labels

Example: http://localhost:20080/labels/FMA_50801

Finds all labels annotated to the indicated term (specifically, all rdfs:label's). For example, the label "Brain" is annotated to FMA_50801.

addlabel

Example: http://localhost:20080/addlabel/RICORDO12345=volume+of+blood+in+aorta

Adds a label to a class that was created with "eqterms". For syntax, see the example above. To be more precise, the label which is added is an <rdfs:label>. Multiple labels can be added for a single class. This command triggers OWLKB to save changes to the ontology to the hard drive (unless saving has been disabled via command line).

JSON

There are three ways to coerce data into JSON format:

  1. Include an URL paramater 'json'.
    Example: http://localhost:20080/subterms/FMA_50801?json
  2. Include an URL parameter 'verbose'. In addition to changing the command output to json, this also causes the command to send additional information (most importantly, it will send labels along with terms).
    Example: http://localhost:20080/siblings/FMA_50801?verbose
  3. Send a request header "Accept: application/json". This has the same effect as method number 1 from above.
    Example: curl --header "Accept: application/json" "http://localhost:20080/subterms/CHEBI_33709"

Verbose Results

Because of backward-compatibility considerations, the default form of OWLKB results is sparse (including nothing but raw terms in most cases, whereas the user is probably interested in the labels of those terms as well). In order to get labels along with terms, use the 'verbose' URL parameter. Note: this will also coerce the results into JSON format.

Example: http://localhost:20080/subterms/CHEBI_33709?verbose

Manchester Syntax

The strength of OWLKB is that in all the API commands where a term is expected, a compound term can be indicated using Manchester Syntax. Of course, when passing Manchester Syntax in an URL, it should be urlencoded. Here are some examples of Manchester Syntax (we've replaced spaces with +'s so these examples can be used in URLs):

  • All subclasses of (GO_0000111 intersect GO_0000112):
    "GO_0000111+and+GO_0000112"
  • All things that are GO_0000111 and part-of some GO_0000112:
    "GO_0000111+and+part-of+some+GO_0000112"
  • All things that are (GO_0000111 intersect GO_0000112) and part-of some GO_0000113:
    "(GO_0000111+and+GO_0000112)+and+part-of+some+GO_0000113"
  • All things that are GO_0000111 and part-of some (GO_0000112 intersect GO_0000113):
    "GO_0000111+and+part-of+some+(GO_0000112+and+GO_0000113)"
  • etc.