Span Linking Annotation

New in v2.1.0

Span linking allows annotators to create typed relationships between spans (text segments) that have already been annotated. This is useful for relation extraction tasks where you need to identify how entities relate to each other, such as "PERSON works_for ORGANIZATION" or "PERSON collaborates_with PERSON".

Overview

The span linking feature provides:

• Typed relationships: Define multiple link types with different colors and constraints
• Directed and undirected links: Support for both directional and symmetric relationships
• N-ary links: Create links between multiple spans (not just pairs)
• Visual arc display: See relationships rendered as colored arcs above the text
• Label constraints: Restrict which span labels can be sources or targets

Configuration

To use span linking, you need two annotation schemes:

1. A span schema to annotate the entities
2. A span_link schema to annotate relationships

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"

Configuration Options

Required Fields

Link Type Options

Visual Display Options

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

Usage

Creating Spans

1. First, annotate the text by selecting span labels and highlighting text
2. Each highlighted span becomes available for linking

Creating Links

1. Select a link type from the available options
2. Click on spans to add them to the current link (selected spans are highlighted)
3. Click "Create Link" to finalize the link
4. For directed links, the first span selected is the source and the last is the target

Viewing Links

• Created links appear in the "Existing Links" section
• If visual display is enabled, arcs are drawn above the text connecting linked spans
• Arcs are color-coded by link type

Deleting Links

• Click the delete button (x) next to any link in the "Existing Links" section

Data Format

Input Data

Standard text data with an ID and text field:

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

Output Format

Annotations include both span annotations and link annotations:

{
  "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"
    }
  ]
}

Label Constraints

Restrict which span labels can participate in each link type:

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

When constraints are violated, the UI shows an error message and prevents link creation.

N-ary Links

By default, links connect exactly 2 spans. For relationships involving more entities:

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

Example

See the complete working example at:

• Config: project-hub/simple_examples/simple-span-linking/config.yaml
• Data: project-hub/simple_examples/simple-span-linking/data.json

To run:

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

Tips

1. Annotate spans first: Make sure to create span annotations before attempting to link them
2. Use colors effectively: Choose distinct colors for different link types
3. Consider direction: Use directed links when the relationship has a clear direction
4. Keyboard shortcuts: Span labels support keyboard shortcuts (1, 2, 3...) for faster annotation

Further Reading

• Span Annotation - Basic span annotation
• UI Configuration - Customize colors and display

For implementation details, see the source documentation.