[an error occurred while processing this directive]
USERS
DEVELOPERS
  graph widget tutorial

The Graph Widget is an alternative to Forms for creating and populating instances of classes in Protégé. It is also particularly useful for visualizing networks of instances and relationships between instances. This tutorial assumes a basic working knowledge of Protégé. For more information about how to use Protégé, see our User's Guide or Getting Started with Protege.

Getting Started

Advanced Topics
Known Bugs
Known Feature Requests



Getting Started


Step 1: Download GraphWidgetExample project

For those of you who are familiar with Protégé, you'll recognize this project as a slightly modified version of the Newspaper example. We'll step through the creation of an organization chart for a group of Newspaper employees.

Download Project


Step 2: Configure Organization class


Screenshot of Protégé after completion of step 2:

step 2 -> configure organization class


Step 3: Configure organization_chart slot to use Graph Widget


Screenshot of Protégé after completion of step 3:

step 3 -> configure organization_slot to use graph widget


Step 4: Configure node appearance

Nodes are the objects that appear in the palette on the left-hand side of the Graph Widget. Each node represents a concrete allowed class for the organization_chart slot (or whatever slot is configured to use the Graph Widget). 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:
Screenshot of the Graph Widget configuration dialog:

step 4 -> configure node appearance

The table in the top portion of the Nodes tab contains a list of all the concrete allowed classes for the organization_chart slot. Note that the Employee class does not appear here because it's an abstract class. Rather, all the the concrete subclasses of Employee are displayed. Try selecting various nodes from the table and changing their 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.

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:

step 4 -> configure node appearance

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


Step 5: Configure a simple connector

There are two types of connectors in the Graph Widget. First we will look at the simple connector type, which is a connector between two nodes that doesn't have an underlying instance. The allowed class type for the organization_slot is Employee. Let's assume that we are interested in focusing on the Editor subclass of Employee and seeing a graphical representation of the relationship between editors and other employees in the newspaper organization. There are two steps to complete for configuring a simple connector:
  1. Choose the Editor class in the Class Heirarchy pane on the Classes tab and create and attach a slot called responsible_for. The slot should be of type Instance, cardinality multiple, and have the Employee class as the allowed class type.

    Screenshot of Protégé after completion of step 5a:

    step 5a -> configure simple connector

  2. On the Forms tab, bring up the widget configuration dialog again and select the Editor class on the Nodes tab. Choose responsible_for 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 Editor nodes and other nodes of type Employee. In other words, for each allowed class displayed in the table on the upper portion of the Nodes tab, the Connector Slot combo box will display a list of type Instance, cardinality multiple slots for that class. You can choose one of these slots from the combo box to indicate what other class types you can draw connectors to. Click OK to save your changes.

    Screenshot of widget configuration dialog after completion of step 5b:

    step 5b -> configure simple connector

Step 6: Populate an instance of the Graph Widget using nodes and simple connectors

In this step, we'll look at an instance of the Organization class and learn how to populate the Graph Widget with nodes and simple connectors.

Navigate to the Instances tab and choose the Organization class in the Class Hierarchy pane. Select San Jose Mercury News in the Instance Browser. To create an instance of the Editor class, select the Editor node in the palette and drag and drop it onto the view. Repeat this step again so that you have two nodes in the Graph Widget view. To draw a simple connector between the two Editor 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 responsible_for relationship.

Tips:
Screenshot of San Jose Mercury News Instance Form after completion of step 6:

step 6 -> populate an instance of the graph widget

Continue adding nodes of various types to the Graph Widget. Notice also that the widget will only allow you to draw valid simple connectors between nodes. Since we only specified one connector slot for the Editor class, we can only draw simple connectors from Editor nodes to other nodes, but not the other way around. For example, try drawing a simple connector from a Columnist or Reporter node to another node. The Graph Widget won't allow such a connection.

Additional screenshot of SJ Mercury News Instance Form after adding more nodes and connectors:

step 6 -> populate an instance of the graph widget

Tips:
Step 7: Configure a reified relation

In this step we will work with the other connector type provided by the Graph Widget called a reified relation. 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. There are three steps to configure a reified relation:
  1. Subclass the :DIRECTED-BINARY-RELATION system class.

    • Choose the :DIRECTED-BINARY-RELATION system class in the Class Hierarchy pane on the Classes tab.
    • Create a subclass called Manager Supervision Relation.
    • Change the allowed class type of the :FROM slot to Manager.
    • Change the allowed class type of the :TO slot to Employee.

    What we have just defined is a class that represents a reified relation between Manager and Employee nodes. Note that you can add additional slots to this class to keep track of other information about the relationship. The screenshot below has examples of what sort of "other information" you might want to add. Note that it's not a necessary step in this tutorial to add additonal slots to the Manager Supervision Relation class.

    Screenshot of Protégé after completion of step 7a:

    step 7a -> configure a reified relation

  2. Create a slot to hold reified relations.

    If you want to use reified relations for a particular class, you need to add a slot to the class that designates what the valid relations are for that class. For our example, add a slot to the Organization class called employee_relationships. The slot should be of type Instance, cardinality multiple, and have the Manager Supervision Relation class as the allowed class type.

    Screenshot of Protégé after completion of step 7b:

    step 7b -> configure a reified relation

  3. Tell the Graph Widget which of the slots attached to your class holds reified relations.

    We need to tell the Graph Widget which slot attached to the Organization class has been created to hold reified relations. This is done in the widget configuration dialog:

    • Return to the Forms tab and bring up the widget configuration dialog.
    • Click on the Reified Relations tab.
    • Choose employee_relationships from the Relation Slots combo box.

      Screenshot of widget configuration dialog after completion of step 7c:

      step 7c -> configure a reified relation

      Tips:
      • Use the Line Color, Line Type, and Arrowhead Type combo boxes to change the appearance of the reified relation connectors.
      • Uncheck the Show Browser Text check box if you don't want your reified relation connectors to have labels on them.

    • Click OK to save your changes.
Step 8: Populate an instance of the Graph Widget using nodes and reified relations

In this step, we'll look at a new instance of the Organization class and learn how to populate the Graph Widget with nodes and reified relations.

Choose the Organization class in the Class Hierarchy pane on the Instances tab. Create a new instance of the Organization class called San Francisco Examiner. Using the Graph Widget, create two instances of the Manager class by dragging and dropping the Manager node from the palette onto the view. To draw a reified relation 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, a reified relation appears between the two nodes, showing a managerial relationship.

Screenshot of Protégé after completion of step 8:

step 8 -> populate an instance of the graph widget

Tips:
Continue adding nodes and experimenting with reified relations. To follow is a screenshot of the San Francisco Examiner Instance Form after adding more nodes, reified relations, a simple connector, and completing the tips specified above:

step 8 -> populate an instance of the graph widget



Congratulations! You have now completed the Graph Widget tutorial. If you have further questions, please post them to the protege-discussion mailing list.




Converting from the Diagram Widget to the Graph Widget

The Graph Widget is the new and improved version of the Diagram Widget. The Diagram Widget existed in earlier versions of Protégé (versions 1.7 and earlier). If you have an old Protégé project with diagram instances, you may want to read the following notes (courtesy of Samson Tu) on how to convert existing instances of the Diagram Widget to the Graph Widget.

Assumptions:
1st Scenario:

You have a project that includes the diagram ontology, that has a number of diagram instances, and you do not need to use the existing location information of nodes and connectors.
  1. Make the :DIRECTED-BINARY-RELATION class the parent class of your classes that inherit from the diagram widget Connector class. Your existing subclasses of the Connector class will then inherit the :FROM and :TO slots from the :DIRECTED-BINARY-RELATION class.
  2. In your existing subclasses of the Network class, add a multi-valued slot (you can choose your own name), whose allowed classes include the allowed classes of the existing connectors slot. This slot will be used to hold arc information in the new Graph Widget.
  3. Save the project.
  4. Open the pins file in a text editor.
  5. Globally replace first_object with :FROM and second_object with :TO (assuming that you are not using the first_object or second_object slots for anything else).
  6. Rename the slot connectors in your instances that hold the diagram to the new slot you've defined in step 2.
  7. Save the pins file.
  8. Reload the project.
  9. Change the metaclasses of your old Connector and Network classes to :STANDARD_CLASS (or any metaclass your want).
  10. Drop Connector and Network classes as parents of your classes.
  11. Delete instances of ObjectLocation, Rectangle, and Point.
  12. In the Forms tab, configure appropriate classes and slots in your project (that used to be shown as diagrams) to use the new Graph Widget.
Do not "uninclude" the diagram project from your own project until you have converted all projects that include the project where you specify the classes that make use of the diagram ontology.

2nd Scenario:

You have a project (Project A) that includes another project (Project B) where diagrams are configured and you do not need to use the existing location information of nodes and connectors.
  1. Convert Project B where you specify the classes that make use of the diagram ontology (see 1st scenario above).
  2. In a text editor, open the pins file for Project A. Globally replace first_object with :FROM and second_object with :TO (assuming that you are not using the first_object or second_object slots for anything else).
  3. Rename the slot connectors in your instances that hold the diagram to the new slot name you've defined.
  4. Save the pins file.
  5. You may have to reconfigure the classes of Project A in the Forms tab so that the Graph Widget gets used appropriately. Alternatively, you can "import" the pont and pins files to rebuild the pprj file. When a new pprj file is built, Protégé will copy the widget configuration information from included projects.




Known Bugs

Known Feature Requests

Troubleshooting new nodes

Information about the graphics library used by the Graph Widget

Rather than reinvent the wheel (write our own graphics library), we used a third party graphics library called JGo from Northwoods Software. JGo has no runtime fees but if you'd like to extend the GraphWidget and you need access to the JGo library, contact them to purchase a license.



[an error occurred while processing this directive] [an error occurred while processing this directive] [an error occurred while processing this directive]