How to use protégé to change the ontology

When an issue is discussed and a conclusion reached, it's time for the implementation. Follow the CONTRIBUTING.md to get git set up to implement the changes. This article expands on step 3, implementing the changes.

1. Choose the right ontology module file

The OEO is structured in several modules with different scopes. If you just change existing classes, find out in which module they are created (please don't confuse with files were they were just imported) and change them there. In most cases please don't make the changes in the oeo.omn file. Most classes there were created in another module and just imported here.

If you add new classes add them in the file that's most appropriate for your topic:

• oeo.omn: Change this file if your concepts combine two or more modules and therefore can't be classified in any of the other modules. This should only be the case with object properties that link concepts from different modules together.
• oeo-physical.omn: Change this file if your concepts concern the "physical world of energy systems modeling" like artificial objects or portion of matter.
• oeo-model.omn: Change this file if your concepts concern models, studies or other aspects of modeling and documents.
• oeo-social.omn: Change this file if your concepts concern social aspects like sectors, persons or organisations.
• oeo-shared.omn: Change this file if your concepts are needed in two or more other modules and should therefore be included in all of them.

Please don't hesitate to ask in your issue where to implement your changes.

Ontology structure at time of release 1.0.0

2. Open ontology files

There are at least three ways to open your chosen file in protégé:

• double click it in the file explorer of your system. If protégé doesn't open by default, right click on it and chose protégé under "open with"
• open protégé. In the menu click file -> open
• if you already have one module open you can quickly switch to another at the top of the program window

3. Implement your changes

This section lists common changes to make to the ontology:

Add classes

Please make sure you set your protégé preferences to numeric identifiers!

1. open Entities tab
2. select parent class
3. Click the yellow icon on the left to add a new class as subclass

Add relation to a class

Relations say sth about how the class is related to other classes. They are written in a formal language

1. open Entities tab
2. select the class
3. click the plus next to "SubClass Of" (or the appropriate field) in the Description window

Add annotation to a class

Annotations say something about the class itself. They contain additional information in natural language, like definitions and term trackers.

1. open Entities tab
2. select the class
3. click the plus next to "Annotations" in the Annotations window

Every class must have at least the following three annotations:

1. A label which is the name of the class.
2. The definition that was agree upon in an issue (or an OEO dev meeting).
3. A term tracker item which includes both the issue of the discussion and the pull request implementing the class (or changes to the class). An example might look like:

issue: https://github.com/OpenEnergyPlatform/ontology/issues/123
pull request: https://github.com/OpenEnergyPlatform/ontology/pull/456

Protégé settings for adding to imported ontologies

Protégé allows you to choose between the following two options:

• Add fresh axioms to active ontology
• Add fresh axioms to subject defining ontology

This setting can be found under File->Preferences->General->Axioms

Changing this from active ontology to subject defining ontology saves a lot of time. Choosing the option Add fresh axioms to subject defining ontology you only have to open oeo.omn, which imports all other modules, and it is possible to add all axioms there. Protegé then sorted them into the correct module automatically. Another use case are term tracker items: After implementing a feature and opening a PR, you don't have to go through all the modules you worked on again to add term tracker items, but you can do everything from oeo.omn.

It is recommended to always using the option Add fresh axioms to subject defining ontology, since it is what we want to do in the OEO for most cases. The only exception is annotating entities from the external modules (i.e, iao- , ro- and uo-module), where you don't want to change the external module itself, but this case is rather rare.

Tips for working with Protégé

Expand the whole treeview automatically

• ALT + CLICK (Windows)
• OPTION + CLICK (Mac)

on top-level node as described in 🔗