Formati di Dati

Formati di dati supportati e come strutturare i dati per l'annotazione.

Potato supporta nativamente più formati di dati. Questa guida spiega come strutturare i dati per l'annotazione.

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

Formati Supportati

Formato	Estensione	Descrizione
JSON	`.json`	Array di oggetti
JSON Lines	`.jsonl`	Un oggetto JSON per riga
CSV	`.csv`	Valori separati da virgola
TSV	`.tsv`	Valori separati da tabulazione

Formato JSON

Il formato più comune. I dati devono essere un array di oggetti:

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

Ogni riga è un oggetto JSON separato. Utile per dataset di grandi dimensioni:

jsonl

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

Formato CSV/TSV

Dati tabulari con intestazioni:

csv

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

Configurazione

Configurazione Base

Configura i file di dati e le mappature dei campi nel tuo 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

File di Dati Multipli

Combina più sorgenti di dati:

yaml

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

I file vengono elaborati in ordine e combinati.

Tipi di Dati

Testo Semplice

Contenuto testuale semplice:

json

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

File Multimediali

Riferimento a immagini, video o audio:

json

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

yaml

item_properties:
  id_key: id
  image_key: image_path

Dialogo/Liste

Le liste vengono visualizzate automaticamente in orizzontale:

json

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

Coppie di Testo

Per attività di confronto:

json

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

File HTML

Riferimento a file HTML archiviati in cartelle:

json

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

Annotazione Contestuale

Includi il contesto accanto al testo principale:

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

Configurazione della Visualizzazione

Opzioni di Visualizzazione delle Liste

Controlla come vengono visualizzate le liste e i dizionari:

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

Contenuto HTML

Abilita il rendering HTML nel testo:

yaml

html_content: true

json

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

Configurazione dell'Output

Directory di Output

Specifica dove vengono salvate le annotazioni:

yaml

output_annotation_dir: "output/"

Formato di Output

Scegli il formato di output:

yaml

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

Struttura dell'Output

Le annotazioni includono l'ID del documento e le risposte:

json

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

Tipi di Dati Speciali

Best-Worst Scaling

Per attività di classificazione, usa elementi separati da virgola:

json

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

Argomenti Personalizzati

Includi campi aggiuntivi per la visualizzazione o il filtraggio:

json

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

Backend Database

Per dataset di grandi dimensioni, utilizza MySQL:

yaml

database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${DB_USER}
  password: ${DB_PASSWORD}

Potato crea automaticamente le tabelle necessarie al primo avvio.

Validazione dei Dati

Potato valida i tuoi dati all'avvio:

Campo ID mancante - Tutti gli elementi devono avere identificatori univoci
Campo testo mancante - Gli elementi devono avere contenuto da annotare
ID duplicati - Tutti gli ID devono essere univoci
File non trovato - Verifica i percorsi dei file di dati

Esempio 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

Buone Pratiche

1. Usa ID Significativi

Facilita il tracciamento e il debug:

json

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

2. Mantieni il Testo Conciso

I testi lunghi rallentano l'annotazione. Considera di:

Troncare alle parti essenziali
Fornire riassunti
Usare contenitori scorrevoli

3. Includi Metadati

Facilitano il filtraggio e l'analisi:

json

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

4. Valida Prima del Caricamento

Controlla i dati offline:

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. Fai il Backup dei Dati Originali

Tieni i dati grezzi separati dalle annotazioni per garantire la riproducibilità.

6. Usa JSON Lines per File di Grandi Dimensioni

Più efficiente in termini di memoria rispetto agli array JSON:

bash

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

Approfondimenti

Caricamento della Directory Dati - Carica da directory con monitoraggio in tempo reale
Annotazione di Dialoghi - Visualizzazione di dati multi-elemento
Formati di Esportazione - Opzioni per il formato di output

Per i dettagli implementativi, consulta la documentazione sorgente.