FAQ

• How do I get started?
• I want to annotate faster!
• How do I get annotations out of knowtator?
• How do I remove a bunch of annotations?
• How can I edit my text source collection file after I've done annotations already?
• How do I configure the displayed text of an annotation?
• How do I configure the displayed text of a slot?
• How do I specify the order that slots appear in?
• Can you explain the Find/Annotate dialog?
• Which version of Knowtator am I using?
• Can a single annotation have multiple spans? (yes)
• How do I modify the span(s) of an existing annotation?
• What is knowtator.pprj, knowtator.pont, and knowtator.pins?
• Does Knowtator work with Protégé-OWL? (no)
• Can I change the annotation schema after I have begun annotation?
• How do I create a new Knowtator project?
• What is an "annotation set"?
• !#$@ undo doesn't work!?
• How do I email an annotation project?
• How do I obtain the latest patch for Knowtator?

How do I get started? Please see the installation instructions and then the quick start tutorial.

I want to annotate faster!
We have many ideas on how to improve the speed of annotation and will gladly accept suggestions. Check back for here as enhancements are added. Here are a few tips that can speed up annotation. In fast annotate mode, a new annotation will be created of the type specified by the fast annotate class whenever a span of text is highlighted. There is a minimal UI above the text viewer that tells you that you are in fast annotate mode, provides a way to change the fast annotate class, and provides a quit button.

• fast annotate mode - There is now a 'fast annotate' mode in . There are two ways to activate 'fast annotate' mode. The first is to select Menu->Knowtator->Fast annotate mode. The other is to select the 'fast annotate' option from the context menu that appears when you select a class in the annotation schema.
• find/annotate - There is a Find/Annotate menu option under Menu->Knowtator->Find/Annotate. You can type in simple search strings or regular expressions and annotate matches to the search string with a class that you specify. You can get fairly tricky with the regular expression by using capturing groups to define what the span selection should be. This accomplished by checking the box labeled "Annotate capturing groups".
• slot filling - Fill a slot value with a newly created annotation. The easiest and slowest way to make a new annotation, A2 (which has not yet been created), the slot value of another annotation, A1 is to do the following:
  • create A1 first
  • create A2 second
  • go back to A1 and select the slot that you want A2 to fill
  • click the button labeled 'Add Instance' for the slot
  • select A2 to fill value for the slot of A1
  This is straightforward to understand but requires a lot of clicking and mouse moving and takes a really long time. A much quicker way to do the same thing is the following:
  • create A1 first
  • highlight the text to be used for A2 (making sure that A1 is still selected in the 'Annotation Instances' panel.
  • click the button labeled 'Create Instance' for the slot of A1.
  This automatically creates the annotation A2 and fills in the slot value of A1. This is much quicker - but less intuitive and requires a little practice.
• slot filling - Fill a slot value with an annotation that already exists. The easiest and slowest way to make one annotation, A2 (which has already been created), the slot value of another annotation, A1 is to do the following:
  • select A1
  • click the button labeled 'Add Instance' for the slot you want to fill
  • select A2 to fill value for the slot of A1
  An alternative approach which may be much quicker depending on the number of annotations already created for the current text source is to do the following:
  • select A1
  • click on the text of A2 in the text viewer. If A2 is valid candidate filler, then a context menu will appear giving you the option to fill in the slot of A1.
  • select the appropriate context menu.

How do I get annotations out of Knowtator?
There are two ways to get annotations out of Knowtator: programmatically or via an XML export. This script provides the basic code that you need to write your own script. It should run as is for printing out annotation information.
The second way to get annotations out of Knowtator is to use the XML export. Select the menu option Knowtator -> Export annotations to XML and then follow the directions. This will generate one XML file per text source in your collection. The XML format used directly parallels the data model that Knowtator uses for storing annotations in Protégé. Looking at the XML files may actually be helpful to understand how Knowtator represents annotations in Protégé.

How do I remove a bunch of annotations?
There is a menu item that helps you remove a bunch of unwanted annotations from an annotation project: Menu->Knowtator->Annotation Removal. You have to understand how filters work to use this effectively - and you should also read the message dialog carefully. See the filters page for details.
When you want to do something quick and dirty, then you can also delete the annotations in the instances tab and delete instances of "knowtator annotation" and instances of the subclasses of "knowtator mention". Do this at your own risk. You should save your annotation project before doing this and close the annotation project without saving it if you are unhappy with the results.

How can I edit my text source collection file after I've done annotations already?
If you are reading text sources in from a "Lines from File" text source collection, then you can add and remove text sources from the file to your heart's content without affecting any of the offsets for the other text sources. The offsets for each text source always start at zero - at the character following the '|' - and therefore are unrelated to the offsets of the text in the file. If you edit the line of a text source, then all bets are off (unless you are simply adding text to the end of a line.) Adding and removing lines is totally fine though.

How do I configure the displayed text of an annotation?
How an annotation is displayed in the list of created annotations is highly configurable. To change the displayed text of annotations of a particular class, do the following:

1. Click on the Protege instances tab.
2. The left hand side of the interface provides a class hierarchy. Navigate to the class of the annotations that you want to configure the display of and select it in the class hierarchy.
3. The middles pane of the instances tab is labeled 'Instances Browser'. The upper-right-hand corner of this pane has a dropdown menu invoked by a button with an triangular icon. See the Protégé documentation for a relevant screenshot. Click on the upside down triangle, and navigate to "Set Display Slot->Multiple Slots...".
4. A dialog labeled "Multislot Display Pattern" appears. The best way to understand how this dialog works is to experiment with it. The drop downs will allow you to display the slots in whatever order you want. The text fields provide a place to enter some text you want displayed. If you type the string "[text]" into a textfield, then the covered text associated with the annotation will be inserted there. See example below. It is not possible to access this dialog if the class you are configuring has not slots. However, it may be desirable to configure the display of annotations of a class that has no slots. The work around is to add a slot to the class (this is done in the "Classes tab"), configure the display (don't include the slot in your display!), and then remove the slot from your class.
5. The display slot of the class 'knowtator annotation' can also be used to globally change the display of all annotations. See example below.

Example:
Imagine you have a class called 'Problem' and another called 'Locus'. The class 'Problem' has a single slot called called 'has_location' which takes an instance of 'Locus'. The following text is annotated:

he has a melanoma on his toe

the span "melanoma" is annotated with the class 'Problem' and the span "toe" is annotated with the class 'Locus'. The "toe" annotation is then made the "has_location" value of the "melanoma" annotation. The default display of the "melanoma" annotation in the annotation instances panel will be:

melanoma

It is possible to make the annotation appear as "melanoma at toe" by doing the following:

1. select the class 'Problem' in the instances tab
2. select the display slot value 'Multiple slots' (see above instructions) for this class.
3. In the first text field type "[text] at "
4. From the first slot dropdown select the slot "has_location"
5. Select OK - the annotation display should be updated when you look at it in Knowtator

It is possible to make the annotation appear as "melanoma at toe [Jane Doe]" by doing the following:

1. Follow the instructions in the above example first
2. select the class 'knowtator annotation' in the instances tab. It is a subclass of 'knowtator support class'.
3. select the display slot value 'Multiple slots' (see above instructions) for this class.
4. In the first slot dropdown select the slot "knowtator_annotation_text"
5. In the second text field type " ["
6. In the second slot dropdown select the slot "knowtator_annotation_annotator"
7. In the third text field type "]"
8. Select OK - the annotation display should be updated when you look at it in Knowtator

How do I configure the displayed text of a slot?
To configure the display of a slot name do the following:

1. Click on the "Forms tab" in Protege.
2. The left hand side of the interface provides a class hierarchy. Navigate to the class that has the slot that want to configure the display of and select it in the class hierarchy.
3. Double click on the slot widget corresponding to the slot you want to configure the display of. See Protégé documentation for a relevant screenshot.
4. A configuration dialog appears. Select the tab labeled "General". Fill in the text field with the label "Label" with the way you want to see the slot displayed. Click OK.

See closed bug 1552151 for more discussion at the bug tracker. Unfortunately, none of the other features of forms such as resizing, positioning, changing slot widgets, or adding or removing buttons will have any affect on how the slot values of an annotation will appear. The reason for this has to do with the fact that an annotation of a class does not create an instances of that class. So when you are looking at the slot values of your annotation you are not looking at an instance of the annotated class, and thus you are not looking at the corresponding form for that class either. However, you can adjust the form for the "knowtator annotation" class, to configure the appearance of the annotation instance which is shown in the lower-right hand corner of the screen (i.e. where the annotator, the spans, etc. or shown).

How do I specify the order that slots appear in? The order that slots appear for an annotation is alphabetical by their display text. See the above FAQ slot display configuration. Simply, change the display text of the slot names such that their alphabetical order is the same as the desired display order. An easy way to accomplish this is by adding a numbers to the display text.

Can you explain the Find/Annotate dialog?
The Find/Annotate dialog is inspired by the Find/Replace search functionality found in most word processors and text editors. Instead of replacing text we will annotate the matched search strings. Search can be done with or without the following: regular expressions, case sensitivity, and whole word matching. Annotation is performed on the selected span corresponding to the matched search string. Alternatively, it is possible to annotate only the text that matches a capturing group (see Pattern doc for more information) by selecting the checkbox labeled "Annotate capturing groups." This option is only available when regular expression search is enabled.

Which version of Knowtator am I using?
To check the version of Knowtator you are running do the following: navigate to Menu->Help->About Plugins->Knowtator. This will contain an information page including version information.

Can a single annotation have multiple spans?
Yes. An annotation can have as many spans associated with it as you want. When you are creating annotation guidelines you should carefully consider whether to allow the annotators to use multiple spans and what circumstances they are allowed. Annotations that have multiple spans can make using the data more difficult. There are two ways to create an annotation with multiple spans. For a new annotation, you can select mulitple spans of text by holding down the control key while selecting spans. Then you create an annotation as you normally would (e.g. by right-clicking a class in the class tree.) The other way is to add a span to an existing annotation. Select the annotation to be modified in the annotation instances panel, select the additional span of text, then click the button labeled 'Add Value' for the 'spans' slot for that annotation. Also, see next FAQ.

How do I modify the span(s) of an existing annotation?
There are two ways to modify the span of an existing annotation. Both approaches require you to select the annotation to be modified in the annotation instances panel. With the annotation selected simply click the grow and shrink span buttons near the label "span edits." This allows for very fine-grained (i.e. character-by-character) modification of a span. The second approach is to select a span of text in the text pane that overlaps with the current span(s). With the text highlighted click the button labeld 'Add Value' for the 'spans' slot for the annotation. This will merge the current span with the selected span. This allows one to make much larger (e.g. sentence-level, paragraph-level) edits to a span.

What is knowtator.pprj, knowtator.pont, and knowtator.pins? Knowtator relies on the frame definitions found in the project knowtator.pprj. When Knowtator is first loaded into a new annotation project the files knowtator.pprj, knowtator.pont, and knowtator.pins are copied into the same directory as the annotation project. The annotation project includes the knowtator project and the support classes can be seen in the Classes tab. All frames defined in the Knowtator project have names that begin with "knowtator" and all of the classes can be found under "knowtator support class". When the the Knowtator project files are updated, Knowtator will automatically update these files after the plugin is updated the first time an annotation project is opened with the new version of Knowtator. You may be asked to save, close, an re-open your annotation project when this happens.

Does Knowtator work with Protégé-OWL? No. Knowtator works with Protégé-Frames only.

Can I change the annotation schema after I have begun annotation? Yes. But here are some things to consider:

1. Knowtator does not respond well to removal of classes (or slots or instances) that have already been annotated. So, the safest thing to do is to deprecate a frame definition rather than delete it. This can be done for a class by moving it to some other location in the class hierarchy and prepending its name with some meaningful prefix (e.g. "deprecated..."). This will ensure that changing your annotation schema does not mess things up for Knowtator.
2. Changing the annotation schema will not change any of your annotations. For example, if you remove a slot from a class definition, annotations of that class can still have values for that slot if they were already there. Or, if you change the value type constraint on a slot value, there is nothing that will change current slot values to conform to the updated constraint.
3. If you want to merge multiple annotation projects that share the same annotation schema, this can be complicated by changing the annotation schema of one of the projects. This is strongly discouraged. If a change needs to take place, then you should be careful to make sure that the same change is made to each annotation project that "shares" the same annotation schema.

How do I create a new Knowtator project? There are three ways to create a new Knowtator project. The first is detailed in the installation instructions. There are two other ways to create a new Knowtator project:

If you already have a Knowtator project, then creating another Knowtator project is very simple.

• Select Menu -> File -> New Knowtator Project.
• Before the currently open project closes you will be given the option to save it. Clicking "Yes" is generally a good idea unless you want to discard all changes since the last time you saved.
• A dialog labeled "Create New Knowtator Project...." appears. Navigate to the folder you want your project saved in and provide a name for the project (e.g. "my-annotation-project") in the text field labeled "File Name". Click 'Open'.
• Knowtator will appear (the Knowtator tab is on the far left) with a sample annotation schema.
• Please visit the quick start guide for what to do next.

If you have downloaded a release of Knowtator that includes the source code, then do the following:

• open a command prompt in the same directory that contains build.xml.
• run ant with the following:

  ant create-new-knowtator-project -Dnew-knowtator-project-dir="my-annotation-project" -Dnew-knowtator-project-name="my-new-project"

What is an "annotation set"? An "annotation set" is a label that can be applied to individual annotations that corresponds to some sensible grouping of annotations in your annotation project. Annotation sets are used by filters to constrain/select annotations of interest. To create an annotation set perform the following steps:

• Click on the "Instances" tab. Below the Protégé menus and the tool bar are tabbed panes. Typical tabs that you will see open are labelled Classes, Slots, Forms, Instances, etc.
• The Instances tab is split into three vertical sections. The left-most section displays the class hierarchy. Expand the subclass of :THING called knowtator support class by clicking the tree expansion icon.
• Select the class called knowtator set.
• The instances of knowtator set appear in the middle section. To create a new filter instance click the create instance icon near the top of the section.
• If the new instance is selected from the list of instances in the middle section, then the slot values for the new instance will appear in the rightmost section. Verify that the new instance is selected and provide a name.

The annotation set can now be used as the default annotation set that is assigned to all new annotations by selecting it in the configuration dialog. Individual annotations can be assigned to the annotation set manually by selecting individual annotations in Knowtator and filling in the slot labeled "annotation set membership". Annotations can also be assigned to an annotation set in batch using the menu option "Assign annotations set value in batch". If you are not happy with the results of using this menu option, then close the project without saving and reopen.

!#$@ undo doesn't work!? True. The undo menu option does not work and should not be used with Knowtator at all. Most user actions that take place in Knowtator correspond to many Protege events. In some cases the undo option may appear to work - but don't be fooled and do not use this option. One work around to the undo option is to close the project without saving it. This will restore the project to the state it was in when it was last saved. You should always save your project before performing any action that creates many changes (e.g. merging projects or re-assigning annotator in batch) so that you can undo the action by closing without saving. You are also encouraged to add your annotation project files to a file repository such as cvs or subversion and commit revisions frequently.

How do I email an annotation project? A Knowtator annotation project consists of six files: knowtator.pprj, knowtator.pont, knowtator.pins, <your-project>.pprj, <your-project>.pont, and <your-project>.pins. When you email a project you should include all six files - perhaps in a single zip file. However, if you are going to do a real annotation project involving multiple people, then it is highly recommended that you use a version control repository such as subversion or CVS. If you do not have access to a repository, then there are many hosting services that will provide you one.

How do I obtain the latest patch for Knowtator? To obtain the latest patch of Knowtator without having to build it yourself from source please do the following:

• Install the latest version of Knowtator
• Download the latest knowtator.jar from here.
• Overwrite the knowtator.jar file that can be found in your Knowtator/Protege installation directory. This should be in your file system at <protege-home>/plugins/edu.uchsc.ccp.knowtator where <protege-home> is generally something like "C:/Program Files/Protege 3.3.1".
• Restart Knowtator/Protege if it is open.

To see a list of what bugs have been fixed and features implemented since the last release that may be available in the latest patch please see the current release notes in the repository which can be found here.