Spannenverknüpfungs-Annotation

Neu in v2.1.0

Die Spannenverknüpfung ermöglicht es Annotatoren, typisierte Beziehungen zwischen Spannen (Textsegmenten) zu erstellen, die bereits annotiert wurden. Dies ist nützlich für Relationsextraktionsaufgaben, bei denen identifiziert werden muss, wie Entitäten zueinander in Beziehung stehen, z. B. „PERSON arbeitet_für ORGANIZATION" oder „PERSON arbeitet_zusammen_mit PERSON".

Überblick

Die Spannenverknüpfungsfunktion bietet:

• Typisierte Beziehungen: Mehrere Verknüpfungstypen mit unterschiedlichen Farben und Einschränkungen definieren
• Gerichtete und ungerichtete Verknüpfungen: Unterstützung für sowohl direktionale als auch symmetrische Beziehungen
• N-äre Verknüpfungen: Verknüpfungen zwischen mehreren Spannen erstellen (nicht nur Paare)
• Visuelle Bogenanzeige: Beziehungen als farbige Bögen über dem Text dargestellt sehen
• Beschriftungseinschränkungen: Festlegen, welche Spannen-Beschriftungen als Quellen oder Ziele dienen können

Konfiguration

Für die Spannenverknüpfung werden zwei Annotationsschemata benötigt:

1. Ein span-Schema zur Annotation der Entitäten
2. Ein span_link-Schema zur Annotation der Beziehungen

annotation_schemes:
  # First, define the span schema for named entities
  - annotation_type: span
    name: entities
    description: "Highlight named entities"
    labels:
      - name: "PERSON"
        color: "#3b82f6"
      - name: "ORGANIZATION"
        color: "#22c55e"
      - name: "LOCATION"
        color: "#f59e0b"
    sequential_key_binding: true
 
  # Then, define the span_link schema for relationships
  - annotation_type: span_link
    name: relations
    description: "Annotate relationships between entities"
    span_schema: entities  # References the span schema above
    link_types:
      - name: "WORKS_FOR"
        directed: true
        allowed_source_labels: ["PERSON"]
        allowed_target_labels: ["ORGANIZATION"]
        color: "#dc2626"
      - name: "COLLABORATES_WITH"
        directed: false
        allowed_source_labels: ["PERSON"]
        allowed_target_labels: ["PERSON"]
        color: "#06b6d4"

Konfigurationsoptionen

Pflichtfelder

Verknüpfungstyp-Optionen

Visuelle Anzeigeoptionen

visual_display:
  enabled: true        # Show arc visualization
  arc_position: "above"  # Position of arcs
  show_labels: true    # Show link type labels on arcs

Verwendung

Spannen erstellen

1. Text zunächst annotieren, indem Spannen-Beschriftungen ausgewählt und Text hervorgehoben wird
2. Jede hervorgehobene Spanne steht zur Verknüpfung zur Verfügung

Verknüpfungen erstellen

1. Einen Verknüpfungstyp aus den verfügbaren Optionen auswählen
2. Auf Spannen klicken, um sie zur aktuellen Verknüpfung hinzuzufügen (ausgewählte Spannen werden hervorgehoben)
3. Auf „Verknüpfung erstellen" klicken, um die Verknüpfung abzuschließen
4. Bei gerichteten Verknüpfungen ist die zuerst ausgewählte Spanne die Quelle und die letzte das Ziel

Verknüpfungen anzeigen

• Erstellte Verknüpfungen erscheinen im Abschnitt „Vorhandene Verknüpfungen"
• Wenn die visuelle Anzeige aktiviert ist, werden Bögen über dem Text gezeichnet, die verknüpfte Spannen verbinden
• Bögen sind nach Verknüpfungstyp farblich kodiert

Verknüpfungen löschen

• Auf die Löschschaltfläche (x) neben einer Verknüpfung im Abschnitt „Vorhandene Verknüpfungen" klicken

Datenformat

Eingabedaten

Standardtextdaten mit einem ID- und Textfeld:

[
  {
    "id": "item_1",
    "text": "John Smith works at Google as a senior engineer."
  }
]

Ausgabeformat

Annotationen enthalten sowohl Spannen- als auch Verknüpfungsannotationen:

{
  "id": "item_1",
  "text": "John Smith works at Google as a senior engineer.",
  "entities": [
    {"start": 0, "end": 10, "label": "PERSON", "text": "John Smith"},
    {"start": 20, "end": 26, "label": "ORGANIZATION", "text": "Google"}
  ],
  "relations": [
    {
      "link_type": "WORKS_FOR",
      "span_ids": ["span_abc123", "span_def456"],
      "direction": "directed"
    }
  ]
}

Beschriftungseinschränkungen

Einschränken, welche Spannen-Beschriftungen an jedem Verknüpfungstyp teilnehmen können:

link_types:
  - name: "WORKS_FOR"
    directed: true
    allowed_source_labels: ["PERSON"]      # Only PERSON can be source
    allowed_target_labels: ["ORGANIZATION"]  # Only ORGANIZATION can be target

Bei Verletzung der Einschränkungen zeigt die Oberfläche eine Fehlermeldung an und verhindert die Verknüpfungserstellung.

N-äre Verknüpfungen

Standardmäßig verbinden Verknüpfungen genau 2 Spannen. Für Beziehungen mit mehr Entitäten:

link_types:
  - name: "MEETING"
    directed: false
    max_spans: 5  # Allow up to 5 participants
    allowed_source_labels: ["PERSON"]
    allowed_target_labels: ["PERSON"]

Beispiel

Das vollständige funktionierende Beispiel ist verfügbar unter:

• Konfiguration: project-hub/simple_examples/simple-span-linking/config.yaml
• Daten: project-hub/simple_examples/simple-span-linking/data.json

Zum Ausführen:

cd project-hub/simple_examples
python ../../potato/flask_server.py start simple-span-linking/config.yaml -p 9001

Tipps

1. Spannen zuerst annotieren: Sicherstellen, dass Spannen-Annotationen erstellt werden, bevor versucht wird, sie zu verknüpfen
2. Farben effektiv einsetzen: Für verschiedene Verknüpfungstypen eindeutige Farben wählen
3. Richtung berücksichtigen: Gerichtete Verknüpfungen verwenden, wenn die Beziehung eine klare Richtung hat
4. Tastaturkürzel: Spannen-Beschriftungen unterstützen Tastaturkürzel (1, 2, 3...) für schnellere Annotation

Weiterführende Lektüre

• Spannen-Annotation - Grundlegende Spannen-Annotation
• UI-Konfiguration - Farben und Anzeige anpassen

Implementierungsdetails sind in der Quelldokumentation zu finden.