View source for Graph Widget Tutorial OWL

<br />
<span style="font-size:18px; font-weight:bold;">Graph Widget Tutorial for OWL Ontologies</span>


<em>This tutorial assumes a basic working knowledge of Protege-OWL.</em>


__TOC__


== What is the graph widget? ==

The graph widget is a custom property widget that serves as an alternative to Protege Forms for creating and/or populating individuals in Protege-OWL. It is particularly useful in the following scenarios:

* visual editing of individuals and relationships between individuals
* visualizing networks of individuals
* visualizing relationships between individuals
* speeding up knowledge acquisition in ontologies with heavily interconnected concepts
* viewing data that resembles process diagrams, flow charts, organizational charts, etc.


== A few words about Protege Forms ==

Before learning to use the graph widget, it is important to understand the concept of a Protege Form.

For each class in your ontology, Protege-OWL generates a default form that can be used to enter data for individual members of the class. Forms contain a data entry field, or "widget" for each property of an individual. There are different types of widgets to handle the various property types, e.g., Protege-OWL assigns a "MultiLiteralWidget" to datatype properties of type string, a "SingleLiteralWidget" for functional datatype properties of type string, etc.

If you do not like the property widgets that Protege-OWL assigns by default, you can customize individual forms on the Forms tab. <em>Please note that the graph widget is only allowed for object properties that accept multiple values (non-functional).</em>


== Download example ontology ==

For the purposes of this tutorial, we will use a simplified version of a clinical trial ontology developed by Ravi Shankar at [[Stanford Center for Biomedical Informatics Research|BMIR]].  For the most part, the concepts in this ontology are self-explanatory.  To follow are some definitions of class names that may be less obvious at first glance:

* '''Aliquot''' – a measured portion of a sample taken for analysis 
* '''Assay''' – a laboratory test to find and measure the amount of a specific substance
* '''Specimen_Protocol''' – protocol for handling a specimen in a clinical trial

In order to follow along with the tutorial in Protege-OWL, please download a copy of the example clinical trial ontology.


== Get started using the graph widget ==

There are a couple of different scenarios in our example ontology that are good candidates for wanting to use the graph widget for knowledge acquisition.  The first scenario is the idea that during the course of a clinical trial, a participant will make multiple visits to a clinical trial facility.  This is something that could be represented by a simple sequence diagram, i.e., one visit, followed by another visit, followed by another visit, etc.  In the following sections, we will perform the necessary steps in Protege-OWL to configure and use the graph widget.

=== Create the has_planned_visits property ===

<ol>
<li>Open Protege-OWL and load the example clinical trial ontology project (ClinicalTrialOntologyLite.pprj).</li>

<li style="padding-top: 5px;">On the OWLClasses tab, notice that we have a class entitled "ScheduleOfActivities", which is intended to model various activities that will take place during the trial.  Another class to take note of is the "Clinical_Trial_Visit" class, which represents a participant's visit to a clinical trial facility during the trial.</li>

<li style="padding-top: 5px;">Navigate to the Properties tab and create a new object property called "has_planned_visits" with ScheduleOfActivities as the domain and Clinical_Trial_Visit as the range. To follow is a screenshot of Protege-OWL after completing this step:
<br /><br />
[[Image:Graph-widget-tutorial_properties-tab.jpg]]
<br /><br />
</li>
</ol>

=== Configure the has_planned_visits property to use the graph widget ===

<ol>
<li>Navigate to the Forms tab and select the ScheduleOfActivities form in the Form Browser pane on the left.</li>

<li style="padding-top: 5px;">In the Form Editor pane on the right, select the has_planned_visits property.  Protege-OWL will outline the property in green once it is selected.</li>

<li style="padding-top: 5px;">Select "GraphWidget" from the "Selected Widget Type" drop-down box in the upper right-hand side of the Form Editor pane. To follow is a screenshot of Protege-OWL after completing this step:
<br /><br />
[[Image:Graph-widget-tutorial_forms-tab.jpg]]
<br /><br />
</li>
</ol>

=== Configure node appearance ===

Nodes are the objects that appear in the palette on the left-hand side of the graph widget.  There will be one node in the palette for each class in the range of the has_planned_visits property (or whatever property is configured to use the graph widget).  In this example, the range only has one class, which is the "Clinical_Trial_Visit" class.  As such, the palette contains one node to represent this class.  Later, we will look at a more complicated example that has multiple nodes in the palette. 

By default, the graph widget assigns all nodes the same shape and color. To change the node shape and color or the text properties of the node's labels:

* Double-click on the has_planned_visits property to bring up the graph widget configuration dialog.
* Select the Nodes tab.

Screenshot of the graph widget configuration dialog:
<br /><br />
[[Image:Graph-widget-tutorial_config-dialog.jpg]]
<br /><br />

The table in the top portion of the Nodes tab contains a list of all the classes in the range of the has_planned_visits property.  Try selecting the Clinical_Trial_Visit class and changing its shape and color using the Shape and Shape Color combo boxes. You can also change the text properties of the node's labels using the Text Color combo box and the Bold and Italic check boxes.  Finally, if you want the node to have a different display name in the palette, you can enter an alternate name in the Display Name text box.  This functionality is useful when your ontology has long class names.  It is often easier when doing knowledge acquisition to see a shorter, more "user friendly" name for a given node in the palette.  For the purposes of this tutorial, we will use the display name of "Visit".

You can ignore the Optional Connector Slot area as we will deal with this in a later step. To follow is a example of what the configuration dialog might look like after configuring node appearance:
<br /><br />
[[Image:Graph-widget-tutorial_config-dialog2.jpg]]
<br /><br />

Click OK to save your changes. <em>(Note that it is not a necessary step in this tutorial to select the same shapes and colors displayed in the screenshot above).</em>

=== Configure a simple connector ===

There are two types of connectors in the graph widget:

* "simple connectors" - a simple connection between nodes with no underlying individual
* "reified relations" - a connection between two nodes that has an underlying individual

In our first scenario dealing with clinical trial visits, we will only use simple connector types.  Later, we will go into a more complicated example that uses reified relations to connect individuals.

Return to the OWLClasses tab and select the Clinical_Trial_Visit class.  Using the Properties View, click the Create object property button to create a new object property called "its_next_visit".  Make the domain and range of the property "Clinical_Trial_Visit" and check the Functional checkbox.  To follow is a screenshot of Protege-OWL after completing this step:
<br /><br />
[[Image:Graph-widget-tutorial_simple-connector.jpg]]
<br /><br />

On the Forms tab, bring up the graph widget configuration dialog again and select the Clinical_Trial_Visit class on the Nodes tab. Choose its_next_visit from the Connector Slot combo box. By making this selection, we are indicating to the graph widget that we want to be able to draw connectors between Clinical_Trial_Visit nodes.  Screenshot of configuration dialog after completion of this step:
<br /><br />
[[Image:Graph-widget-tutorial_config-dialog3.jpg]]
<br /><br />

Click OK to save your changes.

=== Populate the graph widget with nodes and connectors ===

In this step, we will look at an individual member of the ScheduleOfActivities class and use the graph widget to populate the has_planned_visits property with values.

Navigate to the Individuals tab and select the ScheduleOfActivities class in the Class Browser.  Select the schedule_of_activities individual in the Instance Browser.  To create an individual of the Clinical_Trial_Visit class, select the Visit node in the palette and drag and drop it onto the canvas. Repeat this step again so that you have two nodes in the graph widget's canvas. To draw a simple connector between the two nodes, mouse over one of the nodes in an area other than the node label. When the cursor changes from an arrow to a hand, single-click and drag your mouse over to the other node. When you release your mouse over the other node, a connector appears between the two nodes, showing the its_next_visit relationship.


<span style="font-weight:bold; color:red; font-style:italic;">Tips:</span>

* Click on node labels and drag to reposition nodes in the view.
* When a node is selected, grab any of the eight resize handles to resize the node.
* Since the Clinical_Trial_Visit class has a display slot (the has_visit_id property), you can double-click on the node labels and use in-place text editing to change the node's text.
* Double-click on nodes (anywhere except the node label) to bring up individual forms.
* Use the "Create instance" button on the graph widget toolbar to create nodes in the view as an alternative to dragging and dropping from the palette.
* Select multiple nodes and click the "View Selected Instances" button to bring up multiple individual forms.
* Right click on connectors to insert extra points via the Insert Point right-mouse menu item.
* Right click on connectors to remove segments via the Remove Segment right-mouse menu item.
* Use the "Perform Automatic Layout" buttons to automatically layout nodes and connectors in the graph widget.
* Use the "Save Graph as Image" button to save the contents of the graph widget to an image file.


Screenshot of schedule_of_activities individual form after creating nodes and connectors:
<br /><br />
[[Image:Graph-widget-tutorial_individual-form.jpg]]
<br /><br />


== Advanced Topics ==

In order to introduce more advanced topics, we will now move away from our scenario of a sequence of clinical trial visits and instead look at another scenario resembling a process flow.  During the course of a clinical trial, whole blood specimens are collected from trial participants and our example ontology models the protocol for processing those specimens.

Navigate to the OWLClasses tab and take note of the "Specimin_Protocol" class.  This is the class that is intended to model the protocol for handling specimens in the clinical trial.  Also notice the class entitled "Specimen_Protocol_Node", which has several subclasses, each representing some event that occurs during specimen processing.

=== Create the has_specimen_protocol_nodes property ===

Using the Properties View, create a new object property entitled "has_specimen_protocol_nodes" with a domain of Specimen_Protocol and a range that includes all subclasses of the Specimen_Protocol_Node class.  Screenshot of Protege-OWL after completion of property creation:
<br /><br />
[[Image:Graph-widget-tutorial_specimen-nodes-prop.jpg]]
<br /><br />

=== Configure the has_specimen_protocol_nodes property to use the graph widget ===

Navigate to the Forms tab and configure the has_specimen_protocol_nodes property to use the graph widget.  Since the has_specimen_protocol_nodes property has a number of classes in its range, this is a good opportunity to make use of the graph widget configuration dialog to visually differentiate the node types.

=== Configure node appearance and view characteristics ===

On the General tab of the widget configuration dialog, enter a more user-friendly name for the display of the property on the individual form such as "specimen protocol flow":
<br /><br />
[[Image:Graph-widget-tutorial_config-dialog4.jpg]]
<br /><br />

On the Nodes tab, assign different shapes and colors to the classes so that users can easily distinguish the different steps in the protocol flow:
<br /><br />
[[Image:Graph-widget-tutorial_config-dialog5.jpg]]
<br /><br />

<span style="font-weight:bold; color:red; font-style:italic;">Tips:</span>

* Use the View Properties tab to modify the grid style of the canvas (crosses, dots, lines, etc.).
* After clicking OK to save your changes in the widget configuration dialog, double-click anywhere on the background of the Form Editor pane (i.e., away from any of the property widgets) to bring up the Configure dialog for the Specimen_Protocol class.  On the Layout tab, choose the graph widget for the "Fill Vertical Space With" and "Fill Horizontal Space With" options.  This will cause the graph widget to take up any free space on the individual form when editing individuals.


=== Configure a reified relation ===

In our current scenario dealing with specimen protocol flow, instead of using simple connectors, we will use reified relations to connect nodes in the graph. A reified relation is a connector between nodes that has an underlying instance. You use this type of connector when you need to store additional information about the relationship between two nodes.