NEMO Technical Document 2010-001
Last Updated: 2010-03-18
2010-03-05
Gwen Frishkoff
Paea LePendu
Snezana Nikolic
Step-by-step Instructions for Editing NEMO Ontologies
1. Summary
========================================================================
This report describes steps in editing and maintaining NEMO ontologies,
including the following 3 main steps:
 Working with NEMO Ontology Directory and File Structure (Sec 2)
 Editing and maintaining NEMO Ontology (owl/rdf) files (Sec 3)
 Version Stamping and Releasing New Versions of NEMO Ontology (Sec 4)
2. NEMO Ontology Directory and File Structure
========================================================================
NEMOontologies directory contains all the NEMO ontology sub-directories
and files in *.owl format. NEMOontology directory files are stored at the
remote depository and can be viewed at:
http://nemoontologies.svn.sourceforge.net/viewvc/nemoontologies/ontologies/
The webpage displayed below illustrates the NEMOontologies directory
structure. Please note the directory revision number (the Rev. column
between the “Age” and “File” columns) displayed next to each of the
directories
indicating
different
versions
of
the
NEMOontotolgy
directories.
1
NEMOontologies directory consists of three sub-directories old/, release/
and working/. Each of the three folders contains a set of *.owl files of
the NEMO ontology. Below is the brief description of each of the
NEMOontologies sub-directories.
old/
This directory contains several sub-directories, each of which is
previously publicly released version of the NEMO ontology and equivalent
to the corresponding prior versions of NEMO ontology posted on the
BioPortal. (There is one sub-directory per one previously released/old
version of NEMO ontology.) These directories contain old *.owl files
which are kept for project archival purposes and are not crucially
relevant for the current development of NEMO ontology.
release/
This directory contains the *.owl files of current (i.e. most recently
publicly released) version of the NEMO ontology. It is equivalent to most
recent version of NEMO posted on the BioPortal. This directory DOES NOT
contain the ontology files which are currently “under construction” i.e.
files the NEMO ontology curators currently work on.
working/
This is the most important directory for the process of NEMO ontology
development. It contains WORKING VERSIONS of NEMO ontology *.owl files
that are undergoing almost CONSTANT REVISION (and update) due to
processes of ontology curation, development and maintenance performed by
the designated NEMO ontology curators. Each NEMO ontology curator works
on the *.owl files contained in the COPY OF THIS DIRECTORY which they
keep stored LOCALLY on their machines.
The snapshot of the webpage displayed below illustrates current state of
the working/ directory. Please note the different revision numbers (the
Rev. column) next to the each of files indicating different stages of
development process of each of the *.owl files.
2
3. Procedures for NEMO Ontology Development and Maintenance
========================================================================
3.1. General Instructions
In order to be able to work on the NEMO ontology development on your
computer (desktop and/or laptop), you need to acquire three types of
applications: an ontology editor (Protégé), a version controller
(Subversion or Versions) and a text editor.
1. Protégé is an open source cross-platform ontology editor used by
NEMO ontology development team. Protégé can be downloaded from:
http://protege.stanford.edu/download/registered.
Always make sure to have the most recent Protégé version and frequently
check for Protégé updates, patches and new versions.
2. For version-control (revision-control) purposes, depending on
personal preferences, NEMO ontology curators use two version-control
systems:
Subversion (SVN), cross-platform, downloadable from
http://subversion.apache.org
or
Versions for MacOS, downloadable from
http://versionsapp.com.
3. A text editor (by choice) needed for RDF/XML syntax checking and
3
troubleshooting. (Please see section 3.6.2.)
After installing the Protégé and the version-control application (SVN or
Versions) on your machine, you need to download the NEMOontologies
directory to be able to work on the NEMO ontology locally (on your
machine).
3.2. Obtaining the NEMOontologies Directory
How to download the Versions application and obtain the NEMOontologies
directory using Versions application tools, please follow the steps
described in the movie available to watch at:
http://www.screentoaster.com/watch/stVEtQQURIR1xfQVxbXF9eUlVQ/nemo_demo_o
f_versions
After the completed download of NEMOontologies directory and EVERY TIME
you start working on and/or exploring the NEMO ontology please run
“SVNupdate” or NEMOontologies folder Update in Versions. (Please see
below.)
3.3. Working on NEMO Ontology Editing
NEMO ontology curators work on the *.owl files contained within the local
copy of the working/ directory (i.e. copy of the NEMOontologies directory
stored at their machines). WORKING/ SUB-DIRECTORY IS THE ONLY DIRECTORY
THAT CONTAINS THE FILES NEEDED FOR ACTIVE ONTOLOGY DEVELOPMENT AND THE
ONLY DIRECTORY NEMO CURATORS USE. All other directories are of less
importance for ontology editing and current development.
Working on the ontology editing usually includes the following three
obligatory steps:
1. Updating local NEMOontologies directory
2. Ontology editing using Protégé
3. Committing the changes made on the local copy to the remote
NEMOontologies repository.
3.3.1. NEMOontology Directory Updating
EVERY TIME BEFORE you start editing on and/or exploring the NEMO ontology
please run “SVNupdate” or NEMOontologies folder Update in Versions. By
doing this, one makes sure that the working/ (sub-directory of
NEMOontologies folder) that is stored locally (on your machine) is THE
MOST RECENTLY UPDATED VERSION of this NEMOontologies sub-directory.
Frequent updates of the NEMOontologies directory (which includes the
updating of working/) prevent you from doing the work that has already
been completed by other curator(s) (i.e. avoid getting conflicting
revisions messed up among other users) and insure the progress in the
ontology development.
When using Versions application, to update the local NEMOontologies
directory, select for the NEMOontologies folder in the left subspace of
4
the Versions window and click Update (as showed on the snapshot below).
2.Click Update
1.Select for
NEMOontologies
When using the Subversion (SVN) application, run the “SVN Update” to
update the local copy of NEMOontologies folder.
<!-- Need a snapshot for the “SVN update”. -->
3.3.2 Committing the Editorial Changes to Remote NEMOontology Repository
After completing the work on ontology editing and (temporarily) being
satisfied with the changes made, NEMOontology curator needs to transfer
the changes he/she made to the *.owl files in the local copy of the
working/
directory
to
the
corresponding
files
in
the
remote
NEMOontoloigies repository. This “editorial change transfer” is performed
by executing the command “Commit” by which the two copies of the working/
directory (local and remote) are being made the same. In other words,
after performing the “Commit”, the newly changed version of working/ subdirectory is been posted to the NEMOotologies repository and thus made
accessible to all NEMO curators. Since multiple curators make editorial
changes to the working/ sub-directory on multiple locations and commit
the changes they made to the remote NEMOontologies repository, running
frequent updates of your local copy of working/ is obligatory and
necessary.
To commit the editorial changes you made, select for the NEMOontologies
folder on the left subspace of the Versions window and click Commit (as
showed on the snapshot below).
2.Click Commit
5
1.Select for
NEMOontologies
<!-- Need a snapshot for the “SVN update”. -->
3.4. Some Instructions for Ontology Editing Using Protégé
3.4.1. Protégé Settings and NEMO_ID Number Assignment For New Entities
After downloading and installing the
NEMOontologies update (see above), you
newly created terms have NEMO ID numbers
assigned NEMO ID numbers in the ENTIRE
you need to adjust the settings in
assignemnt) for you automatically.
Protégé and AFTER RUNNING THE
need to make sure that all the
DIFFERENT from all other already
NEMO ontology. To achieve this,
the Protégé to that (NEMO ID
Open the Protégé and open any of the *.owl files contained in working/
directory. Go to Preferences and click New Entities. The following window
will open (see below). (NOTE: The snapshots are taken on the Mac OS
machine. Protégé version for Windows looks slightly different with option
featured under different menus.)
6
Please make sure that these Protégé preferences’ settings are ABSOLUTELY
the same on your machine as the ones that are showed in the snapshot
above. Any settings different from the ones showed above will surely
create mess in the ontology and unnecessary additional work for NEMO
ontology curators.
If by some unfortunate chance the Specified URI field (in the topmost
pink rectangle) and the Custom label field (in the middle pink rectangle)
you have in your Protégé preferences settings are NOT IDENTICAL to the
ones showed above, please make sure to make those necessary corrections.
In order to fix this problem, you need to check the option button next to
the problematic field (“Specified URI” or “Custom label”), enter the text
manually (please make sure that the http addresses are EXACTLY THE SAME
as in the window snapshot above). After entering the text in the
appropriate field please uncheck those option buttons and re-check the
ones checked in the window snapshot above.
NOTE:
Paea LePendu has expressed some skepticism about this Protégé autonumbering feature, questioning how can Protégé "know" what ID has not
7
been already used unless ALL the known (used) IDs are
front of it?
For this reason, the NEMO OTF has agreed to be cautious
this Protégé automated ID number assignment feature. We
use it, but will also check periodically to be sure that
planned.
sitting right in
about relying on
will continue to
it is working as
3.5. Annotating NEMO Terms
For NEMO terms property annotation rules and practices, please see the
LATEST VERSION of the NEMO-PropertyAnnotations.doc downloadable from:
http://nemo.nic.uoregon.edu/wiki/Technical_Reports
3.6. Checking RDF/XML Syntax Output from Protégé
There are two available ways to check the RDF/XML syntax changes in *.owl
file code that correspond to the results of Protégé actions.
3.6.1 Checking RDF/XML Syntax Output While Working in Protégé
First way to do the owl code check is to open a RDF/XML rendering subwindow in Protégé while still using it for ontology editing purposes.
Snapshot below shows the randomly created new class called NewClass and
the drop down menu with RDF/XML rendering option. (To see the drop-down
menu, you need to click on the tools’ options arrow as showed below).
Please note the NewClass NEMO_ID number (NEMO_4682000) and its superclass (dependent_continuant).
8
After selecting for RDF/XML rendering option Asserted class hierarchy
sub-window will be instantly replaced by another sub-window showing the
RDF/XML code of the opened *.owl file (In this particular case, the file
we are “working on” is TEST.owl.)
The advantage of Protégé RDF/XML rendering tool is that one can check how
the syntax of the *.owl file has been altered after each step of the
editorial work has been made. On the other hand, the drawbacks of such
“in Protégé” syntax check are 1) one has to scroll through the RDF/XML
9
code to find the code section for the target term and 2) there are no
code line numbers to facilitate the term search and syntax check (which
can make curator life much harder when one needs to search for one
particular term multiple times.)
3.6.2 Checking RDF/XML Syntax Output Using Text Editor
Another way of performing RDF/XML syntax check and exploration is to use
a text editor. Which text editor to use is largely a matter of personal
preference and different NEMO ontology curators use different text
editors: UltraEdit, TextMate, EditRocket, BBEdit to name a few.
Snapshot below shows exactly the same section of code of the TEST.owl
file for our target class (NewClass, NEMO_4682000) as it was illustrated
in the snapshot above, only rendered by EditRocket text editor. (Please
note that the code is exactly the same to the one showed in the Protégé’s
RDF/XML rendering window.)
The advantages of using a text editor are obvious: color coding of
RDF/XML
and ontology categories, code line numbers, easy string search
(Command+F in MacOs and Ctrl+F in Windows), change font size/type option
etc. One caveat, though: by using text editor, the code can be easily
messed up by careless handling and typing, which in turn can create a
much bigger problem if such a file is saved and committed to the remote
NEMO repository.
Below is one more example snapshot showing the advantage of text editor’s
RDF/XML syntax rendering. Here, careful comparison of the code lines
below, reveals that lines 65, 71 and 74 are exactly the same. Since there
is no need for such code redundancy and repetition, lines 71 and 74 need
to be deleted. The same line repetition could also be detected in
10
Protégé’s RDF/XML rendering sub-window, but due to the font size and the
absence of code line numbers, such “code defect” tracing would be much
harder and more time consuming.
3.7 Deprecating NEMO Classes/Objects and Object Properties
During the active ontology development some objects, classes and/or
object properties, for various reasons, become deemed unfit by NEMO
ontology curators, to continue their life in the present NEMO ontology
structure and thus become deprecated. Deprecation is the process of
changing the status of an ontology term and its position within the
ontology structure by moving it into a designated _deprecated class or
deprecatedObjectProperty, depending on the subject category.
There are two ways of performing class/object or object property
deprecation: by using Protégé tools or directly altering the RDF/XML code
of the corresponding *.owl file.
3.7.1 Deprecating Classes, Objects and Object Properties using Protégé
For the purposes of this step-by-step tutorial two new terms have been
created and randomly placed into the NEMO_spatial sub-ontology tree, a
class that we want to deprecate (called ClassToDeprecate) and an object
property that we want to deprecate (called PropertyToDeprecate).
11
Snapshot below shows the target ClassToDeprecate which was arbitrarily
made to be a sub-class of dependent_continuant. (Please note the
information displayed in the Class Usage window showing the class NEMO_ID
number (label) which has been automatically assigned to our newly created
ClassToDeprecate. This is because we set up Protégé to do automatic
NEMO_ID number assignment for us. (Please section see 3.2.1.))
In order deprecate a class (or an object of a class) the target
class/object needs to be moved (dragged-and-dropped) from its original
position in the ontology structure into the _deprecated class (“higher
up” in the ontology tree) as it is illustrated by the snapshot below.
Please note that the NEMO_ID number has not been changed, but only the
super-class
of
the
deprecated
ClassToDeprecate.
In
other
words
ClassToDeprecate has become a sub-class of the class called _deprecated.
12
The procedure of deprecating object properties in Protégé is basically
the same as the one used for class/object deprecation. Arbitrarily
created property (PropertyToDeprecate) was randomly placed somewhere in
object_property sub-ontology. (The NEMO label for the our property has
not been displayed in “Object Properties” sub-window, but only in
“Annotations” sub-window. (A bug in Protégé.))
13
The
result
of
the
PropertyToDeprecate
“movement”
to
deprecatedObjectProperty (storage place for all deprecated object
properties) is illustrated below. Our PropertyToDeprecate has now been
deprecated and become a sub-property of the deprecatedObjectProperty
(whose ID is NEMO_3786000, and label not showed below due to Protégé
bug). Note that the NEMO_ID number has not been changed (NEMO_9154000),
just as in the case of class/object deprecation.
3.7.2 Deprecating Classes, Objects and Object Properties in *.owl file
To deprecate a class/object or object property in the *.owl file, the
line describing the super-class of the deprecated class/object or object
properties should be altered to reflect the change of the super-class to
_deprecated or deprecatedObjectProperty. Following two snapshots show the
comparison
between the *.owl file code for the two randomly chosen
target terms (ClassToDeprecate and PropertyToDeprecate) before the
deprecation and after the deprecation has been performed. Please note the
difference in the URIs pointing to the super-class of the deprecated
class and object property (the next to the last line of the corresponding
code).
14
Before-after mark-up code comparison for class deprecation
Before-after mark-up code comparison for object property deprecation
15
3.8. Deprecating Annotation Properties
During the ontology development curators sometimes make a decision that a
particular annotation property is not suitable for serving their purpose
in the ontology any more. When such a decision has been made by curation
authorities the subject annotation property has to be deprecated.
Deprecation process has to be performed in NEMO_annotation_properties.owl
file and done MANUALLY USING THE TEXT EDITOR EXCLUSIVELLY. (The reason
for such manual editing is Protégé’s bad behavior of making thoroughly
messed up NEMO_annotation_properties.owl file, as noticed by Paea
LePendu.)
In order to deprecate a no longer needed/used annotation property, but to
still keep track about the information carried by the subject annotation
property, NEMO curation authorities have designed the twofold deprecation
process (intended to be executed when deprecating NEMO annotation
properties only):
1.Target annotation property is replaced by another already existing
annotation property. This is done by “assigning” a new annotation
property to the target annotation property called “isReplacedBy”. By
doing this two important information retention goals are being
accomplished: 1) the information “stored in” soon-to-be deprecated
annotation property has been “re-assigned” (or “re-alocated”) to another
already existing annotation property and thus retained, not deleted or
lost; 2) the information about the status change of to soon-to-be
16
deprecated annotation property has also been saved, which is important
for maintaining good ontology-housekeeping practices.
2. Target annotation property is deprecated by becoming a subdeprecatedAnnotationPorperty.
Put in RDF/XML terms, the critical part of the mark-up code which
determines the “replacement” and deprecation of an annotation property
looks like this:
First line shows that a target annotation property (name not obvious from
the code section above) has been replaced by another annotation property,
here called just “AnnotherAnnotProperty”. Line two shows that the target
annotation
property
has
become
a
sub-property
of
deprecatedAnnotationProperty, i.e. it has been deprecated. Line three is
giving us the information about the date when this editorial change has
been made.
NOTE:
In the case when a particular annotation property just needs to be
dispensed with (and no information about it and/or “stored within it”
needs to be retained), for the purposes of keeping only ONE deprecation
procedure, it still needs to be replaced by another annotation property.
In such situation, that “another annotation property” (that a to-bedeprecated-property is going to be replaced with) is now just an empty
string, meaning that in the mark-up code there is NO CHARACTER in the
place of fragment identifier, that is, no character after “#” (e.g.,
<isReplacedBy>http://nemo.nic.uoregon.edu/ontologies/working/NEMO_annotat
ion_properties.owl#</isReplacedBy> ).
4.0 NEMO Ontologies Version Information, Version Stamping
and Releasing a New Version of NEMO Ontology
======================================================================
4.1 NEMO Ontologies Version Information
Each of the NEMO_*.owl files, at any given point of time MUST have THE
CORRECT VERSION NUMBER SPECIFIED as ontology-level annotation property
coded in owl line as the example showed below:
<owl:versionInfo>v0.95</owl:versionInfo>
The number between the tags should be equivalent to the version number
stamped on the latest NEMO release, excluding the version numbers carried
by the old (not most recent) versions of NEMO ontologies.
17
4.2 Version Stamping and Releasing a New Version of NEMO Ontology
After some period of active ontology development, when deemed stable, a
new set of NEMO ontology *.owl files should be archived with appropriate
correct version stamp. Another copy of the same set of files should be
released to the public. The stable set of the soon-to-be released files
is the one that, at the time instant of releasing event, lives in the
WORKING/ sub-directory. This set of *.owl files will become the new
release/ which in turn will be archived within the old/ sub-directory.
After the releasing procedure has been completed, there SHOULD be TWO
identical copies of stable NEMO_*.owl files carrying the same (and
latest) version number: one within the release/ sub-directory and the
other within the old/ sub-directory.
To perform the version stamping and releasing a
version, several steps must be performed CAREFULLY:
new
NEMO
ontology
1. NEMO curation authorities MUST make a decision about the NEW
VERSION STAMP (NUMBER), i.e. which version number should be assigned to
the soon-to-be released set of stable NEMO_*.owl files.
2. Within the old/ sub-directory of the NEMOontologies a NEW SUBDIRECTORY should be created and the NEW VERSION STAMP (NUMBER) should be
declared as folder name. For instance, if the most recently released
version of NEMO was v0.95, the newly determined version number should be
at least for one number unit greater than the number of the previous
version (v0.96, in this case.)
This new and EMPTY sub-directory carrying the NEW VERSION STAMP NUMBER
will be the home for the archived (i.e. back-up) version of the released
stable set of NEMO_*.owl files.
3. IN ALL the NEMO_*.owl files within the working/ sub-directory the
ontology-level version number in owl line should changed (see 4.1 above).
NEW VERSION STAMP NUMBER (determined by NEMO curators) should be put
between the owl tags and that number MUST BE EQUIVALENT to the number
stamped on the newly-created sub-directory in old/ (v0.96, in our
example).
4. Next step, ALL the NEMO_*.owl files within the working/ subdirectory (carrying the new version number) should be
COPIED (COPY-PASTED NOT CUT-PASTED)
into the release/ sub-directory. By doing this, ALL the previously
existing NEMO_*.owl files within the release/ will be REPLACED by the new
stable files copied from the working/ folder.
5. Do GLOBAL URI ADUSTMENT.
URIs in ALL the newly copied NEMO_*.owl files within the release/,
that were previously pointing to working/ folder, SHOULD BE ADJUCTED TO
POINT TO THE RELEASE/ sub-directory. For instance (please note the
difference):
18
Old URI - Before adjustment:
http://nemo.nic.uoregon.edu/ontologies/working/NEMO_annotation_properties
.owl
New URI - ADJUSTED URI:
http://nemo.nic.uoregon.edu/ontologies/release/NEMO_annotation_properties
.owl
6. After the URI adjustment has been made, ALL the NEMO_*.owl files
within the release/ sub-directory should be
COPIED (COPY-PASTED NOT CUT-PASTED)
into the newly created (empty) folder in the old/ which carries the NEW
STAMP NUMBER. This, version stamped sub-directory in old/, thus becomes
an archived copy (i.e. a back-up) of the new release of NEMO ontology.
The set of *.owl files in this folder MUST HAVE the version number
between the owl:versionInfo tags IDENTICAL to the stamped version number
found in the name of the folder these files are in, and also IDENTICAL to
the version number in the released *.owl files.
After performing the URI adjustment and final, round of NEMO_*.owl file
re-location, please DOUBLE CHECK two important things:
1) whether all the files in all three sub-directories involved
in just performed version number change and re-location have THE
SAME VERSION NUMBER in the corresponding owl code line.
2) whether the URIs in the *.owl files within the release/ are
ALL ADJUSTED and pointing to the release/.
If the answer to the above is “Yes” (both times), then new NEMO ontology
version is ready for release.
7.Notify the BioPortal designee to upload the latest release/ files’
copies to the BioPortal.
8. E-mail all the members of NEMO consortium to notify the users of
the new NEMO release and ask them to do the OBLIGATORY NEMOontologies
folder update INSTANTLY.
After successfully performing the release and archiving, this SHOULD BE
THE STATUS of NEMO ontologies sub-directories and *.owl files:
1. ALL NEMO_*.owl files within the working/, release/ and the newest
sub-directory within old/ should have the same version number EQUIVALENT
to the number stamped on the newest sub-directory within old/.
2. The URIs in ALL NEMO_*.owl files within the release/ and the
newest sub-directory within old/ SHOULD ALL BE THE SAME and pointing to
the release/ (see bullet #5).
3. The URIs in ALL NEMO_*.owl files within the working/ should point
to /working.
19
20