Tutorials

  1. Setting up SVN and file access
  2. How to get sourceforge access
  3. How to checkout OBI from SVN, install Protege 3.4 and edit it using Protege
  4. Managing OBI's imports
  5. How to reason with OBI in Protege 3.4
  6. Working with OBI version Protege 4
  7. OBI release process
  8. How to import external terms into OBI
  9. Obsoleting terms in OBI
  10. Editing OBI in Protege 3.4
  11. Editing instances

OBI Tutorial from ICBO conference

Contents

SVN

see http://obi-ontology.org/page/General_introduction#SVN

check out latest version of OBI 

 svn co  http://obi.svn.sourceforge.net/svnroot/obi/trunk/src/ontology/

Sourceforge

First, you need to have a sourceforge.net account. If you do not have one, register at sourceforge: https://sourceforge.net/account/registration/ .

Second, email one of the OBI sourceforge administrators listed OBI sourceforge site. Alternatively, email the obi developer mailing list (obi-devel@lists.sourceforge.net). You will very likely be issued the right to access OBI sourceforge. This will allow you to make changes in OBI sourceforge.

Editing

  • Install latest Protege 3.4.1 version from

http://protege.stanford.edu/download/registered.html Use only 3.4.1, other versions are buggy or have reasoning issues

  • Install an svn client. For windows, we recommend

http://tortoisesvn.tigris.org/ for Mac try SmartSVN http://www.syntevo.com/smartsvn/index.html

  • Using the svn client, check out

http://obi.svn.sourceforge.net/svnroot/obi/trunk/src/ontology (If you want to commit changes back to the repository, you will need to use https: instead of http:, and will need a sourceforge password for obi. Contact the project admins to do this - Alan Ruttenberg, Melanie Courtot are admins)

  • Go to the directory: ontology\branches
  • we made some changes 8 Oct 09. There is a new OBI file which gives a widget to help adding annotation properties and curation status etc. These instructions have been updated accordingly
  • download obi.owl, obi-edit.owl and the .template extension files. Rename the obi-edit.pprj.template file to obi-edit.pprj, and obi-edit.repository.template -> obi-edit.repository
  • open the obi-edit.pprj file in protege 3.4.1

(double clicking works on windows)

  • This will give you access to the obi.owl merged file plus annotation assistance widgets. If you use the pprj and Protege 3.4.1 then the rdfs labels will display obi class names automatically.
  • You must select the obi.owl as the active ontology by clicking on the meta data tab, select obi.owl. If you don't do this edits will not propagate to the correct file obi.owl and you'll be editing obi-edit.owl.
  • Pencil icon should be active, if not go to OWL tab, ontology repositories and deselect read only for the relevant file, pencil icon now should be active
  • When new classes are created, they will display as URLs in the class

view until they are assigned an rdfs:label. Add the label as usual - rdfs:label should is listed in the annotation properties.

  • If you are editing OBI we are now working with a merged file rather than a series of branch files(pre mid 2009) therefore:
  • You MUST edit in 3.4.1
  • Do an SVN update of your local repository prior to editing to ensure your files are updated
  • Send email to the devel list before checking out, after checking in
  • Keep edits short, save and reason regularly.
  • OBI imports several ontologies, you can find these in svn at:
  • launch the file using the obi-edit.pprj by clicking on it - you will find on editing that the obi.owl file has been updated and the obi-edit.owl, which imports this file has also been updated. You can also the obi.owl (not the obi-edit.owl) file in 3.4.1. - you won't get the widgets for annotation properties if you chose to edit this file. NOT recommended.
  • As of Mar 2010 reasoning is working in 3.4.1 using Pellet 1.5.2. If reasoning is running slowly you may be importing some parts of OBI from the web. You need to point these at local files.

Imports

  • OBI imports some external ontologies e.g. IAO and these are present in OBI svn - see \obi\trunk\src\ontology\external which you should have checked out - the files you need are .owl extensions in this directory and sub-directories. If you use the obi-edit.pprj it manages these for you. You can also set these manually see below, but this should not be necessary if you use the obi-edit.pprj
  • In protege 3.4.1 (described here for windows) go to OWL tab
  • choose ontology repositories
  • Use the project tab and for each import point the path of the import to the local file you have checked out and force read only - you don't want to be editing imported ontologies.
  • click the + (plus) symbol, choose local folder, browse for the folder you need, and then force read only, you'll need to do this once for each import file in the svn\obi\trunk\src\ontology\external directory: 
 iao.owl
 bfo.owl
 bfo11.owl
 protege.owl
 protege-dc.owl
 ro.owl
 ro_bfo_bridge11.owl
  • Once all the imports are local, you should find reasoning speed improved.

PC Screenshot of Protege repository tav

Reasoning

  • Use Protege 3.4.1 and Pellet 1.5.2 as standard.

If reasoning fails with these try 4, or try the development version java application. In general over-use of axioms and over-modelling will slow reasoning down, so decide if these are really necessary e.g there is a use case. If the pattern has been used already elsewhere then there is a good chance reasoning will be OK. It's a good idea to compare reasoning times before and after editing.

Java 1.5 is highly recommended. Java 1.6 will slow down the reasoning speed. 

google doc explaining a diagnotics application

Authors: Melanie Courtot, Alan Ruttenberg - Alan's google group page and Helen Parkinson.

The aim is to detect problems with the OWL file that cause OBI to reason slowly. Some use of axioms prevents this. The application described provides some support for detecting and visualising these cases and some usage examples are included here. It's bleeding edge, contact Alan for details on usage, or see the google doc link above.

Protege4

Protege4 is OWL2 compatible. Editing OBI using Protege4 has been tested in both Windows and Mac machines in May 2010. It can be used to edit OBI from now on.

  • Downloading Protege4 OBI version

Download OBI friendly Protege4 for windows: http://dl.dropbox.com/u/4905123/Protege_Windows.zip

or Download OBI friendly Protege4 OBI version for Mac: http://dl.dropbox.com/u/4905123/Protege41MAC.zip

  • Starting Protege4 OBI version

For PC users, please go to the 'Protege_Windows' directory after unzip the file. Double click 'run.bat' file which is in the 'Protege_Windows' folder to start Protege4.

Both Java 1.5 and 1.6 worked well when classify using Hermit.

Java 1.5 is recommended for Pellet. Details about setting Java classpath: http://www.cs.waikato.ac.nz/~jcleary/230/jdkdocs/tooldocs/win32/classpath.html and http://faculty.ed.umuc.edu/~arnoldyl/NetBeansTutorials/Setting-Classpath.html.

  • Setting Protege perferences

Click 'File' menu and choose 'Preferences...':

  1. In the 'Renderer' tab, click on the 'Annotations ...' button, add 'en, en-US, !' in the languages column. (Leave the column empty, works well too).
  2. In the 'Reasoner' tab, unselect all but the first two choices ( = Unsatisfiability, and Superclasses are checked).
  3. In the 'Save' tab, make sure XML Writer 'Use XML Entities' is checked off.
  4. To display the class labels rather than the OBI ids, choose 'Render entitities using annotation values' in the 'Renderer' tab.
  5. Hit 'OK' button when you finish the setting

You may need to assign Protege more memory. Details here http://protegewiki.stanford.edu/index.php/Setting_Heap_Size.

  • Opening OBI with protege 4 OBI version

Before running the Protege 4, please check that there is a file catelog-v0001.xml in the ontology/branches directory. The file is needed for Protege 4 to find where the imported ontologies are. If you don't see the file, do a fresh SVN checkout.

  1. Start protege 4
  2. Choose open owl ontology
  3. Select obi.owl from your local copy of OBI obi\obi\trunk\src\ontology\branches.
  4. Reasoner "HermiT" is used for classification. It has better performance. Classification took about 3 minutes.

Need support from Protege group, please indicate it is Protege 4 OBI version.

Have questions about running Protege 4 in PC, please contact jiezheng at pcbi.upenn.edu.

Have questions about running Protege 4 in Mac, please contact Alan Ruttenberg.

Release

The current OBI release process is documented here You may need to request edit privs to this document

We are considering to move OBI release using JAVA based program. Here are discussion about it.

MIREOT

MIREOT refers to the way that terms are imported into OBI from an external ontology e.g, Chebi retaining their namespace.

Paper and OBI wiki page :http://obi-ontology.org/page/MIREOT

Presentation from Melanie Courtot:

http://ashby.csail.mit.edu/web/2008/obi/20091215-MIREOT-NIF/

MIREOT step by step

Requisites: be able to run Perl and Java programs

1. Checkout the OBI files that needed for MIREOT

Check out the related OBI files under: http://obi.svn.sourceforge.net/svnroot/obi/trunk/src/

  • external.owl and externalDerived.owl can be found under /src/ontology/branches
  • add-to-external.pl is under /src/tools
  • external-templates.txt can be found under /src/tools/build


2. Add the minimum information into external.owl for the classes/instances you wish to add.

The minimum information includes the full URI of the terms you want to import, the resource of terms, and which class in OBI they are subclass of or instance of.

The template shown as below.

For a class, the template is: 

 <owl:Class rdf:about="_CHILD_">
   <rdfs:subClassOf rdf:resource="_PARENT_"/>
   <IAO_0000412 rdf:resource="_ONT_"/>
 </owl:Class>

For an instance, the template is: 

 <rdf:Description rdf:about="_CHILD_">
   <rdf:type rdf:resource="_PARENT_"/>
   <IAO_0000412 rdf:resource="_ONT_"/>
 </rdf:Description>

where _CHILD_ is the full URI of the term to be added, _PARENT_ the one of its parent, and _ONT_ the resource from which we import. Note: IAO_0000412 is the "imported_from" annotation property.

2.1 Add the minimum information into external.owl manually

Example 1:

If you want to import "cell" in Cell ontology which ID is CL_0000000 from the resource http://purl.org/obo/owl/CL , to be a subclass of "MaterialEntity" in OBI, you need to add the following piece of information into external.owl. 

 <owl:Class rdf:about="http://purl.org/obo/owl/CL#CL_0000000">
   <rdfs:subClassOf rdf:resource="http://www.ifomis.org/bfo/1.1/snap#MaterialEntity"/>
   <IAO_0000412 rdf:resource="http://purl.org/obo/owl/CL"/>
 </owl:Class>

where 

 _CHILD_ is http://purl.org/obo/owl/CL#CL_0000000
 _PARENT_ is http://www.ifomis.org/bfo/1.1/snap#MaterialEntity
 _ONT_ is http://purl.org/obo/owl/CL

Example 2:

If you want to import "gram" in Units of measurement ontology which ID is UO_0000021 from the resource http://purl.org/obo/owl/UO, to be an instance of UO_0000002 mass unit, you need to add the following piece of information into external.owl. 

 <rdf:Description rdf:about="http://purl.org/obo/owl/UO#UO_0000021">
   <rdf:type rdf:resource="http://purl.org/obo/owl/UO#UO_0000002"/>
   <IAO_0000412 rdf:resource="http://purl.org/obo/owl/UO"/>
 </rdf:Description>

where 

 _CHILD_ is http://purl.org/obo/owl/UO#UO_0000021
 _PARENT_ is http://purl.org/obo/owl/UO#UO_0000002
 _ONT_ is http://purl.org/obo/owl/UO

2.2 Add the minimum information into external.owl using add-to-external.pl

This piece of information can be automatically added into external.owl using a Perl script "add-to-external.pl" which is under /src/tools. Currently, the Perl script can handle the terms which resources are PATO, PRO, FMA, CHEBI, GO, CL, NCBITaxon, ENVO, RNAO, SO, UO, UBERON, VO, NIF-GrossAnotomy.

The command to run the script of adding a class: 

 perl add-to-external.pl CHILD_ID PARENT_ID [path to external.owl]

The command to run the script of adding an instance: 

 perl add-to-external.pl instance CHILD_ID PARENT_ID [path to external.owl]

(The command is run under the directory where contains add-to-external.pl file)

For example 1 shown above, import "cell" in Cell ontology which ID is CL_0000000 to be a subclass of "MaterialEntity" in OBI. You can the following command: 

 perl add-to-external.pl CL:0000000 snap:MaterialEntity

For example 2 shown above, import "gram" in Units of measurement ontology which ID is UO_0000021 to be an instance of UO_0000002 mass unit. You can the command shown below: 

 perl add-to-external.pl instance UO:0000021 UO:0000002

2.3 Check external.owl file

After adding the minimal information of external terms into external.owl, reload the project in Protege. You should see your classes in the obi hierarchy, but with no anotations, not even label. If this work, you can go to the next step.

3. Generate externalDerived.owl

3.1 Download the required files

Download the jar files from the website: http://code.google.com/p/lsw2/downloads/list

You need both lsw.jar and owltool.jar.

Get help of the jar files run command: 

 java -jar lsw.jar -m owltool.jar -help

(The command is run under the directory that contains both lsw.jar and owltool.jar)

3.2 Delete externalDerived.owl (which is under /src/ontology/branches)

3.3 Run program to generate externalDerived.owl

The command is: 

 java -jar lsw.jar -m owltool.jar -create-external-derived <external.owl> -template <external-template.txt> -dest <externalDerived.owl> -ontology-iri "http://purl.obolibrary.org/obo/obi/externalDerived.owl"

where 

 <external.owl> is the location of external.owl file.
 <external-templates.txt> is the location of OBI's externals template file for creating the externalDerived.owl. The template file can be found under checked /src/tools/build directory.
 <externalDerived.owl> is the output file which should be the one you would like to replace the old externalDerived.owl. 
 The "-ontology-iri" argument is the URI of the externalDervived.owl. For OBI external derived file, it should be "http://purl.obolibrary.org/obo/obi/externalDerived.owl".


Example:

I checked out http://obi.svn.sourceforge.net/svnroot/obi/trunk/src/ under "C:/Documents and Settings/Jie/My Documents/Ontology/obi/trunk/src/" and download lsw.jar and owltool.jar under "C:/obi-lsw" in my PC.

The command used to generate externalDerived.owl is: 

 java -jar lsw.jar -m owltool.jar
 -create-external-derived "C:/Documents and Settings/Jie/My Documents/Ontology/obi/trunk/src/ontology/branches/external.owl"
 -template "C:/Documents and Settings/Jie/My Documents/Ontology/obi/trunk/src/tools/build/external-templates.txt"
 -dest "C:/Documents and Settings/Jie/My Documents/Ontology/obi/trunk/src/ontology/branches/externalDerived.owl"
 -ontology-iri "http://purl.obolibrary.org/obo/obi/externalDerived.owl"

After run the command, the new external derived owl file is generated and named as "externalDerived.owl".

3.4 Check externalDerived.owl file

Reload the project in Protege. You should see the terms you wish to import in the obi hierarchy with label and some other annotations. If everything looks fine, check both external.owl and externalDerived.owl in. You are DONE.

4. Add new resources for MIREOT

Currently, the programs can handle the terms which resources are PATO, PRO, FMA, CHEBI, GO, CL, NCBITaxon, ENVO, SO, UO, UBERON, VO, NIF-GrossAnotomy. To add other resources for MIREOT, two files may need to be modified.

4.1 add-to-external.pl which is under /src/tools

In this perl script, add the resource name, IRI and the pattern of ID it used. For example: 

 ["UO", "http://purl.org/obo/owl/UO#UO_", "http://purl.org/obo/owl/UO","\\d{7}","UO:0000683"]

4.2 external-templates.txt which is under /src/tools/build

You may need to add SPARQL query like template for the new resources. Current templates can be applied to all (almost all) OBO foundry ontologies.

http://sparql.obo.neurocommons.org/sparql/ is used as endpoint. Before add the new template, please try the SPARQL query on the SPARQL form first, http://sparql.obo.neurocommons.org/

After testing the modified files work properly to import terms from new resources, please commit your changes.

If you need help, please contact Alan Ruttenberg at alanruttenberg at gmail.com.

Obsoletion

See policy http://obi-ontology.org/page/OBI_Deprecation_Policy , IMPORTANT, deprecated terms need to be advertised to the list prior to deprecation, see policy link


Step by step:

Checkout a fresh update of OBI, open in 3.4.1

1. remove any child classes of your term-to-be-deprecated to sensible parent, drag and drop one by one

2. add reason for deprecation property to the term-to-be-deprecated - use the widget - scroll down in the class editor, and select a term from the list e.g. failed exploratory term

3. add replacement term property if there is one

4. add prefix to rdfs label obsolete_

5. remove from existing parent class

6. add Obsolete parent class

7. remove any logical definitions and check used by in Protege. Click the blue arrow icon left on class editor panel. This will tell you if your term-to-be-deprecated is used in any other classes. You need to remove these as well.

8. save

9. open and reason over in p4, check consistency - if you leave the old parent and the obolste one will generate an inconsistency

10. if OK check in as a new file with an svn log

EditingOBI

To edit OBI in Protege 3.4

1. Click on the obi-edit.pprj file - this will open the OWL file in Protege 3.4 and will render all properties etc with rdfs labels

2. Click on the meta data tab, select the obi.owl

3. Click Pencil icon. (Pencil icon should be active, if not go to OWL tab, ontology repositories and deselect read only for the relevant file.)

4. Navigate to the classes for adding/editing/deleting classes or instances tab for adding/editing/deleting instances. Instances for a given class are shown when navigate to the instance tab. Choose the class you want to add sibling or subclasses to or add instances for and add these.

5. To add a class - click on 'create subclass' or 'create sibling class' icon (two dots linked by lines with a plus). Add rdfs label, definition, 'has curation status', restriction etc.

6. To add an instance - click on the diamond with a plus - this will add instances for the selected class. Add rdfs labels, definitions, restrictions etc.

For minimal requirement of meta data for a term in OBI, please check http://obi-ontology.org/page/OBI_Minimal_metadata

7. Save and reason over in p4 using Hermit before committing, commit the obi.owl.

Instances

To edit OBI instances e.g. for the investigation use case

1. Click on the obi.pprj file - this will open the OWL file in 3.4.1 and will render all properties etc with rdfs labels

2. Click on the meta data tab, select the instances file e.g. Investigation-use-case.owl

3. Pencil icon should be active, if not go to OWL tab, ontology repositories and deselect read only for the relevant file. If you need to add a class then you'll be editing the obi.owl so repeat the process for selecting the active ontology but select the obi.owl file.

4. Navigate to the instances tab. Instances for a given class are shown, unless click on owl thing when all are shown. Choose the class you want instances for and add these

4. To add an instance - click on the diamond with a plus - this will add instances for the selected class. Add rdfs labels, definitions, restrictions etc.

5. Save and reason over in p4 before committing, if you've edited classes and instances commit both the obi.owl and investigation-use-case.owl

Retrieved from "http://obi-ontology.org/page/Tutorials"

Search

Tools

This page