Tutorials


 * 1) Setting up SVN and file access
 * 2) How to get sourceforge access 
 * 3) Things to do for editing OBI
 * 4) Imports external ontologies locally 


 * 1) Working with Protege 4
 * 2) OBI release process
 * 3) How to import external terms into OBI - MIREOT

OBI Tutorials at ICBO conferences
 * 1) Obsoleting terms in OBI

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

check out latest version of OBI svn co http://svn.code.sf.net/p/obi/code/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
http://protege.stanford.edu/download/registered.html
 * Install latest version Protege (v 4.3), details see Working with OBI version Protege 4

for window users: http://tortoisesvn.tigris.org/ for Mac users: may try SmartSVN http://www.syntevo.com/smartsvn/index.html
 * Install an svn client. We recommend

https://svn.code.sf.net/p/obi/code/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 - Jie Zheng, Alan Ruttenberg, Melanie Courtot are admins)
 * Using the svn client, check out


 * 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 for editing to announce obi owl file is locked, and after checking in to indicate the file is unlocked


 * Keep edits short, save and reason regularly. Hermit is recommended reasoner to use.

https://svn.code.sf.net/p/obi/code/trunk/src/ontology/external
 * OBI imports several ontologies, you can find these in svn at:

Imports

 * OBI imports some external ontologies e.g. IAO and these are present in OBI SVN - see \src\ontology\external which you should have checked out - the files you need are .owl extensions in this directory and sub-directories.


 * In checkout \src\ontology\branches directory, there is a configuration file, catalog-v001.xml, which set Protege load imported ontologies from local files.

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

http://protege.stanford.edu/download/download.html


 * Setting Protege preferences

Click 'File' menu and choose 'Preferences...':
 * 1) In the 'Renderer' tab, click on the 'Annotations ...' button, add 'en, en-US, !' in the languages column.
 * 2) OBI users may want to change 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) 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. If the OBI classes are still displaying as IDs, go the the 'Renderer tab', click on the 'Annotations ...' button, select 'label', leave the language column blank and hit ok.
 * 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.

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:    

For an instance, the template is:    

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.     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.     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/OBIDeprecationPolicy, IMPORTANT, deprecated terms need to be advertised to the obi-dev mailing list (obi-devel@lists.sourceforge.net) prior to deprecation. The terms can be deprecated if no objection in a week.

Step by step:

Checkout a fresh update of OBI, open in Protege

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

2. remove all logical axioms of term-to-be-deprecated, you can copy axioms to the editor notes as record

3. make sure no any other terms use term-to-be-deprecated, check usage tab

4. add reason for deprecation property to the term-to-be-deprecated by adding annotation 'has obsolescence reason', choose predefined terms (e.g. 'failed exploratory term', 'placeholder removed' , 'terms merged' , 'term imported' , 'term split') from 'Entity IRI' tab's 'Individuals' tab and add replacement term property if there is one

5. add prefix to rdfs label obsolete_

6. remove from existing parent class

7. add annotation 'deprecated' with value "true" and type "boolean"

8. save

9. 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