Documentation

efoimporter builds an OWL-format ontology module for the import of classes from one or more ontologies into another. It reads the import specification from file and writes the module to file. Optionally, the module can be merged with a target ontology and target classes replaced.

Description

The import of classes en masse from one ontology to another is a common ontology engineering requirement which, if done manually, can be time-consuming and error prone. efoimporter automates this task. efoimporter builds an OWL-format ontology module which can be written to file, or merged with a target ontology and then written to file. Optionally, imported class URIs will replace URIs in the target ontology.

efoimporter reads an import specification file which includes, for each class to import, the source ontology URI, source class URI and one or both of the parent class URI (the new "parent" of the imported class) and the target class URI (of the class to replace). If a source class URI already exists in the target ontology the default behaviour is to not do the import, although an import can be forced. A log file of actions taken is written.

efoimporter preserves the URI and annotations on the import class (but discards other axioms), whereas annotations on the target class (if defined) are mostly discarded (but other axioms are retained). Before using efoimporter, please read carefully the full import behaviour!



Availability

Download efoimporter from http://www.ebi.ac.uk/fgpt/sw/downloads/.



Usage (command-line tools only)

efoimporter [-h -v] [-s file] [-o file -u URI | -m file -t file -p -r -f] [-l]

efoimporter is invoked using the script build.sh. For example, to create a module of OWL classes defined in the import specification file import.spec, merge this module with the target ontology target.owl and write a new, merged ontology to merge.owl:

$ import.sh -s import.spec -m merge.owl -t target.owl

When you first use efoimporter, you must generate import.sh for your specific environment using the bundled script build.sh, which requires the path to java and efoimporter installation directory, e.g.:

$ build.sh /usr/bin/java/ /usr/local/efoimporter/

build.sh creates import.sh which you can then use.

Log file

A log file of informative messages called efoimporter.log is written in the invocation directory.

Command-line options

OptionAlternativeValueDescription
-h--helpPrint (to stdout) usage information and the bug-reporting address, then exit.
-v--verbosePrint verbose usage information.
-s--specfileRead class import specification from file.
-o--outputfileWrite module (imports) ontology to OWL-format file.
-u--uriuriSet module (imports) ontology URI to uri.
-m--mergefileWrite merged ontology (target + import module) to OWL-format file.
-t--targetfileOrUrlRead target ontology from OWL-format fileOrUrl.
-p--parentsSpecify parents (URIs of classes in the target ontology) for imported classes. The parent URIs must be specified in the import specification file.
-r--replaceReplace URIs in the target ontology with imported class URIs. The URIs to replace must be specified in the import specification file.
-f--forceForce import. Where an import class URI already exists in the target ontology, force the import. The import class annotations will replace those on the existing class, but existing class axioms will be retained.
-l--logfileLog import messages to file.

Modes of Operation

ModeDescriptionOptionDescription
Create moduleCreate stand-alone ontology module-oModule ontology file name
-uOntology URI
Merge Create merged ontology from importing classes into target ontology-mMerged ontology (target + import module) file name
-tTarget ontology file name or URL
-rSpecify parent URIs in the target ontology.
-rReplace URIs in the target ontology.
-fForce import of classes.

Exit status

The application returns the following values to the operating system:

  • (0) (Success)
  • (1) (Failure to execture or unrecoverable error)



Usage examples

To see a list of all command-line options, run efovalidator with the -h option:

usage:
efoimporter [-h -v] [-s file] [-o file -u uri | -m file -t file -p -r -f]
-f,--force Force import. Where an import class URI already
exists in the target ontology, force the import. The
import class annotations will replace those on the
existing class, but existing class axioms will be
retained.
-h,--help Print (to stdout) usage information and the
bug-reporting address, then exit.
-m,--merge file Write merged ontology (target + import module) to
OWL-format file.
-o,--output file Write module (imports) ontology to OWL-format
file.
-p,--parents Specify parents (URIs of classes in the target
ontology) for imported classes. The parent URIs must
be specified in the import specification file.
-r,--replace Replace URIs in the target ontology with imported
class URIs. The URIs to replace must be specified in
the import specification file.
-s,--spec file Read class import specification from file.
-t fileOrUrl Read target ontology from OWL-format fileOrUrl.
-u,--uri uri Set module (imports) ontology URI to uri.
-v,--verbose Print verbose usage information.

For more information, see http://www.ebi.ac.uk/fgpt/efoimporter

To create an ontology module and write it to file:

$ ./import.sh -s import.spec -o module.owl -u http://wwwdev.ebi.ac.uk/fgpt/module

To create a merged ontology (merge.owl) by importing classes into target ontology (efo_release_candidate.owl) under specific classes:

$ ./import.sh -s import.spec -m merge.owl -p -t efo_release_candidate.owl -f

To create a merged ontology (merge.owl) from importing classes into target ontology (efo_release_candidate.owl), replacing URIs in the target ontology (forcing import if necessary):

$ ./import.sh -s import_replace.spec -m merge.owl -t efo_release_candidate.owl -r -f



Notes

Creating a stand-alone module ontology

When creating a stand-alone module ontology file, the following "standard behaviour" is applied for each import class:

  • Add URI of the source class
  • Add all annotations on the source class
  • Add a new <definition_editor> annotation on the source class with the value Class imported / merged by efoimporter
  • Add a new subclass axiom (between the source and parent classes)

Creating a merged ontology

When creating a merged ontology, by default, it contains:

  • Stand-alone ontology module (as above)
  • The target ontology

New subclass axioms (between the source and parent classes) are only defined if "parents" behaviour is set (-p option)

If "replace" behaviour is set (-r option), the following additional changes are applied for each import class:

  • Delete the URI of the target class but preserve it within a new <EFO_URI> annotation on the new (imported) class
  • Retain the <definition_editor> annotation on the target class, but delete all its other annotations
  • Retain all other axioms of the target class, but redefining these to now be axioms on the new (imported) class

What-if scenarios

efoimporter behaves gracefully in case of difficulties with the supplied import specification, as follows.

Scenario 1: Source class URI not found in the source ontology

No import is performed.

Scenario 2: Parent class URI does not exist in the target ontology

Parent class URI will be created in the merge (output) ontology.

Scenario 3: Target class URI does not exist in the target ontology

The source class URI will be added, if possible, as per standard "standard behaviour" above.

Scenario 4: Source class URI already exists in the target ontology

The default behaviour is to not do the import, although an import can be forced (-f option), which will:

  • Perform "standard behaviour" as above
  • Retain the <definition_editor> annotation on the existing class, but delete all its other annotations
  • Retain all other axioms of the existing class, but redefining these to now be axioms on the new (imported) class
  • Do not add a new subclass axiom (between source and parent classes). As the source class URI already exists, it is assumed that correct subclass relations are arlready defined for it.

Note that if a replace is forced and "replace" behaviour is set (-r option), then the effects are cumulative.



Configuration

efoimporter may be configured using Java properties defined in a file (.efoimporter.properties) in the invocation directory, e.g.:

efoimporter.target = http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
efoimporter.merge = efoout.owl
efoimporter.module = module.owl
efoimporter.uri = http:/www.ebi.ac.uk/import
efoimporter.spec = import.spec
efoimporter.log = efo.log

This provides default values for the command-line options. For example, given the properties file above, the following command-line would read an ontology module specification from import.spec and write a module called module.owl:

$ ./import.sh -s -o

The properties correspond to and are overridden by the command-line options of the same name. For example, here the ontology specification file import2.spec set using -s takes precedence over the value of efoimporter.spec:

$ ./import.sh -s import2.spec -o

The properties file is written (to the current working directory) whenever efoimporter is run. The values written are those set on the command-line in the last run, or default values (if not set).

Developers downloading the code may also configure using Spring XML. The Spring configuration has a lower precedence than both command-line options and java properties. Default property values are defined in a bundled file (efoimporter.properties).



Input file format

The import specification file includes one line per class to import. Each line must include 3 or 4 space-separated values depending on mode (see below).

Create module (-o)

Specify 3 values per line:

SourceOntologyURI SourceClassURI ParentClassURI

For example:

file:///data2/jison/projects/ontologies/chebi.owl http://purl.obolibrary.org/obo/CHEBI_100 http://purl.obolibrary.org/obo/CHEBI_37577

SourceOntologyURI can be a URL or file name, so this is also acceptable:

http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_101278 http://purl.obolibrary.org/obo/CHEBI_37577

For example:

http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_124991 http://purl.obolibrary.org/obo/CHEBI_37577
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_15343 http://purl.obolibrary.org/obo/CHEBI_37577
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_15365 http://purl.obolibrary.org/obo/CHEBI_37577
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_15367 http://purl.obolibrary.org/obo/CHEBI_37577
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_15372 http://purl.obolibrary.org/obo/CHEBI_37577
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_15551 http://purl.obolibrary.org/obo/CHEBI_37577
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl
http://purl.obolibrary.org/obo/CHEBI_100 http://purl.obolibrary.org/obo/CHEBI_37577

Create merged ontology, specifying parent URI only (-m -p)

Specify 3 values per line (same as for "create module" above):

SourceOntologyURI SourceClassURI ParentClassURI

Create merged ontology, specifying replace URI only (-m -r)

Specify 3 values per line:

SourceOntologyURI SourceClassURI ReplaceClassURI

Create merged ontology, specifying both parent and replace URIs (-m -p -r)

Specify 4 values per line:

SourceOntologyURI SourceClassURI ParentClassURI TargetClassURI

For example:

http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl http://purl.obolibrary.org/obo/CHEBI_63916 http://purl.obolibrary.org/obo/CHEBI_37577 http://www.ebi.ac.uk/efo/EFO_0003187
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl http://purl.obolibrary.org/obo/CHEBI_7575 http://purl.obolibrary.org/obo/CHEBI_37577 http://www.ebi.ac.uk/efo/EFO_0003226
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl http://purl.obolibrary.org/obo/CHEBI_63918 http://purl.obolibrary.org/obo/CHEBI_37577 http://www.ebi.ac.uk/efo/EFO_0003229
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl http://purl.obolibrary.org/obo/CHEBI_63921 http://purl.obolibrary.org/obo/CHEBI_37577 http://www.ebi.ac.uk/efo/EFO_0003230
http://bar.ebi.ac.uk:8080/trac/export/head/branches/curator/ExperimentalFactorOntology/ExFactorInOWL/releasecandidate/efo_release_candidate.owl http://purl.obolibrary.org/obo/CHEBI_6078 http://purl.obolibrary.org/obo/CHEBI_37577 http://www.ebi.ac.uk/efo/EFO_0003232

Output file format (OWL-format ontology)

efoimporter writes an output file in the RDF/XML serialization format of the Web Ontology Language (OWL).

Output file format (log file)

Examples of messages that might appear in the log file is:

IMPORT OK (http://purl.obolibrary.org/obo/CHEBI_101278)
FORCING IMPORT (http://purl.obolibrary.org/obo/CHEBI_15365)- Source class already present in target ontology. Import was forced.
FAILED IMPORT (http://purl.obolibrary.org/obo/CHEBI_2709) - Source class not found in source ontology.
IMPORT OK (http://purl.obolibrary.org/obo/CHEBI_63916)
MERGE OK (source class http://purl.obolibrary.org/obo/CHEBI_63916 with target class http://www.ebi.ac.uk/efo/EFO_0003187)
FAILED MERGE (source class http://purl.obolibrary.org/obo/CHEBI_43876 with target class http://www.ebi.ac.uk/efo/EFO_0003244) - Target class not found in target ontology. Source class will still be added (if possible).



See also

There are a few couple of validators that perform complementary (syntactic) checks:

  • OntoFox is a web-based Ontology tool that fetches ontology terms and axioms. OntoFox allows users to input terms, fetch selected properties, annotations, and certain classes of related terms from source ontologies and save the results using the RDF/XML serialization of the OWL. OntoFox follows and expands the MIREOT principle.
  • Mireot Protege Plug in. A method that can extract required segments from an ontology according to some special criteria.



Issues and support

Issues and feature requests

To request a new feature or if you think you've found a bug, please use the JIRA Tracker.

Support

If you need help using this tool, please email fgpt@ebi.ac.uk.

Contact

For more information or to get involved please email Jon Ison.



Acknowledgements

This tool was developed by Jon Ison and the EBI Functional Genomics Production Team.

We gratefully acknowledge the support of our funders.



Software

spacer