Anotación de Eventos

Crea estructuras de eventos N-arios con activadores y argumentos tipados para extracción de información.

Anotación de Eventos

La anotación de eventos permite la creación de estructuras de eventos N-arios para tareas de extracción de información. Los eventos consisten en un segmento activador (la palabra o frase que indica el evento) y segmentos de argumento (segmentos de entidad con roles semánticos tipados).

Este tipo de anotación se usa comúnmente para extracción de información, detección de eventos, etiquetado de roles semánticos y construcción de grafos de conocimiento.

Configuración Básica

La anotación de eventos requiere un esquema de anotación de segmentos definido primero, que proporciona los segmentos de entidad usados como activadores y argumentos.

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

Opciones de Configuración

Tipos de Evento

Cada tipo de evento define:

Propiedad	Tipo	Requerido	Descripción
`type`	string	Sí	Nombre del tipo de evento (por ejemplo, "ATTACK", "HIRE")
`color`	string	No	Color para visualización (predeterminado: auto-asignado)
`trigger_labels`	list	No	Etiquetas de segmento permitidas como activadores (vacío = cualquier segmento)
`arguments`	list	Sí	Lista de definiciones de argumentos

Argumentos

Cada argumento define:

Propiedad	Tipo	Requerido	Descripción
`role`	string	Sí	Nombre del rol semántico (por ejemplo, "attacker", "target")
`entity_types`	list	No	Etiquetas de segmento permitidas para este rol (vacío = cualquier segmento)
`required`	boolean	No	Si este argumento debe ser llenado (predeterminado: false)

Visualización

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)

Flujo de Trabajo de Uso

Crear segmentos de entidad: Anota segmentos de entidad usando la herramienta de anotación de segmentos (haz clic y arrastra para seleccionar texto, luego elige una etiqueta)
Seleccionar tipo de evento: Haz clic en un botón de tipo de evento (por ejemplo, "ATTACK") para entrar en modo de creación de evento
Seleccionar activador: Haz clic en un segmento para establecerlo como activador del evento. Si trigger_labels está configurado, solo se pueden seleccionar segmentos con etiquetas coincidentes
Asignar argumentos: Para cada rol de argumento, haz clic en el botón del rol para activarlo, luego haz clic en un segmento para asignarlo. Los argumentos requeridos deben ser llenados antes de crear el evento
Crear evento: Una vez que todos los argumentos requeridos están llenos, haz clic en "Crear Evento" para guardar
Ver eventos: Los eventos creados aparecen en la sección "Eventos Existentes" con sus activadores y argumentos listados

Formato de Datos

Entrada

La anotación de eventos funciona con cualquier formato de datos basado en texto:

json

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

Salida

Los eventos se almacenan con la siguiente estructura:

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

Visualización

La visualización de arcos muestra:

Un hub (círculo relleno) en la posición del activador
Radios (flechas) conectando a cada argumento
Etiquetas de rol en cada radio
Los eventos están codificados por color según su tipo

Múltiples eventos se apilan verticalmente para evitar solapamiento.

Ejemplo Completo

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

Mejores Prácticas

Usar nombres de tipo descriptivos - Elige nombres de tipo de evento claros e inequívocos que reflejen el significado semántico
Restringir los activadores apropiadamente - Usa trigger_labels para limitar qué segmentos pueden ser activadores. Para eventos basados en verbos, crea una etiqueta dedicada "EVENT_TRIGGER"
Equilibrar argumentos requeridos vs opcionales - Marca los argumentos centrales como requeridos, pero permite argumentos opcionales para contexto que puede no estar siempre presente
Usar restricciones de tipo de entidad - Aplica restricciones semánticas en los argumentos (por ejemplo, un "attacker" debe ser PERSON u ORGANIZATION)

Lectura Adicional

Anotación de Segmentos - Requerido para definir segmentos de entidad
Vinculación de Segmentos - Alternativa para relaciones binarias
Cadenas de Correferencia - Para correferencia de entidades

Para detalles de implementación, consulta la documentación fuente.