Skip to content
Documentation
Docs/Annotation Types

Event Annotation

Create N-ary event structures with triggers and typed arguments for information extraction.

Event Annotation

Event annotation enables the creation of N-ary event structures for information extraction tasks. Events consist of a trigger span (the word or phrase indicating the event) and argument spans (entity spans with typed semantic roles).

This annotation type is commonly used for information extraction, event detection, semantic role labeling, and knowledge graph construction.

Basic Configuration

Event annotation requires a span annotation schema defined first, which provides the entity spans used as triggers and arguments.

yaml
annotation_schemes:
  # Step 1: Define entity spans
  - annotation_type: span
    name: entities
    description: "Label entities in the text"
    labels:
      - name: PERSON
        color: "#3b82f6"
      - name: ORGANIZATION
        color: "#10b981"
      - name: LOCATION
        color: "#f59e0b"
      - name: WEAPON
        color: "#ef4444"
      - name: EVENT_TRIGGER
        color: "#8b5cf6"
        tooltip: "Words indicating events"
 
  # Step 2: Define event types and arguments
  - annotation_type: event_annotation
    name: events
    description: "Annotate events with triggers and arguments"
    span_schema: entities
    event_types:
      - type: "ATTACK"
        color: "#dc2626"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true
          - role: "target"
            entity_types: ["PERSON", "ORGANIZATION", "LOCATION"]
            required: true
          - role: "weapon"
            entity_types: ["WEAPON"]
            required: false

Configuration Options

Event Types

Each event type defines:

PropertyTypeRequiredDescription
typestringYesEvent type name (e.g., "ATTACK", "HIRE")
colorstringNoColor for visualization (default: auto-assigned)
trigger_labelslistNoSpan labels allowed as triggers (empty = any span)
argumentslistYesList of argument definitions

Arguments

Each argument defines:

PropertyTypeRequiredDescription
rolestringYesSemantic role name (e.g., "attacker", "target")
entity_typeslistNoSpan labels allowed for this role (empty = any span)
requiredbooleanNoWhether this argument must be filled (default: false)

Visual Display

yaml
visual_display:
  enabled: true           # Show arc visualization (default: true)
  arc_position: above     # Position of arcs: "above" (default)
  show_labels: true       # Show role labels on arcs (default: true)

Usage Workflow

  1. Create entity spans: Annotate entity spans using the span annotation tool (click and drag to select text, then choose a label)
  2. Select event type: Click on an event type button (e.g., "ATTACK") to enter event creation mode
  3. Select trigger: Click on a span to set it as the event trigger. If trigger_labels is configured, only spans with matching labels can be selected
  4. Assign arguments: For each argument role, click the role button to activate it, then click on a span to assign it. Required arguments must be filled before the event can be created
  5. Create event: Once all required arguments are filled, click "Create Event" to save
  6. View events: Created events appear in the "Existing Events" section with their triggers and arguments listed

Data Format

Input

Event annotation works with any text-based data format:

json
[
  {
    "id": "event_1",
    "text": "John attacked the building with a rifle."
  }
]

Output

Events are stored with the following structure:

json
{
  "event_annotations": [
    {
      "id": "event_abc123",
      "schema": "events",
      "event_type": "ATTACK",
      "trigger_span_id": "span_xyz789",
      "arguments": [
        {"role": "attacker", "span_id": "span_def456"},
        {"role": "target", "span_id": "span_ghi012"},
        {"role": "weapon", "span_id": "span_jkl345"}
      ],
      "properties": {
        "color": "#dc2626",
        "trigger_text": "attacked",
        "trigger_label": "EVENT_TRIGGER"
      }
    }
  ]
}

Visual Display

The arc visualization shows:

  • A hub (filled circle) at the trigger position
  • Spokes (arrows) connecting to each argument
  • Role labels on each spoke
  • Events are color-coded by type

Multiple events are stacked vertically to avoid overlap.

Full Example

yaml
annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Label entities in the text"
    labels:
      - name: PERSON
        color: "#3b82f6"
      - name: ORGANIZATION
        color: "#10b981"
      - name: LOCATION
        color: "#f59e0b"
      - name: WEAPON
        color: "#ef4444"
      - name: EVENT_TRIGGER
        color: "#8b5cf6"
 
  - annotation_type: event_annotation
    name: events
    description: "Annotate events"
    span_schema: entities
    event_types:
      - type: "ATTACK"
        color: "#dc2626"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "attacker"
            entity_types: ["PERSON", "ORGANIZATION"]
            required: true
          - role: "target"
            entity_types: ["PERSON", "ORGANIZATION", "LOCATION"]
            required: true
          - role: "weapon"
            entity_types: ["WEAPON"]
            required: false
 
      - type: "HIRE"
        color: "#2563eb"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "employer"
            entity_types: ["ORGANIZATION"]
            required: true
          - role: "employee"
            entity_types: ["PERSON"]
            required: true
 
      - type: "TRAVEL"
        color: "#059669"
        trigger_labels: ["EVENT_TRIGGER"]
        arguments:
          - role: "traveler"
            entity_types: ["PERSON"]
            required: true
          - role: "destination"
            entity_types: ["LOCATION"]
            required: true
          - role: "origin"
            entity_types: ["LOCATION"]
            required: false

Best Practices

  1. Use descriptive type names - Choose clear, unambiguous event type names that reflect the semantic meaning
  2. Constrain triggers appropriately - Use trigger_labels to limit which spans can be triggers. For verb-based events, create a dedicated "EVENT_TRIGGER" label
  3. Balance required vs optional arguments - Mark core arguments as required, but allow optional arguments for context that may not always be present
  4. Use entity type constraints - Enforce semantic constraints on arguments (e.g., an "attacker" should be a PERSON or ORGANIZATION)

Further Reading

For implementation details, see the source documentation.

PreviousDialogue AnnotationNextEntity Linking