Quick Start Tutorial

This tutorial introduces basic concepts of using Knowtator and assumes that you have already installed Knowtator and created a new and empty annotation project. If you have not yet installed Knowtator and created a new and empty annotation project, then please consult the installation instructions. You should start this tutorial with Protégé and Knowtator running such that the application looks like this screenshot.

Creating an annotation schema

A new annotation project will have no annotation schema, so let's create one:

1. Click on the tab labeled 'Classes'
   
2. Click on the node in the Class Hierarchy labeled ':THING'.
   
3. Click on the 'Create Class' button.
   
4. Enter a name for the newly created class "person"
   
5. Create two more classes called "date" and "coreference" (repeating from step 2)
   
6. Select the class called 'coreference'.
7. Click on the 'Create Slot' button.
   
8. Perform the following steps on the new slot:
• Set the name of the new slot to "coref_person"
• Set the value type to be 'Instance'
• Set the allowed classes to be 'person'
• Set the cardinality to 'multiple'
• The slot should look like this:
  
• close the slot definition dialog

We have now create a simple annotation schema! The annotation schema we have created is very simple compared to what can be expressed using Protégé. To make richer annotation schemas you will likely want to understand inheritance, slots and their facets, and instances. The Protégé project has excellent documentation and a great tutorial that will step you through the process of creating class, slot, facet, and instance frames. Note that Knowtator may not work as you expect it to for some of the more advanced representational constructs of Protégé such as slot inheritance and multiple inheritance. Please experiment!

Setting up Knowtator

Now when you click on the Knowtator tab you should see the classes you created on the left-hand side in the panel labeled "annotation schema." The first thing we will do is fill in some of the important configuration parameters. There are also detailed instructions on how to set configuration parameters. Please consult these as needed.

1. From the top menu, select Knowtator->Configure
2. Remove ":THING" from the root classes parameter and add "person", "date", and "coreference"
3. Create a new instance for default annotator by clicking the "Create Instance" button:
   
   Choose "Knowtator Human Annotator" and fill in the annotator's information.
4. Create three new instances for the "color assignments" parameter. Assign "green-yellow" to person, "magenta" to date, and "sienna" to coreference. You may need to save, close, and reopen your annotation project for the colors to appear correctly.
5. Close the config dialog

Next we will load some texts to annotate:

1. Click on the "open text source collection" button.
   
   Do not confuse this with the "open project" button (hover your mouse over the button to see the tool tip text.)
2. Select "Local Files" and click OK.
3. Navigate to a directory that contains plain text files. If you do not have any plain text files, then you can download 10 files selected arbitrarily from the sci.space newsgroup from the widely used 20 newsgroups corpus.
4. Click "Open"

You should now see that the first file loaded into Knowtator and the text source collection navigation buttons should now be enabled.

We are now ready to start annotating! Note that because Knowtator uses stand-off annotation the text sources that are loaded into Knowtator are never modified.

Your first annotation

To annotate a mention of "person" do the following:

1. Highlight a span of text corresponding to a person mention.
2. Click on the person class in the annotation schema:
   
   A context menu pops up.
3. From the context menu select "create annotation..."
4. You have created your first annotation and it should be selected. All the details of this annotation appear on the right-hand side of the window.

Fast annotate

Now we are going to quickly create some more person annotations:

1. Click on the person class in the annotation schema
   
2. Select "fast annotate: person" from the context menu.
3. Observe that you are now in "fast annotate" mode.
   
4. Select another span of text corresponding to a person mention.
5. Boom goes the dynamite!
6. Select another span of text corresponding to a person mention.
7. Click the quit button to get out of fast annotate mode.

Coreference annotation

I am not endorsing the annotation schema used in this example as the way one should annotate coreference - this is simply for illustrative purposes. There are many ways one might model coreference in the annotation schema.

1. Click on the coreference class in the annotation schema.
2. Select "create annotation: coreference" from the context menu. The result is a spanless annotation that has been created and selected.
3. Click the button for the slot "Coref Person".
   
4. Select any two (or more) person annotations from the popup dialog that correspond to the same person. Multiple selection is achieved by clicking with the mouse while holding down the control ('Ctrl') key. Result: You have created a coreference annotation.
5. Please see the FAQ for tips and tricks on how to annotate quicker. In particular, look at the tips for filling slot values.
6. You may observe that the displayed text for the annotation is quite uninformative (e.g. "quickstart_Instance_10023"). Please see the FAQ for instructions on how to change the display text of the annotation. This is particularly useful for spanless annotations.

Selecting annotations

There are several ways to select an annotation:

1. From the annotation schema: Each class in the annotation schema that has annotations will have a number in parentheses that indicates how many annotations there are of that class.
   
   Clicking on a class will will provide a context menu with options to select the annotations of that class. If the class has more annotations than some predifined threshold, then a "more..." option will be available.
   
2. From the text viewer: Every annotation that has a span can be selected from the text viewer. Simply clicking on the span of text will select that annotation. However, if there are multiple annotations that overlap at the point where the mouse is clicked or the annotations at that location can fill one or more of the slot values of the currently selected annotation, then a context menu will appear that provides selection and slot filling options.
3. From the selected annotation: If an annotation has slot values that are filled in with other annotations, then double-clicking on the slot value will cause the annotation to be the selected annotation.
4. From the "select annotation" buttons: There are two buttons on the tool bar that have the tool tip texts "select previous annotation" and "select next annotation".
   
   Clicking the "select next annotation" button will select the next annotation of the same type as the currently selected annotation. This would give you a convenient way to iterate through all coreference annotations, for example, without having to select them from the context menus of the annotation schema.