Difference between revisions of "Ontology workflow"

From phenoscape
(Created page with "ZigVersion is the SVN client we use for keeping local copies of ontologies on your computer synchronized with those in the SVN (SubVersion server) * Note: we will start using Sma...")
 
 
(5 intermediate revisions by one other user not shown)
Line 1: Line 1:
−
ZigVersion is the SVN client we use for keeping local copies of ontologies on your computer synchronized with those in the SVN (SubVersion server)
+
====Using Version Control ====
−
* Note: we will start using SmartSVN because ZigVersion is no longer being developed or maintained.
+
SmartSVN is the SVN client we use for keeping local copies of ontologies on your computer synchronized with those in the SVN (SubVersion server)
 +
To get SmartSVN, go to their site [http://www.smartsvn.com/SmartSVN]].
 +
 
 +
Do an SVN checkout of [http://phenoscape.svn.sourceforge.net/viewvc/phenoscape/trunk/vocab/]
 +
Contact Hilmar or Jim if you need help with passwords.
  
 
General workflow; begin each day by:
 
General workflow; begin each day by:
−
Starting up Zigversion and connect to repository
+
Starting up SmartSVN and update the edit (phenoscape-ext) directory.
 +
 
 +
===Read Me File===
 +
 
 +
NOTE that there is a "Read Me" file in the phenoscape-ext directory here:
 +
[http://phenoscape.svn.sourceforge.net/viewvc/phenoscape/trunk/vocab/edit/README.txt?view=log]
 +
 
 +
The content here is to get you started, but you should always be working in such a way as to be consistent with the Read Me file. Look for updates to this file when you update your SVN.
 +
 
 +
===Setting up your ID range===
 +
 
 +
Ensure that you have Protege configured to generate new IRIs in your own range. The ranges are indicated in this file:
 +
[http://phenoscape.svn.sourceforge.net/viewvc/phenoscape/trunk/vocab/edit/phenoscape-idranges.owl?view=log]
 +
You can adjust the ID range in the preferences panel, New Entities tab.
 +
 
 +
Note that if you edit multiple files, you need to check this every time to ensure that the proper settings are in place. ALWAYS check the URI of the first class you create in each session to see that it is working properly.
 +
 
 +
== Ontology definitions ==
 +
Term definitions are important because they facilitate consistent use of a term in annotation of disparate data types by different curators.  Ontologies follow the convention that each term should have a textual definition of the genus-differentia form, i.e., a subclass structure of A is an A that has properties X and Y that distinguish it from the other subclass structures of A (Smith et al. 2007).
 +
 
 +
The entity term B is defined by its membership in higher category entity A and distinguished from its sibling terms by characteristic X. Entity definitions are primarily based on structural criteria.  Distinguishing characteristics (X) can include the location, shape, and a list of the parts of the entity.
 +
 
 +
The following are examples of genus-differentia definitions in the Teleost Anatomy Ontology:
 +
#''Antorbital:'' Dermal bone that is located on the anterior margin of the infraorbital series, dorsal to the first infraorbital and lateral to the nasal bone.
 +
#''Dentary:'' Dermal bone that forms the anterolateral part of the lower jaw.
  
−
For ontology editing, use the “Vocab” URL in Zigversion. “Vocab” folder contains ontology files for OBO-Edit.
+
In example 1, the definition mentions the parent dermal bone of the term antorbital, followed by the characteristics that differentiate antorbital from all other dermal bones.
−
Select the top-level folder named with a forward slash (/)
 
−
Click "update" to download recent versions of files to your local, working folder
 
  
−
Within OBO-edit, open the local copy of your file and proceed with your curation work.
+
Comments: Taxonomic statements to be applied to a structure, which are not universals, are recorded in the comment field for that term. For example, Weberian apparatus (TAO: 0001188 ) has the following definition: “Anatomical cluster that consists of the modified anteriormost vertebrae and associated structures that connect the swim bladder to the inner ear.,” and the following is recorded in the comment field: “Vertebra 1-4, and sometimes vertebra 5 in some catfishes, are part of the Weberian apparatus. Weberian apparatus is present in Otophysi.”  Here the statements about components of the Weberian apparatus do not universally apply to all teleosts, but is included in the comment field because this information is potentially helpful to the ontology user for general understanding  and for identifying structures.
−
After saving your file, go back to ZigVersion and “check in” your modified file(s) to the repository. Remember to add a comment to the bottom of the check in window describing the changes you made to the file.
 
  
−
Wasila uses SmartCVS as the CVS client for obtaining local copies of ontologies on the OBO CVS server.  Question: do all curators need this? Could also download ontologies directly from OBOFoundry and Phenoscape ontologies are kept in SVN.
 
  
−
====Making ontology updates using ZigVersion and OboEdit====
+
===Making ontology edits using Protege 4===
−
1. Start OboEdit. Go to File>Load ontologies.
 
−
Select the correct “stored adapter settings” for the ontology you want to update
 
−
Nizar will have VAO-edit and Amniote-draft settings saved
 
−
Browse Path or URL will connect to the local copies of these ontologies
 
−
Make sure “allow dangling references” is checked
 
  
−
4. ID profile mismatch message: hit yes
+
1. Start P4. Go to File>Load ontologies.
 +
Navigate to Phenoscape-ext on your versioned directory on your hardrive.
  
−
5. Make edits...
+
2. Switch on the Elk reasoner. If you are making changes, be sure to
 +
synchronize the reasoner. If you do not have the ELK reasoner, you can get it here:
 +
[http://code.google.com/p/elk-reasoner/downloads/list]
  
−
6. When adding a new term, make sure a high ID number is assigned. If assigned number is XX:0000000, then fix the ID in the ID Manager panel under Metadata. Click “+” to add new ID profile; Then hit gears button. Give Profile name (e.g., TAO) and Default rule (e.g., TAO:$sequence(7,0,9999999)$). Hit commit.
+
You have access rights to any classes that are highlighted in bold font. Do not make changes to classes that are NOT in bold - changes here go through the uberon tracker, or be brought up on the mailing
 +
list. Note that it is fine for any request to go on the uberon tracker.
 +
The tracker is here: [https://github.com/cmungall/uberon/issues?direction=desc&sort=created&state=open]
  
−
7. Saving to local file
+
3. Saving to same file location regularly.
−
File>Save as. Ignore non-fatal warnings.Create new “stored adapter settings” for your ontology.  In Tag filtering, uncheck “modification date”, “modified by”, “creation_date”, and “created_by”.
 
−
Make sure “filter tags” and “allow dangling parents” are checked.
 
−
ID rules: select “Write originally loaded ID rules”
 
−
Hit OK, overwrite is OK.
 
  
−
8. Save to SVN repository
+
4. Commit regularly. Always describe the changes you have made at a high level in the svn commit messages. These are searchable in the logs and very helpful for troubleshooting. It is ok to be verbose, it is not ok to be too terse. Always do a "svn diff" before committing to look at your changes. It is easier to look at a few changes, as there are often serialization changes from Protege, usually you can see that things have moved around but not really changed. You should be able to identify the intended changes.
−
Open Zigversion
 
−
Navigate to ontology file and hit “View changes” to verify your updates
 
−
Hit “check in” and add a comment (e.g., “added new terms: scapula, coracoid) and hit check in.
 
  
−
Opening ontology files in OBO-Edit  --
+
5. Commit to SVN repository
−
1. Create new “Stored adaptor settings” for each ontology (e.g., VTO, VAO, AMAO)
 
−
2. Hit “+” button next to stored adapter settings field, and type in ontology name
 
−
3. Hit “add” button to specify the ontology file location; hit “browse” to find the file
 
  
−
OORT for reasoning
+
===Fulfilling ORB requests===
  
−
Anatomy ontology call minutes, development plans
+
1. Go to the ORB tracker here: http://rdf.phenoscape.org/provisional/
−
http://phenoscape.org/wiki/Anatomy_Ontology_Conf_calls
 
  
−
http://phenoscape.org/wiki/Ontologies
+
2. Implement a request as per the ReadMe and instructions above.
  
−
https://phenoscape.org/wiki/Project_Plan
+
3. Commit, and then wait for the Jenkins build to tell you the build was successful here: http://build.berkeleybop.org/view/Anatomy/job/build-phenoscape/
  
−
Recent phenoscape-curators discussions:
+
4. Add the URI/IRI to the ORB tracker.
−
http://sourceforge.net/mailarchive/forum.php?forum_name=phenoscape-curators
 
  
−
Open issues
+
This process will ensure that the new entity is available to Phenex when indicated in the ORB tracker.
−
- provenance documentation in ontologies
 
−
- terminology vs. ontology; use of synonyms (related; incorrect); produce ‘slim’ version of VAO/AMAO for archosaur group
 
−
- tracker items: see CARO tracker, VAO tracker, Uberon tracker
 

Latest revision as of 19:20, 18 December 2012

Using Version Control

SmartSVN is the SVN client we use for keeping local copies of ontologies on your computer synchronized with those in the SVN (SubVersion server) To get SmartSVN, go to their site [1]].

Do an SVN checkout of [2] Contact Hilmar or Jim if you need help with passwords.

General workflow; begin each day by: Starting up SmartSVN and update the edit (phenoscape-ext) directory.

Read Me File

NOTE that there is a "Read Me" file in the phenoscape-ext directory here: [3]

The content here is to get you started, but you should always be working in such a way as to be consistent with the Read Me file. Look for updates to this file when you update your SVN.

Setting up your ID range

Ensure that you have Protege configured to generate new IRIs in your own range. The ranges are indicated in this file: [4] You can adjust the ID range in the preferences panel, New Entities tab.

Note that if you edit multiple files, you need to check this every time to ensure that the proper settings are in place. ALWAYS check the URI of the first class you create in each session to see that it is working properly.

Ontology definitions

Term definitions are important because they facilitate consistent use of a term in annotation of disparate data types by different curators. Ontologies follow the convention that each term should have a textual definition of the genus-differentia form, i.e., a subclass structure of A is an A that has properties X and Y that distinguish it from the other subclass structures of A (Smith et al. 2007).

The entity term B is defined by its membership in higher category entity A and distinguished from its sibling terms by characteristic X. Entity definitions are primarily based on structural criteria. Distinguishing characteristics (X) can include the location, shape, and a list of the parts of the entity.

The following are examples of genus-differentia definitions in the Teleost Anatomy Ontology:

  1. Antorbital: Dermal bone that is located on the anterior margin of the infraorbital series, dorsal to the first infraorbital and lateral to the nasal bone.
  2. Dentary: Dermal bone that forms the anterolateral part of the lower jaw.

In example 1, the definition mentions the parent dermal bone of the term antorbital, followed by the characteristics that differentiate antorbital from all other dermal bones.

Comments: Taxonomic statements to be applied to a structure, which are not universals, are recorded in the comment field for that term. For example, Weberian apparatus (TAO: 0001188 ) has the following definition: “Anatomical cluster that consists of the modified anteriormost vertebrae and associated structures that connect the swim bladder to the inner ear.,” and the following is recorded in the comment field: “Vertebra 1-4, and sometimes vertebra 5 in some catfishes, are part of the Weberian apparatus. Weberian apparatus is present in Otophysi.” Here the statements about components of the Weberian apparatus do not universally apply to all teleosts, but is included in the comment field because this information is potentially helpful to the ontology user for general understanding and for identifying structures.


Making ontology edits using Protege 4

1. Start P4. Go to File>Load ontologies. Navigate to Phenoscape-ext on your versioned directory on your hardrive.

2. Switch on the Elk reasoner. If you are making changes, be sure to synchronize the reasoner. If you do not have the ELK reasoner, you can get it here: [5]

You have access rights to any classes that are highlighted in bold font. Do not make changes to classes that are NOT in bold - changes here go through the uberon tracker, or be brought up on the mailing list. Note that it is fine for any request to go on the uberon tracker. The tracker is here: [6]

3. Saving to same file location regularly.

4. Commit regularly. Always describe the changes you have made at a high level in the svn commit messages. These are searchable in the logs and very helpful for troubleshooting. It is ok to be verbose, it is not ok to be too terse. Always do a "svn diff" before committing to look at your changes. It is easier to look at a few changes, as there are often serialization changes from Protege, usually you can see that things have moved around but not really changed. You should be able to identify the intended changes.

5. Commit to SVN repository

Fulfilling ORB requests

1. Go to the ORB tracker here: http://rdf.phenoscape.org/provisional/

2. Implement a request as per the ReadMe and instructions above.

3. Commit, and then wait for the Jenkins build to tell you the build was successful here: http://build.berkeleybop.org/view/Anatomy/job/build-phenoscape/

4. Add the URI/IRI to the ORB tracker.

This process will ensure that the new entity is available to Phenex when indicated in the ORB tracker.

Retrieved from "https://wiki.phenoscape.org/wg/phenoscape/index.php?title=Ontology_workflow&oldid=10456"