Formatos de Datos

Formatos de datos soportados y cómo estructurar tus datos de anotación.

Potato soporta múltiples formatos de datos de forma nativa. Esta guía explica cómo estructurar tus datos para la anotación.

How data flows through Potato: input files become instances with an id and text plus metadata, get annotated, and are exported to many formats From input file to exported labels

Formatos Soportados

Formato	Extensión	Descripción
JSON	`.json`	Array de objetos
JSON Lines	`.jsonl`	Un objeto JSON por línea
CSV	`.csv`	Valores separados por comas
TSV	`.tsv`	Valores separados por tabulaciones

Formato JSON

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

json

[
  {
    "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:

jsonl

{"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:

csv

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:

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:

yaml

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:

json

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

Archivos Multimedia

Referencia imágenes, videos o audio:

json

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

yaml

item_properties:
  id_key: id
  image_key: image_path

Diálogos/Listas

Las listas se muestran automáticamente de forma horizontal:

json

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

Pares de Texto

Para tareas de comparación:

json

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

Archivos HTML

Referencia archivos HTML almacenados en carpetas:

json

{
  "id": "1",
  "html_file": "html/document_001.html"
}

Anotación Contextual

Incluye contexto junto con el texto principal:

json

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

yaml

item_properties:
  id_key: id
  text_key: text
  context_key: context

Configuración de Visualización

Opciones de Visualización de Listas

Controla cómo se muestran las listas y diccionarios:

yaml

list_as_text:
  # Add prefixes to items
  text_prefix: "A"  # A., B., C. (or "1" for 1., 2., 3.)
 
  # Display orientation
  horizontal: true  # Side-by-side (false for vertical)
 
  # Randomization
  randomize_values: true   # Shuffle list items
  randomize_keys: true     # Shuffle dictionary keys

Contenido HTML

Habilita el renderizado de HTML en el texto:

yaml

html_content: true

json

{
  "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:

yaml

output_annotation_dir: "output/"

Formato de Salida

Elige el formato de salida:

yaml

output_annotation_format: "json"  # json, jsonl, csv, or tsv

Estructura de Salida

Las anotaciones incluyen el ID del documento y las respuestas:

json

{
  "id": "doc_001",
  "user": "annotator_1",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Tipos de Datos Especiales

Escalamiento Mejor-Peor

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

json

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

Argumentos Personalizados

Incluye campos adicionales para visualización o filtrado:

json

{
  "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:

yaml

database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${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

yaml

task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
  context_key: metadata
 
# Display settings
list_as_text:
  text_prefix: "1"
  horizontal: false
 
# Output
output_annotation_dir: "output/"
output_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
allow_all_users: true

Mejores Prácticas

1. Usa IDs Significativos

Facilita el seguimiento y la depuración:

json

{"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:

json

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

4. Valida Antes de Cargar

Comprueba tus datos sin conexión:

python

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 arrays JSON:

bash

# 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 multi-elemento
Formatos de Exportación - Opciones de formato de salida

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