TMTab User's Guide

Kal Ahmed


Table of Contents

1. Introduction
What Is TMTab ?
2. Getting Started
Installation
Installation Prerequisites
Installation Procedure
Creating A Topic Map
Creating A Topic
Creating Names
Creating Occurrences
Creating An Association
My First Topic Map
3. Exporting the Topic Map
Export Configuration
4. Creating a Topic Map-based Ontology
Subclassing TOPIC
Constraining Topic Type
Creating a Controlled Occurrence
Creating a Controlled Name
Creating an Association-specifying slot
Subclassing Association
5. Conclusion
Reporting Bugs

Table of Contents

What Is TMTab ?

What Is TMTab ?

TMTab is a Tab-Widget plugin and base ontology for Protégé-2000 which allows the user to create and populate an ontology which may then be exported as an XTM format Topic Map. Currently, TMTab only supports the export of ontologies which are derived from its own base topic map ontology. However, the TMTab topic map ontology has some flexible featues which should make a mapping an existing ontology into the TMTab topic map ontology relativey straightforward.

In addition to providing a base ontology for topic maps, TMTab allows topic map ontology designers to express constraints on their topic map ontology and for those constraints to be enforced by Protégé. The TMTab topic map ontology also supports the author by enabling a number of short-cut mechanisms, such as the ability to define an association between two instances by simply making one a slot-value of the other.

TMTab is experimental software and is released now for the purpose of community evaluation only. Feedback on TMTab would be gratefully received by the author.

Installation

Installation Prerequisites

Before installing TMTab, you must install Protégé. The Protégé software may be downloaded from http://www.smi.stanford.edu/projects/protege/index.html. TMTab was built against and should only be installed on version 1.6 beta (build 813 or later).

Installation Procedure

To add TMTab to your Protégé installation you must:

  • Unzip tmtab.zip into a temporary directory
  • Copy the directories plugins and projects from the temporary directory into your Protégé installation directory.
  • Restart Protégé
  • open the file projects/topicmap/topicmap.pprj
  • From the "Project" menu, select ""Configure..."". In the dialog that appears, check the entry labelled "TMTab".
  • You should now have an additional tab in the Protégé window labelled "Topic Map"

Note

Once you have restarted Protégé, if you do not see the TMTab entry in the configure dialog, the most likely cause is that tmtab.jar is not in the plugins subdirectory of your Protégé installation - if necessary, copy the file from the temporary directory into the plugins directory by hand and then restart Protégé.

Creating A Topic Map

The basic topic map ontology shipped with TMTab enables you to start creating topic maps straight away. To do this, you must first create an empty Protégé project and then include the TMTab topic map ontology:

  • From the "Project" menu select "New"
  • In the pop-up dialog that is displayed, select "Standard Text Files" and click "OK"
  • From the "Project" menu select "Include..." and in the file dialog that is displayed, navigate to <your protege installation dir>/projects/topicmaps and select topicmap.pprj. This should add the class TOPIC and its subclasses to the class hierarchy.

You are now ready to start creating topics and associations.

Creating A Topic

To create a topic, go to the Instances tab of the Protégé window and select the class TOPIC from the tree on the left. In the Direct Instances pane, click "C" to create a new instance of the TOPIC class. The new instance will be created immediately and selected. You may then use the form on the right hand side of the window to enter the information for this topic. You may provide values for any or all of the following fields.

"Model Name" is used to enter a default name for the topic. This name will be generated as a baseName in the unconstrained scope for the topic.

"Subject "specifies the URI which identifies the resource which is the subject of the topic.

"Subject Indicators "is a list of URIs which address resources which describe the subject of the topic.

"Names" is a list of instances of the NAME class. See the section called “Creating Names” for more details.

"Occurrences" is a list of instances of the OCCURRENCE class and is used to identify information resources related to the topic. See the section called “Creating Occurrences”

"Types" is a list of instances of the TOPIC class and is used to define the topics which establish the class(es) to which this topic belongs. See

Creating Names

Names are created as instances of the class NAME. The NAME class is derived from the TOPIC class to enable a name to be reified. In addition to the fields provided for the TOPIC class (as described above), the NAME class has the following slots:

Name String is used to specify the string value of the name.
Scope is a list of instances of the TOPIC class which defines the set of themes which make up the scope of the name.
Variants is a list of instances of the VARIANT-NAME class which defines the set of variants of the parent NAME instance.

The VARIANT-NAME class is used only to create variants on an instance of the NAME class. As with NAME, VARIANT-NAME is derived from TOPIC to enable a variant to be reified. In addition to the slots of the TOPIC class, the VARIANT-NAME class has the following slots:

"Name Resources" is a list of strings which should be URIs of resources which may be used as a variant name.
"Name Strings" is a list of strings which may be used as a variant name.
"Scope" is a list of instances of the TOPIC class and is used to define the 'parameters' of the variant (the topics define additional context for the variant name).

Creating Occurrences

Occurrences of topics are creates as instances of the OCCURRENCE class. As with NAME, OCCURRENCE is derived from TOPIC to enable reification and has the following additional slots:
"Resource" is a string which specifies the occurrence information. Use this for 'inline' occurrences such as topic meta data.
"Resource Locator" is a string which specifies the address of occurrence information. Use this for 'out-of-line' occurreces such as web-pages related to the topic.

Creating An Association

Associations between topics are created as instances of the ASSOCIATION class. The ASSOCIATION class has only one class-specific slot, Members, which accepts a list of instances of the MEMBER class. The MEMBER class is used to define each member role of the association and the topics which play that role. The MEMBER class defines the following additional slots:

"Role Players" is a list of instances of the TOPIC class. This list specifies which topics play the role defined by the MEMBER instance in the parent ASSOCIATION instance.

My First Topic Map

<<To Be Completed: A step-by-step guide to creating a simple topic map with the basic topic map ontology >>

Table of Contents

Export Configuration

The current version of TMTab does not read in XTM files, nor does it maintain the ontology in XTM format. However it is possible to export the TMTab topic map ontology as an XTM file for further processing by topic map tools (such as loading into a topic map viewer application like TMNav). The export process is controlled from the tab labelled "Topic Map!.

To export a file, simply specify the name of the file to be written (you can use the Browse button to locate a file using a standard Java File Save dialog), then click "Export".

Note

If the file you specify already exists, it will be overwritten.

Export Configuration

You can create an store one or more Export Configuration records as part of your Protégé project. These configurations control certain aspects of how TMTab creates the XTM file. Export Configuration records are simply created and manipulated like any other object in Protégé. To create a new Export Configuration record, go to the Instances tab of Protégé and create a new instance of the class TMTAB-EXPORT-CONFIGURATION. The following form may be used to set the confguration options:

Figure 3.1. The TMTab Export Configuration Form

Enter a name for the configuration in the field labelled "Configuration Name". Currently, the only configuration options available control how the contents of the Model Name slot are treated by TMTab during export. In the "Export Model Name" drop-down list you may choose from "As Base Name", "As ID" and "No".

Choosing "As Base Name" will result in the value of the Model Name string being used to generate a Base Name fro the object. If the object is not itself a topic (i.e. not an instance of the TOPIC class), a new topic will be created that reifies the object and that topic will be assigned the Base Name. You can specify a scope for this generated Base Name by adding TOPIC instances to the list box labelled "Model Name Scope".

Choosing "As ID" will result in the value of the Model Name string being used to generate the value of the ID attribute of the XTM element which represents that object.

Warning

Use this option with caution, as TMTab does not ensure the required uniqueness constraint of ID attribute values. If you have duplicate Model Name values for different objects you may find that TMTab will either generate errors or else will silently combine Topics with the same ID. Ideally, if using this option, you should encode some additional Protégé constraints to ensure uniqueness of this slot value.

The ID attribute values generated by this means can be URL encoded to ensure that they are valid for use as part of a URI. To have this encoding performed, check the box labelled "Encode ID". Additionally, ID attribute values which begin with a digit will have an additional underscore ('_') character prepended to ensure that they are valid XML/SGML ID values.

Choosing "No" simply ignores the Model Name slot value completely and its value is not used in generating the XTM file at all.

As we have seen in the previous sections, creating a topic map with the base ontology is relatively easy, but it is very unconstrained. It is not possible to express that a 'born-in' association must have a 'person' role and a 'place' role that should be played by topics of type 'Person' and 'Place' respecitvely. It is also a relatively long-winded operation to create an association between two topics, requiring the creation of an instance of ASSOCIATION and two new instances of MEMBER. TMTab makes use of Protégé's subclassing features to enable an ontology designer to specify constraints on both topics and associations and also provides some internal conventions which enable more convenient creation of topic names, occurrences and of associations between topics.

Subclassing TOPIC

By subclassing topic, we can create a class which constrains the characteristics of the topic objects which are generated from the instances of the derived class. These constraints include:
A fixed set of types
A controlled set of occurrences
A controlled set of names
A controlled set of roles played in associations.

When subclassing from TOPIC, it is important to be aware that you are not implicitly creating a 'typing topic', you are simply defining a set of constraints which may be applied to a class of topics. You still need to create the topic or topics which define the subclass your are providing constraints for.

Constraining Topic Type

To specify a default type of al topics of this class, simply provide a template value for the Types slot at the class level.

Example 4.1. Creating the Person Topic Class

  1. On the Instances tab, select the TOPIC class and in the Direct Instances pane, click the button marked C to create a new instance. Give this new instance the Model Name "Person".
  2. On the Classes tab, select the TOPIC class and click the button marked "C" to create a new subclass.
  3. Change the name of the subclass to "Person"
  4. Double-click on the "Types" slot of the new Person class. In the dialog that is displayed, select "View slot at class" and click OK.
  5. In the displayed dialog, click the button marked "+" over the list labelled "Template Values". In the dialog that is displayed, select "Person" (Note that you can select an instance of any class which is subclassed from TOPIC).

The procedure outlined above ensures that any instance of the Person class created in the second step will, when exported as a topic map, result in a topic which is an instance of the topic generated from the Person TOPIC instance created in the first step.

As an exercise, create a Place subclass of TOPIC and a Place topic. Constrain the Place subclass to have the Place topic as its type. Once you have done this, create and instance of the Person class for yourself and an instance of the Place class for the place where you were born.

Creating a Controlled Occurrence

You can create an constrained occurence slot for your derived topic class simply by adding a new slot which accepts as its value a single instance of the OCCURRENCE class or any class derived from OCCURRENCE. A controlled occurrence can be used for a number of reasons:
To mandate that a particular piece of information always be entered for a given class of topic.
To mandate that a particular piece of information is given a specific occurrence type.
To make it more convenient for a person creating instances of a given topic class to specify occurrences of that topic.

Example 4.2. Creating a controlled occurrence of Person

In this example we will add a "homepage" occurrence slot to the Person class

  • Create a new instance of TOPIC and give it the Model Name "Homepage"
  • Create a new subclass of OCCURRENCE and give it the class name "Homepage"
  • Select the "Homepage" class on the Classes tab and then double-click the "Types" slot
  • Choose to edit the slot at the class level
  • Add a value to the Template Values list. Select the topic named "Homepage" we created in the first step of this excercise. This means that any instance of the Homepage class will automatically be typed by the "Homepage" topic.
  • Select the "Person" class on the Classes tab and add a new slot.
  • Give the slot the name "Homepage_occ"; and set its allowed value to be an Instance and the allowed class to be the "Homepage" class.

Having completed the above steps, you should now be able to go to the Person instance you created in the previous exercise and see that the form has a new, empty slot called "Homepage occ". Click on the C button on this slot to create and add a new value. Type your homepage URL (if you don't have one, make something up!) into the "Resource Locator" slot.

Note

You will notice that the "Homepage" occurrence class actually still allows us to enter either a Resource Locator or a Resource. Ideally, we would want to prevent users from entering a value into the Resource slot. This can be easily done by modifying the form for the Homepage class to remove the Resource slot from the form, but this is beyond the scope of this tutorial. See the Protégé documentation for more details on how you can customise forms.

Creating a Controlled Name

You can create an constrained occurence slot for your derived topic class simply by adding a new slot which accepts as its value a single instance of the NAME class or any class derived from NAME. Using constrained slots for names enables you to mandate a particular scope be applied to a given name, as well as providing separately labelled slots for different names in the UI.

Example 4.3. Adding User Name to the Person topic

Lets add a slot which is used to record the person's system user name.

  • Create a new instance of the TOPIC class and give it the Model Name "User Name"
  • Create a new subclass of NAME and give it the name "User Name"
  • Select the "User Name" class on the Classes tab and then double-click the "Types" slot
  • Choose to edit the slot at the class level
  • Add a value to the Template Values list. Select the topic named "User Name" we created in the first step of this excercise. This means that any instance of the "User Name" class will automatically be typed by the "User Name" topic.
  • Select the "Person" class on the Classes tab and add a new slot.
  • Give the slot the name "User Name_occ"; and set its allowed value to be an Instance and the allowed class to be the "User Name" class.

You should now be able to return to the instance of Person and add a value for the new "User Name occ" slot.

Creating an Association-specifying slot

To make data entry more convenient, it is possible to specify slots on a TOPIC subclass which are provided for the purposes of recording the topic(s) which are associated with the current topic. Any slot which accepts an instance of TOPIC or one of its subclasses is treated as defining the other topic(s) in the association. Each such slot may be combined with up to three other slots to provide additional information. These additional information slots use the same name as the slot defining the other topics, but with an additional suffix. So, if your slot is named "EmployedBy", then:

The slot "EmployedBy_assoc" may be used to specify the TOPIC which defines the class of associations to which this association belongs.
The slot "EmployedBy_thisrole" may be used to specify the TOPIC which defines the role played by the this topic in the association.
The slot "EmployedBy_otherrole" may be used to specify the TOPIC which defines the role played in the association by the TOPIC(s) provided in the "EmployedBy" slot.

Example 4.4. Creating a works-for association

In this example, we will create a slot in which the ontology editor need only select an organisation from a list of all organisations in the ontology in order to establish a works-for relationship between the Person instance on the Organisation instance.

  • Create the 4 new instances of TOPIC with the following Model Names:
    Organisation
    Works For
    Employee
    Employer
  • Create a subclass of "TOPIC" and give it the name "Organisation"
  • Set the template value of the Types slot of the Organisation class to the "Organisation" topic created in the first step.
  • Select the Person class on the Classes tab and add a new slot. The slot should be named "Employed By"; has allowed value "Instance" and allowed classes "Organisation"
  • Add another slot to the Person class. This slot should be named "Employed By_assoc"; has allowed value "Instance"; allowed classes "TOPIC"; and the Template Value should be the "Works For" topic.
  • Add a third slot to the Person class. This slot should be named "Employed By_thisrole". This slot defines the role played in the "Works For" association by the Person instance. Give the slot the allowed value "Instance"; allowed classes "TOPIC" and template value "Employee"
  • Add one more slot to the Person class. This slot should be named "Employed By_otherrole". This slot defines the role played in the "Works For" association by the value assigned to the "Employed By" slot (in other words, the role played by the "Organisation" instance). Givethe slot the allowed value "Instance"; allowed classes "TOPIC" and template value "Employer".

You should now create an instance of the Organisation class to represent your employer. Then go to the Person instance you created for yourself and add that new instance to the "Employed By" slot. Once again, notice that although all of the other slots you just created are displayed on the form by default, they could equally well be hidden as the user cannot modify the values of those slots. See the Protégé documentation for how to customise the appearance of the form.

Subclassing Association

The Types and Scope slots of a class derived from ASSOCIATION class may be provided with template values as the Types slot on the TOPIC class can. However, TMTab additionally allows the creation of additional slots which provide a more convenient way for ontology creators to enter the role players in an association and which enable ontology designers to constrain the types of topics which may play certain roles in the association.

To create a slot to represent a role in an association, you simply need to add a new slot which accepts one or more instances of TOPIC or a subclass of TOPIC. This slot can be used to add the players of a role in the association. By constraining the allowed subclass of TOPIC, you can mandate that a topic playing a particular role is of a specific type. For each slot which specifies role players, a slot with the same name and the suffix "_type" can be added to the class to provide the TOPIC instance which defines the association role.

Example 4.5. Creating the born-in association

  1. Create a new instance of TOPIC with the Model Name set to "born in"
  2. On the Classes tab, select ASSOCIATION and create a new subclass. Give the subclass the name "Born In".
  3. With the "Born In" class selected, double-click on the Types slot and choose to modify the slot at the class level. Add the "born in" topic as a template value.
  4. Create four new slots for the "Born In" class as follows:

    Table 4.1. New slots for the "Born In" class

    Slot NameAllowed TypeAllowed ClassesTemplate Value
    role_PersonInstancePerson 
    role_Person_typeInstanceTOPIC"Person" TOPIC
    role_PlaceInstancePlace 
    role_Place_typeInstanceTOPIC"Place" TOPIC

Table of Contents

Reporting Bugs

This document has presented a brief overview of how to use the TMTab topic map ontology and the TMTab export tab together to enable Protégé-2000 to be used as a topic map editing tool. TMTab will be developed further with at least the aim of being able to use an XTM file as a storage format for all Protégé ontologies (even ones that are not based on the TMTab topic map ontology).

Reporting Bugs

If you find any bugs with TMTab or if you have any requests for new features of the plugin, please contact the author, Kal Ahmed on kal@techquila.com