Task XML reference

The XML format for the task files (see "Creating a New Task") is described in this document. Use cases are described here. Click here for a split-screen view.

The reference for declaring annotations and their display properties is handled separately, and can be found here.

Element hierarchy

<tasks>

A container for <task> elements. Either this element or <task> can be the toplevel element in the file.

Children

<task>

The usual toplevel element in the file. For historical reasons, some of the tags are obligatory and some not. Conceptually speaking, you always need to specify either <annotation_set_descriptors> and <annotation_display> or <annotations>; and <engines>, <workflows> and <steps> are required for using the engine and experiment infrastructure. <workspaces> should be defined if you want to define a default workflow to use as your workspace, or customize a workflow for use in a workspace. The other elements are for advanced customizations.

If you want to define multiple tasks in the same task.xml file (if, for instance, you're defining a task and a set of child tasks), you can use <tasks> as your toplevel element. This element has no attributes, and only one repeatable child: <task>.

Attributes

Children

<languages> (of <task>)

As of MAT 3.0, each task must declare the languages it applies to. The task can apply to multiple languages. This element contains those language definitions.

Attributes

Children

<language> (of <languages>)

This element declares a single language. You can assign a shorthand code (e.g., the ISO language code) for use in most places where languages must be specified, and

Attributes

<doc_enhancement> (of <task>)

The MAT documentation, which you're currently reading, has two slots in its documentation sidebar for additional pages provided by the installed tasks. These slots are not visible unless one of the installed tasks places documentation there. See here for further details.

Children

<app_header> (of <doc_enhancement>)

Use this element to add documentation to the "application" slot in the documentation sidebar, which is at the top, above "Getting started". You might use this slot if you're using MAT for a single purpose that you want the documentation to lead with. This element will also allow you to "brand" the documentation, changing the documentation window title and the initial page. Each <app_header> entry is its own header in the sidebar, so it will seldom make sense for you to provide more than one of these, or install multiple tasks with this entry. See here for further details.

Attributes

Children

<doc_entry> (of <app_header>)

This element is a normal page within the documentation section in question. At the toplevel, it is listed in the sidebar at the same indent level as the section header; at lower levels, it will be indented farther to the right. See here for further details.

Attributes

<doc_section> (of <app_header>)

This element is a new section within the documentation section in question. At the toplevel, it is listed in the sidebar at the same indent level as its parent section header; at lower levels, it will be indented farther to the right. Its children will be indented farther to the right. See here for further details.

Attributes

Children

<customization_header> (of <doc_enhancement>)

Use this element to add documentation to the "customization" slot of the documentation sidebar, which is near the top, above "For users". This is the default place to put documentation about your task. Each <customization_header> entry is its own header in the sidebar.

Attributes

Children

<external_id_header> (of <doc_enhancement>)

Use this element to add documentation to an <app_header> or <customization_header> section which was defined by a parent task. The children of this element will appear in the documentation as if they had been defined in the scope of the referenced elements.

Attributes

Children

<web_customization> (of <task>)

Among the ways that tasks can be customized is the Web UI can be customized in a number of ways. This process is quite complicated; it's almost entirely code-oriented, and it's not documented at all. This section is here for reference only; users who aren't really, really brave shouldn't go anywhere near most of these customizations.

Attributes

Children

<engines> (of <task>)

Tasks can define automated processing engines, which may be trainable (see the <model_config> element below).

Attributes

Children

<java_subprocess_parameters> (of <engines>)

MAT has some built-in tools to control jCarafe and other Java subprocesses. Using this element, you can declare default settings for Java heap and stack sizes. If not set locally, these settings are inherited from parent tasks.

Attributes

<engine> (of <engines>)

Each engine references a Python class which implements the engine, and optionally configuration information for training the engine.

Attributes

Children

<step_config> (of <engine>)

This element defines the class which implements the engine, and any settings which should be passed to the class when it is created.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<create_settings>	no	no	Default settings for initializing the engine implementation.

<create_settings> (of <step_config>)

These are settings that an engine might pass to the initialization phase of its step config class. These settings can be overridden by the values in the <create_settings> element for <step> in the <workflow> element. You can configure these settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

<setting> (of <create_settings>)

An individual step creation setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<model_config> (of <engine>)

Some of your engines will be trainable. If so, you must provide at least one <model_config> element for the engine. The settings for the config are identical to the command-line options available for the MATModelBuilder.

MAT is delivered with a default jCarafe model builder.

You can have multiple <model_config> entries for an engine, as long as they differ by the config_name attribute.You can inherit an engine from a parent task, and override various elements of the parent engine definition, including the model config.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<build_settings>	no	no	The settings for this model config

<build_settings> (of <model_config>)

The <build_settings> tag supports arbitrary attribute-value pairs which are passed to the model builder. See the documentation for the jCarafe model builder to see which attributes should be supplied to that engine. You can configure these settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

<setting> (of <build_settings>)

An individual build setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<steps> (of <task>)

Steps represent the way engines are used within workflows, and how humans interact with workflows. Signal steps modify the signal (and must be workflow-initial); transform steps transform the signal (and must be workflow-final); and annotation steps add or modify annotation sets.

Attributes

Children

<signal_step> (of <steps>)

Signal steps modify the signal, and must be workflow-initial.

Attributes

<annotation_step> (of <steps>)

Annotation steps add or modify annotations. This is probably the only step you'll define.

There are four types of annotation steps:

• hand steps (value "hand"), which only allow hand annotation
• automated steps (value "auto"), which only allow automated annotation (e.g., zoners and tokenizers)
• correction steps (value "auto-with-correction"), which require automated annotation followed by optional hand correction
• mixed steps (value "mixed"), which support optional automated annotation plus hand annotation

Each step is associated with annotation sets or categories which it adds or modifies.These declarations are used to determine which annotations to make available to the user in the UI in each step, and how much progress has been made in each step. Annotation steps support the ability to declare sets forbidden, desired and required as well; these declarations were intended to be used in computation of well-formedness conditions in workflows which we have not had a chance to implement yet.

Attributes

<transform_step> (of <steps>)

Transform steps modify the signal based on the previous annotation, and must be workflow-final. Transform steps are all auto steps.

Transform steps support the ability to declare sets forbidden, desired and required; these declarations were intended to be used in computation of well-formedness conditions in workflows which we have not had a chance to implement yet.

Attributes

<workspaces> (of <task>)

In MAT 3.0, any workflow which contains at least one hand-annotatable step can be used to create a workspace. You might want to define this element if you want to define a special configuration which customizes a workflow for use in workspaces, or if you want to declare a default workflow or configuration.

Attributes

Children

<workspace> (of <workspaces>)

This element is a container for workspace configurations, which provide options to workspace operation arguments. The workspace operations which can be configured are listed here.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<operation>	yes	yes	An individual operation configuration

<operation> (of <workspace>)

Specifies the configuration of a workspace operation. Note that in spite of the fact that operations are associated with folders, these operations are referenced only by name. Currently, no operations which are ambiguous among folders are configurable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<settings>	no	no	The operation settings.

<settings> (of <operation>)

The settings for the operation. What these settings are depend on what sort of operation it is. For instance, for operations which invoke the MAT engine, these settings will be the arguments to the MAT engine. For operations which invoke the MAT model builder, these settings will be the arguments to the MAT model builder. See the documentation on workspaces to find out which operations are configurable, and how they can be configured.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

<setting> (of <settings>)

An individual operation setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<settings> (of <task>)

These are settings that a specialized task might require which the user wishes to be able to configure in XML, rather than by modifying the source code for the specialized task. The chances that a normal user will use this are extremely slim. These settings are not inherited by task children.

You can configure the settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

<setting> (of <settings>)

An individual task-level setting.

Children

<workflows> (of <task>)

Workflows are ordered sets of steps, corresponding to a larger-scale activity the user may wish to apply to the documents.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<workflow>	no	yes	An individual workflow

<workflow> (of <workflows>)

Each non-inherited workflow is specified by a <workflow> element.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<ui_settings>	no	no	These are settings that are intended to be passed unmodified to the UI. This is not currently used.
<step>	no	yes	An individual step of a workflow.

<ui_settings> (of <workflow>)

These are settings that are intended to be passed unmodified to the UI, in order to declaratively configure UI customizations for particular workflows. At the moment, no tasks use this feature. You can configure these settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

<setting> (of <ui_settings>)

An individual UI setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<step> (of <workflow>)

Each workflow contains a sequence of globally-defined steps.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<create_settings>	no	no	Settings to pass to the initializer of the step
<run_settings>	no	no	Settings to pass to the execution of a step
<ui_settings>	no	no	Settings to pass to the UI for this step. Not currently used.

<create_settings> (of <step>)

These are settings that a step might pass to the initialization phase of its step class. These settings override the values in the <create_settings> element for <step_config>. You can configure these settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

<setting> (of <create_settings>)

An individual step creation setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<run_settings> (of <step>)

These are settings which are passed to the do() or doBatch() method of the step config class of the step (i.e., the engine implementation). You can configure the settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

Most predefined step implementations in MAT do not support any run settings. Two implementations which do are MAT.JavaCarafe.CarafeTokenizationStep and MAT.JavaCarafe.CarafeTagStep. The MAT.JavaCarafe.CarafeTagStep step implements automatic tagging. Any step which implements automatic tagging can bear the following additional attribute-value pairs:

In addition, the jCarafe tagging and tokenization steps support other run settings, documented here.

<setting> (of <run_settings>)

An individual run setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<ui_settings> (of <step>)

These are settings that are intended to be passed unmodified to the UI, in order to declaratively configure UI customizations for particular tasks. At the moment, no tasks use this feature. You can configure these settings either with a child <setting> element, or with an attribute on the <settings> element itself; they're interchangeable.

Attributes

Children

Element	Obligatory?	Repeatable?	Description
<setting>	no	yes	An attribute-value pair.

<setting> (of <ui_settings>)

An individual UI setting.

Children

Element	Obligatory?	Repeatable?	Description
<name>	yes	no	The name of the setting. This element has no attributes or element children; its value is the text it delimits.
<value>	yes	no	The value of the setting. This element has no attributes or element children; its value is the text it delimits.

<annotation_set_descriptors> (of <task>)

The <annotation_set_descriptors> element allows you to define multiple annotation sets. You can inherit annotations from other tasks.

The <annotation_set_descriptors> element and its children, along with the <annotation_display> element and (most of) 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.

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

Children

<annotation_set_descriptor> (of <annotation_set_descriptors>)

The <annotation_set_descriptor> element is described in detail elsewhere. In simple tasks, you'll have a single element of this type; we tend to define this single element with category="content" and name="content". However, you can define multiple sets, and the categories and set names can be whatever you want. See the "Sample Relations" task for an example.

Attributes

Virtually all annotation sets are managed. The one circumstance in which you might want to define an unmanaged set is if you have an automated engine which adds tokens simultaneously with another type of annotation (e.g., sentences). In this case, you'd have to define the set which contains the sentence annotation as unmanaged, because the step you'll declare will add both annotation sets, and you can't define a step which adds both managed and unmanaged annotation sets simultaneously. Since tokens are unmanaged, and the engine adds them and sentences at the same time, sentences must also be unmanaged.

<annotation_display> (of <task>)

This element defines all the display-related properties in the MAT UI of the elements defined in the <annotation_set_descriptors> 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. The <annotation_display> element is described in detail elsewhere.

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>.

<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. The <annotations> element is described in detail elsewhere.

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

<similarity_profile> (of <task>)

When you run the MATScore engine, or produce a visual comparison of annotations, MAT uses a set of heuristics to determine the best pairing of annotations. You can affect this process using the <similarity_profile> element.

Similarity profiles are not inherited.

Attributes

Children

<stratum> (of <similarity_profile>)

The comparison algorithm is stratified (see the algorithm for more details). You can use this element to define the strata, rather than allowing them to be inferred.

Attributes

<tag_profile> (of <similarity_profile>)

There's a default similarity profile for spanned and spanless annotations. If you want to declare your own profile explicitly, you can do that with this element. See the algorithm for details on how to use these.

Attributes

Children

<dimension> (of <tag_profile>)

Each profile consists of a number of dimensions, which define some aspect of the annotation to use in comparison, along with the method to be used for comparison and the relative weight of the dimension. See the algorithm for details about the various dimensions.

Attributes

<attr_equivalences> (of <tag_profile>)

The true labels in your tag profile may vary in their attribute names, but you may still want these attributes to be comparable. This element allows you to declare your equivalences. See the algorithm for details about the various dimensions.

Attributes

<score_profile> (of <task>)

When you run the MATScore engine, you can control how the scored elements are aggregated, decomposed, or filtered in the scoring output. See the algorithm for details on how to use this.

Score profiles are not inherited.

Attributes

Children

<label_limitation> (of <score_profile>)

The scorer will pair all annotations which are not specified as being ignored. Sometimes, you might need to pair some annotations as part of the scoring process (let's say they're arguments of relations, for instance), but you don't want them in the final output, even though you can't ignore them. You can use this element to provide that filter.

Attributes

<attrs_alone> (of <score_profile>)

Sometimes, you might want to know what the scores of the individual attributes for a label are, if, for instance, you have a processing step which adds attribute values. This element instructs the scorer to produce these individual scores, for all pairs of annotations bearing the specified labels. These scores are produced for each aggregation and decomposition in which the relevant annotations appear.

Attributes

<aggregation> (of <score_profile>)

Under normal circumstances, annotations are aggregated per document and per run by effective label (if available) or true label, or by equivalence classes passed to MATScore, and then all together into a single heap. You can add other aggregations of true labels using this element.

Attributes

<attr_decomposition> (of <score_profile>)

Under normal circumstances, the only way to decompose true labels in the score output is by effective label. If you want to decompose them by a particular attribute (e.g., you want to see the score for ENAMEXes when type = NOM), you can use this element. Decompositions can overlap with each other.

Attributes

<partition_decomposition> (of <score_profile>)

Under normal circumstances, the only way to decompose true labels in the score output is by effective label. If you want to decompose them by a Python function, you can use this element. Decompositions can overlap with each other.

Attributes