-
Notifications
You must be signed in to change notification settings - Fork 2
Managing imports
- Overview
- The structure of the imports source files
- Example imports source files
- Module extraction methods
- Excluding entities from an import module
- Importing full ontologies
As you define entities for your new ontology, you will probably need to use at least some entities from other ontologies, either as parent classes or properties for your new entities or in formal, logical definitions of your new entities. If you use entities from other ontologies, you need some way to import those entities into your new ontology. OWL provides an import mechanism that can be used to import external ontologies in their entirety, but this is usually discouraged because you will often use only a small subset of entities from an external ontology. In that case, importing the entire external ontology to get only a handful of entities is inefficient. A better approach is to create import "modules" by extracting a set of entities from an external ontology and saving the extracted entities (and relevant axioms) to a standalone OWL file. These import module OWL files can then be imported by your new ontology.
The files in the directory src/imports in your ontology project directory define which entities your ontology needs to import from other ontologies. There is a single top-level imports file, called imported_ontologies.csv by default, which lists all of the ontologies that you wish to import. For each imported ontology (and each row in imported_ontologies.csv), there is a corresponding CSV or spreadsheet file that lists all of the entities to import from the external ontology. Thus, the procedure for importing entities from an external ontology is as follows (assuming you are using the default project folder structure).
- Add a row for the external ontology to
imported_ontologies.csv. - Create a CSV file or spreadsheet file to contain entities from the external ontology. The name of this file must correspond to the file name given in
imported_ontologies.csv(see details below). - Add the entities to import from the external ontology to the new CSV or spreadsheet file.
When you build your ontology, OntoPilot will read the ontology-specific input files and generate an import module for each external source ontology.
This file is called imported_ontologies.csv by default. Each row in the file specifies one external ontology from which an import module should be extracted.
| Column name | Description |
|---|---|
| Name | The name of the external ontology; this can be any character string. |
| IRI | The location of the ontology; this must be a functional HTTP URL. |
| Entities file | The name of the CSV or spreadsheet file containing the entities to import from the external ontology. |
| Ignore | If the value of this field is "true", "yes", "t", or "y" (not case sensitive), then the row will be ignored by OntoPilot when building the import modules. This provides a way to "comment out" one or more source ontologies if, for whatever reason, you don't want them included in the set of import modules. |
These files list the terms to import from a single external source ontology.
| Column name | Description |
|---|---|
| ID | The identifer of an entity to import. This can be specified as a label (e.g., 'whole plant' or PO:'whole plant'), a full IRI (e.g., http//purl.obolibrary.org/obo/BFO_0000002), a prefix IRI (e.g., obo:BFO_0000002, assuming the prefix obo is defined to mean http://purl.obolibrary.org/obo/), or an OBO ID (e.g., BFO:0000002). |
| Method | The method (algorithm) to use when constructing an import module. This must be one of either locality or single. If this column is missing or no value is provided, locality is used by default. For more information about these methods, see the section "Module extraction methods" below. |
| Related entities | Whether to retrieve entities that are related to the target entity for inclusion in the import module. This can either be empty, in which case no related entities are explicitly retrieved, or it can be a comma-separated list of one or more of the following values: ancestors, descendants, equivalents, disjoints, domains, ranges, inverses, types, or property assertions. For more information, see "Retrieving related entities", below. |
| Exclude | If the value of this field is “true”, “yes”, “t”, or “y” (not case sensitive), then this entity (and related entities, if specified in the Related entities column), will be explicitly excluded from the final import module. |
| Ignore | If the value of this field is "true", "yes", "t", or "y" (not case sensitive), then the row will be ignored by OntoPilot when building the import module. This provides a way to "comment out" one or more rows in a source file if, for whatever reason, you don't want them included in the module. |
Here is an excerpt of a valid imported_ontologies.csv, taken from the Plant Phenology Ontology.
| Name | IRI | Entities file | Ignore |
|---|---|---|---|
| Basic Formal Ontology | http://purl.obolibrary.org/obo/bfo.owl | bfo_ppo_terms.csv | |
| Relations Ontology | http://purl.obolibrary.org/obo/ro.owl | ro_ppo_terms.csv | |
| Plant Ontology | http://purl.obolibrary.org/obo/po.owl | po_ppo_terms.csv | |
| Phenotypic Quality Ontology | http://purl.obolibrary.org/obo/pato.owl | pato_ppo_terms.csv | |
| Ontology for Biomedical Investigations | http://purl.obolibrary.org/obo/obi.owl | obi_ppo_terms.csv |
As an example of an ontology-specific entities file, here are the contents of obi_ppo_terms.csv.
| ID | Method | Exclude | Related entities |
|---|---|---|---|
| OBI:'has_specified_input' | single | ancestors, inverses, domains, ranges | |
| OBI:'has_specified_output' | single | ancestors, inverses, domains, ranges | |
| BFO:'quality' | Y |
And for an example of an ontology-specific entities file that uses a different module building algorithm, here are the contents of bfo_ppo_terms.csv.
| ID | Method | Related entities | Exclude |
|---|---|---|---|
| BFO:'occurrent' | locality | ||
| BFO:'spatiotemporal region' | locality |
OntoPilot supports two module extraction methods, specified as the value of the Method column in the ontology-specific entities files. The supported methods are locality and single.
The locality extraction method is the default and the simplest to use. This method extracts a set of entities from the source ontology using the notion of syntactic locality, as implemented by the SyntacticLocalityModuleExtractor component of the OWL API. This approach to generating modules is described in detail by Sattler et al. (http://ceur-ws.org/Vol-477/paper_33.pdf for the published version; http://www.dcs.bbk.ac.uk/~michael/insepDL.pdf for an extended version). The basic idea is that, given a set of terms from a source ontology, we want to find a set of entities and axioms from the source ontology that, when imported, are logically indistinguishable from having imported the full source ontology. Thus, all entities in a module source file that are flagged with the locality method will be grouped together in a single "seed set", and this seed set will be used to generate the syntactic locality module from the source ontology.
Ideally, a syntactic locality import module will be much smaller than the source ontology while preserving all logical entailments with regard to the set of seed entities. However, finding a minimal set of entities and axioms that satisfies the logical entailment requirement is a hard problem, and in general, the import module generated when using the locality method is not guaranteed to be minimal. Sometimes, the generated module will still be quite large and might be too cumbersome for use in reasoning, in which case single-entity extraction should be considered as an alternative.
As its name implies, the single extraction method extracts a single entity from the external source ontology and adds it to the new import module. All annotations for the entity are also retrieved, but by default, all other axioms and entities related to the entity are ignored. This gives an ontology developer very fine-grained control over the contents of an import module, and that can be advantageous when it is important that important modules be as small as possible. The obvious downside to this simplistic approach is that we might lose related entities and axioms that we are also interested in, such as the superclasses of an imported class. To address this, OntoPilot can retrieve entities and axioms that are related to the target entity in some way and add them to the import module, too.
Often, we want to extract not only a single entity from an external ontology, but also the entities and axioms that are related to the target entity in some way. For example, we might want to get the hierarchy of superclasses for a target class, all descendants (subclasses or subproperties) of a target entity, or the domains and ranges of imported properties. OntoPilot can easily accomodate these scenarios through custom values of the Related entities column in the imports source files.
The Related entities field can take any of the following values. Multiple values can be provided as a comma-separated list.
-
ancestors: Retrieve the target entity and all of its ancestors (superclasses or superproperties). -
descendants: Retrieve the target entity and all of its descendants (subclasses or subproperties). -
equivalents: Retrieve the target entity and all other entities to which it is equivalent, according to explicit equivalency axioms. -
disjoints: Retrieve the target entity and all other entities with which it is disjoint, according to explicit disjointness axioms. -
domains: Retrieve the target object or data property and all named classes that are explicitly stated to be in its domain. -
ranges: For object properties, retrieve the target property and all named classes that are explicitly stated to be in its range. For data properties, retrieve the target property and all axioms defining its range. -
inverses: Retrieve the target object property and any properties explicitly stated to be its inverse. -
types: Retrieve the target named individual, all class assertion axioms for the named individual that reference named classes, and all named classes used in those assertions. In other words, retrieve the target named individual and all of its named types. -
property assertions: Retrieve the target named individual, all property assertion axioms for the named individual, and all properties used in those assertions.
It is important to note that related entity/axiom retrieval is recursive across all desired relationship types. Suppose, for example, that you want to retrieve a target object property and you provide ancestors, domains as the value of the Related entities field in the module source file. In this case, OntoPilot will retrieve the target entity from the source ontology, all of its ancestors (superproperties), all classes in the domain of the target property, all classes in the domains of the target property's ancestors, and all ancestors (superclasses) of the property domain classes.
Sometimes, one of the automated module extraction methods will extract terms that you explicitly do not want in the final import module. If this is the case, you can use the Exclude column in the module source files to tell OntoPilot which terms it should ensure are not included in an import module. Exclude can be used with Related entities to define sets of related terms that should be excluded from an import module. So if, for example, you wanted to make sure that neither a particular target class nor any of its descendants are included in an import module, you would add a row to the module source file table for the excluded class, set the value of the Exclude field to True (or T, true, yes, etc.), and set the value of the Related entities field to descendants. When excluded entities are included in a source file, OntoPilot will first build the import module using all included entities, then examine all excluded entities (and related entities, if specified), and ensure that they are removed form the final module.
There are situations where it makes the most sense to simply import an external ontology in its entirety rather than try to extract a suitable import module from it. OntoPilot can easily handle this situation. To import an entire source ontology, add a row for the external ontology to the top-level imports file (imported_ontologies.csv by default), then simply leave the Entities file field blank.
Once you've defined some new terms for your ontology and specified your ontology's imports, you are ready to build your ontology.