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.
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:
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:
It is possible to make the annotation appear as
"melanoma at toe" by doing the following:
It is possible to make the annotation appear as
"melanoma at toe [Jane Doe]" by doing the following:
How do I configure the displayed text of a slot?
To configure the display of a slot name do the following:
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.
Can I change the annotation schema after I have begun annotation? Yes. But here are some things to consider:
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.
Menu -> File -> New Knowtator Project.
If you have downloaded a release of Knowtator that includes the source code, then do 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:
knowtator support classby clicking the tree expansion icon.
knowtator setappear in the middle section. To create a new filter instance click the create instance icon near the top of the section.
!#$@ 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:
<protege-home>/plugins/edu.uchsc.ccp.knowtatorwhere <protege-home> is generally something like "C:/Program Files/Protege 3.3.1".