# Event Annotation

Source: https://www.potatoannotator.com/docs/annotation-types/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:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | Event type name (e.g., "ATTACK", "HIRE") |
| `color` | string | No | Color for visualization (default: auto-assigned) |
| `trigger_labels` | list | No | Span labels allowed as triggers (empty = any span) |
| `arguments` | list | Yes | List of argument definitions |

### Arguments

Each argument defines:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `role` | string | Yes | Semantic role name (e.g., "attacker", "target") |
| `entity_types` | list | No | Span labels allowed for this role (empty = any span) |
| `required` | boolean | No | Whether 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

- [Span Annotation](/docs/annotation-types/span-annotation) - Required for defining entity spans
- [Span Linking](/docs/annotation-types/span-linking) - Alternative for binary relationships
- [Coreference Chains](/docs/annotation-types/coreference) - For entity coreference

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/main/docs/event_annotation.md).