This is a list of all the different state types and how they are defined. All states require type and transitions to be defined.

The type defines the kind of state we are dealing with, while the transitions defines where to go next, depending on the path a user chooses.

We define the following state types.

Loading states load a specific kind of data from the database and and display it in the client.

Loads text data from the database. It only takes its type and transitions definition. We strongly recommend to use this type of state only as the start state.

start:
    type: loadText
    transitions:
        - "*":
              target: <target-state>

Loads a image instance from the database. It only takes its type and transitions definition. We strongly recommend to use this type of state only as the start state.

start:
    type: loadImage
    transitions:
        - "*":
              target: <target-state>

Loads a PDF instance from the database. It only takes its type and transitions definition. We strongly recommend to use this type of state only as the start state.

start:
    type: loadPdf
    transitions:
        - "*":
              target: <target-state>

deprecated

We recommend to use this state type after a loading state. It displays the loaded text data and prompts the annotator to read the text carefully. It requires the question field, in which you can fill the prompt shown to the annotator.

"s0": {
    "type": "read",
    "question": "Read the content and its context below."
    "transitions": [["NEXT", "s1"]] 
}

States of the type read only require the NEXT path to be defined in its transitions. When an annotator clicks the NEXT button in the GUI, the state-machine will the proceed to the defined target-state (here: state s1).

A select-state is an annotation-state which shows a question and a number of options to chose from. Only one option may be selected (vs. checkmark-states, which allow several options to be selected at once). It requires the definition of a question and the various options to show.

Required fields: question, options

Example:

orientation:
    type: select
    question: Is this text factual or opinion-oriented?
    options: ["factual", "opinion"]
    transitions:
        - "factual":
              target: targets
        - "opinion":
              target: end

A checkmark state is similar to a select-state. However, it allows the annotator to choose several options at once. Analogously, it requires the question and options fields. As opposed to select states which can have a large number of different paths and target-states defined in their transitions, checkmark states only define one transition, NEXT or *.

referee:
    type: checkmark
    question: Who are the targets being negatively evaluated?
    options: ["politician", "migrant", "other"]
    transitions:
        - "*":
              target: labels

A labeling question is a special type of state that can only follow select and checkmark states. It allows the annotator to highlight words in the text data that fit to a previously chosen option. Let's say the annotator previously chose politician and migrant in the previous checkmark state, the labeling state will now show these two options and ask the annotator to label any words in the text that refer to the chosen options politician and migrant.

Label state-types require the question field to be set.

"s3": {
    "type": "label",
    "question": "Please label all targets."
    "transitions": [["NEXT", "s4"]] 
}

This state-type only defines the NEXT transition. Here, the annotator is directed to state 4 once he clicks the NEXT button.

Sometimes, all we need is a clear yes or no. For these types of questions there is the boolean-state. It requires the question field.

"s4": {
    "type": "boolean",
    "question": "Is this a happy comment?"
    "transitions": [["YES", "s5"],
                    ["NO", "end"]] 
}

States of type boolean only take two transitions, YES and NO. Here, if the annotator chooses YES, they land in state s5, while NO sends them to the end state.

When dealing with PDFs, the annotator needs to choose the page to annotate. This page will then be converted into an image for further annotation. For this, we use the choosePage type.

"s0": {
    "type": "choosePage",
    "question": "Please select a page to annotate."
    "transitions": [["onDone", "s1"]]
}

Note that it requires the onDone transition.

When annotating images, we might want to mark certain parts of the image using bounding boxes. This can be done with the bbox type. Apart from an instruction written in the question field, it also requires the api_call field. The basic API call currently defined here is paragraph_segmentation, which just returns an initial bounding box to adjust. However, it is possible to create custom API calls which allow to pre-select certain features of an image. More on this here.

"s1": {
    "type": "bbox",
    "api_call": "paragraph_segmentation"
    "question": "Please adjust the bounding boxes."
    "transitions": [["NEXT", "end"]]
}

The bboxLabel type takes previously set bounding boxes (from a bbox or loading state) and asks the annotator to add one textual label to each of them. The construction of this state is analogous to the bbox type. However, the current default API call here is classify_words.

"s1": {
    "type": "bboxLabel",
    "api_call": "classify_words"
    "question": "Please adjust the bounding boxes and label them."
    "transitions": [["NEXT", "end"]]
}

The bboxMultilabel type takes one previously set bounding box (from a bbox or loading state) and asks the annotator to add multiple textual labels to them. The construction of this state is analogous to the bbox type. However, the current default API call here is classify_words.

"s1": {
    "type": "bboxMultilabel",
    "api_call": "classify_words"
    "question": "Please adjust the bounding boxes and label them."
    "transitions": [["NEXT", "end"]]
}

These are the different state types. Each state can also perform certain actions, like saving to the database. Continue here to learn about actions and more detailed information on transitions.