Formatos de Datos

Potato lee la entrada de anotación desde archivos JSON, JSON Lines, CSV y TSV. Esta guía explica cómo estructurar esos datos, qué campos necesita Potato de cada registro y dónde quedan las anotaciones.

Del archivo de entrada a las etiquetas exportadas

Formatos Soportados

Formato JSON

El formato más común. Tus datos deben ser un array de objetos:

[
  {
    "id": "doc_001",
    "text": "This is the first document to annotate.",
    "source": "twitter",
    "date": "2024-01-15"
  },
  {
    "id": "doc_002",
    "text": "This is the second document.",
    "source": "reddit",
    "date": "2024-01-16"
  }
]

Formato JSON Lines

Cada línea es un objeto JSON separado. Útil para conjuntos de datos grandes:

{"id": "doc_001", "text": "First document"}
{"id": "doc_002", "text": "Second document"}
{"id": "doc_003", "text": "Third document"}

Formato CSV/TSV

Datos tabulares con encabezados:

id,text,source
doc_001,"This is the first document",twitter
doc_002,"This is the second document",reddit

Configuración

Configuración Básica

Configura los archivos de datos y las asignaciones de campos en tu YAML:

data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id      # Field name for unique ID
  text_key: text  # Field name for content to annotate

Múltiples Archivos de Datos

Combina múltiples fuentes de datos:

data_files:
  - "data/batch_1.json"
  - "data/batch_2.json"
  - "data/batch_3.jsonl"

Los archivos se procesan en orden y se combinan.

Tipos de Datos

Texto Plano

Contenido de texto simple:

{
  "id": "1",
  "text": "The product arrived quickly and works great!"
}

Archivos Multimedia

Un elemento de imagen, video o audio indica su archivo en un campo del registro, y un campo de instance_display lo muestra en la página:

{
  "id": "1",
  "image_path": "photo_001.jpg"
}

media_directory: media    # the default, relative to task_dir
 
instance_display:
  fields:
    - key: image_path
      type: image

Potato sirve los archivos de media_directory en /media/. Por defecto la carpeta es media/ dentro de task_dir, y una ruta absoluta la dirige a una carpeta en cualquier lugar de la máquina. En un campo de visualización multimedia (p. ej., image, video, audio, pdf), un nombre de archivo sin ruta como photo_001.jpg se convierte en /media/photo_001.jpg cuando el archivo está en esa carpeta, y una URL completa se usa tal como está escrita. item_properties.image_key no pone la imagen en la página. Indica al soporte de IA y a la detección de duplicados qué campo contiene la imagen.

Diálogos/Listas

Un campo text que contiene una lista JSON se presenta con un elemento por línea, porque la lectura vertical se adapta a un diálogo. Configura list_as_text.horizontal para colocar los elementos lado a lado en una comparación por pares:

{
  "id": "1",
  "text": ["Option A", "Option B", "Option C"]
}

Pares de Texto

Un campo text que contiene un objeto JSON se renderiza con el tipo de visualización que declare la configuración (conversation_tree, web_agent_trace y similares). Si no se declara ningún tipo de visualización, se muestra como JSON formateado, así que declara uno para una tarea de comparación:

{
  "id": "pair_001",
  "text": {
    "A": "Response from Model A",
    "B": "Response from Model B"
  }
}

Archivos HTML

Guarda los archivos .html en una carpeta dentro de task_dir y apúntalos desde el campo text habitual, ya que Potato no tiene una propiedad de elemento separada para HTML. La tarea incluida examples/advanced/html-annotation incrusta cada uno:

{
  "id": "1",
  "text": "<embed width=\"1020\" height=\"440\" src=\"data/html_data/1.html\" type=\"text/html\">"
}

Anotación Contextual

Incluye contexto junto con el texto principal:

{
  "id": "1",
  "text": "This is great!",
  "context": "Previous message: How do you like the new feature?"
}

Los campos distintos del id y el texto llegan a la página a través de kwargs, que nombra las claves adicionales que se toman de cada elemento:

item_properties:
  id_key: id
  text_key: text
  kwargs:
    - context

Configuración de Visualización

Opciones de Visualización de Listas

Controla cómo se presenta un campo cuyo valor es una lista. La clave admite tres subclaves, y list_as_text: true la activa con los valores predeterminados:

list_as_text:
  # Prefix each item so an annotator can refer to one by name.
  text_list_prefix_type: alphabet   # alphabet, number, bullet, or none
 
  # Side-by-side suits a pairwise comparison. The default is vertical.
  horizontal: true
 
  # Shade alternate turns, which keeps a long dialogue readable.
  alternating_shading: true

Contenido HTML

El marcado en un campo text se renderiza sin ninguna clave de configuración. Potato lo sanea en lugar de escaparlo, de modo que las etiquetas de una lista permitida (<b>, <i>, <span> y similares) se convierten en formato, mientras que <script> y todo lo que no está en la lista se escapa y queda inerte. Los resaltados de spans se insertan en el elemento como marcado, por eso escapar el campo completo no es una opción.

{
  "id": "1",
  "text": "<p>This is <strong>formatted</strong> text.</p>"
}

Configuración de Salida

Directorio de Salida

Especifica dónde se guardan las anotaciones:

output_annotation_dir: "output/"

Formato de Salida

Las anotaciones siempre se conservan como archivos user_state.json por usuario. Además, export_annotation_format escribe periódicamente una exportación plana en <output_annotation_dir>/exports/<format>/, que es la forma que conviene analizar. Ningún exportador se llama json:

export_annotation_format: "jsonl"   # or csv, tsv, parquet, coco, conll_2003, ...

Ejecuta python -m potato.export --list-formats para ver el registro completo.

Estructura de Salida

Cada user_state.json contiene las etiquetas de ese anotador indexadas por instancia, con los spans registrados por separado:

{
  "user_id": "annotator_1",
  "instance_id_to_label_to_value": {
    "doc_001": {
      "sentiment": {"labels": {"positive": true}}
    }
  },
  "instance_id_to_span_to_value": {
    "doc_001": {
      "ner": [
        {"start": 0, "end": 5, "label": "PERSON", "text": "Alice"}
      ]
    }
  }
}

Tipos de Datos Especiales

Escalamiento Mejor-Peor

Para tareas de clasificación, usa elementos separados por comas:

{
  "id": "1",
  "text": "Item A,Item B,Item C,Item D"
}

Argumentos Personalizados

Incluye campos adicionales para visualización o filtrado:

{
  "id": "1",
  "text": "Document content",
  "category": "news",
  "priority": "high",
  "custom_field": "any value"
}

Backend de Base de Datos

Para conjuntos de datos grandes, usa MySQL:

database:
  type: mysql
  host: localhost
  port: 3306
  database: potato_db
  username: ${DB_USER}
  password: ${DB_PASSWORD}

Potato crea automáticamente las tablas necesarias en el primer inicio.

Validación de Datos

Potato valida tus datos al iniciar:

• Campo ID faltante - Todos los elementos necesitan identificadores únicos
• Campo de texto faltante - Los elementos necesitan contenido para anotar
• IDs duplicados - Todos los IDs deben ser únicos
• Archivo no encontrado - Verifica las rutas de los archivos de datos

Ejemplo Completo

annotation_task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
 
# Display settings
list_as_text:
  text_list_prefix_type: number
  horizontal: false
 
# Output
output_annotation_dir: "output/"
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
user_config:
  allow_all_users: true
  users: []

Mejores Prácticas

1. Usa IDs Significativos

Facilita el seguimiento y la depuración:

{"id": "twitter_2024_001", "text": "..."}

2. Mantén el Texto Conciso

Los textos largos ralentizan la anotación. Considera:

• Truncar a las partes clave
• Proporcionar resúmenes
• Usar contenedores con scroll

3. Incluye Metadatos

Ayuda con el filtrado y el análisis:

{
  "id": "1",
  "text": "Content",
  "source": "twitter",
  "date": "2024-01-15",
  "language": "en"
}

4. Valida Antes de Cargar

Comprueba tus datos sin conexión:

import json
 
with open('data.json') as f:
    data = json.load(f)
 
# Check for required fields
for item in data:
    assert 'id' in item, f"Missing id: {item}"
    assert 'text' in item, f"Missing text: {item}"
 
# Check for duplicates
ids = [item['id'] for item in data]
assert len(ids) == len(set(ids)), "Duplicate IDs found"
 
print(f"Validated {len(data)} items")

5. Respalda los Datos Originales

Mantén los datos crudos separados de las anotaciones para reproducibilidad.

6. Usa JSON Lines para Archivos Grandes

Más eficiente en memoria que los arrays JSON:

# Convert JSON array to JSON Lines
cat data.json | jq -c '.[]' > data.jsonl

Lectura Adicional

• Carga desde Directorio de Datos - Carga desde directorios con observación en vivo
• Anotación de Diálogos - Visualización de datos con varios elementos
• Formatos de Exportación - Opciones de formato de salida

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