Viewing and editing annotation details

The MAT UI provides a full range of functionality for editing (and viewing) annotation details.

• Which annotations have annotation detail views?
• Modifying annotations and launching an annotation editor
• The annotation editor
• Annotation-valued attributes, annotation editors, and choose mode
• Linking annotations via the annotation editor
  
• Atomic vs. set- or list-valued annotation attributes
  
• The "Actions" menu in the annotation editor
• Linking annotations via the annotation popup menus
• Guided navigation mode
  
• Highlighting and scrolling
  

Which annotations have annotation detail views?

An annotation has a detail view if

• it has any attributes (including attributes which define effective labels); or
  
• it can serve as the value of another annotation's annotation-valued attribute.

If the document is editable, those details which are currently editable will be editable in the detail view.

We refer to these views as annotation editors, and we refer (perhaps confusingly) to summoning these views as "editing (or viewing) an annotation".

Modifying annotations and launching an annotation editor

Let's select an annotation which has some rich structure:

You can see that you can modify the annotation in a number of ways:

• You can edit the annotation in an annotation editor, with full access to all the annotation's attributes.
• If the annotation type has choice (enumerated) attributes (such as the "nomtype" attribute above) or boolean attributes, and those attributes are currently editable, you can set them directly from a submenu in the annotation popup menu. If the choice attribute has keyboard accelerators defined, you can press the specified key when the submenu is visible, which will have the same effect as selecting the menu item. Boolean attributes will always have the accelerators Y and N defined.
  
• If the annotation can fill annotation-valued attributes, or has annotation-valued attributes, and those attributes are currently editable, you can make these links from the annotation popup menu directly (see the section on annotation-valued attributes).

You have a similar range of actions available when you click on an annotation in the annotation table:

In the remainder of this section, we'll focus on summoning an annotation editor.

By default, the popup menu gives you the option of editing the annotation in a popup, or in a tab. You can provide a default via the "View -> Edit/view annotations in tabs" or "View -> Edit/view annotations in popups" option from the top menubar. If you choose one or the other of these, the popup menu will have a single "Edit annotation" entry, which will open an annotation editor in your preferred mode.

By default, the editor popup appears as a dialog in the upper right corner of your window:

The editor tab appears in the detail tab area at the bottom, where the annotation tables appear:

Note the green border around the editor; this indicates that the editor is the active editor, which becomes relevant when we want to fill annotation-valued attributes.

If none of the attributes are editable (if, e.g., the document was opened read-only, or the current step doesn't make hand annotation available, or the current step doesn't allow you to edit any of the attributes of the annotation type), the entry in the annotation popup menu will read "View..." instead of "Edit...". In all cases, the editor will allow you to edit only those attributes which are currently editable:

The annotation editor

The annotation editor contains a brief description of the annotation, either in the title bar (if editing in a popup) or the tab itself (if editing in a tab). This description supplements the attribute details in the editor itself.

At the top of the editor is a two-column table, with the attributes and their types on the left and the value editor elements on the right. Attributes which are not currently editable will be described. Each editable attribute type has a different type of value editor:

Below this table is an optional "References" section, which we'll see exemplified below, and then an "Actions" menu.

You can dismiss an editor a popup by pressing "Done" or pressing the "x" in the title bar, and you can dismiss an editor in a tab by pressing the "x" in the tab label.

Annotation-valued attributes, annotation editors, and choose mode

Annotation-valued attributes can be filled either via the annotation which has the attribute, or from the candidate filler. In addition, they can be filled either from the annotation editor, or directly from the annotation popup menu.

Linking annotations via the annotation editor

In annotation editors, annotation-valued attributes, when unfilled, present the string "(null)" and two buttons: "Choose", and "Unset", which clears the value.

Pressing "Choose" causes the document to enter choose mode. Choose mode allows you to create or select an annotation which can be the value of this attribute. In choose mode, the "Choose" button now reads "Choosing (press to exit)", and the status line above the document text now reads "Choose mode: active", along with an option to exit:

In choose mode, you have two options:

• If your current annotation step supports creating any of the annotation types, you can swipe text or click on a blank space in the sidebar to create a new annotation to serve as the attribute value. If there's only one kind of annotation that can fill the attribute (or if only one kind of annotation can currently be created) the annotation will be created immediately. Otherwise, you'll get a popup menu corresponding to your choices. One difference between creating a span annotation in choose mode versus normal annotation mode is that clicking on a token in the annotation pane will not create a swipe spanning that token; you must actually swipe the text.
• You can select an existing annotation, to choose it as the value.
  

Unfortunately, the UI doesn't provide immediate feedback, when hovering over an annotation, whether it's an acceptable value for the attribute in choose mode. You'll see the annotation details, as usual, in the status line immediately below the annotation text, but it's up to you to determine whether the annotation you're about to select is appropriate. If it's not (e.g., if it's a LOCATION, but the attribute is limited to PERSON), you'll get a popup dialog informing you that the choice is incorrect, and giving you the option to try again, or exit.

You can select an existing annotation as filler either by clicking on it in the annotation pane itself, or by clicking on it in the annotation table. When you click on an annotation in the annotation table, and choose mode is active, the popup menu will contain a "Choose this annotation" action; selecting this action is equivalent to clicking on the annotation in the annotation pane.

In addition to invoking choose mode from the annotation editor itself, another way to add annotations to the active editor is to select the candidate value annotation in the annotation pane. For the active editor, the annotation popup menu will contain entries which allow you to set any eligible attribute value in the active editor. For example, in the case above, clicking on "David Asher" will bring up a menu which contains an entry "Add as actor to edited annotation". The background color of this entry will be the same as the border color of the active editor. Selecting this entry will make this annotation the value of the actor attribute in the active editor.

When an acceptable annotation is selected as an attribute value, the annotation and attribute which point to it are listed in the "References" column in the annotation tables, and in the "References" section of the annotation editor for the value:

These references are mouseable, and will present a popup menu:

The important menu item here is "Detach from this location". If you select this item, the annotation will be removed from the specified attribute value. The parallel situation arises with the attribute values themselves; they too are mouseable, and you can detach the values via the popup menu:

We'll discuss scrolling below.

Atomic vs. set- or list-valued annotation attributes

For simple annotation-valued attributes, the button to enter choose mode will be labeled "Choose"; once you select an acceptable value, the UI exits choose mode automatically.

If the annotation attribute is a set or list attribute, the presentation will be slightly different. The value(s) will be enclosed in curly brackets ({...}), and each value will be separately mouseable.

The button to enter choose mode will be named "Add" rather than "Choose". When you enter choose mode, the UI will remain in choose mode until you explicitly exit, allowing you to select multiple fillers without having to re-enter choose mode each time.

If you detach all the annotation values, your result will be an empty list or set, which is not equivalent to a null value; to clear the value entirely, use the "Unset" button.

The "Actions" menu in the annotation editor

The "Actions" menu in the annotation editor allows you to delete annotations, but also to attach annotations to other annotation attribute values, if the task allows:

If you select one of the "Add..." items, you'll enter choose mode again, but this time, you'll be selecting or creating the annotation to attach this annotation to, rather than the annotation to attach to this annotation. Note that each "Add..." entry specifies an attribute into which this attribute will be inserted. If you enter choose mode, you will be able to exit by choosing the orange "Choosing (press to exit)" button that will appear immediately under the "Actions" button, or by clicking the orange "Exit" button in the status line as in the previous choose mode example.

Linking annotations via the annotation popup menus

As we saw here, you can also use the annotation popup menus to link annotations together. If you're starting with the candidate filler, you can attach it to other annotations in the same way you can use the "Actions" menu, as we just saw. No annotation editor needs to be involved. Let's return to our original example:

If you select "Add as location to LOCATED_EVENT...", you'll enter choose mode, but the contextual information you need is provided not by an annotation editor, but by a separate popup:

Guided navigation mode

While the annotation editors are easily navigable, experienced annotators might prefer to navigate through them more quickly. To support this activity, we've introduced guided navigation mode. In this mode, you can navigate through your annotation editor almost exclusively via the keyboard (the lone exception is annotation-valued attributes, which require mouse interaction).

To enter guided navigation mode, you will most likely have to modify the UI settings. Select "View -> All settings...", and change the setting labeled "When to enter guided navigation mode in annotation editors". There are three possible values:

• "never" (default): you will not have the opportunity to enter guided navigation mode.
• "always": when an annotation editor opens, it will enter guided navigation mode immediately.
• "on request": when an annotation editor opens, you'll have the option of entering guided navigation mode. If you press "*", you'll enter guided navigation mode and nothing else will happen; if you press "+", you'll enter guided navigation mode, and until you disable guided navigation mode by selecting "never", any annotation editor for an annotation with the same annotation label will enter guided navigation mode immediately when opened.
  

You can change the default value as described here.

Here's what your annotation window will look like when you edit the first instance of "North Korea", and you've selected "on request" as the UI setting:

As you can see, the annotation editor bears the instruction "Press '*' to enter guided navigation mode, or '+' to also enter automatically for this label in the future" at the top.

Once you're in guided navigation mode (either because you pressed "*" or "+", or you've entered guided navigation mode automatically), your window will look like this:

Note that the annotation editor now says "In guided navigation mode" at the top, and the first attribute is outlined. Note, too, that the menu associated with this attribute has been changed from a native HTML menu to a more feature-rich menu which better supports this mode, and that this menu is open.

When you choose a value for an attribute in guided navigation mode, you'll be automatically advanced to the next attribute. So in this case, if you press "2", you'll choose the value "Proper name" for the "nomtype" attribute, and you'll be advanced to the boolean "is_political_entity" attribute:

Note that the instructions have changed. Press 'y' to identify this element as a political entity; once you do this, the annotation editor will close automatically, since there are no other attributes to set.

There are multiple ways to navigate through the attributes in keyboard navigation mode:

• You can set each value to advance through the attributes.
• You can advance past an attribute by pressing the <return> or <enter> key (usually; for multi-line string attributes, the advance key is the right arrow).
  
• For non-annotation-valued attributes, you can select an attribute with the mouse (e.g., a type-in or menu), and keyboard navigation mode will move the focus to that attribute.
• You can tab through the annotation editor as you would through any HTML form, and keyboard navigation mode will follow the focus (with the exception of annotation-valued attributes, which have no focusable elements).

Each attribute provides different facilities for setting the value via the keyboard. The interaction instructions are provided as each attribute is edited.

When you advance out of the final navigable attribute, one of two things will happen. If there are no more editable attributes, the annotation editor will close automatically. If, on the other hand, there are editable, non-navigable attributes (e.g., attributes with custom editors) which follow the final navigable attribute, you'll exit guided navigation mode but the editor will remain open.

Highlighting and scrolling

The various annotation popup menus give you the option to "Scroll to annotation". If you select this action, the UI will do its best to vertically center the selected annotation in the main editor window.

In conjunction with scrolling, the UI provides highlighting so you can find the annotation you're looking for. When you hover over an annotation just about anywhere other than the main document window - in the title of an annotation editor, or over a row in the annotation table, or in the "References" section of the annotation editor, or the "References" column of the annotation table, or the value of an annotation-valued attribute in the annotation editor - the annotation itself will be highlighted in the main annotation window:

Notice here that "he" in the third paragraph is surrounded by a box as the mouse hovers over the annotation attribute value.

You can also examine links between annotations using highlighting. When you highlight an annotation in the document window which has annotation attribute values, its attribute values will be highlighted, along with the attribute that the value fills:

Similarly, if you hover over an annotation which is the value of another annotation attribute, the annotation it's linked to will be highlighted, along with the attribute it fills in that other annotation.