Annotation and annotation display XML reference

The XML format for defining annotations and their display properties in the task files (see "Creating a New Task") is described in this document. Use cases can be found here. Click here for a split-screen view.

There are two methods for defining annotations and their display elements. The legacy method consists of the <annotation_set_descriptor> element and its children, along with the <annotation_display> element and (most of) its children. The new method, more concise and differently organized, is represented by the <annotations> element. For a comparison of the two mechanisms, see the use cases here.

It's possible to combine the two methods. In that case, the processing order is first <annotation_set_descriptors>, then <annotations>, then <annotation_display>.

Element hierarchy

<annotation_set_descriptor>
<annotation>
<attribute>
<range>
<choice>
<label_restriction>
<attributes>
<annotation_display>
<label>
<gesture>
<attribute>
<choice>
<label_group>
<gesture>
<annotations>
<span>
<effective_labels>
<label>
<display_group>
<int>
<choice>
<int_set>
<int_list>
<string>
<choice>
<string_set>
<string_list>
<float>
<float_set>
<float_list>
<boolean>
<filler>
<filler_type>
<filler_set>
<filler_list>
<spanless>
<int>, <int_set>, <int_list>, <float>, <float_set>, <float_list>,
<effective_labels>, <string>, <string_set>, <string_list>,
<boolean>, <filler>, <filler_set>, <filler_list>
<display_group>
<span>, <spanless>, <display_group>

<annotation_set_descriptor>

The toplevel element. Each annotation set descriptor corresponds to a subset of the annotations used in your task.

For simple tasks, there's no reason to define more than one set of content annotations. If your task is more complex - e.g., if you have both mentions and relations between them, for instance - you may choose to have multiple content annotation sets; you can specify that particular steps in your workflow modify or add different sets, and you can do mixed-initiative annotation for each set separately, if you have different trainable engines for the different sets. You can even have sets which contain attributes of annotations which were introduced in a different set, so you can edit these attributes in their own step.

XML attributes

XML attribute
Value
Obligatory?
Description
name a string
yes The name of the annotation set descriptor. By convention, for tasks with a single set of content annotations, this is "content". There are no restrictions on the name.

Children

Element
Obligatory?
Repeatable?
Description
<annotation> no yes A possible annotation in the descriptor.
<attribute> no yes An attribute for some annotation(s) in the descriptor.

<annotation> (of <annotation_set_descriptor>)

Each annotation type in the set descriptor is defined by one of these elements. Note that the attributes for the annotation are defined as sister elements, not children, to make it possible for attributes to be defined in separate sets from their annotations.

XML attributes

XML attribute
Value
Obligatory?
Description
label a string
yes The label for the annotation type.
all_attributes_known "yes"
no Under normal circumstances, MAT does not object to finding "undeclared" attributes of annotations in the documents it reads. If this XML attribute/value pair is present, the annotation type is "locked"; in other words, when MAT reads in a document in the context of a task corresponding to this annotation set descriptor, it will object to any "stray" attributes which appear on annotations of this type.
span "no"
no By default, annotation types define spanned annotations. If this XML attribute/value pair is present, this type will be spanless.
processable
"no"
no
By default, all annotation types can be used as training input, if you train a model on the annotation step that adds the set they're a member of. In some cases, however, the annotator might want an annotation available during hand annotation for a step, but intended intended as a memo for hand annotation only, rather than input to a training algorithm (e.g., "LookAtThisAgain", "WhatIsThis"). You can designate such an annotation by adding processable="no" to its declaration. Both the model trainer and the scorer will ignore labels marked in this way.

<attribute> (of <annotation_set_descriptor>)

Attributes are defined separately from the annotations that bear them. The reason for this is to enable annotation sets, and steps which edit them, which only add an attribute to an existing annotation (e.g., part-of-speech tagging implemented as adding a "POS" attribute to the "lex" tag).

The default value of every attribute is null unless otherwise specified.

XML attributes

XML attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
of_annotation a comma-separated sequence of strings
yes The annotation label or labels which bear this attribute.
type one of "string", "int", "float", "boolean", "annotation"
no The type of the attribute value. Default is "string".
aggregation one of "set", "list"
no By default, the values of attributes are singletons. If you want the value to be a set or list of the objects of the specified type, indicate it with this XML attribute.
default various
no If present, a default value for this attribute. The value must be of the appropriate type. For "boolean" attributes, use "yes" or "no". Defaults are not available for "annotation" attributes. This attribute can't be defined alongside the "default_is_text_span" attribute.
default_is_text_span "yes"
no If present, the default value for this attribute is digested from the span of the annotation (so this option is only available for attributes of spanned annotations). If the span can't be digested into a value of the appropriate type, no default will be set. This attribute can't be defined alongside the "default" attribute.

This attribute is available for "int", "string", and "float" attributes.

Children

Element
Obligatory?
Repeatable?
Description
<range> no no For "int" and "float" attributes, the range of permitted values.
<choice> no yes For "string" and "int" attributes, one of the possible choices for values. If the attribute has at least one <choice> child, the choices listed are the only permitted values.

This element has no element children; its value is the text it delimits.
<label_restriction> no yes For "annotation" attributes, a restriction on attribute value. For any "annotation" attribute, there must be at least one label restriction. Every value must satisfy at least one of the restrictions.

<range> (of <attribute>)

For "int" and "float" attributes, you can define a range for the possible attribute values. You can define both endpoints of the range, or only one.

For "int" attributes, <choice> and <range> cannot cooccur.

XML attributes

XML attribute
Value
Obligatory?
Description
from
an int or float
no The minimum (inclusive) endpoint of the range. The required type of the value depends on the type of the attribute that bears it.
to an int or float
no The maximum (inclusive) endpoint of the range. The required type of the value depends on the type of the attribute that bears it.

<choice>

For "string" and "int" attributes, you may provide a list of explicit choices. If the attribute has at least one <choice> child, the choices listed are the only permitted values. The <choice> element enclosed text is the choice itself.

You can further specify choices as "effective labels", which are notional labels which are actually implemented as a label + attribute/value pair, e.g., "PERSON" implemented as "ENAMEX" + "type" = "PER". You can refer to these effective labels in various places in the task and annotation set descriptor specifications, as marked.

If one <choice> element has an effective label, they all must; and no more than one attribute for a given annotation type may define effective labels. The effective label must be distinct from all other effective labels in the set, and all other annotation labels.

For "int" attributes, <choice> and <range> cannot cooccur.

XML attributes

XML attribute
Value
Obligatory?
Description
effective_label a string
no If present, the effective label corresponding to the combination of this annotation with this attribute value.

<label_restriction> (of <attribute>)

For "annotation" attributes, you must define at least one label restriction. Every value of the attribute must satisfy at least one of the restrictions. The restrictions can be a simple label or effective label, or they can also bear attribute/value restrictions.

XML attributes

XML attribute
Value
Obligatory?
Description
label a string
yes A label or effective label which the attribute value must match in order to satisfy this restriction.

Children

Element
Obligatory?
Repeatable?
Description
<attributes> no no Arbitrary attribute/value pairs which must also be satisfied.

<attributes> (of <label_restriction>)

Label restrictions may also bear attribute/value pairs which must be satisfied in order to satisfy the restriction.

XML attributes

XML attribute
Value
Obligatory?
Description
<attr> a string no the <attributes> element supports arbitrary XML attribute-value pairs. Each <attr> must be defined for the label restriction label, and must be a choice attribute (i.e., either a string or int attribute which has choices associated with it).

<annotation_display>

This element defines all the display-related properties in the MAT UI of the elements defined in an <annotation_set_descriptor> element. Most of what you can do here is define the display-related properties of labels, although you can also define some of the properties of attributes, and also define groups for hierarchical annotation displays.

Note that the order in which the elements in <annotation_display> are defined is the order in which the CSS display rules are defined; so the styling of <label> and <label_group> elements takes precedence of the styling of previous <label> and <label_group> elements.

The <annotation_display> element and (most of) its children, along with the <annotation_set_descriptors> element and its children, constitute the legacy method for defining annotations and their display elements. For a more concise and differently organized mechanism, see the <annotations> element. For a comparison of the two mechanisms, see the use cases here. Note that the <gesture> element is only definable in the legacy <annotation_display> subsystem.

It's possible to combine the two methods. In that case, the processing order is first, <annotation_set_descriptors>, then <annotations>, then <annotation_display>.

Children

Element
Obligatory?
Repeatable?
Description
<label> no yes Defines the display-related properties for a true or effective label
<attribute> no yes Defines the display-related properties for an attribute of a particular label
<label_group> no yes Defines groups for hierarchical annotation displays
<gesture>
no
yes
Defines arbitrary menu gestures for the annotation popup menu

<label> (of <annotation_display>)

This element defines the display-related properties of true or effective labels.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The true or effective label to which this definition applies.
accelerator a single-character string
no If specified, this accelerator will be available in the annotation selection menu in the Web UI; if the user presses this key, this annotation will be selected for the span, just as if the element in the menu had been chosen. If the same accelerator is used in more than one place, and only one of the uses is visible (if, e.g., you have set up label groups to create a hierarchical menu), the visible one will be used. Otherwise, in the case of unresolved ambiguity, nothing will happen when you press the key.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.
edit_immediately "yes"
no If a label has attributes, or if it can be the value of an annotation-valued attribute, it is possible to edit the annotation in the UI, either in a popup dialog or in a detail tab. If the annotation is spanless, this editor will appear automatically when the annotation is created; if it is spanned, it will not. If you provide this attribute-value pair, the editor will appear automatically when the annotation is created, whether or not it's spanned.
presented_name a format string
no In the UI, there are many places (e.g., in the annotation tables) where the annotation can be described, and by default, the description for spanned annotations is the covered text, while the description for spanless annotations is the annotation ID. Sometimes, this name isn't what you would prefer it to be, and you can use this attribute to define the name you prefer. The syntax for the value of this string is described immediately below.
css a string of legal CSS
no If the label is a spanned label, the UI will apply this CSS on a token-by-token basis to any span labeled by this annotation. If the label is a spanless label, the CSS will be applied to its icon in the spanless sidebar. Because there's no text in the spanless sidebar, and because annotations can overlap and be displayed in an exploded, stacked representation in spanned hand annotation and in comparison, it's probably best to ensure that the primary aspect of this CSS is background styling.
overlap_rank
an integer
no
By default, the overlap order of spanned annotations in a task is the order in which they're defined. However, you can modify this overlap order by specifying overlap_rank on some or all of your labels. If at least one overlap_rank is specified, all labels lacking the specification will be ordered (in the order they're defined) behind the labels bearing a specification, and all those labels bearing a specification will be ordered in front of those other labels, in the order of their overlap_rank value. If the task has a parent task, all labels not defined locally will be ordered behind the locally defined labels.

Children

Element
Obligatory?
Repeatable?
Description
<gesture>
no
yes
Defines special menu gesture for the annotation popup menu for this label

The syntax of the presented_name attribute

The presented_name attribute is a simple string, with format directive of the form $(...). The values within the parentheses can be any of the attributes of the label (in which case the format directive will be replaced by the attribute value), or one of the special values listed below. The format directive can also contain key-value pairs, as in $(val:a=b,c=d). We describe the possible key-value pairs below as well.

special value
interpretation
_start
The start index of the spanned annotation
_end
The end index of the spanned annotation
_parent
The parent annotation(s) (i.e., the annotation(s) which have this annotation as a value of an annotation-valued attribute)
_label
The true or effective label of the annotation
_text
The spanned text of the spanned annotation

key
available for
possible value
interpretation
truncate
_text
integer
If specified, the UI will ensure that the spanned text is no longer than n characters long. This value cannot be less than 5. The UI will show the beginning and end of the text, and show the truncated medial text with ellipses (...).
truncate
_parent
integer
If specified, the UI will limit the number of parent annotations listed, and indicate the remainder of the list with ellipses (...).
showLabel
_parent, any annotation-valued attribute
"no"
By default, when the UI displays an annotation attribute value as part of the name of an annotation, it contains the label of the annotation value. If you don't want the label displayed, provide this key-value pair.
showIndices
_parent, any annotation-valued attribute "yes"
By default, when the UI displays an annotation attribute value as part of the name of an annotation,it does not display its start and end indices. If you want these indices displayed, provide this key-value pair.
showFormattedName
_parent, any annotation-valued attribute "yes"
By default, when the UI displays an annotation attribute value as part of the name of an annotation, it does not display the value's formatted name. If you want the formatted name displayed, provide this key-value pair.
showFeatures
_parent, any annotation-valued attribute "yes"
By default, when the UI displays an annotation attribute value as part of the name of an annotation, it does not display the values attribute-value pairs. If you want these pairs displayed, provide this key-value pair.

So, for example, if you want the presented name of your annotation to contain the text truncated to 20 characters, your value for presented_name would be "$(_text:truncate=20)".

<gesture> (of <label>)

In some cases, you may want to customize the annotation menu actions for an existing annotation. These actions will appear in the annotation popup menu when you select an existing annotation, not when you create a new one. You'll need to be able to do some programming to implement the action. If this gesture is defined in the scope of a true label which corresponds to effective labels, the gesture will be made available to all the effective labels.

See also the for_label attribute of the <gesture> subelement of <annotation_display>.

Attributes

Attribute
Value
Obligatory?
Description
label a string
yes The label that will appear in the annotation popup menu.
function a string
yes
This Javascript function will be invoked on the existing annotation and the document display. You can define your function in your task directory in your Javascript customization file. Unfortunately, we don't really have the resources to document the API this function has to conform to; either dig through the source code yourself, or ask us for help.

<attribute> (of <annotation_display>)

This element defines the display-related properties for specific annotation attributes.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of a known attribute
of_annotation a string
yes The name of a known true or effective label
editor_style "long_string"
no There are two ways of providing attribute values for non-choice string attributes in the UI: via a short typein window or via a multi-line typein window. By default, a short typein window will be used. If you provide this attribute-value pair, a long typein window will be used. Ignored if the attribute is not a string attribute, or if it's a choice attribute.
max_choice_size
an integer
no
For set-valued string and int attributes with choices, this attribute provides a way of limiting the size of the presented multi-select in the UI. By default, the maximum size is 5. For choice sets above this size, the multi-select will scroll.
read_only
"yes"
no
Attributes are typically editable. If for some reason you don't want to be able to edit an attribute directly in the annotation editor (e.g., the attribute value is automatically populated by a custom editor, as described below), use this setting.
custom_editor a string
no You may have a string attribute which is actually a date, which you want to use a calendar widget to populate; or you might want to look up the annotation text in a database, and use the results to populate the attribute value. If you're willing to do some programming, you can use this attribute to specify an arbitrary JavaScript function for a string, int, or float attribute, to use as its editor. You can define your function in your task directory in your Javascript customization file. Unfortunately, we don't really have the resources to document the API this function has to conform to; either dig through the source code yourself, or ask us for help.
custom_editor_is_multiattribute "yes"
no If you've associated a custom_editor with this attribute, this attribute-value pair tells the UI that the editor will fill multiple attributes.
custom_editor_button_label
a string
no
If you have a custom editor, but you want the label to be something other than "Edit" (let's say the value is automatically calculated when you press the button), use this.
url_link
a string
no
When the annotation attribute is displayed in the annotation editor or the annotation table, the annotation will be used to construct a URL link. The syntax is identical to that of presented_name above, except that of the special values, only _text is recognized, and no key-value pairs are recognized within each directive. So, e.g., if you want the link on an annotation attribute to search for the spanned text in Google, the value of url_link would be

http://www.google.com/search?q=$(_text)

Children

Element
Obligatory?
Repeatable?
Description
<choice> no yes Container for accelerators for choice attributes

<choice> (of <attribute>)

When you select an existing annotation in the UI, you have the option of modifying choice attributes of that annotation via the annotation popup menu. The purpose of the <choice> element in the annotation display is to specify a keyboard accelerator you can use to select a particular choice attribute. The value of the choice attribute is the text it delimits, and that text must match precisely the value defined in the corresponding <choice> element in the annotation set descriptor. If this task has a parent task, and an accelerator for this annotation, attribute and choice is defined, it will be inherited unless overridden locally.

Attributes

Attribute
Value
Obligatory?
Description
accelerator a single-character string
yes This accelerator will be available in the annotation popup submenu in the Web UI which corresponds to the attribute which bears this choice; if the user presses this key, this choice will be selected for the attribute, just as if the element in the menu had been chosen.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.

<label_group> (of <annotation_display>)

Under some circumstances, you might want to create cascaded annotation menus in the MAT UI, perhaps in order to group together similar annotations, or provide options for more or less general annotations, or to compress the screen real estate taken up by the annotation popup menu. You can use the <label_group> element to accomplish this.

Each label group has a name. This might correspond to a known true or effective label (in which case it refers to that annotation), or it might be a previously unknown name, in which case it serves merely as a group. The children of each label group can be actual annotation names, or other known label groups. The annotations the label group refers to must be content annotations. If the label group is not otherwise known, it has the option of declaring CSS styling for the menu entry.

Label groups are inherited from an available parent task; this group information is filtered by the locally defined annotations. Local label groups override parent label groups.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the label group, either a new name or the name of a true or effective content annotation
children a string
yes A comma-delimited sequence of names, either names of existing content annotations or of known label groups
css a string
no Like the css attribute on the <label> element above. Used to assign styling to otherwise unknown label groups.

<gesture> (of <annotation_display>)

This element defines arbitrary menu gestures for the annotation popup menu. Its functionality is similar to the custom_editor and url_link attributes of the <attribute> element. These elements refer primarily to swiped text, so they're only available in the spanned annotation pane.

Attributes

Attribute
Value
Obligatory?
Description
label a string
yes The label that will appear in the annotation popup menu.
function a string
no You might wish to invoke a Javascript function on the text, start index and end index of your mouse selection (either a swipe, or a selected annotation). If you're willing to do some programming, you can use this attribute to specify an arbitrary JavaScript function to call. You can define your function in your task directory in your Javascript customization file. Unfortunately, we don't really have the resources to document the API this function has to conform to; either dig through the source code yourself, or ask us for help.

Either this or the url_link attribute must be specified.
url_link
a string
no
The text, start index and end index are used to create a URL, which will be presented in new browser window. The syntax is identical to that of presented_name above, except that only _text, _start and _end are recognized, and no key-value pairs are recognized within each directive. So, e.g., if you want this gesture to search for the spanned text in Google, the value of url_link would be

http://www.google.com/search?q=$(_text)

Either this or the function attribute must be specified.
for_label
a string
no
If present, this element duplicates the functionality of the <gesture> subelement of the <label> element in <annotation_display>. The value should be the true or effective label for which this gesture applies, and function must be specified, and url_link must not be. The primary value of this attribute is to ensure that label-specific gestures can be conveniently declared when using the new <annotations> element.

<annotations> (of <task>)

The <annotations> element, introduced in MAT 3.1, provides a more concise and differently organized mechanism for defining annotations and their display elements, in comparison with the legacy <annotation_set_descriptors> element and its children, along with the <annotation_display> element and (most of) its children. For a comparison of the two mechanisms, see the use cases here.

It's possible to combine the two methods. In that case, the processing order is first, <annotation_set_descriptors>, then <annotations>, then <annotation_display>.

Attributes

Attribute
Value
Obligatory?
Description
all_annotations_known "yes" no By default, the task leaves its annotation sets "open"; i.e., if the task encounters an unknown annotation label, it won't raise an error. If you provide the value "yes" for this attribute, an error will be raised if the task encounters an unknown annotation.
inherit a comma-separated list of labels to inherit no You can inherit annotations from other tasks, either by true label, by set (see the "of_set" attribute of the child elements) or by category (see the "of_category" attribute of the child elements). To inherit an annotation by label, simply list it; to inherit a category or set, list "category:" or "set:" + the category or set name. Individual true labels will be inherited with all of their attributes, even those defined in other sets. You can augment inherited sets, categories or true labels in the child task.

A typical value for this attribute is "category:zone,category:token", which inherits the annotations for the zone and token categories from the parent (usually root) task.

Children

Element
Obligatory?
Repeatable?
Description
<span> no yes A spanned annotation label.
<spanless> no yes A spanless annotation label.
<display_group> no yes A grouping of labels for hierarchical label display.

<span> (of <annotations>)

This element defines a spanned annotation type.

Attributes

Attribute
Value
Obligatory?
Description
label a string
yes The label for the annotation type.
all_attributes_known "yes"
no Under normal circumstances, MAT does not object to finding "undeclared" attributes of annotations in the documents it reads. If this XML attribute/value pair is present, the annotation type is "locked"; in other words, when MAT reads in a document in the context of a task corresponding to this annotation set descriptor, it will object to any "stray" attributes which appear on annotations of this type.
of_set
a string
no
The annotation set descriptor to which this annotation type belongs. If not specified, the value is "content". The names are user-definable, and you can have a many-to-one mapping from names to categories, to facilitate set grouping. See here for an overview.
of_category
a string
no
The category to which the annotation set descriptor for this annotation type belongs. If not specified, the value is "content". See here for an overview.
processable "no"
no By default, all annotation types can be used as training input, if you train a model on the annotation step that adds the set they're a member of. In some cases, however, the annotator might want an annotation available during hand annotation for a step, but intended intended as a memo for hand annotation only, rather than input to a training algorithm (e.g., "LookAtThisAgain", "WhatIsThis"). You can designate such an annotation by adding processable="no" to its declaration. Both the model trainer and the scorer will ignore labels marked in this way.

Display attributes

All attributes related to the display of this annotation in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_css a string of legal CSS no The UI will apply this CSS on a token-by-token basis to any span labeled by this annotation.
d_presented_name a format string no In the UI, there are many places (e.g., in the annotation tables) where the annotation can be described, and by default, the description for spanned annotations is the covered text. Sometimes, this name isn't what you would prefer it to be, and you can use this attribute to define the name you prefer. The syntax for the value of this string is described here.
d_accelerator a single-character string no If specified, this accelerator will be available in the annotation selection menu in the Web UI; if the user presses this key, this annotation will be selected for the span, just as if the element in the menu had been chosen. If the same accelerator is used in more than one place, and only one of the uses is visible (if, e.g., you have set up label groups to create a hierarchical menu), the visible one will be used. Otherwise, in the case of unresolved ambiguity, nothing will happen when you press the key.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.
d_edit_immediately "yes" no If a label has attributes, or if it can be the value of an annotation-valued attribute, it is possible to edit the annotation in the UI, either in a popup dialog or in a detail tab. If you provide this attribute-value pair, the editor will appear automatically when the annotation is created.
d_overlap_rank
an integer
no
By default, the overlap order of spanned annotations in a task is the order in which they're defined. However, you can modify this overlap order by specifying overlap_rank on some or all of your labels. If at least one overlap_rank is specified, all labels lacking the specification will be ordered (in the order they're defined) behind the labels bearing a specification, and all those labels bearing a specification will be ordered in front of those other labels, in the order of their overlap_rank value. If the task has a parent task, all labels not defined locally will be ordered behind the locally defined labels.

Children

Element
Obligatory?
Repeatable?
Description
<effective_labels> no no A string attribute which defines an effective label.
<int> no yes An integer attribute.
<int_set> no yes A set-valued integer attribute.
<int_list> no yes A list-valued integer attribute.
<string> no yes A string attribute.
<string_set> no yes A set-valued string attribute.
<string_list> no yes A list-valued string attribute.
<float> no yes A float attribute.
<float_set> no yes A set-valued float attribute.
<float_list> no yes A list-valued float attribute.
<boolean> no yes A boolean attribute.
<filler> no yes An annotation attribute
<filler_set> no yes A set-valued annotation attribute.
<filler_list> no yes A list-valued annotation attribute.

<effective_labels> (of <span>)

An <effective_labels> attribute is a special type of string attribute. String (and integer) attributes can have explicit lists of choices as possible values for the attribute. An "effective label" is a notional label which are actually implemented as a label + attribute/value pair, e.g., "PERSON" implemented as "ENAMEX" + "type" = "PER". You can refer to these effective labels in various places in the task and annotation set descriptor specifications, as marked. Because these string choices can be given notional names and their own display properties, we've chosen to break out these string attributes in their own definition.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
of_set a string
no The annotation set descriptor to which this attribute belongs. If not specified, the value is "content". The names are user-definable, and you can have a many-to-one mapping from names to categories, to facilitate set grouping. See here for an overview. Attributes can be defined in separate sets from the annotations that bear them, to facilitate distinct automated and human processing of the attributes.
of_category a string
no The category to which the annotation set descriptor for this attribute belongs. If not specified, the value is "content". See here for an overview.

Children

Element
Obligatory?
Repeatable?
Description
<label> yes yes An effective label alternative.
<display_group> no no The presence of this element indicates that these effective labels ought to be hierarchically organized as a group for display

<label> (of <effective_labels>)

Each <effective_labels> element can have multiple <label> children, each of which has a value and an optional label (which defaults to the value). The label attribute defines what the user sees; e.g., if an ENAMEX annotation type has a "type" <effective_labels> attribute which a <label> whose value is "PER" and whose label is "PERSON", an ENAMEX annotation with a "PER" value for the "type" attribute will see the label "PERSON" in the UI.

Attributes

Attribute
Value
Obligatory?
Description
value a string
yes One of the permitted values for the attribute.
label a string
no If present, the label the user sees in the UI when this attribute is set. Defaults to the value of the value attribute.

Display attributes

Because these labels are essentially the same as true toplevel labels from the point of view of the UI, the display attributes here are identical to those for the <span> and <spanless> elements.

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_css a string of legal CSS no If the label is a spanned label, the UI will apply this CSS on a token-by-token basis to any span labeled by this annotation. If the label is a spanless label, the CSS will be applied to its icon in the spanless sidebar. Because there's no text in the spanless sidebar, and because annotations can overlap and be displayed in an exploded, stacked representation in spanned hand annotation and in comparison, it's probably best to ensure that the primary aspect of this CSS is background styling.
d_presented_name a format string no In the UI, there are many places (e.g., in the annotation tables) where the annotation can be described, and by default, the description for spanned annotations is the covered text, while the description for spanless annotations is the annotation ID. Sometimes, this name isn't what you would prefer it to be, and you can use this attribute to define the name you prefer. The syntax for the value of this string is described here.
d_edit_imediately "yes"
no If a label has attributes, or if it can be the value of an annotation-valued attribute, it is possible to edit the annotation in the UI, either in a popup dialog or in a detail tab. For effective labels of <spanless> elements, this editor will appear automatically when the annotation is created; for effective labels of <span> elements, it will not. If you provide this attribute-value pair, the editor will appear automatically when the annotation is created, whether or not it's spanned.
d_accelerator a single-character string no If specified, this accelerator will be available in the annotation selection menu in the Web UI; if the user presses this key, this annotation will be selected for the span, just as if the element in the menu had been chosen. If the same accelerator is used in more than one place, and only one of the uses is visible (if, e.g., you have set up label groups to create a hierarchical menu), the visible one will be used. Otherwise, in the case of unresolved ambiguity, nothing will happen when you press the key.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.
d_overlap_rank
an integer
no
By default, the overlap order of spanned annotations in a task is the order in which they're defined. However, you can modify this overlap order by specifying overlap_rank on some or all of your labels. If at least one overlap_rank is specified, all labels lacking the specification will be ordered (in the order they're defined) behind the labels bearing a specification, and all those labels bearing a specification will be ordered in front of those other labels, in the order of their overlap_rank value. If the task has a parent task, all labels not defined locally will be ordered behind the locally defined labels.

<display_group> (of <effective_labels>)

This child of <effective_labels> defines a display group whose parent name is, by default, the name of the annotation which bears the <effective_labels> attribute, and whose children are the effective labels. See the definition of <display_group> below. If you want a different name (and, optionally, style) for the parent of this group, specify the name and css attributes here.

Attributes

Attribute
Value
Obligatory?
Description
name a string
no The name of the display group, which must not be the true or effective label of a known annotation type. If this attribute is not present, the first child of the display group is treated as the parent.
css a string of legal CSS
no Like the d_css attribute on the <span> and <spanless> elements above. Used to assign styling when a name is present.

<int> (of <span>)

This element defines an integer-valued attribute.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
default an integer
no If present, a default value for this attribute. This attribute can't be defined alongside the "default_is_text_span" attribute.
of_set a string
no See <effective_labels>.
of_category a string
no See <effective_labels>.
default_is_text_span "yes"
no If present, the default value for this attribute is digested from the span of the annotation (so this option is only available for attributes of spanned annotations). If the span can't be digested into a value of the appropriate type, no default will be set. This attribute can't be defined alongside the "default" attribute.
range_from an integer
no If present, the minimum (inclusive) endpoint of the range. Range declarations cannot cooccur with choices.
range_to an integer
no If present, the maximum (inclusive) endpoint of the range. Range declarations cannot cooccur with choices.
choices a comma- or space-separated sequence of integers
no If present, the possible values for this attribute. You can also use the <choice> child element to specify choices, and you can use both of these alternatives at once. Choices cannot cooccur with range_from and range_to.
aggregation one of "set", "list"
no By default, the values of attributes are singletons. If you want the value to be a set or list of the objects of the specified type, indicate it with this XML attribute. See also <int_set> and <int_list>.

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_url_link a string
no When the annotation attribute is displayed in the annotation editor or the annotation table, the annotation will be used to construct a URL link. The syntax is identical to that of presented_name above, except that of the special values, only _text is recognized, and no key-value pairs are recognized within each directive. So, e.g., if you want the link on an annotation attribute to search for the spanned text in Google, the value of url_link would be

http://www.google.com/search?q=$(_text)
d_custom_editor a string
no You may have a string attribute which is actually a date, which you want to use a calendar widget to populate; or you might want to look up the annotation text in a database, and use the results to populate the attribute value. If you're willing to do some programming, you can use this attribute to specify an arbitrary JavaScript function for a string, int, or float attribute, to use as its editor. You can define your function in your task directory in your Javascript customization file. Unfortunately, we don't really have the resources to document the API this function has to conform to; either dig through the source code yourself, or ask us for help.
d_custom_editor_button_label a string
no If you have a custom editor, but you want the label to be something other than "Edit" (let's say the value is automatically calculated when you press the button), use this.
d_custom_editor_is_multiattribute "yes"
no
If you've associated a custom_editor with this attribute, this attribute-value pair tells the UI that the editor will fill multiple attributes.
d_max_choice_size an integer
no For set-valued attributes with choices, this attribute provides a way of limiting the size of the presented multi-select in the UI. By default, the maximum size is 5. For choice sets above this size, the multi-select will scroll.
d_read_only "yes"
no Attributes are typically editable. If for some reason you don't want to be able to edit an attribute directly in the annotation editor (e.g., the attribute value is automatically populated by a custom editor, as described below), use this setting.

Children

Element
Obligatory?
Repeatable?
Description
<choice> no yes A possible value for this attribute.

<choice> (of <int>)

The <choice> element can be used to declare a possible value for this integer-valued attribute. It can cooccur with the choices attribute described above. One situation where you might want to use the element instead of the attribute is when you want to define a keyboard accelerator.

Attributes

Attribute
Value
Obligatory?
Description
value an integer
yes The possible value.
d_accelerator a single-character string no This accelerator will be available in the annotation popup submenu in the Web UI which corresponds to the attribute which bears this choice; if the user presses this key, this choice will be selected for the attribute, just as if the element in the menu had been chosen.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.

<int_set> (of <span>)

Equivalent to specifying an <int> element with aggregation="set".

<int_list> (of <span>)

Equivalent to specifying an <int> element with aggregation="list".

<string> (of <span>)

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
default a string
no If present, a default value for this attribute. This attribute can't be defined alongside the "default_is_text_span" attribute.
of_set a string
no See <effective_labels>.
of_category a string
no See <effective_labels>.
default_is_text_span "yes"
no If present, the default value for this attribute is digested from the span of the annotation (so this option is only available for attributes of spanned annotations). If the span can't be digested into a value of the appropriate type, no default will be set. This attribute can't be defined alongside the "default" attribute.
choices a comma- or space-separated sequence of strings no If present, possible values for this attribute. If commas are present in the XML attribute value, it will be split at commas; otherwise, it will be split at whitespace. You can also use the <choice> child element to specify choices, and you can use both of these alternatives at once.
aggregation one of "set", "list" no By default, the values of attributes are singletons. If you want the value to be a set or list of the objects of the specified type, indicate it with this XML attribute. See also <string_set> and <string_list>.

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_editor_style "long_string" no There are two ways of providing attribute values for non-choice string attributes in the UI: via a short typein window or via a multi-line typein window. By default, a short typein window will be used. If you provide this attribute-value pair, a long typein window will be used. Ignored if the attribute has choices.
d_url_link a string
no See <int>.
d_custom_editor a string
no See <int>.
d_custom_editor_button_label a string
no See <int>.
d_custom_editor_is_multiattribute "yes"
no
See <int>.
d_max_choice_size an integer
no See <int>.
d_read_only "yes"
no See <int>.

Children

Element
Obligatory?
Repeatable?
Description
<choice> no yes A possible value for this attribute.

<choice> (of <string>)

The <choice> element can be used to declare a possible value for this string-valued attribute. It can cooccur with the choices attribute described above. One situation where you might want to use the element instead of the attribute is when you want to define a keyboard accelerator; another might be where your possible value contains both commas and whitespace.

Attributes

Attribute
Value
Obligatory?
Description
value a string
yes The possible value.
d_accelerator a single-character string no This accelerator will be available in the annotation popup submenu in the Web UI which corresponds to the attribute which bears this choice; if the user presses this key, this choice will be selected for the attribute, just as if the element in the menu had been chosen.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.

<string_set> (of <span>)

Equivalent to specifying an <string> element with aggregation="set".

<string_list> (of <span>)

Equivalent to specifying an <string> element with aggregation="list".

<float> (of <span>)

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
default a float
no If present, a default value for this attribute. This attribute can't be defined alongside the "default_is_text_span" attribute.
of_set a string
no See <effective_labels>.
of_category a string
no See <effective_labels>.
default_is_text_span "yes"
no If present, the default value for this attribute is digested from the span of the annotation (so this option is only available for attributes of spanned annotations). If the span can't be digested into a value of the appropriate type, no default will be set. This attribute can't be defined alongside the "default" attribute.
range_from
a float
no If present, the minimum (inclusive) endpoint of the range.
range_to a float
no If present, the maximum (inclusive) endpoint of the range.
aggregation one of "set", "list" no By default, the values of attributes are singletons. If you want the value to be a set or list of the objects of the specified type, indicate it with this XML attribute. See also <float_set> and <float_list>.

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_url_link a string
no See <int>.
d_custom_editor a string
no See <int>.
d_custom_editor_button_label a string
no See <int>.
d_custom_editor_is_multiattribute "yes"
no
See <int>.
d_read_only "yes"
no See <int>.

<float_set> (of <span>)

Equivalent to specifying an <float> element with aggregation="set".

<float_list> (of <span>)

Equivalent to specifying an <float> element with aggregation="list".

<boolean> (of <span>)

This element defines a boolean-valued attribute.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
default "yes" or "no"
no If present, a default value for this attribute. Use "yes" or "no".
of_set a string
no See <effective_labels>.
of_category a string
no See <effective_labels>.
aggregation
one of "set", "list" no
By default, the values of attributes are singletons. If you want the value to be a set or list of the objects of the specified type, indicate it with this XML attribute.

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_custom_editor a string
no See <int>.
d_custom_editor_button_label a string
no See <int>.
d_custom_editor_is_multiattribute "yes"
no See <int>.
d_read_only "yes"
no See <int>.
d_url_link a string
no See <int>.

<filler> (of <span>)

This element defines an annotation-valued attribute. For each <filler> element, you must define at least one filler type. Every value of the attribute must satisfy at least one of the types. The types can be a simple label or effective label, or they can also bear attribute/value restrictions.

Attributes

Attribute
Value
Obligatory?
Description
name a string
yes The name of the attribute.
of_set a string
no See <effective_labels>.
of_category a string
no See <effective_labels>.
filler_types a comma- or space-separated sequence of labels
no If present, a sequence of labels or effective labels which the annotation filler can match. If commas are present in the XML attribute value, it will be split at commas; otherwise, it will be split at whitespace. You can also use the <filler_types> child element to specify filler types, and you can use both of these alternatives at once.
aggregation one of "set", "list" no
By default, the values of attributes are singletons. If you want the value to be a set or list of the objects of the specified type, indicate it with this XML attribute. See also <filler_set> and <filler_list>.

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_custom_editor a string
no See <int>.
d_custom_editor_button_label a string
no See <int>.
d_custom_editor_is_multiattribute "yes"
no See <int>.
d_read_only "yes"
no See <int>.
d_url_link a string
no See <int>.

Children

Element
Obligatory?
Repeatable?
Description
<filler_type> no yes A label or effective label, possibly including attribute/value pairs, which the annotation filler can match.

<filler_type> (of <filler>)

This element defines a filler type which the annotation filler can match. You can use this element in conjunction with the filler_types attribute above. One situation in which you might want to use this element is if you want to define further attribute/value pairs which the filler must match, or if the label contains whitespace and commas.

Attributes

Attribute
Value
Obligatory?
Description
label a string
yes A true or effective annotation label which the annotation filler can match.
<attr> a string no The <filler_type> element supports arbitrary XML attribute-value pairs. Each <attr> must be a choice attribute defined for the label (i.e., either a string or int attribute which has choices associated with it). To satisfy this filler type, the filler must bear all the specified attribute/value pairs.

<filler_set> (of <span>)

Equivalent to specifying an <filler> element with aggregation="set".

<filler_list> (of <span>)

Equivalent to specifying an <filler> element with aggregation="list".

<spanless> (of <annotations>)

This element defines a spanless annotation type. The child elements which define the annotation attributes are identical to those for the <span> element.

Attributes

Attribute
Value
Obligatory?
Description
label a string
yes The label for the annotation type.
all_attributes_known "yes"
no Under normal circumstances, MAT does not object to finding "undeclared" attributes of annotations in the documents it reads. If this XML attribute/value pair is present, the annotation type is "locked"; in other words, when MAT reads in a document in the context of a task corresponding to this annotation set descriptor, it will object to any "stray" attributes which appear on annotations of this type.
of_set
a string
no
The annotation set descriptor to which this annotation type belongs. If not specified, the value is "content". The names are user-definable, and you can have a many-to-one mapping from names to categories, to facilitate set grouping. See here for an overview.
of_category
a string
no
The category to which the annotation set descriptor for this annotation type belongs. If not specified, the value is "content". See here for an overview.

Display attributes

All attributes related to the display of this annotation in the MAT UI begin with "d_".

Attribute
Value
Obligatory?
Description
d_css a string of legal CSS no The UI will apply this CSS to the annotation's icon in the spanless sidebar. Because there's no text in the spanless sidebar, and because annotations can overlap and be displayed in an exploded, stacked representation in spanned hand annotation and in comparison, it's probably best to ensure that the primary aspect of this CSS is background styling.
d_presented_name a format string no In the UI, there are many places (e.g., in the annotation tables) where the annotation can be described, and by default, the description for spanless annotations is the annotation ID. Sometimes, this name isn't what you would prefer it to be, and you can use this attribute to define the name you prefer. The syntax for the value of this string is described here.
d_accelerator a single-character string no If specified, this accelerator will be available in the annotation selection menu in the Web UI; if the user presses this key, this annotation will be selected for the span, just as if the element in the menu had been chosen. If the same accelerator is used in more than one place, and only one of the uses is visible (if, e.g., you have set up label groups to create a hierarchical menu), the visible one will be used. Otherwise, in the case of unresolved ambiguity, nothing will happen when you press the key.

Note: there are two bugs in version 3.1.1 in the interaction between this feature and hierarchical menus. Non-ambiguous non-visible accelerators will be triggered, and ambiguous accelerators which are present at the same nesting level in multiple hierarchical menus will overwrite each other. These bugs cannot be fixed in 3.1.1, but will be fixed in the upcoming 3.2 release.
d_edit_immediately "yes" no If a label has attributes, or if it can be the value of an annotation-valued attribute, it is possible to edit the annotation in the UI, either in a popup dialog or in a detail tab. If the annotation is spanless, this editor will appear automatically when the annotation is created, so this attribute has no effect; it's here for consistency.

Children

Element
Obligatory?
Repeatable?
Description
<int> no yes See previous description.
<int_set> no yes See previous description.
<int_list> no yes See previous description.
<float> no yes See previous description.
<float_set> no yes See previous description.
<float_list> no yes See previous description.
<effective_labels> no yes See previous description.
<string> no yes See previous description.
<string_set> no yes See previous description.
<string_list> no yes See previous description.
<boolean> no yes See previous description.
<filler> no yes See previous description.
<filler_set> no yes See previous description.
<filler_list> no yes See previous description.

<display_group> (of <annotations>)

Under some circumstances, you might want to create cascaded annotation menus in the MAT UI, perhaps in order to group together similar annotations, or provide options for more or less general annotations, or to compress the screen real estate taken up by the annotation popup menu. You can use the <display_group> element to accomplish this.

If the display group does not have a name, its first child must be either a <span> element or a <spanless> element, and that element will be chosen as the parent of the group. If the group does have a name, it must be otherwise unknown, and that name serves as the parent of the group. In this latter case, you can style the name via the css attribute.

Display groups are inherited from an available parent task; this group information is filtered by the locally defined annotations. Local display groups override parent display groups.

Attributes

Attribute
Value
Obligatory?
Description
name a string
no The name of the display group, which must not be the true or effective label of a known annotation type. If this attribute is not present, the first child of the display group is treated as the parent.
css a string of legal CSS
no Like the d_css attribute on the <span> and <spanless> elements above. Used to assign styling when a name is present.

Children

Element
Obligatory?
Repeatable?
Description
<span> no yes See previous description.
<spanless> no yes See previous description.
<display_group> no yes See previous description.