Information in this guide is written specifically for eagle-i data curators. Curators will find instructions and guidelines for:
- Adding terms to the eagle-i ontology. Ontology terms are added, edited and obsoleted using an open source ontology editor. This section contains instructions for downloading and configuring the ontology editor as well as guidelines for adding new terms, obsoleting terms and the use of annotation properties.
- Adding resources to the eagle-i repository using the bulk loading process, ETL (extract, transfer, load). Resources such as instruments, laboratories, reagents and more, can be added using eagle-i's data tool. Large data sets can be added using an ETL process explained in this section.
- Adding Harvard Catalyst-compliant data. The eagle-i repository now supplies all of the core facility data that is displayed in the Harvard Catalyst database of core facilities at Harvard University. Guidelines in this section explain how curators should enter catalyst-compliant data.
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.
Downloading and Configuring Protégé
eagle-i curators use Protégé OBI (Ontology for Biomedical Investigations) to manage and view the eagle-i ontology. Protégé is a free, open source ontology editor and knowledge-base framework.
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é
Download OBI-friendly Protégé 4 for:
Windows: http://dl.dropbox.com/u/4905123/Protege_Windows.zip
Mac: http://dl.dropbox.com/u/4905123/Protege41MAC.zip
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é
Start Protégé and open an ontology. Any ontology will work.
A dialog may appear asking you about importing OWL files; if so, click Cancel.
Step 3: Set Protégé preferences
Open the File menu and click Preferences...
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.
Open the Save tab to confirm that the 'Use XML Entities' is checked.
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.
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.
To begin, locate the SVN local copy on your machine.
Select File > Ontology Libraries form 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:
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.
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.
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
Click Update to update the entire trunk.
show me This will update 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. Enter the following information in each column:
A: Choose the next consecutive number
B: Leave blank
C: Type the name of the term
D: Type Class
E: Select the next consecutive number
Column A |
Column B |
Column C |
Column D |
Column E |
choose the next consecutive number |
nothing |
Enter the name of the term |
type Class |
choose the next consecutive number |
Save the file, but leave the spreadsheet open, you'll come back to retrieve the ERO ID#.
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.
show me
From the Active Ontology tab, click Classes.
show me
The default file that opens is eagle-i-app.owl, use the drop-down menu to change the file to the ero file.
show me
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.
show me
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.
show me
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.
show me
All labels MUST be in lowercase and every annotation must be a datatype, String.
To change the datatype, choose String from the Type drop-down list at the bottom of the Annotation box.
show me
Click OK.
Choose a definition from the list of annotation properties. The definition must be IAO (Information Artifacts Ontology); hover over the definition to make sure.
show me
If necessary, you can add an alternate term. Click to add a new annotation. Again, make sure the type is STRING. Click OK.
show me
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.
Click again, and select definition source. Copy and paste the definition source. Make sure the type is STRING. Click OK.
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.
From the toolbar, switch to eagle-i-app.owl.
show me
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).
Click to add a new annotation value.
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.
Click OK.
Type the name/label (Use capitalization as appropriate, typically capitalize the first letter of the word)
Click OK and then click Save.
Step 5: Use the Hermit Reasoner to classify the ontology and make sure it is consistent.
From the toolbar, select Reasoner > Hermit 1.3.2.
Select Start Reasoner.
If the reasoner finds errors, correct the errors and run it again. If no errors are found, move to the next step.
show me
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 changes you've made when committing.
Open the SmartSVN Professional, click Refresh.
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.
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.
Overview
Content Tools