Difference between revisions of "Protege4NamingAndRendering"

From Protege Wiki
Jump to: navigation, search
(→‎New entity creation preferences: updated image)
(→‎Translating ontologies)
 
(13 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
<div class="orangeBox">
 
<div class="orangeBox">
−
<span class="orangeBoxTitle">Naming and rendering of entities in Protege 4.x</span>
+
<span class="orangeBoxTitle">Naming and rendering of entities in Protege</span>
  
−
 
+
This page describes the various options for naming entities in an ontology for Protege 4, 5 and newer.
−
This page describes the various options for naming entities in an ontology.
 
−
 
 
−
''You must install build 65 or higher to access the functionality described on this page.''
 
 
</div>
 
</div>
  
  
−
Back to [[Protege4UserDocs]]
+
'''Back to [[Protege4UserDocs|Protege User Documentation]]'''
  
  
Line 25: Line 22:
  
 
* '''base URI''' the (leftermost) part of the URI that will likely be common across multiple entities (eg '''http://www.co-ode.org/ontologies/pizza/pizza.owl#''').
 
* '''base URI''' the (leftermost) part of the URI that will likely be common across multiple entities (eg '''http://www.co-ode.org/ontologies/pizza/pizza.owl#''').
−
* '''URI fragment''' the part of a URI after the delimiter '''#''' (eg '''Pizza'''). In Protege 4.x, we sometimes broaden this to include the last path element if no fragment is available - particularly for rendering.
+
* '''URI fragment''' the part of a URI after the delimiter '''#''' (eg '''Pizza'''). In Protege, we sometimes broaden this to include the last path element if no fragment is available - particularly for rendering.
  
 
It is common for a base URI to be used across many entities with each having its own unique fragment.
 
It is common for a base URI to be used across many entities with each having its own unique fragment.
  
−
== Naming of entities in Protege 4.x ==
 
  
−
Because URIs will often be fairly long strings, Protege 4.x uses a renderer to show a shortened form of the name.
+
== Rendering of entities in Protege ==
 +
 
 +
Because URIs will often be fairly long strings, Protege uses a '''renderer''' to show a shortened form of the name.
  
−
The renderer can be changed in the preferences and can show the fragment or ending part of the URI, or can show a name provided by an annotation on the entity.
+
The renderer can be changed in the preferences (see below) and can show the fragment or ending part of the URI, or can show a name provided by an annotation on the entity.
  
 
So '''Pizza''' is actually just a rendering of the URI http://www.co-ode.org/ontologies/pizza/pizza.owl#Pizza.
 
So '''Pizza''' is actually just a rendering of the URI http://www.co-ode.org/ontologies/pizza/pizza.owl#Pizza.
Line 39: Line 37:
 
The full URI can always be viewed by hovering over an entity in its tree (the tooltip shows the full name).<br>
 
The full URI can always be viewed by hovering over an entity in its tree (the tooltip shows the full name).<br>
 
Also, the <span style="color:#B87A3D; font-weight:bold;">Refactor | Rename entity</span> menu item always works with the URI - in fact you can see the full URI by just clicking on the checkbox in the rename dialog.
 
Also, the <span style="color:#B87A3D; font-weight:bold;">Refactor | Rename entity</span> menu item always works with the URI - in fact you can see the full URI by just clicking on the checkbox in the rename dialog.
 +
 +
 +
=== Rendering preferences ===
 +
 +
[[Image:Renderer-prefs.png|right|400px]]
 +
 +
There are 4 options for the type of renderer you can select
 +
* '''URI fragment''' the part of the URI following the '''#''' or last '''/''' character
 +
* '''qnames''' (qualified name) the fragment but with a [[#Prefixes...|prefix]] set
 +
* '''annotation values''' uses the value of an entity annotation specified in [[#Annotations...|Annotations...]]
 +
* '''annotation values with prefixes''' uses a combination of the [[#Annotations...|annotation]] value and the qname [[#Prefixes...|prefixes]]
 +
 +
When using the 3rd and 4th option you probably wish to also set the [[#New_entity_creation_preferences|New entities preferences]] to create labels when a new entity is created.
 +
 +
 +
<br style="clear: both;" />
 +
 +
==== Prefixes... ====
 +
 +
[[Image:Prefix-mappings.png|right|400px]]
 +
 +
URIs are long. A short form (prefix) can be specified to represent the commonly used leftmost part of a URI.
 +
 +
eg. if we have a prefix mapping:
 +
  pizza = http://www.co-ode.org/ontologies/pizza/pizza.owl#
 +
 +
then the following class:
 +
  http://www.co-ode.org/ontologies/pizza/pizza.owl#CheeseTopping
 +
 +
can be written much more concisely:
 +
  pizza:CheeseTopping
 +
 +
Prefixes can be configured using the ''Ontology Prefixes'' view.  This view will appear in the default state of the Active Ontology tab and can be added to any tab by clicking Window->Views->Ontology Views->Ontology Prefixes.
 +
 +
The table that is brought up allows the user to add new prefixes by hand or get Protege to generate them from the loaded ontologies.
 +
Several prefixes are available as default.
 +
 +
 +
<br style="clear: both;" />
 +
 +
==== Annotations... ====
 +
 +
[[Image:Annotation-label-prefs.png|right|400px]]
 +
 +
If you have set the renderer to be either of the annotations versions then the ''Configure'' button will allow you to set the annotation properties and languages to be used.
 +
 +
You can specify a list of which annotations are searched for a rendering in order of preference.
 +
 +
eg the setup on the right will first try to find a '''label''' annotation in English, followed by one with no language set. If it fails, then it will look for any '''prefLabel''' it can find.
 +
 +
If the annotations renderer fails to find an appropriate label then it will default to the fragment.
 +
 +
In addition, for each given annotation, you can specify a comma-separated list of languages (again in order of preferences).
 +
 +
<br style="clear: both;" />
 +
 +
== Naming of new entities ==
  
 
Until build 65, new entities were created with respect to the renderer settings, ie:
 
Until build 65, new entities were created with respect to the renderer settings, ie:
Line 53: Line 108:
 
So the automatic naming has been revisited to make this more flexible.
 
So the automatic naming has been revisited to make this more flexible.
  
−
== New entity creation preferences ==
+
=== New entity creation preferences ===
  
−
[[Image:Image:New-entities-preferences.png|right|400px]]
+
[[Image:New-entities-preferences.png|right|400px]]
  
 
A new set of preferences has been created to separate off the renderer from the creation of new entities.
 
A new set of preferences has been created to separate off the renderer from the creation of new entities.
Line 65: Line 120:
  
  
 +
==== Entity URI ====
 +
New entities will be given a URI starting with the base:
 +
* '''Active ontology (default)''' the URI of the currently selected active ontology will always be used as the base URI.
 +
* '''Specified URI''' the user can specify a static URI that is always used as the base.
  
−
=== Default base URI ===
+
Followed by a separator character ('''#''' or '''/''')
−
New entities will be given a URI starting with this base:
 
−
* '''Active ontology (default)''' the URI of the currently selected active ontology will always be used as the base URI (with a separator of # added)
 
−
* '''Specified URI''' the user can specify a static URI that is always used as the base. If no separator is specified then # will be added
 
  
 +
And finally ending with:
 +
* '''user supplied name (default)''' the string typed in when a new entity is being created.
 +
* '''auto ID''' generated automatically (see below).
  
−
=== Entity name ===
 
−
Determines what gets used to create the URI of the new entity and what gets placed in an annotation
 
−
* '''URI fragment''' new entities will have a URI fragment generated. Must be one or the other of below:
 
−
** '''User supplied name (default)''' the string typed in when a new entity is being created
 
−
** '''Auto ID''' generated automatically (see below)
 
−
* '''Create label''' generate an annotation on the new entities containing the selected name (or ID)
 
  
 +
==== Entity label ====
 +
Selecting one or both of the '''create label''' options generate an annotation on the new entities containing the supplied name (or ID).
  
−
=== Entity label ===
+
Selection also enables control over which annotations get produced when labels are being generated.
−
Control over which annotations get produced when labels are being generated.
 
  
−
''Create label'' must be selected for either name or ID in order for these options to be available
 
 
* '''Same as label renderer (default)''' mimicks the current behaviour, the top preferred rendering annotation URI and language will always be used when generating a label
 
* '''Same as label renderer (default)''' mimicks the current behaviour, the top preferred rendering annotation URI and language will always be used when generating a label
 
* '''Custom label''' a static annotation URI and language can be set separately from the renderer preferences
 
* '''Custom label''' a static annotation URI and language can be set separately from the renderer preferences
  
  
−
=== Auto ID ===
+
==== Auto ID ====
 
Create a numerical identifier for new entities.
 
Create a numerical identifier for new entities.
  
Line 101: Line 154:
 
** ''[user]'' the name of the current user
 
** ''[user]'' the name of the current user
 
* '''Suffix''' add a string to the end of the generated ID. The same macros are available as above.
 
* '''Suffix''' add a string to the end of the generated ID. The same macros are available as above.
 +
 +
 +
== Converting URIs to labels ==
 +
 +
Many ontologies have been developed with the meaningful names in the URI fragment.
 +
 +
If you wish to move these names into labels and change the URIs into meaningless IDs, there is a tool for doing this under '''Refactor | Convert entity URIs to labels'''.
 +
 +
Any entities that already have a reasonable label will not be changed (so this is useful if you changed your preferences half way through building).
 +
 +
This refactor uses '''your current new entities preferences''' to determine what labels get generated and how the IDs are created.
 +
 +
 +
== Translating ontologies ==
 +
 +
Using a combination of the annotation renderer and label generation (both described above) it is possible to come up with and view an ontology in a given language.
 +
 +
If you wish to provide multiple labels for internationalization of your ontology, a quick way to do this is using the [https://github.com/co-ode-owl-plugins/matrix matrix plugin].
 +
 +
[http://code.google.com/p/co-ode-owl-plugins/wiki/MatrixViews#Translation Instructions for setting up the translation].
 +
 +
 +
'''Back to [[Protege4UserDocs|Protege User Documentation]]'''

Latest revision as of 20:03, May 23, 2016

Naming and rendering of entities in Protege

This page describes the various options for naming entities in an ontology for Protege 4, 5 and newer.


Back to Protege User Documentation


Note on naming in OWL ontologies

OWL, being a semantic web language identifies all named things (entities) uniquely with URIs (Uniform Resource Identifiers).

Examples of URIs include URLs (web addresses), URNs and others.

eg The Pizza class in the pizza ontology is identified by its URI (http://www.co-ode.org/ontologies/pizza/pizza.owl#Pizza)

As URLs with fragments are often used, it is worth quickly explaining the terminology used later on:

  • base URI the (leftermost) part of the URI that will likely be common across multiple entities (eg http://www.co-ode.org/ontologies/pizza/pizza.owl#).
  • URI fragment the part of a URI after the delimiter # (eg Pizza). In Protege, we sometimes broaden this to include the last path element if no fragment is available - particularly for rendering.

It is common for a base URI to be used across many entities with each having its own unique fragment.


Rendering of entities in Protege

Because URIs will often be fairly long strings, Protege uses a renderer to show a shortened form of the name.

The renderer can be changed in the preferences (see below) and can show the fragment or ending part of the URI, or can show a name provided by an annotation on the entity.

So Pizza is actually just a rendering of the URI http://www.co-ode.org/ontologies/pizza/pizza.owl#Pizza.

The full URI can always be viewed by hovering over an entity in its tree (the tooltip shows the full name).
Also, the Refactor | Rename entity menu item always works with the URI - in fact you can see the full URI by just clicking on the checkbox in the rename dialog.


Rendering preferences

Renderer-prefs.png

There are 4 options for the type of renderer you can select

  • URI fragment the part of the URI following the # or last / character
  • qnames (qualified name) the fragment but with a prefix set
  • annotation values uses the value of an entity annotation specified in Annotations...
  • annotation values with prefixes uses a combination of the annotation value and the qname prefixes

When using the 3rd and 4th option you probably wish to also set the New entities preferences to create labels when a new entity is created.



Prefixes...

Prefix-mappings.png

URIs are long. A short form (prefix) can be specified to represent the commonly used leftmost part of a URI.

eg. if we have a prefix mapping: 

 pizza = http://www.co-ode.org/ontologies/pizza/pizza.owl#

then the following class: 

 http://www.co-ode.org/ontologies/pizza/pizza.owl#CheeseTopping

can be written much more concisely: 

 pizza:CheeseTopping

Prefixes can be configured using the Ontology Prefixes view. This view will appear in the default state of the Active Ontology tab and can be added to any tab by clicking Window->Views->Ontology Views->Ontology Prefixes.

The table that is brought up allows the user to add new prefixes by hand or get Protege to generate them from the loaded ontologies. Several prefixes are available as default.



Annotations...

Annotation-label-prefs.png

If you have set the renderer to be either of the annotations versions then the Configure button will allow you to set the annotation properties and languages to be used.

You can specify a list of which annotations are searched for a rendering in order of preference.

eg the setup on the right will first try to find a label annotation in English, followed by one with no language set. If it fails, then it will look for any prefLabel it can find.

If the annotations renderer fails to find an appropriate label then it will default to the fragment.

In addition, for each given annotation, you can specify a comma-separated list of languages (again in order of preferences).


Naming of new entities

Until build 65, new entities were created with respect to the renderer settings, ie:

  • if the fragment renderer was selected, new entities would be given a URI using the base of the active ontology and a fragment provided by the name the user entered.
  • if the annotation values renderer was selected, new entities would be given:
    • a URI using the base and a "meaningless" numeric fragment provided by the system time
    • an annotation using the preferred URI and language containing the name the user entered

This was not sufficient for several reasons:

  1. the base URI was always the active ontology
  2. the user may not want to automatically create meaningless URIs even if the label renderer was being used
  3. there was no control over the form of the IDs being generated

So the automatic naming has been revisited to make this more flexible.

New entity creation preferences

New-entities-preferences.png

A new set of preferences has been created to separate off the renderer from the creation of new entities.

This gives much more flexibility and control over what gets generated in our ontology.

The pane can be found under File | Preferences... | New Entities
To the right is the new pane with default settings when first opened, some of the advanced features disabled.


Entity URI

New entities will be given a URI starting with the base:

  • Active ontology (default) the URI of the currently selected active ontology will always be used as the base URI.
  • Specified URI the user can specify a static URI that is always used as the base.

Followed by a separator character (# or /)

And finally ending with:

  • user supplied name (default) the string typed in when a new entity is being created.
  • auto ID generated automatically (see below).


Entity label

Selecting one or both of the create label options generate an annotation on the new entities containing the supplied name (or ID).

Selection also enables control over which annotations get produced when labels are being generated.

  • Same as label renderer (default) mimicks the current behaviour, the top preferred rendering annotation URI and language will always be used when generating a label
  • Custom label a static annotation URI and language can be set separately from the renderer preferences


Auto ID

Create a numerical identifier for new entities.

Auto ID must be selected for at least one of the options in Entity name for these options to be available.

  • Numeric (pseudo random) (default) generates an number from the system time (so not currently random at all)
  • Numeric (iterative) generates a sequence of numbers iterating in single steps from the first available (uniqueness only guaranteed for URI fragments)
    • Start the lowest ID that will be allocated
    • End the highest ID that will be allocated (an error will be reported if this is superceded) - set to -1 for no maximum
  • Digit count the length the numeric part of the IDs will be padded/trimmed to - this should always be made big enough to contain the range of IDs you will generate
  • Prefix (recommended) add a string to the start of the generated ID. Macros are available.
    • [type] OWLClass, OWLObjectProperty, etc
    • [user] the name of the current user
  • Suffix add a string to the end of the generated ID. The same macros are available as above.


Converting URIs to labels

Many ontologies have been developed with the meaningful names in the URI fragment.

If you wish to move these names into labels and change the URIs into meaningless IDs, there is a tool for doing this under Refactor | Convert entity URIs to labels.

Any entities that already have a reasonable label will not be changed (so this is useful if you changed your preferences half way through building).

This refactor uses your current new entities preferences to determine what labels get generated and how the IDs are created.


Translating ontologies

Using a combination of the annotation renderer and label generation (both described above) it is possible to come up with and view an ontology in a given language.

If you wish to provide multiple labels for internationalization of your ontology, a quick way to do this is using the matrix plugin.

Instructions for setting up the translation.


Back to Protege User Documentation

Retrieved from "https://protegewiki.stanford.edu/index.php?title=Protege4NamingAndRendering&oldid=13450"