Annotationsschemata

Annotationsschemata legen die Beschriftungsaufgaben für Ihre Annotatoren fest. Potato unterstützt 76 Annotationstypen, die sich zu komplexen Annotationsaufgaben kombinieren lassen.

Aufbau eines Annotationsschemas

Grundstruktur

Jedes Schema wird im Array annotation_schemes definiert:

annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral

Pflichtfelder

Jedes Schema enthält diese drei Felder. Einzelne Typen fügen eigene Pflichtfelder hinzu, die weiter unten beim jeweiligen Typ aufgeführt sind.

Unterstützte Annotationstypen

1. Radio (Einfachauswahl)

Genau eine Option aus einer Liste auswählen:

- annotation_type: radio
  name: sentiment
  description: "What is the sentiment of this text?"
  labels:
    - Positive
    - Negative
    - Neutral
 
  # Assigns keys 1, 2, 3... in the order the labels are listed
  sequential_key_binding: true
 
  # Horizontal layout instead of vertical
  horizontal: true

Sequenzielle Belegungen legen die Ziffern 1-9 auf die ersten neun Beschriftungen, sodass eine Umsortierung der Beschriftungsliste auch die Tasten neu zuweist. Für eine Belegung, die eine Umsortierung übersteht, geben Sie jeder Beschriftung eine eigene Taste (siehe Tastaturkürzel).

2. Likert-Skala

Bewertungsskalen mit beschrifteten Endpunkten:

- annotation_type: likert
  name: agreement
  description: "How much do you agree with this statement?"
  size: 5  # Number of scale points
  min_label: "Strongly Disagree"
  max_label: "Strongly Agree"
 
  # Show the numeric value of the selected point
  displaying_score: true

size ist zusammen mit beiden Endpunkt-Beschriftungen erforderlich. Fünf Punkte geben den Annotatoren eine neutrale Mitte; eine gerade Anzahl erzwingt eine Richtung.

3. Multiselect (Mehrfachauswahl)

Mehrere Optionen aus einer Liste auswählen:

- annotation_type: multiselect
  name: topics
  description: "Select all relevant topics"
  labels:
    - Politics
    - Technology
    - Sports
    - Entertainment
    - Science
 
  # Require at least one box before the annotator can move on
  label_requirement:
    required: true
 
  # Allow free text response
  has_free_response: true

has_free_response fügt ein Textfeld für "Sonstiges" hinzu. Es lohnt sich, dieses Feld zu aktivieren, solange die Beschriftungsmenge noch überarbeitet wird, denn die gesammelten Einträge benennen die Kategorien, die Ihnen fehlen.

4. Span-Annotation

Textabschnitte markieren und beschriften:

- annotation_type: span
  name: entities
  description: "Highlight named entities in the text"
  labels:
    - PERSON
    - ORGANIZATION
    - LOCATION
    - DATE
 
  # Show the label name on each highlighted span
  show_span_labels: true
 
  # Ctrl/Cmd+click to add non-contiguous ranges to one annotation
  allow_discontinuous: false
 
  # Keyboard shortcuts for labels
  sequential_key_binding: true

allow_discontinuous deckt Spans ab, die aus getrennten Bereichen bestehen, etwa geteilte Antezedenten, nicht aber Spans, die sich gegenseitig überlappen. Lassen Sie die Option ausgeschaltet, solange das Phänomen, das Sie beschriften, nicht tatsächlich über eine Lücke hinweg auftritt, denn die Strg/Cmd-Klick-Geste wird leicht versehentlich ausgelöst.

5. Schieberegler

Kontinuierlicher Zahlenbereich:

- annotation_type: slider
  name: confidence
  description: "How confident are you in your answer? (0 = not at all, 100 = completely)"
  min_value: 0
  max_value: 100
  starting_value: 50
  step: 1
 
  # Shows min_value and max_value at the ends of the track
  show_labels: true

min_value, max_value und starting_value sind alle drei erforderlich. Ein Schieberegler nimmt keine labels-Liste an. Wird eine hinzugefügt, wechselt die Frage zu einem Radio-Button-Layout und der Schieberegler verschwindet, daher gehören Formulierungen für die Enden der Skala in description. Der Startwert ist die Position, an der der Regler jedes Annotators steht, bevor er ihn berührt. Ein Wert in der Mitte vermeidet daher, dass die Annotatoren zu einem der beiden Enden hin verankert werden.

6. Texteingabe

Freitextantworten:

- annotation_type: text
  name: explanation
  description: "Explain your reasoning"
 
  # Multi-line input
  rows: 4
 
  # Require a minimum length and show a running count
  min_chars: 20
  show_char_count: true
 
  # Placeholder text
  placeholder: "Enter your explanation here..."
 
  # Disable paste (for transcription tasks)
  allow_paste: false

allow_paste: false ist bei Transkriptions- und Free-Recall-Aufgaben wichtig, weil eine eingefügte Antwort aus der Quelle kopiert wurde und nicht vom Annotator stammt.

7. Zahleneingabe

Zahleneingabe mit Einschränkungen:

- annotation_type: number
  name: count
  description: "How many entities are mentioned?"
  min: 0
  max: 100
  step: 1

8. Multirate (Matrixbewertung)

Mehrere Elemente auf derselben Skala bewerten:

- annotation_type: multirate
  name: quality_aspects
  description: "Rate each aspect of the response"
 
  # Rows: the items being rated
  options:
    - Accuracy
    - Fluency
    - Relevance
 
  # Columns: the shared rating scale
  labels:
    - Poor
    - Fair
    - Good
    - Very Good
    - Excellent
 
  # Randomize row order per annotator
  option_randomization: true
 
  # Layout options
  arrangement: "vertical"
  display_config:
    num_columns: 2

options und labels sind beide erforderlich, da eine Matrix Zeilen und Spalten braucht. Eine zufällige Zeilenreihenfolge verteilt einen Reihenfolgeeffekt über alle Elemente, statt ihn auf den Aspekt zu konzentrieren, der zufällig als erster aufgeführt ist.

Allgemeine Optionen

Tastaturkürzel

Die Annotation mit Tastenbelegungen beschleunigen:

# Automatic sequential binding: digits 1, 2, 3... in label order
sequential_key_binding: true

Für eine Belegung, die sich nicht verschiebt, wenn sich die Beschriftungsliste ändert, übergeben Sie Beschriftungsobjekte und geben jedem einen key_value:

labels:
  - name: Positive
    key_value: "1"
  - name: Negative
    key_value: "2"
  - name: Neutral
    key_value: "3"

Tooltips

Hinweise beim Überfahren einzelner Beschriftungen anzeigen. Tooltips gehören zur Beschriftung, nicht zum Schema, und werden daher innerhalb von labels konfiguriert:

labels:
  - name: Positive
    tooltip: "Expresses happiness, approval, or satisfaction"
  - name: Negative
    tooltip: "Expresses sadness, anger, or disappointment"
  - name: Neutral
    tooltip: "No clear emotional content"

Für formatierte Hinweise verweisen Sie tooltip_file stattdessen auf eine HTML-Datei:

labels:
  - name: Economic
    tooltip_file: "config/tooltips/economic.html"

Beschriftungsfarben

Eigene Farben zur visuellen Unterscheidung, einmal für das gesamte Projekt unter ui definiert:

ui:
  label_colors:
    entities:
      PERSON: "#3b82f6"
      LOCATION: "#10b981"
      ORGANIZATION: "#f59e0b"

Die Farben sind nach Schemaname und dann nach Beschriftung geordnet. Eine Farbe lässt sich auch an einer einzelnen Beschriftung neben ihrem Tooltip setzen:

labels:
  - name: positive
    color: "#22C55E"
    tooltip: "Positive sentiment"

Pflichtfelder

Ein Schema vor dem Absenden verpflichtend machen:

- annotation_type: radio
  name: sentiment
  description: "What is the sentiment?"
  label_requirement:
    required: true
  labels:
    - Positive
    - Negative

Um statt einer beliebigen Antwort eine bestimmte Option zu verlangen, nennen Sie diese mit required_label. Der Schlüssel akzeptiert eine einzelne Beschriftung oder eine Liste.

Mehrere Schemata

Mehrere Annotationstypen pro Instanz kombinieren:

annotation_schemes:
  # Primary classification
  - annotation_type: radio
    name: sentiment
    description: "Overall sentiment"
    labels:
      - Positive
      - Negative
      - Neutral
    label_requirement:
      required: true
    sequential_key_binding: true
 
  # Confidence rating
  - annotation_type: likert
    name: confidence
    description: "How confident are you?"
    size: 5
    min_label: "Guessing"
    max_label: "Certain"
 
  # Topic tags
  - annotation_type: multiselect
    name: topics
    description: "Select all relevant topics"
    labels:
      - Politics
      - Technology
      - Sports
      - Entertainment
    has_free_response: true
 
  # Notes
  - annotation_type: text
    name: notes
    description: "Any additional observations"
    rows: 4
    label_requirement:
      required: false

Hier ist nur die Sentiment-Beschriftung erforderlich. Wenn die Konfidenzbewertung und die Notizen optional bleiben, beschränkt sich die Pflichtmenge auf das eine Feld, von dem die Studie abhängt, und Annotatoren werden nicht von einem Feld aufgehalten, das für die Analyse kein Gewicht hat.

Erweiterte Funktionen

Paarweiser Vergleich

Zwei Elemente vergleichen. Die Elemente stammen aus der Instanz selbst und werden über items_key benannt:

- annotation_type: pairwise
  name: preference
  description: "Which response is better?"
  mode: binary
  items_key: "responses"   # Field holding a list of 2+ items
 
  # Labels for the two sides
  show_labels: true
  labels:
    - "Response A"
    - "Response B"
 
  # Tie option (opt-in)
  allow_tie: true
  tie_label: "No preference"

Die Datendatei liefert das Paar, daher enthält jede Zeile eine Liste mit mindestens zwei Elementen:

{"id": "1", "responses": ["First response text", "Second response text"]}

Eine Unentschieden-Schaltfläche lohnt sich, wenn wirklich gleichwertige Paare häufig vorkommen. Ohne sie entscheiden Annotatoren Gleichstände willkürlich, und dieses Rauschen zeigt sich als Nichtübereinstimmung.

Best-Worst Scaling

Elemente einordnen, indem aus einem Tupel das beste und das schlechteste ausgewählt wird. Die Tupel werden von einem bws_config-Block auf oberster Ebene gebildet, nicht vom Schema, und ein bws-Schema ohne diesen Block zeigt eine Frage über einer leeren Elementliste an:

bws_config:
  tuple_size: 4              # Items per tuple
  min_item_appearances: 8    # Minimum appearances per item across tuples
  seed: 42
  scoring:
    method: counting         # counting | bradley_terry | plackett_luce
 
annotation_schemes:
  - annotation_type: bws
    name: ranking
    description: "Sentiment Intensity"
    best_description: "Which sentence expresses the MOST positive sentiment?"
    worst_description: "Which sentence expresses the LEAST positive sentiment?"
    tuple_size: 4
    sequential_key_binding: true

Jede Zeile der Datendatei ist ein Element, und Potato zieht die Tupel aus diesem Pool. Ein höherer Wert für min_item_appearances macht die Punktzahl jedes Elements genauer, kostet aber mehr Vergleiche.

Dropdown-Auswahl

Platzsparende Einfachauswahl:

- annotation_type: select
  name: category
  description: "Select a category"
  labels:
    - Category A
    - Category B
    - Category C
    - Category D
    - Category E
 
  # Vary the option order between annotators
  randomize_order: true

Ein Dropdown verbirgt die Optionen, bis es geöffnet wird. Es eignet sich daher für lange Beschriftungsmengen, bei denen Radio-Buttons den Text aus dem Bildschirm schieben würden. Bei kurzen Mengen sind Radio-Buttons schneller, weil sie einen Klick statt zwei brauchen.

Datenformat-Referenz

Eingabe

Annotationsschemata arbeiten mit Ihrem Datenformat:

{
  "id": "doc_1",
  "text": "This is the text to annotate."
}

Ausgabe

Annotationen werden mit den Schemanamen als Schlüssel gespeichert:

{
  "id": "doc_1",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 4,
    "topics": ["Technology", "Science"],
    "entities": [
      {"start": 0, "end": 4, "label": "ORGANIZATION", "text": "This"}
    ],
    "notes": "Clear positive sentiment about technology."
  }
}

Bewährte Vorgehensweisen

1. Klare Beschriftungen

Eindeutige, klar unterscheidbare Beschriftungen verwenden:

Diese Beschriftungen benennen unterscheidbare Punkte auf einer Dimension:

labels:
  - Strongly Positive
  - Somewhat Positive
  - Neutral
  - Somewhat Negative
  - Strongly Negative

Diese nicht. Zwei Annotatoren werden die Grenze zwischen "OK", "Fine" und "Acceptable" nicht an derselben Stelle ziehen, und die daraus folgende Nichtübereinstimmung betrifft die Beschriftungsmenge und nicht die Daten:

labels:
  - Good
  - OK
  - Fine
  - Acceptable

2. Hilfreiche Tooltips

Tooltips für nuancierte Beschriftungen hinzufügen:

labels:
  - name: Sarcasm
    tooltip: "The text says the opposite of what it means"
  - name: Irony
    tooltip: "A mismatch between expectation and reality"

3. Tastaturkürzel

Kürzel für Aufgaben mit hohem Volumen aktivieren:

sequential_key_binding: true

4. Logische Reihenfolge

Beschriftungen einheitlich ordnen:

• Häufigste zuerst
• Alphabetisch
• Nach Intensität (niedrig bis hoch)

5. Optionen begrenzen

Zu viele Auswahlmöglichkeiten verlangsamen die Annotation:

• Radio: 2-7 Optionen
• Multiselect: 5-15 Optionen
• Likert: 5-7 Punkte

6. Zuerst testen

Annotieren Sie selbst einige Beispiele, bevor Sie das Projekt in Betrieb nehmen, um Folgendes zu erkennen:

• Mehrdeutige Beschriftungen
• Fehlende Kategorien
• Unklare Anweisungen