Installation is as follows.
- Ensure a java runtime and java compiler are installed.
- Use "git clone", or any other means, to copy the repository from http://github.org/semitrivial/owlkb
- Within the directory containing the copy of the repository, expand OWLKB's dependencies using "jar -xf dep.jar"
- Within the directory containing the copy of the repository, compile OWLKB using "make" (or on Windows: "javac -g Owlkb.java")
- 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
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.
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
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.
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.
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.
API Quick Nav
Finds all subterms of the indicated term. For example, "amino acid" is a subterm of "acid".
Finds all the direct parents (i.e., the direct superclasses) of the indicated term.
Finds all the direct children (i.e., the direct subclasses) of the indicated term.
Finds all siblings of the indicated term. A 'sibling' is defined to be an immediate subterm of an immediate superterm of the indicated term.
Finds all subterms of the indicated term, and displays them in a hierarchical format (using JSON).
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).
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.
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.)
Finds all labels annotated to the indicated term (specifically, all rdfs:label's). For example, the label "Brain" is annotated to FMA_50801.
Finds all classes in the ontology with the given label (specifically, the given rdfs:label). Note that this is an exact, case-sensitive search--a search for "Brai" or "brain" will not return "Brain" for instance.
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).
There are three ways to coerce data into JSON format:
Include an URL paramater 'json'.
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).
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"
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.
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):
- All things that are GO_0000111 and part-of some GO_0000112:
- All things that are (GO_0000111 intersect GO_0000112) and part-of some GO_0000113:
- All things that are GO_0000111 and part-of some (GO_0000112 intersect GO_0000113):