Page History

This section contains specific instructions for eagle-i editors who are working with the ontology in Protégé, as well as an overview of the general workflow for various common editing tasks.

The eagle-i Ontology

A unique feature of eagle-i is that the data collection and search tools are completely driven by ontologies. These ontologies are a set of modules that are written in the OWL language and edited and managed using Protégé. The following instructions will help you configure Protégé, edit the core ontology module, and add annotations to drive the user interfaces.

Goals

Our modeling approach had three main drivers. The first was to represent real data collected about resources. The second was to have the ontology control the userinterface (UI) and the logic of the data collection tool and search application. The third was a commitment to build a set of ontologies that could be reusable and interoperable with other ontologies and existing efforts for representing biomedical entities. This latter requirement translated into decisions to a) follow OBO Foundry principles and best practices for biomedical ontology development and b) engage in active discussions within the bio-ontology community in order to provide context for eagle-i interoperability and align with domain-wide standards for resource representation (http://bit.ly/rrcoord).

Ontology structure

Viewing the ontology using Protégé

...

...

Setting up Protégé

Note: You can view the Ontology using Protégé 4.0.2 but to edit, you must install Protégé 4.1.

Step 1: Download Protégé

1. 1. Download OBI-friendly Protégé 4
for:
Windows: http://dl.dropbox.com/u/4905123/Protege_Windows.zip
Mac
2. 1. .3 or 5: http://
dl
3. 1. protege.
dropbox
4. 1. stanford.
com/u/4905123/Protege41MAC.zip
5. 1. edu/
   2. If prompted, do not install updates for the plugins, as the plugin versions contained in the download work specifically with OBI.

Step 2: Configure Protégé

If you are editing for the first time in Protégé, you will need to adjust the settings (should only need to be done once).

1. 1. Start Protégé and open an ontology. Any ontology will work.
2. 1. A dialog may appear asking you about importing OWL files; if so, click Cancel.

Step 3: Set Protégé preferences

1. Open the File menu and click Preferences...
2. Click Renderer, and then click Annotations ..., add 'en, en-US, !' in the languages column. Include the apostrophe.
   Note: OBI users may want to change the "reasoner" default settings to improve reasoning performance. In the reasoner tab "initialization" , choose only "class members" and under "Displayed inferences" choose only "unsatisfiable classes", "equivalent classes" and "superclasses". No instance reasoning is done, but for most OBI development this isn't necessary. These settings can make a particularly big difference when using Hermit as the reasoner.
3. Open the Save tab to confirm that 'Use XML Entities' is checked.
4. To display the class labels rather than the IDs, open Renderer and choose Render entities using annotation values. If the eagle-i classes still display as IDs, open the Renderer and click Annotations ..., then select label. Leave the language column blank and click OK.
5. Click OK.

Step 4: Add the local files for ontologies you want to import.

This step adds a set of directories from your local (Subversion) SVN repositories. This example uses the /datamodel/ directory.

1. To begin, locate the SVN local copy on your machine.
2. Select File > Ontology Libraries from the menu.
   This step add directories. For each directory, click + and then navigate to the specific directory:

/datamodel/trunk/src/ontology/imports
/datamodel/trunk/src/ontology/external
/datamodel/trunk/src/ontology/external/iao
/datamodel/trunk/src/ontology/external/iao/external
/datamodel/trunk/src/ontology/external/iao/protégé

Your dialog window should look like this:

https://sites.google.com/a/eagle-i.org/workspace/data-curators-workspace/configuring-and-editing-with-protege-4/onto_lib.tiff?attredirects=0

1. Close Protégé.

Adding a New Term to the eagle-i Ontology

It is important to note that the following steps assume that you have a basic understanding of Protégé, and the revision control software Subversion as well as an understanding of an ontology.

There are seven basic steps when adding a new term to the ontology.

Step 1: Send an e-mail to notify the curators you are locking files.

1. You will be working with several files under Subversion (SVN) revision control. Before you begin, notify the curators by e-mail that you are locking two of these files: ero.owl and eagle-i-app.owl

The body of the e-mail should looks something like   this:{{\[LOCKING\] eagle-i-app.owl and ero.owl for editing.}}

Step 2: Open Subversion and update the ontology files.

1. Open SmartSVN. The files you will be working with are located here: svn+ssh://orchestra.med.harvard.edu/svn/cbmi/u24/eagle-i-dev/datamodel/trunk/src/ontology
2. Click Update to update the entire trunk.

  Image Removed
This step updates three files, ids.xlsx, ero.owl and eagle-i-app.owl, as well as all relevant imports.

Step 3: Add the new term to the ontology.

Open the Excel file, IDS.xlsx, which is typically located here: SVN ---> src -> ontology. This file consists of five columns of information labeled as follows: column (A) ERO ID #, column (B) Mireot, (C) Label, (D) Class and column (E) URI.

1. Enter the following information in each column:

   Column A ERO ID #	Column B Mireot	Column C Label	Column D Type	Column E URI
   Choose the next consecutive number	Nothing	Enter the name of the term	Typ Class	Choose the next consecutive number

2. Save the file, but leave the spreadsheet open, you'll come back to retrieve the ERO ID#.
3. Open Protégé. Open the OWL ontology. Choose the file, eagle-app.owl from your directory. For example: /Users/JaneCurator/eagle-i-datamodel/trunk/src/ontology/eagle-i-app.owl.
4. From the Active Ontology tab, click Classes.

Image Removed

1. The default file that opens is eagle-i-app.owl, use the drop-down menu to change the file to the ero file.
2. If you don't see the parent term, use the search box in the upper-left corner of the screen. In this example, the parent term is technique. Once you find the parent term, highlight the correct class and then click Subclass to add a subclass.
3. When the dialog box, Create a new Owl Class, appears copy and paste the ERO ID (from Column A in the Excel spreadsheet) into the text box: "Please enter a class name". Click OK.

Image Removed

1. Click to change the label for the new term you just added.  Highlight the existing label and replace the ERO_xxxx ID (from the Excel spreadsheet) with the name of the term.
   All labels MUST be in lowercase and every annotation must be a datatype, String.
2. To change the datatype, choose String from the Type drop-down list at the bottom of the Annotation box. Click OK.

Image Removed

1. Choose a definition from the list of annotation properties.  The definition must be IAO (Information Artifacts Ontology); hover over the definition to make sure. If necessary, you can add an alternate term. Click to add a new annotation. Again, make sure the type is STRING. Click OK.
2. Add two annotation values: definition editor and definition source: Click (add new annotation) and select definition editor from the annotation properties list and type your name using the format: PERSON: First name Last name. Click OK.
3. Click again, and select definition source.
4. Copy and paste the definition source. Make sure the type is STRING. Click OK.
5. Save the term. Click Save and hover over the term to confirm it has a valid URI.

Step 4: Change the term label to an eagle-i preferred label.

Follow these next series of steps to the eagle-i preferred label. Typically, new terms entered into an ontology are always lowercase. Exceptions are made for terms that are proper names or acronyms, like DNA. The eagle-i preferred label is the proper label for the term, typically with the first letter capitalized. For example, polymerase chain reaction would be entered as "polymerase chain reaction" in the ero.owl file and the eagle-i preferred label would be Polymerase chain reaction.

1. From the toolbar, switch to eagle-i-app.owl.
2. Use the search box to locate the class you wish to re-label.
   Note: Terms that are in bold are from the currently open ontology. Terms that are not bold, were imported from another file (ontology).
3. Click to add a new annotation value.
4. From the list, select the eagle-i preferred label. Note: eagle-i preferred label should be bold. If it is not bold, check to make sure you are in the correct file.
5. Click OK.
6. Type the name/label (Use capitalization as appropriate, typically capitalize the first letter of the word)
7. Click OK and then click Save.

Step 5: Use the Hermit Reasoner to classify the ontology and make sure it is consistent.

1. From the toolbar, select Reasoner > Hermit 1.3.2.
2. Select Start Reasoner.
3. If the reasoner finds errors, correct the errors and run it again.  If no errors are found, move to the next step.

Step 6: Commit the changes in Subversion

Best practice is to make only a few changes before committing to SVN. Keep detailed notes of the changes you make and always add comments describing the hanges you've made when committing.

1. Open the SmartSVN Professional, click Refresh.
2. Select CHANGES. Confirm that everything looks okay and there were no mistakes. Here are two examples of changes in SVN. Often times, SVN will display changes that are not actual changes but just mirror images of terms. Look carefully at the changes and make sure they are either just mirror images or a term that was inserted.
3. Select changed files, (files with a red icon). Click Commit.  Make sure to enter comments.

Step: 7: Notify the curators that the file has been unlocked

This is the last step.  Notify the curators that the file has been unlocked using an e-mail that looks similar to: {{\[UNLOCKING\] ero.owl and eagle-i-app.owl.}}

Obsoleting a Term in the Ontology

Before obsoleting a term it is best practice to check the usage of the terms across the repositories. You can do this using either SPARQL queries or ECDT tools.

Step 1: Update Subversion

1. 1. Open the Save tab under Preferences and ensure ‘Use XML Entities’ is NOT checked.
   2. Go to: Preferences > New Entities and set up your new entity URI settings as shown below:

Image Added

Entity URI Start with: select 'Specified URL' and enter 'http://purl.obolibrary.org/obo' Followed by: select '/' End with: select 'Auto-generated ID' Entity Label (for use with Auto-generated ID) Select 'Same as label renderer' Auto-generated ID Select 'Numeric (iterative)' Prefix: enter 'ERO_' Digit count: enter '7' Start: enter a four digit number one higher than that of the last ID created. To determine correct number: consult the IDs.xlsx spreadsheet, located in trunk > docs to find the last ID number used search for the next highest ID number in Protégé to double check no additional IDs have been created End: -1

Step 4: Reasoning

The reasoner tests the logic and consistency of the asserted axioms in the ontology and computes the inferred hierarchy. The suggested reasoner for eagle-i is FaCT++. It is good practice to run the reasoner periodically before committing, to ensure nothing has been accidentally moved. The ‘Class hierarchy’ tab shows only the asserted hierarchy; the ‘Class hierarchy (inferred)’ tab shows the inferred hierarchy relationships (i.e. the hierarchy seen in the software). The inferred hierarchy is only visible after the reasoner has been run in that file.

Viewing the eagle-i ontology

Before viewing or editing the ontology, make sure you’re looking at the most current version:

1. Update the ontology trunk in your Subversion repository to get the latest changes: https://open.med.harvard.edu/svnOpen SmartSVN. The files you will be working with are located: svn+ssh://orchestra.med.harvard.edu/svn/cbmi/u24/eagle-i-dev/datamodel/trunk/src/ontology
2. Click Update to update the entire trunk.
   This will update three files: ids.xlsx, ero.owl and eagle-i-app.owl, as well as all relevant imports.

Step 2: Obsolete the term

1. Open Protégé Open the OWL ontology.
2. Choose the file, eagle-app.owl from your directory. For example:
   /Users/JaneCurator/eagle-i-datamodel/trunk/src/ontology/eagle-i-app.owl.
3. From the Active Ontology tab, click Classes.
   The default file that opens is the eagle-i-app.owl file, use the drop-down menu to change the file to the ero file.
4. If you don't see the term, use the search box in the upper-left corner of the screen to find the term.
5. To find out if the term you want to obsolete is used as domain and range for some property or some logical definition, select the term and click Usage. If it is, you will need to replace the obsolete class with the new class at the end of the process or delete the properties and logical definitions that will be obsoleted along with the resource.
6. Rename rdfs:label to obsolete_rdfs:label.  Look at a pre-existing obsolete term for an example.
7. Click to add the annotation property, "has obsolescence reason" and type the reason why this term is being obsoleted. If it is being replaced by a new term, enter the new term.
8. Add new parent term: In the description box, under Superclass, click
9. Delete the existing parent name and replace with ObsoleteClass. Click OK.
10. Look under the obsolete term you obsoleted, and recheck the usage of the obsoleted class (step #6) and fix any property or logical definitions that still include the obsoleted resources.

Remember to keep track of any data that is currently using the obsoleted term. That data will need to be migrated. Provide a migration (Excel) file for the build team.

Step 3: Use the Hermit Reasoner to classify the ontology

1. From the menu, select Reasoning > Hermit 1.3.2.
2. Select Start Reasoner.

Step 4: Commi to SVN

1. Open SmartSVN.
2. Click Update to check for any changes.
3. Write a detailed list of the changes that have been made.
4. Commit.

Annotation Properties

Application-specific properties and annotations are kept in the eagle-i app file. https://sites.google.com/a/eagle-i.org/workspace/build-team-workspace/data-model-integration/applicationspecificannotations for most current values) The purpose of these annotation properties and their values is to allow curators to "flag" classes and properties to "tell" the eagle-i, for example, to which class is a resource is connected or which property connects a resource to a lab.

Currently the following properties that can be used:

{{- inClassGroup

- inPropertyGroup}}

There is a specific set of values for both

{{inClassGroup and

inPropertyGroup}}

( see https://sites.google.com/a/eagle-i.org/workspace/build-team-workspace/data-model-integration/applicationspecificannotations for most current values)

You can see all these values in the ontology by:

1)Selecting the eagle-i-app-ont ontology as the native ontology in Protégé from the drop-down of active ontology as shown below:

2)Click on the individuals tab and check each single value (note that there is comments explaining the usage and i the Types" indicates if value applies to classes or properties

In order to flag a class or properties with a particular value:

1)Make sure you are adding annotation in the eagle-i-app ontology (see below)

2)Select the class or property form the class or property hierarchy that you want to annotate

3)Select the annotation tab on the right panel and click on add annotation

4)Select inClassGroup or inPropertyGroup from the list (depending what you are annotating)

5)Select 'Individuals' and 'Entity URI' form the right tabs as shown below:

6)Select the value of annotation from the list. And click OK.

For the specifics of the values and meaning of current annotation values please refer to:

...

1. .
2. Use the module scripts to generate the local ontology
   
   1. Right click on the src\isf\module-scripts folder and select ‘Open in Terminal’ to open a command window. (Note: these instructions are specific to the SmartSVN client, but a variation on this workflow should be possible from other clients. See Ontology File Structure > src/isf/module-scripts for more details.)
   2. Type ei-all.bat (for Windows) and hit enter. The script is done when the command prompt reappears. This process will take some time and potentially slow your computer down.
3. Depending on what part of the ontology you wish to view, open one of the following OWL files in Protege:
   1. eaglei-modules-top.owl — imports the source (the ISF), the module configuration, and the exclude and include files.
   2. eaglei-module-configuration.owl — shows only the source (ISF) and the module configuration.
   3. eagle-i-extended-app.owl —  shows both the eagle-i ontology generated and application OWL files.

Reminder: do not edit the generated files. Any direct edits of the generated files will not be committed to SVN (these files are SVN ignored) and they will be lost the next time the scripts are ran. Only view these files in Protégé:

• Select Show all loaded ontologies under View settings to show terms from all files. Terms in bold are contained in the current active file. Hover over the name of unbolded terms to see their actual location.
• Show the imports closure of the active ontology shows terms both directly and indirectly imported into that file.
• Show only the active ontology shows only terms contained in the active file; no imports.

...