Diagrams: A Guide for the Perplexed



Table of Contents:
  1. What is a Diagram
  2. Walking Through an Example
  3. The Diagram Knowledge Base
1. What is a Diagram

Most user interaction with the Protege GUI is done via forms. Each class has a form associated to it, and each instance is simply a filled out form. For example, the Editor class has an associated form, and instances of Editor are displayed as filled-out forms. This approach facilitates structured data entry for instances. More generally,  it simplifies local interaction with the knowledge base (e.g., looking at and editing small number of instances in great detail). Often, however, users want to be able to view a large number of instances at once, along with selected relationships among the instances.

Diagrams are one way to accomplish this latter goal. A diagram is, visually, a set of nodes and connectors (also known as "links" or "wires") that join the nodes. Underlying these are instances of classes. Nodes map to domain objects and connectors map to instances of Connector-- a class the diagram widget uses to represent important relationships. When the user sees a diagram, they see a high-level summary of a large number of instances, without seeing a lot of the details of any particular instance. For example, in this diagram (which we'll discuss in detail later), 8 nodes, which are instances of 3 distinct classes (represented by distinct shapes and colors), are displayed. In addition, 7 connectors, visually representing the "supervises" relationship are displayed. While the user cannot, for example, immediately determine the social security number of Mr. Science, she does immediately see Mr. Science's place in the organization chart (and, if she is a domain expert, can probably immediately intuit his roles and responsibilities within the organization).
 

2. Walking Through an Example

To make this more concrete, we're going to walk through an example, adding the ability to use the diagram widget to an existing project. In this case, we will be adapting the newspaper project.
 

Step 1:  Load the existing project and decide what you will represent using diagrams

We will use the newspaper project. We will use the diagram widget to visually represent the chain of command in the newsroom (e.g., we will create an organization chart).

Step 2: Make sure the diagram project is included

The next step is to make sure that the project being modified includes the diagrams project (the diagrams  project contains a few key concept definitions the diagram widget requires). The diagram project is included in your Protege-2000 distribution, as part of the examples directory. To see if the diagrams project is already included, you can use the Project menu and choose the Show Included Projects option. If the diagram project is not included,  you can include it by using the Include... option on the Project menu.

Step 3: Find the class you want to use in conjunction with the diagram widget

Our goal is to represent the managerial hierarchy (who reports to whom)  visually  in an organization chart. The newspaper project already contains a class, Organization, which contains this information. So we will start by modifying Organization, to bring it in line with what the diagram widget requires.

Step 4: Make the diagram class from step 3 a subclass of Network and an instance of Network_Metaclass

We need to alter Organization in two ways: we need to make it a subclass of Network and we need to make it an instance of Network_Metaclass. Both Network and Network_Metaclass are defined in the diagrams project we included as part of step 2. Making Organization a subclass of Network, causes 5 template slots to be attached to Organization. These slots will be used by the diagram widget to record information about the visual representation of the diagram (e.g., object locations and connectivity relationships). Making Organization an instance of Network_Metaclass attaches the slot node_slot to Organization as an own slot. We will use node_slot to tell the diagram widget a little bit more about the structure of our intended diagram.

At the end of this step, Organization looks like this.

Step 5: Choose the nodes slot

Once we've finished altering the definition of Organization, we still need to set a value for node_slot. The motivation for using node_slot is this: knowledge-bases should be structured, as much as possible, in ways that make sense to domain experts, based on their experience in the domain. In particular, choosing to use a diagram widget shouldn't alter the knowledge-base structure (in step 4, this precept is violated. But only a little bit, and only by adding slots to classes).

This rule leads to a problem: the diagram widget needs to know where to store the instances corresponding to the nodes in the diagram. Since the instances corresponding to nodes are often instances of important domain concepts, there is usually already a slot that points to them (unlike Connectors. The connectors slot attached to Organization probably isn't redundant with an existing slot). In our example, Organization already has a slot called employees, which points to all the employees in the Organization.

What we need to do is find a way to tell the diagram widget "store the instances corresponding to the nodes in the diagram in this slot." We do this by storing a slot reference in  node_slot does-- the diagram widget stores all the instances corresponding to nodes in a slot, which is the value of  node_slot.

The value of node_slot must meet three criteria: it must be attached to must be attached to Organization as a template slot it must be multiple-valued, and it must be of type Instance. The value of node_slot is the slot is used by the diagram widget to store the instances which are displayed in the diagram as nodes.

In our example, we use the employees slot as the value of node_slot.

Step 6: Create connectors

Connectors are classes whose instances store information about a link in a diagram. A definition of a connector  records two distinct types of information: which types of objects can be connected by this link and which (if any) slots on the objects to fill out. In our example, there is a single type of connector, Supervises. As with all connectors, Supervises is a subclass of Connector and an instance of Connector_Metaclass. An instance of Supervisor can connect an instance of Editor to an instance of Employee. And, when it does so, the supervises slot on the instance of Editor will point to the instance of Employee.

Defining the connectors is the last step which involves modifying the ontology. The remaining steps all involve either configuring the diagram widget or acquiring instances.

Step 7:  Choose which slots to display and select the diagram widget:

The first step in configuring the diagram class  is probably to hide the slots it inherited from Network. These slots are automatically filled out by the diagram widget and contain information that, while important to the structure of the knowledge-base, are slots the user probably won't want to see.
In our example, we hide all of the inherited slots: connectors, last_divider_location, main_panel_height, main_panel_width, and layout_information.

After doing this, we must still choose to use the diagram widget for the employees slot.

Step 8: Configure the diagram widget

Double-clicking on the diagrams widget brings up a panel with an extensive number of configuration options. These options allow the diagram widget to display different types of information (e.g., different node classes) in different ways. In our example, our node types (Editor, Columnist, Reporter, and Salesperson) all have distinct visual representations.

Step 9: Acquire instances

Finally, after all this hard work, knowledge-acquisition can actually take place. Here is a screenshot of the diagram widget in action.

Step 10: Send feedback to the Protege group

The diagram widget is one of the more complex, and cumbersome, widgets that ships with Protege. As you use it, you will undoubtedly notice many shortcomings. We'd like to hear about them. The appropriate venue for comments and discussions is the protege-discussion mailing list.
 
 

3. The Diagram Knowledge Base

The diagrams knowledge base is a small knowledge base which must be included in any project which will use the diagram widget. The diagrams knowledge base contains the following 7 classes:
 
 

Class Name What it Really Represents Role in Diagrams Knowledge Base Role during Ontology Design  Role during Knowledge Acquisition
DiagramEntity Nothing. DiagramEntity  has no conceptual content at all.  DiagramEntity is only used to help organize the diagrams knowledge base ontology-- all other classes in the diagrams knowledge base are subclasses of DiagramEntity.  None. None.
Network Subclasses of  Network are  classes which have some content which can be visualized as a diagram. That is, there is a slot attached to the subclass whose values can be viewed using the diagram widget.  Network is  an abstract superclass of any class whose form will use the diagram widget. It defines 5 slots (connectors, last_divider_location, layout_information, main_panel_height, and main_panel_width) which the diagram widget will use to store information.  Domain classes which will use the diagram widget must be subclasses of Network That is, subclasses of Network are usually domain classes that have been (slightly) altered so that the diagram widget will work. Subclasses of Network  must also be instances of Network_Metaclass in order for the diagram widget to function properly.  Instances of Network, or its subclasses,  will be acquired from the user.
Network_Metaclass None.  Network_Metaclass is used to attach a single own slot, node_slot,  to subclasses of Network.  Subclasses of Network should be instances of Network_Metaclass (rather than :STANDARD-CLASS). node_slot, which will be an own slot on the subclass of Network, must have its value set to a slot which is attached to the subclass of Network being configured.  The value of node_slot is used by the diagram widget. From the usr's point of view, once the ontology is defined, Network_Metaclass can be ignored.
Connector Subclasses of Connector are classes whose instances are visually represented, in a diagram, as a wire. Subclasses of Connector are reified slot-value bindings.  Connector is an abstract superclass which has two slots: first_object and second_object Subclasses of Connector are often not part of the conceptualization of a domain, but instead are explicitly added to the knowledge base in order to visually represent knowledge (*).  Subclasses of Connector must also be instances of Connector_Metaclass in order for the diagram widget to function properly. Instances of Connector, or its subclasses, are usually generated automatically by the diagram widget, and stored in the connectors slot on an instance of Network.
Connector_Metaclass None.  Connector_Metaclass is used to attach a pair of own slots, first_object_slot_pointer and second_object_slot_pointer,  to subclasses of Connector.  Subclasses of Connector should be instances of 
Connector_Metaclass (rather than :STANDARD-CLASS). first_object_slot_pointer and second_object_slot_pointer
don't have to have values. But if a value is set, it should be to a slot which is attached to the appropriate object (e.g., the value of first_object_slot_pointer should be a slot which is actually attached to any object which can be stored in the slot first_object). 
If one of the own slots on a subclass of connector has a value, the diagram widget will attempt to fill in the slot. For example: if first_object_slot_pointer has, as value, the slot foo, then when both the first_object and second_object slots on an instance of the subclass are filled in (e.g., visually when the wire is "connected" at both ends), the diagram widget will fill in the slot foo on the value of first_object with the value of second_object.
ObjectLocation An instance of ObjectLocation records the location of an object. The Location is stored as a Rectangle, the object could be any frame. Used to record visual information. Objects in a diagram have locations that must be stored (so that if a knowledge base is closed and opened later, the diagram will look the same). ObjectLocation has two slots: location and object. None. There is no reason to make any changes to this class, or to create subclasses of it. This class could be entirely hidden during knowledge acquisition. Instances of ObjectLocation are  generated automatically by the diagram widget, and stored in the layout_information slot on an instance of Network.
Rectangle   None. There is no reason to make any changes to this class, or to create subclasses of it. This class could be entirely hidden during knowledge acquisition. Instances of Rectangle are  generated automatically by the diagram widget, and stored in the location slot on an instance of ObjectLocation.
Point None. There is no reason to make any changes to this class, or to create subclasses of it. This class could be entirely hidden during knowledge acquisition. Instances of Point are  generated automatically by the diagram widget, and stored in the upper_left_corner and lower_right_corner slots on an instance of Rectangle.

 

(*) Although there is some debate about this point. As one prominent user of diagrams has stated, "Connector classes represent reified relations, and as such, they should be part of the conceptualization of a domain. It's true that are structured according to the specification of Connector class/metaclass so that they can be visualized, but I think it's better to encourage people to see them as playing a role in the conceptualization of the domain."