View source for Protege5 5 setup for GO Eds

= About this documentation =
These instructions were done on Mac OS. 

= Protege version =

As of July 2019, GO Ontology Editors are using <code>Protege version 5.5.0 </code>

= Download and install Protege =
* Get Protege from [http://protege.stanford.edu protege.stanford.edu]
* Unzip and move the Protege app to your <code>Applications</code> folder. 
* See [https://protegewiki.stanford.edu/wiki/Install_Protege5_Mac Install_Protege5_Mac] for more instructions and troubleshooting common problems.

==Fix memory settings==

Protege needs at least 4G of RAM to cope with the GO, ideally use 12G or 16G if your machine can handle it. 

* If launching from ./run.command, edit run.command to jre/bin/java -Xmx6000M. (Is anybody doing this?)
* If running from Protege.app on a mac, open the /Applications/Protege-5.5.0/Protégé.app/Contents/info.plist file 
** Below the line: <code><string>-Xss16M</string></code>
** Insert another line: <code><string>-Xmx12G</string></code>

==Fix Deprecate Entity functionality==
There is a bug in the Deprecate Entity functionality - it adds <code>OBSOLETE</code> rather than <code>OBSOLETE.</code> in front of (will be fixed at the next Protege release). To fix: 
* Edit the /Applications/Protege-5.5.0/Protégé.app/Contents/Java/conf/deprecation/go.yaml file (inside the Protege App – access it with "Show Package Contents" by Ctrl + Clicking on the Protege Mac App).
* Change line 10 from <code>annotationValuePrefix: OBSOLETE</code> to <code>annotationValuePrefix: OBSOLETE.</code>

== Configuring layout ==
===Adding Views as Windows or as Tabs===
* Go to <code>Windows</code> > <code>View</code> > Select the view you want to insert in the Protege layout.
* The mouse pointer will have a small black target icon above it. 

====Adding a view as a new window====
* Mouse-over the window you want to add a new window to, until you see a blue rectangle splitting the window approximately in half, and click to drop the window there.
[[File:Protege_new_window.jpeg|850px]]]]

====Adding a view as a new tab====
* Mouse-over the middle area of the window you want to add a new tab to, until you see a large blue rectangle covering the entire window to which you want to add a tab, and click to drop the window there.
[[File:Protege_new_tab.jpeg|850px]]

The following tabs are sufficient for GO work: 

* '''Active ontology'''
* '''Entities''' (which also contains tabs for object properties and annotation properties by default)
* '''DL query'''
* [https://github.com/hdietze/protege-obo-plugins/raw/master/org.protege.oboeditor.jar '''OBO Annotation'''] (May not need - looks like all the functionality has been added in the 'Annotations' panel. However if you are used to this plugin you can install it). Can be obtained from <code>File</code> > <code>Check for Plugins</code>
** If you have had the OBO Annotation plugin installed in a previous version of Protégé, you must first remove the old Tab from the layout. Click on the x at the top right corner to remove the window or tab. Then add it where you want it using the instructions above for “Adding Views as Windows or as Tabs".
** Note that the OBO Annotation plugin may not work the first time. After installing the OBO Annotation plugin, close Protege, reopen, and add OBO Annotation view." 
** Note that the OBO Annotation plugin also contains the Obsoletion functionality (Edit > Make entity obsolete)

* The '''layout, id ranges''' (contained in the file: go-ontology/src/ontology/go-idranges.owl), '''user name''' and '''date_created''' parameters should be kept from the previous version. Please check that all parameters are correct before starting to use Protege to edit the ontology.

* Protege has a highly configurable layout and a plugin architecture. You can control which components are visible from the window menu. To insert a view, go to the <code>Entities</code> tab, selecting <code>Window</code>><code>Views</code>><code>OBO Views</code>><code>OBO Annotation</code>. Drag the black circle that appears to the area where you want it and click. The panel will appear.

[[Image:Protege_setup_images-media-image03.png|250px]]

* You can remove plugins by clicking on the arrow at the right of the plugin tab.
* Once the layout is to your liking, go to <code>Windows</code> > <code>Store current layout</code>

==Installing plugins==
If some plugins are not available from the <code>Window</code>><code>Views</code> tab, go to <code>File</code> <code>Check for plugins</code>. '''Note: this takes some time. You can see Protege running by looking at the top right corner for the spinning wheel.'''
The plugin menu will appear, showing available plugins or newer versions of already installed plugins: 

[[File:Plugins menu.jpeg|450px]]

'''Note the checkbox 'Always check for updates on startup''''. It is recommended that you uncheck this box, since this notably slows down launching Protege. 

* '''ELK OWL reasoner''': Used to compute relationship inferences derived from logical definitions. 
** Download from [https://github.com/liveontologies/elk-reasoner/releases] '''Update 2019-07-10: ELK should now be available from the 'Check for plugins' menu.'''
** Add them in the Protege plugins directory by dragging and dropping the file:  
** To see the directory structure, control-click/right click on the <code>Protege app</code/> icon, then select <code>Show Package Contents</code> and drill down to the directory you want. 
** The directory structure is <code>Protege-5.5.0.app/Contents/Java/plugins/</code>. Note there are two plugins folders. Make sure you use the correct one.

The following plugins can be installed from the <code>Protégé menu</code>: 
* '''OntoGraph view:''' This view displays a connected graph of classification (is_a) and other relationship types. 

[[Image:Ontograph plugin.jpg|650px]]
* Both children and parents can be viewed.
* All relations are shown (or at least, many, see screenshot).
* Double click on the <code>+</code> sign in the top left corner of each box to expand that part of the ontology. 
* Mouse over the arrow on an edge to view details about the relation.
* The icon representing logical definitions (LD; <code>≡</code>) is shown on edges that have inferences based on LDs. 
* If terms have logical definitions, those are shown with the icon representing LDs (<code>≡</code>).
* Full instructions can be found at: https://protegewiki.stanford.edu/wiki/OntoGraf

=Instructions for new Protege users=

==Obtaining your ID range==
* Curators and projects are assigned specific GO term ID ranges by senior editors.
* These ID ranges are stored in the file: [https://github.com/geneontology/go-ontology/blob/master/src/ontology/go-idranges.owl go-idranges.owl]
* '''NOTE:''' You should only use IDs within your range.

== Setting ID range ==
* Once you have your assigned ID range, you need to configure Protege so that your ID range is recorded in the Preferences menu. Protege does not read the go-idranges.owl file.
* In the Protege menu, select Preferences.
* In the resulting pop-up window, click on the New Entities tab and set the values as described below.

[[File:SettingIDranges.jpeg|750px]]

# In the <code>Entity IRI</code> section: 
#* <code>Start with:</code> Specified IRI: [http://purl.obolibrary.org/obo http://purl.obolibrary.org/obo]
#* <code>Followed by</code> /
#* <code>End with:</code> Select <code>Auto-generated ID</code>
# In the <code>Entity Label</code> section:
#* Select <code>Same as label renderer</code> option
#** <code>IRI</code> [http://www.w3.org/2000/01/rdf-schema#label http://www.w3.org/2000/01/rdf-schema#label]
# In the <code>Auto-generated ID</code> section:
#* Select <code>Numeric (iterative)</code>
#* <code>Prefix:</code> "GO_"
#* <code>Suffix:</code> ''leave this blank''
#* <code>Digit Count:</code> "7"
#* <code>Start</code> and <code>End:</code> see [https://github.com/geneontology/go-ontology/blob/master/src/ontology/go-idranges.owl go-idranges.owl]. Only paste the number after the <code>GO:</code> prefix.  Also, note that when you paste in your GO ID range, the number will automatically be converted to a standard number, e.g. pasting 0110001 will be converted to 110,001.)
#* Check the <code>Remember last ID between Protege sessions</code> box ('''Note: You want the ID to be remembered to prevent clashes when working in parallel on branches.''')

WARNING: The ID generator in Protege doesn't overwrite existing IRIs, but it can't cope with the OBO alt_id system - where losing IDs following a merge are stored in annotation properties. This system is problematic for OWL translations as it leads to the loss or IRIs. Without IRIs, this ID generator doesn't know about the IDs and will stomp on them if they fall in the specified ID range. Until this is fixed, ??????

We plan to move to a system in which obsolete classes with these IRIs are created for all alt_ids on OBO to OWL translation.

== Setting username and auto-adding creation date ==

# In the Protege menu, go to <code>Preferences</code> > <code>New Entities Metadata</code> tab
# Check <code>Annotate new entities with creator (user)</code> box
# <code>Creator property</code> Add http://www.geneontology.org/formats/oboInOwl#created_by
# <code>Creator value</code> Select <code>Use user name</code>
# Check <code>Annotate new entities with creation date/time</code> box
# <code>Date property</code> Add http://www.geneontology.org/formats/oboInOwl#creation_date
# <code>Date value format</code> Select <code>ISO-8601</code>

[[File:New_entity_metadata.png|550px]]

==Configuring User details==

* In the Protege menu, go to <code>Preferences</code> > <code>User details</code> 
* <code>User name</code>Select <code>Use supplied user name</code>, and use your GOC identity (see your 'xref' in [https://github.com/geneontology/go-site/blob/master/metadata/users.yaml users.yaml]). Enter the initials following ''GO:'' in the users.yaml file.

== Setting Rendering ==

(The default settings may be fine, but details are included for reference)

* In the Protege menu, go to <code>Preferences</code> > <code>Renderer</code> 

Protege allows users to set the annotation property to be used for rendering OWL entities (classes, object properties, annotation properties, individuals) in graphs, trees and text etc. This should be set to <code>rdfs:label</code>, as follows:

[[Image:Protege_setup_images-media-image07.png|350px]]

'''More on rendering.''' All entities in OWL are identified by an IRI (Internationalized Resource Identifier [https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier]). Entities also includes annotation properties such as human-readable labels. In the absence of an annotation to annotation property specified as suitable for rendering, the short form of this IRI (the bit following a '#' or a '/') is displayed. Choosing to render with <code>rdfs:label</code> displays term labels in Protege.

= Protege 5.5.0 new features =
See [https://github.com/protegeproject/protege-distribution/releases Protege wiki - 5.0 new features]

= Review Status =

Last reviewed: July 10, 2019

[http://wiki.geneontology.org/index.php/Ontology_Developmente Back to: Ontology_Development]

[[Category:GO Editors]][[Category:Editor_Guide_2018]]
[[Category:Protege]]