NOMOS Tutorials and HOWTOs

Overview Download Manual Tutorials Bug Tracker Contact

Introductory Tutorials

(No programming required.)

How to import native NOMOS annotation files so you can access the annotations

CSLI and other researchers sometimes make annotation files available in native NOMOS format (*.n3 and *.xml files), see for example our ICSI/ISL action item and topic annotations. In this HOWTO we describe how to unzip collections of NOMOS annotation files like this so that you may load them into your local NOMOS installation.

• Step 1: Locate the NOMOS "archive" directory

NOMOS files are loaded into NOMOS from two locations: the "serialization" directory - where new annotation files are written, and the "archive" directory - where annotations may only be read from. You will want to put your annotation dataset in the latter of these two folders. By default, this is located in your home directory in a folder called nomos-archive. However, you or someone else may have locally configured this to a different location using the opi.file.archive configuration property (see local configuration).

• Step 2: Unzip the annotations to the "archive" directory

Usually, annotation file sets are compressed into a *.tar.gz archive. Simply uncompress this archive file into NOMOS's "archive" folder while the application is not running. Be sure that the directory structure is in alignment such that the first folders under your "archive" folder contain the name of the ontology (e.g. corpora_2_0).

If you do uncompress the files while NOMOS is running, you must restart the application before it will reread its local data.

How to open existing NOMOS annotations

In this tutorial, we lead you through a specific example of opening a previously-created set of annotations for viewing in NOMOS. To perform this tutorial you will need to have imported the ICSI corpus (see corpus importing) and our ICSI/ISL action item and topic annotations.

• Step 1: Open the "New Session Wizard"

Choose Session > New... from the application menus, or click on the toolbar button depicting a file, to start a new session.

• Step 2: Choose an annotator name

You will be presented with a dialog box with instructions to "Enter or select an annotator name". You may either enter your name in the text field at the top or, if your name has already been recorded, simply select your name from the list. Then, press Next.

NOTE: To open existing annotations, there are two basic options:

• The preferred option is to create a new session with your name as the annotator and then import the session you want to view. This is in keeping with the "layering" approach to annotation that NOMOS supports, even if you don't actually make any changes to be saved.
• However, if you know the name of the annotator who produced the data you want to view, you can choose their name at this step of the wizard and effectively re-open their existing session. This approach is not recommended.

• Step 3: Choose a task for this session

This next step in the Wizard asks you to "Choose a task for the new session." For this example, choose deepActionItems to open and view action items in the "2006 deep scheme". If you are having trouble finding this task in the list of available tasks, simple type the first few letters in the Search field at the top of the window and your options will be filtered to those that match. After you've selected deepActionItems, press Next.

• Step 4: Choose the meeting corpus (Optional)

This next step in the Wizard asks you to "If needed, choose the corpus of the desired meeting." You do not have to select an option here, but for this example it is easiest to select the islMeetingCorpus from the list. After you've selected the islMeetingCorpus, press Next.

• Step 5: Choose a specific meeting

This next step in the Wizard asks you to "Choose a meeting." If you selected a meeting corpus in the last step, only meetings associated with that corpus will be shown. Otherwise, all meetings will be shown. For this example, select meeting m042. Note, the Search feature is often particularly helpful at this step, as there can be many meetings to choose from. After you've selected the m042 meeting, press Next.

• Step 6: Choose an import producer (Optional)

This next step in the Wizard asks you to "Select producers of your desired imports, or select nothing to display all possible imports." You do not have to select an option here, but for this example it is easiest to select ehlen from the import producers list. For future reference, note that you can select multiple producers during this step. After you've selected ehlen, press Next.

• Step 7: Choose a specific import

This next step in the Wizard asks you to "Choose 0 or more models to import." If you selected an import producer in the last step, only imports associated with that producer will be shown. Otherwise, all available imports will be shown. For this example, select meeting deepActionItems__m042__ehlen__null. Note, the Search feature is often particularly helpful at this step, as there can be many imports to choose from. After you've selected the deepActionItems__m042__ehlen__null import, press Next.

• Step 8: Choose a perspective

This next step in the Wizard asks you to "Choose a perspective for the new session." For this example, select the DeepActionItemsWithAllPartOfs perspective. After you've selected DeepActionItemsWithAllPartOfs, press Finish.

If all goes well, you will see a progress bar at the bottom of the window. When loading completes, the transcript and action item annotations will be loaded.

• Step 9: Examine a portion of the discourse

Click on a portion of the discourse to move the red cursor. Try jumping to a point of interest in the meeting using the Jump To Time feature. Select View > Jump To Time... and enter 612. Select OK and you will see the view jump to 612 seconds into the meeting, where an action item has been identified.

• Step 10: Save the session

Let's save this session, even though we haven't made any changes, so we can come back to it later. Choose Session > Save from the menus, and provide a filename when prompted. Annotation Sessions are stored as .ann files, which describe your working environment and allow you to quickly return to a particular task in the future.

.ann files do not save the actual annotation data! That data is saved within the NOMOS directory so that it can be accessed through the Wizard later. The .ann file is a collection of metadata about your session that allows you to quickly restore your session without using the Wizard. .ann files can therefore be stored anywhere convenient and can be deleted without affecting actual NOMOS annotation data.

• Step 11: Close the session

When you are done looking at the discourse, choose Session > Close or Session > Quit from the menus.

How to create new annotations, save them, and reopen them later

In this tutorial, we lead you through a specific example of creating new annotations of action items in a meeting. To perform this tutorial you will need to have imported the ICSI corpus (see corpus importing) and our ICSI/ISL action item and topic annotations.

Using the "New Session" wizard, make the following selections:

• Step 1: Choose/enter your name.

• Step 2: Choose the task deepActionItems .

• Step 3: Choose the islMeetingCorpus .

• Step 4: Choose meeting m035 .

• Step 5: Select no producers of imports, to see all possible imports (Just press Next) .

• Step 6: Choose meetTranscript__m035__islCorpusLdc__null .

• Step 7: Choose the DeepActionItemsWithReminders perspective .

• Step 8: Find a section of the transcript where you would like to annotate an action item.

• Step 9: Right-click on the ActionItemsGroups track, near the action item's time.

Select "Create Action Item..." and wait for the "Edit Thing..." dialog to appear.

• Step 10: In the dialog that appears, note that the Class has already been set for you. Simply add a NOMOS-description and press Done.

Your new ActionItemGroup should appear on the track, near where you clicked.

• Step 11: Now, right-click on the ActionItemsSubgroups track, near the time of the item you just made.

Select "Create Action Item Subgroup..." and choose "Owner" from dialog that appears.

• Step 12: After selecting "Owner", a new "Edit Thing..." dialog appears. The defaults are fine for now, so press Done.

• Step 13: We must now connect the two entities we've created.

• Step 14: Drag-select the text in the transcript entity that refers to the action item you are annotating, and continue dragging until you can 'drop' that text on your new ActionItemsSubgroups entity.

• Step 15: Choose Yes from the "Mark as AI owner utterance?" dialog that appears.

• Step 16: Drag-select the text in the ActionItemsSubgroups entity, and continue dragging until you can 'drop' that text on your new ActionItemsGroup entity.

Your entities should now be connected (note the lines/arrows) in a simple hierarchy: (Transcript entity) -> ActionItemsSubgroups entity -> ActionItemGroups entity.

• Step 17: Select Session > Save from the menu bar and choose a place to save the .ann file.

Remember, all annotations are stored in the NOMOS sub-directories; the .ann file is only a shortcut for your convenience.

• Step 18: Select Session > Open from the NOMOS menu, then find and select your .ann file.

• Step 19: Select Session > New from the NOMOS menu, and retrace your choices to retrieve your saved annotations.

How to compare two annotations

Comparing two sets of annotations is easy in NOMOS, but dependent upon the perspective you would like to use during the comparison process. For the next few steps, we'll use a simple perspective that is already set up to compare sessions from different sources.

Open a new session and import two other sessions

Using the "New Session" wizard, make the following selections:

1. Choose/enter your name.
2. Choose the task deepActionItems.
3. Choose the islMeetingCorpus.
4. Choose meeting m063.
5. Select no producers of imports, to see all possible imports (Just press Next).
6. Choose both deepActionItems__m063__HierarchicalActionItemIdentifier__... and deepActionItems__m063_ehlen_null.
7. Choose the DeepActionItemsWithPartOfs perspective.

Note that you may want to re-order similar tracks to group them by original producer, to ease comparison.

Perspectives and partitioning

Effectively, we are loading two sessions at the same time. However, since we are comparing similar sessions, they will probably contain entities that exist upon the same track (i.e. ActionItemGroup). Therefore, the perspective must be set to "partition by source." This means that the loaded data from both imported sessions is partitioned (split) into separate but same-labeled tracks, based on their origin session.

This feature is enabled in most standard perspectives, but you can check the setting by choosing Configure > Manage Perspectives... from the NOMOS menu bar, then choosing the desired perspective, choosing Edit, and verifying/setting the Partition by source checkboxes are enabled for your entities of interest. Note that this setting must be in effect before the perspective is used to view session data.

How to output annotations to an easily processable format

Both queries and processors are methods to extract and export data from within NOMOS, without having to even open a session. However, queries can be constructed within the NOMOS GUI and processors must be written in Java. Many simple tasks can be accomplished with a query instead of a processor, for users uncomfortable with Java development.

Queries

1. Choose Run > Run Query... from the NOMOS menu.
2. In the dialog that appears, choose your desired OPI.
   • For this example, choose corpora_2_0.
3. Choose at least one model from the list that appears.
   • For this example, any model will do.
4. Choose the query you wish to use.
   • For this example, choose Utterances.
5. Choose an output directory for the produced data. For this example, choose any convenient directory.
6. Choose Run.

A progress dialog will appear to inform you of the query's progress. The output files from the query are simple text files, with one file created per model selected. Files are named according to: (name of model).(name of query).txt. The files contain space/line delimited rows and columns of data, where each column is a script variable and rows are actual query results.

Processors

1. Choose Run > Run Processor... from the NOMOS menu.
2. At the top of the dialog that appears, you can choose a script to run.
   • For this example, choose TranscriptScript.
3. In the middle, you can highlight multiple sessions (using the Control or Shift keys) on which you would like this script to run.
   • For this example, any session will do.
4. At the bottom, you can choose an output directory for the script (though some scripts may ignore this output directory).
   • For this example, choose any convenient directory.
5. Press OK to execute the chosen script on each session selected.

NOMOS comes pre-installed with the TranscriptScript which will output a text transcript of the utterances in a session.

How to upgrade NOMOS to a new version without overwriting your data

NOMOS is under active development, so new versions of the software are released regularly. We recommended that you always update to the latest version available, since it likely includes new features, optimizations, and bug fixes. However, you may be concerned about what happens to your data during the upgrade process. This tutorial provides our recommended procedure for retaining all your data.

Backing Up Your Data

Before any upgrade, you should always back up your NOMOS directory to another location. The NOMOS directory is that which contains the NOMOS application, often something like C:\Program Files\NOMOS under Windows or /Applications/NOMOS under MacOS X. Simply copy (Note: not move!) the directory to another location, such as your desktop (safe) or an external hard/flash/network drive (safest).

Uninstalling the Old Version

(Windows Versions Only)

Uninstall the old version of NOMOS using one of these equivalent methods:

• In your Windows Control Panel, choose Add or Remove Programs, find NOMOS in the list, and select the Remove button.
• In your Windows Start Menu, find the NOMOS program group and choose "Uninstall".
• In your NOMOS installation directory, run "uninstall.exe".

The uninstaller will only remove files originally installed. To emphasize, any new files that have been added will not be removed by the uninstaller. Additionally, the file nomos.local.config will never be modified or removed during this process, thereby preserving your local configuration settings between upgrades.

Installing the New Version

• In Windows:
  Simply follow the instructions in the NOMOS installation guide. Be sure to select the same installation directory that you originally chose, so that the new files are placed in the correct location.
• In other operating systems (MacOS X, Linux, etc):
  Simply unzip the NOMOS compressed archive over the same location as the installation directory. The files in the archive will be placed in the correct locations, without overwriting your own data. NOTE: This is different from unzipping the archive to a temporary location and copying the new directory over the original NOMOS directory. Under MacOS X, this will literally replace the old directory with the new one and will effectively delete all your NOMOS data files. When in doubt, simply unzip the compressed archive to a temporary location and execute cp -rfv path-to-new-version path-to-old-version from the command line or in Terminal.

How to report a problem or request a feature in NOMOS

We use an online issue tracking system to manage bug reports, feature requests, and other "to-do" items. If you would like to report a problem with NOMOS, notify us of an error in the documentation, or request a feature, please use this system so that we can address your issue as quickly and efficiently as possible. While working with the bug tracker, you may be asked to "choose a project"; simply select "NOMOS" from the provided list.

1. Open the bug tracker web page.
2. If you plan to report several issues and stay involved in their discussion, it's easiest to register for an account. However, you may also simply click Login Anonymously at the top-right corner of the login prompt.
3. You should now see a summary of issues and their status. First, make sure that your issue has not already been reported: Click on View Issues in the top navigation bar, then type a key word or phrase into the Search box on the resulting list. If your issue has been reported, feel free to confirm that you are also experiencing difficulty by adding a note and explanation to the existing issue.
4. If your issue has not yet been reported, click Report Issue and fill out the provided form.

Case Studies and Walkthroughs

(Beginner tutorials recommended.)

#Advanced

Advanced Tutorials

(Some programming or schema design required.)

How to create queries

The goal of this example query is to pick out a particular set of PartOf relations: those relations where the subject is a SubSpeak and the object is a Speak. Recall that we did not include SubSpeak as a type in the ontology proper; so, when we say SubSpeak, we actually mean objects of type Event where the temp-type slot is set to the string value "SubSpeak".

We can see that the query above does just that. The query is defined as a table, where the first column -- Property -- signifies the property we are interested in. Each subsequent column sets the properties of a particular variable. The first variable, v, is special: it represents the object we are actually interested in picking out in the query. So, the table depicted above could be re-written as the following list of constraints:

1. v is the "main" variable to be returned by the query
2. v has Type set to PartOf
3. The subject slot of v is set to w
4. The object slot of v is set to x
5. w has Type set to Event
6. The temp-type slot of w is set to the string "SubSpeak"
7. x has Type set to Speak

Taken together, these constraints pick out the set of PartOf entities we are interested in. We note that blank entries are ignored.

Always use the drop-down menus to choose Type names, any text typed into a table cell will be treated as a String. So, typing "Thing" means the String "Thing" rather than the type Thing.

Disjunction

Now, let's look at another query which shows off some more capabilities of the NOMOS query system. For practice, you should try constructing this query yourself (hit "New Query"). This query will get all PartOf relations where the subject is either of type Speak or and Event with temp-type "SubSpeak."

Note the use of HasDisjunct which says that x can be either z or y.

Subclasses

In each of the queries so far, we known the exact type of what we are looking for. But let's say we wanted to write a query to get every entity we know about. It's tempting to want to write a query which simply returns things of type Thing, however this won't work. In fact, you must write the following:

That is, we are looking for entities where the Type is w, where w is a Subclass of Thing.

Partitioning Variable

Finally, we'll note one final feature of Queries: the partitioning variable. Sometimes it is useful to use a single query which displays results in multiple tracks. To do this, we must use a partitioning variable. A good example of doing this is the query for utterances:

This query gets all entities of type Speak which are PartOf some Meeting and have an agent w which is of type Person. Moreover, you'll note that the Partitioning Variable is set to w, which means that a separate track will be made for each Speak object found which has a different agent. In this case of utterances, this means that we get a single track for each participant in the meeting. This is because each Speak has its agent slot set to the value of the person who uttered it. Hence, we can partition based on the value of the agent slot to get one track per speaker.

How to import a new (currently unsupported) corpus into NOMOS

As you have seen, NOMOS provides many useful functions and tools for analyzing corpora. However, the corpora must be in a NOMOS-readable format before you can use these tools. Follow this guide to learn how to import an external corpus into NOMOS.

Set up the new class

• To ensure that your new class will be seen in the Run Importer menu, create it in the csli.dialog.app.calo.importers_ package.
• Have your class extend GenericImporter and implement GenericPlugin. GenericImporter provides helpful functions common to all importers.
• When run from NOMOS, the script will execute the public void run(ProgressDialogIface progress) method.

Your script should now look something like this:

public class ImportMyCorpus extends GenericImporter implements GenericPlugin{
   public ImportMyCorpus()
   {
      super([required_corpora], “vers1”);
   }

   public void run(ProgressDialogIface progressDlg)
   {
      run(progressDlg);
   }
}

Set up the Annotation Layers

Recall that an annotation layer contains the meta-information about a corpus. Therefore, we must enter this meta-information into NOMOS so the annotation layer can eventually read it. We will add the corpus information to csli.dialog.corpora.model.CorpusList. To do so, add these lines where appropriate:

 
public final String MY_CORPUS_NAME = "myCorpus"; 
results.add(MY_CORPUS_NAME); 

Similarly, the annotation layer will need to know the name of the annotater. Go to the AnnotationProducer class in the same package, and add these lines in the appropriate places:

 
public final AnnotationProducer MY_CORPUS = new AnnotationProducer(“myCorpusProducer", null); 
list.add(MY_CORPUS); 

Adding these identifiers helps ensure that NOMOS will be able to access this information. We are now ready to open the new layers. Opening the layers will look like this:

 
AnnotationLayer meetingLayer = getLayerForCorpusTask(taskList.CORPUS_MEETING_LIST_TASK, 
                                                                        corpusList.MY_CORPUS_NAME, prodList.MY_CORPUS);   

Your general strategy probably will be to open up a meetingLayer, which will contain all the meeting names and times. A participantLayer, which will contain all the participants, and a transcriptLayer, which will contain the utterances of the participants. These goals are reflected in the first parameter of the getLayersForCorpusTask method.

• taskList.CORPUS_MEETING_LIST_TASK is for listing all the meetings in a corpus.
• taskList.CORPUS_PERSON_LIST_TASK is for listing all the participants in a corpus.
• taskList.MEET_HUMAN_TRANSCRIPT_TASK is for listing the utterances in a meeting. You will probably want a different meetingLayer for every meeting in the corpus.

In the rest of this tutorial I will continue to refer to a meetingLayer, participantLayer, and transcriptLayer. You may have fewer, more, or different layers depending on your corpus.

If you want to check if the annotation layer loaded correctly, you can view it in XML format. The annotation layer corresponds to .n3.xml files.

Populate the Annotation Layers

We don’t directly add objects to the AnnotationLayer, but to its model. The model corrosponds to the .n3 files. To get a model, use a line like the following:

 
CorporaOpi_2_0 peepOpi = (CorporaOpi_2_0) openNew(layerPeople); 

There are three common types of NOMOS objects to add. You will probably need to use the CorporaOpi_2_0 version of these objects.

1. NOMOSPerson
2. NOMOSMeeting
3. NOMOSSpeak

All NOMOS objects must have a globally unique name, and it is also often convenient to provide a shorter human readable name, the altId. Use DigestUtils.md5Hex when creating a globally unique name. In addition NOMOSMeeting and NOMOSSpeaks should have start and end times. The NOMOSSpeak also needs the person speaking. Adding a NOMOS object looks like this:

CorporaOpi_2_0 meetOpi = (CorporaOpi_2_0) openNew(meetingLayer);
for (int meetingNum = 0; meetingNum < numMeetings; meetingNum++)
{
   String globalName = getGlobalMeetingName(meetingNum);
   XSDDateTime startTime = getMeetingStartTime(meetingNum);
   String duration = getMeetingDuration(meetingNum);
   NOMOSMeeting meeting = meetOpi.addNOMOSMeeting_CorporaOpi_2_0(DigestUtils.md5Hex(“myCorpus” + globalName)); 
   meeting.SetNOMOSAltId(globalName);
   meeting.setNOMOSTimeBegins(start);
   meeting.setNOMOSTimeEnds(JenaOpiHelpers.addSeconds((int)Float.parseFloat(duration), startTime));  
  // other helpful functions can be found in JenaOpiHelpers, take a look
}

It is often helpful to load information already stored in another layer. For instance, the utteranceLayer might want information about a participant. To do this, use a JenaQuery like this:

NOMOSPerson person = (NOMOSPerson) JenaOpiQueryHelpers.getIndWithProp(peepOpi, peepOpi
        .getNOMOSAltIdOpiSlot(), peepOpi.createOpiLiteral(global_name));

Set up dependencies and save the layers

Probably one layer will end up depending on another layers information. Often the transcriptLayer won’t know anything about the meetings and participants in the corpus, it needs to get this information from the meetingLayer and participantLayer. Setting up dependencies looks like this:

// getManager() is a helpful function provided by GenericImporter
getManager().importModel(utterOpi, meetOpi);
getManager().importModel(utterOpi, peepOpi);

We are now ready to save the layers. Saving layers looks like this:

annotationManager.saveLayer(meetingLayer,meetOpi);

Remember to save the appropriate layer with the appropriate model.

How to create a novel annotation schema

To make annotations, you will need to create your own annotation ontology or use one of the ontologies we have designed for various corpora. To do this, you will follow the steps outlined below:

• Specification: An ontology is designed which contains a terminology to serve as an annotation schema
• Generation: Java code and a core ontology file are automatically generated from the initial specification
• Configuration: The tool is personalized for the annotation task
• Annotation: Annotations are produced which conform to the ontology

Specifying the Ontology

The properties.txt File

Ontologies are specified in the corpora/lib/opi directory. Browsing this directory will give you a general understanding of the required files. The first file you will need to create is the properties file at corpora/lib/opi/nameofnewopi_X_X/properties.txt. In this file, you specify which ontologies the ontology will inherit from, to which Java package the OPI code will be written, a unique identification URI for the ontology terms, and a file format. Here is an example properties.txt file for a new ontology called myontology_1_0:

opi.inherits=corpora_2_0
opi.package=csli.dialog.corpora.opis
opi.namespace=http://godel.stanford.edu/myontology_1_0#
opi.file.format=N3

The name of your ontology must be string_D_D where D is a digit.

Inheritance between Ontologies

Every set of annotations (model) conforms to at least one ontology. Ontologies can inherit terms from one another by building extensions to an existing ontology. To inherit multiple ontologies, just place multiple names in the opi.inherits files separated by a comma.

As an example, we import the MRDA Corpus into annotations which conform to the mrda_1_0 ontology. The MRDA corpus contains annotations of the ICSI corpus, for which we have produced annotations which conform to the icsimr_1_0 ontology. Thus, these ontologies have the following structure:

• icsimr_1_0 inherits from corpora_2_0
• mrda_1_0 inherits from icsimr_1_0

Note that MRDA did not need to inherit from corpora since this ontology was already inherited into the ICSI ontology.

The ontology.txt File

In the future, we would like to allow users to design their ontologies directly in OWL, but this capability has not yet been finished. Rather, NOMOS currently requires ontologies to be specified using a special syntax designed specifically for NOMOS which is not fully capable of expressing OWL (and which is unfortunately not very formally defined). Nonetheless, we specify this temporary format here, though users should note that the requirement to specify ontologies in this form will soon not be required.

The following is an example of an ontology of animals.

("class" |organism| ())
("class" |animal| (|organism|))
   ("class" |insect| (|animal|))
      ("class" |termite| (|insect| |herbivore|))
   ("class" |mammal| (|animal|))
      ("class" |lion| (|mammal| |carnivore|))
      ("class" |giraffe| (|mammal| |herbivore|))
      ("class" |zebra| (|mammal| |herbivore|))
("class" |plant| (|organism|))
   ("class" |baobab| (|plant|))
   ("class" |carnivore| (|animal|))
   ("class" |herbivore| (|animal|))

("slot" |predator| (|N-to-N|) (|giraffe| |zebra|) (|lion|))
("slot" |is-trampled-by| (|N-to-N|) (|termite|) (|mammal|))

The syntax of the the "class" directive is:

• ("class" |name| (|superclass| |othersuperclass|))

The syntax of the the "slot" directive is:

• ("slot" |name| (|functionality|) (|range| |otherrange|) (|domain| |otherdomain|))

Functionality is currently not handled well by this syntax and may effectively be ignored until the full OWL specification abilities are in place. Simply put the string N-to-N in that place.

Generating the Ontology Files

Once the ontology has been specified in the opi directory, two things must happen before the ontology may be used.

First, Java code must be generated from the ontology. This Java code (known as an Ontology Programming Interface (OPI)) will provide NOMOS a convenient way to accessing the data programmatically. More importantly, it will provide you (the researcher) the very same access by providing a customized and convenient Java interface to the data. To build the Java code, select Run > Opi Generator... from the NOMOS menu.

Second, a root ontology model will be built. This ontology model will be written to the data directory where all annotation files are kept. It will be given the name nameofopi/ontology/ontology/ontology/nameofopi.n3. You will see later, when you learn more about the importing of models, that this ontology model must be imported, either directly or indirectly, by any annotation model which wishes to conform to this newly designed ontology. To build the ontology model, select Run > Ontology Model Generator... from the NOMOS menu.

Configuring NOMOS for the Ontology

Annotating with the Ontology

How to add new features to the NOMOS interface

To develop new plugins for NOMOS, you must obtain the source code and API documentation. Please see our software page for details. Local CSLI users may obtain the source code from CVS. All plugin interfaces are in the package csli.dialog.corpora.tool while the provided basic plugin implementations are in the package csli.dialog.corpora.tool.plugins.

Quick Setup (for Experts)

NOMOS searches for external plugins in the plugin folder inside the folder in which it was installed (e.g. nomos_x_x/plugin/). Plugins packaged as jar files placed in this directory will be automatically discovered by NOMOS. To properly compile a plugin, you will need the three jars in the core/ folder on your classpath: corpora.jar, model.jar, and util.jar. Depending on the exact nature of your plugin, there is a high probability that you will need to include additional supporting jars which are referenced by these jars. If you have compilation problems, you would do well to also add all jars which appear until corpora/ext/, model/ext/, and util/ext/.

Eclipse-based Tutorial

In this section, we give an example of writing and deploying a plugin using the Eclipse development environment, which we highly recommend for Java development. To follow this tutorial, you must be using Eclipse 3.1 or later.

The first task is to create a new project containing your plugin(s) (or, you may already have an existing project you would like to use to develop plugins -- this is fine). In this tutorial, we'll create a new project called "myplugin". The "new project" screen should look like this one. Note that the compiler compliance should be set to 5.0

After hitting Next we come to the "Java Settings" window. Click on the "libraries" tab and then click "Add external Jars". Locate your installation of NOMOS, and highlight the three jar files in core/ (they should be corpora.jar, model.jar, and util.jar). Before clicking "Finish",the dialog should look something like this

Finally, if you have installed the NOMOS source, we highly recommend associating this source code with the jar files we've just put on the library path. You can do this by finding each of the three jar files in the package explorer and right-clicking on them to get their properties, like this. Under Properties, choose "Java Source Attachment" on the left and then hit the "External Folder" button on the right. Navigate to your installation of NOMOS (or to the location where you unzipped the source) and choose the appropriate src directory. For instance, for the corpora.jar file, you should use nomos_1_0/core/corpora/src/java/ as shown in this screenshot

This will allow Eclipse to display the appropriate javadoc information for methods you override or want to access in the NOMOS source.

Now, we are going to create a new class which extends csli.dialog.core.tool.plugins.generic.labels.ThingLabel. This will be our plugin: a new type of label called ColorLabel which randomly chooses a different background color for each label. You should choose "New Class" from the "File" menu, and make the superclass ThingLabel and the name of the new class ColorLabel. In this example, we put the class in the package edu.stanford.csli.nomosplugins, though you can make this whatever you like. Before clicking "Finish" things should look like this.

The contents of your newly created class should be the following

package edu.stanford.csli.nomosplugins;

import java.awt.Color;

import csli.dialog.corpora.CorporaOpi_2_0;
import csli.dialog.corpora.CorporaOpi_2_0.Thing;
import csli.dialog.corpora.tool.plugins.generic.labels.ThingLabel;

public class ColorLabel extends ThingLabel {
   @Override
   public void init(Thing thing, CorporaOpi_2_0 opi, Object settings) {
      super.init(thing, opi, settings);
      changeColor();
   }

   @Override
   public void update() {
      super.update();
      changeColor();
   }
   
   /**
    * Change the color of the label randomly
    */
   private void changeColor() {
      setBackground(new Color((int) (Math.random() * 256.0)));
   }
}

Note that we have overridden the init() and update() methods of ThingLabel. The former is called when the label is first created, while update() is called whenever the thing represented by the label is modified by the user. So the behavior of this plugin will be that each label is a different random color, and anytime that the user modified a thing represented by a label, the color of that label will change.

In many development environments, you would now have to compile your new class. However eclipse compiles as you work, so just save ColorLabel.java and make sure no compile errors pop up.

Finally, we are going to build the jar containing our newly minted plugin and drop it in the plugin folder for NOMOS. In Eclipse, it's easy to make a jar file from the IDE. In other environments, you might want to make an Ant script to do this step for you.

Right click on the your project in the Package Explorer. If you followed the tutorial, it's called myplugin. In the menu that comes up, choose "Export," then click on "Jar File" and press "OK." For the "export destination" choose a file inside NOMOS's plugin/ folder -- for example: nomos_1_0/plugin/myplugin.jar. The dialog should look like this before you hit "Next."

You may want to save a description of this jar file in your workspace for future use. If you do, enter it in the next screen, as in this example.

Now finish the wizard, and a new jar called myplugin.jar should be in your nomos_1_0/plugin/ folder. Also, there should be a file called plugin.jardesc in your eclipse project (if you chose to save this plugin description for future use). If you right-click on this and choose "Create Jar" you can drop a new copy of this jar file any time you like into your NOMOS plugin's folder.

Verifying your plugin in NOMOS

Finally, you should verify that NOMOS was able to find your plugin. Start NOMOS, and edit one of the tracks in a template so that Thing maps to your newly created class ColorLabel. A good track to modify would be one that shows PartOf relations. Then, open a session using this template and you should see all of your PartOf relations in different colors!

How to access and process annotations directly using Java code

NOMOS uses the OPI software framework as its core Java interface to its annotations and sessions. When programming plugins, import scripts, and other programmatic interactions with the underlying data, one will need to use the OPI. Please see the framework documentation? for details on using the OPI.