Condurre studi di annotazione su Prolific

Punta l'URL dello studio Prolific al tuo server Potato con ?PROLIFIC_PID={{%PROLIFIC_PID%}}, imposta login.type: url_direct e un completion_code uguale al codice dello studio, e ogni partecipante accede con il proprio ID Prolific e viene rimandato a Prolific quando finisce.

Prolific è un bacino di partecipanti pensato per gli studi accademici, ed è la piattaforma di crowdsourcing che Potato supporta in modo più completo. Questa guida copre la configurazione di cui Potato ha bisogno, le impostazioni dello studio dal lato di Prolific e il controllo di qualità da avere pronto prima di spendere soldi.

Perché i ricercatori usano Prolific per l'annotazione

Prolific seleziona i propri partecipanti e li paga attraverso la piattaforma, quindi le parti del crowdsourcing che di solito consumano il budget di uno studio vengono gestite fuori dal tuo server. Impone una tariffa oraria minima, filtra i partecipanti su criteri demografici e linguistici e registra il consenso, il che accorcia le pratiche con il comitato etico (IRB) per uno studio di etichettatura. Mechanical Turk, il termine di paragone abituale, ha chiuso il 30 settembre 2026, e spostare uno studio da MTurk spiega il passaggio per gli studi che giravano lì.

Cosa ti serve prima di iniziare

1. Un account ricercatore su Prolific.
2. Potato in esecuzione su un server con un URL HTTPS pubblico. La guida al deployment su server copre questo passaggio.
3. Una configurazione con i tuoi file di dati, item_properties e almeno uno schema di annotazione.

La configurazione di cui Potato ha bisogno

Quattro impostazioni trasformano un normale progetto Potato in uno che Prolific può pilotare. login.url_argument indica il parametro URL che porta l'ID Prolific del partecipante, completion_code deve corrispondere a un codice configurato sullo studio Prolific, e le due chiavi di reindirizzamento rimandano i partecipanti a Prolific invece di lasciarli su una pagina di fine. Le chiavi di assegnazione subito sotto limitano quanto lavoro riceve ciascun partecipante, ed è questo che rende prevedibile il costo di uno studio.

annotation_task_name: "Sentiment Annotation Study"
task_description: "Classify the sentiment of short text snippets. This task takes about five minutes."
 
# Participants are logged in from the PROLIFIC_PID URL parameter
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
# Must match a completion code configured on the Prolific study
completion_code: "C1ABCDEF"
auto_redirect_on_completion: true
auto_redirect_delay: 5000
 
# Keep participants on task
hide_navbar: true
jumping_to_id_disabled: true
 
# Each participant labels 20 items; each item is labeled by 3 participants
assignment_strategy: random
max_annotations_per_user: 20
num_annotators_per_item: 3
 
data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: text
 
output_annotation_dir: annotation_output/prolific-study/
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true
  users: []
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment expressed in this text?"
    labels:
      - name: positive
      - name: neutral
      - name: negative
    sequential_key_binding: true
    label_requirement:
      required: true

Scegli num_annotators_per_item in base a cosa intendi fare con i dati. Tre è la scelta abituale quando vuoi riportare l'accordo o prendere l'etichetta di maggioranza, e uno basta quando un pilota ha già mostrato che il task è ben definito. La guida all'accordo tra annotatori spiega come leggere il risultato.

Impostare lo studio su Prolific

Nel modulo dello studio su Prolific, imposta come URL esterno dello studio il tuo server Potato, con i segnaposto di Prolific nella query string:

https://your-server.com/?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}

Alla domanda su come vengono registrati gli ID Prolific scegli "I'll use URL parameters", poi configura sullo studio un codice di completamento uguale a completion_code nella tua configurazione. STUDY_ID e SESSION_ID vengono salvati nella sessione del partecipante per il tracciamento successivo.

Un partecipante che clicca sul link arriva su Potato con il proprio ID nell'URL. Potato crea un account senza password con quell'ID, accompagna il partecipante attraverso le fasi che hai configurato e, alla fine, mostra il codice di completamento con un pulsante Return to Prolific che punta a https://app.prolific.com/submissions/complete?cc=<code>. Con auto_redirect_on_completion impostato, il reindirizzamento avviene da solo dopo auto_redirect_delay millisecondi.

Scrivi il dominio come app.prolific.com. Il vecchio dominio app.prolific.co non serve più HTTPS, quindi un URL di completamento copiato da una guida vecchia manda i partecipanti su una pagina morta dopo che hanno fatto il lavoro.

Consenso, istruzioni e questionari finali

La maggior parte degli studi in crowdsourcing ha bisogno di più della sola pagina di annotazione. Il blocco phases di Potato colloca consenso, preselezione, istruzioni e un questionario post-studio attorno alla fase di annotazione, e i partecipanti le attraversano nell'ordine in cui le elenchi:

phases:
  order: [consent, prestudy, instructions, annotation, poststudy]
 
  consent:
    type: consent
    file: surveyflow/consent.json
 
  prestudy:
    type: prestudy
    file: surveyflow/prescreening.json
 
  instructions:
    type: instructions
    file: surveyflow/instructions.html
 
  poststudy:
    type: poststudy
    file: surveyflow/demographics.json

Aggiungi questo blocco alla configurazione precedente. La fase annotation è l'unica obbligatoria, quindi uno studio che non richiede un modulo di consenso può omettere tutte le altre voci. I progetti più vecchi configurano la stessa cosa tramite surveyflow, che Potato legge ancora ma non raccomanda più per i progetti nuovi.

Controlli di attenzione

Un controllo di attenzione è un item con una risposta corretta nota, mescolato nella coda in modo che un partecipante disattento produca una risposta sbagliata rilevabile. Potato li carica da un file a parte e non dai tuoi dati, così i controlli restano fuori dal tuo dataset:

attention_checks:
  enabled: true
  items_file: "data/attention_checks.json"
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    block_threshold: 5

Aggiungi questo blocco alla configurazione precedente. frequency: 10 inserisce un controllo ogni dieci item, e min_response_time fa fallire una risposta che arriva prima di quanto chiunque impiegherebbe a leggere l'item, qualunque cosa dica. Il cronometro gira sul server, dal momento in cui ha inviato l'item al momento in cui ha ricevuto il salvataggio.

Ogni item di controllo porta un id, il testo che vede il partecipante e la risposta attesa per ciascuno schema, per nome:

[
  {
    "id": "attn_001",
    "text": "Please select 'positive' for this item to verify you are reading carefully.",
    "expected_answer": {"sentiment": "positive"}
  }
]

Regola block_threshold sulla lunghezza del tuo studio. Un partecipante che fallisce cinque controlli in un task di 20 item non stava annotando; uno che ne fallisce cinque su 300 item forse è stato stanco per un tratto, e bloccarlo fa perdere il resto del suo lavoro.

Monitorare uno studio in corso

Imposta login.type: prolific e aggiungi un blocco prolific, e Potato interroga l'API di Prolific sullo stato degli invii, oltre al login diretto da URL che già gestisce:

login:
  type: prolific
  url_argument: PROLIFIC_PID
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "C1ABCDEF"

Aggiungi questo blocco alla configurazione precedente. Il file a cui punta contiene il token dell'API, quindi tienilo fuori dal controllo di versione:

# configs/prolific_config.yaml
token: "your-prolific-api-token"
study_id: "your-study-id"
workload_checker: true
max_concurrent_sessions: 30
workload_checker_period: 300

Con il token configurato, la dashboard di amministrazione acquisisce un pannello Prolific che pubblica, mette in pausa e interrompe lo studio, approva o rifiuta gli invii, paga i bonus e mostra in anteprima il costo dell'aggiunta di posti. Il monitor del carico di lavoro mette in pausa lo studio quando i partecipanti attivi raggiungono max_concurrent_sessions e lo riprende quando il conteggio scende sotto il 20% di quel massimo. Riprende solo uno studio che ha messo in pausa da sé, quindi uno studio che metti in pausa a mano su Prolific resta in pausa.

Partecipanti che abbandonano

Prolific segnala un invio come RETURNED, TIMED-OUT o REJECTED quando un partecipante se ne va senza finire. Potato libera gli item assegnati a quei partecipanti perché altre persone possano prenderli, e conserva le annotazioni che avevano già completato. Usa instance_reclaim quando il motivo deve cambiare ciò che succede a quel lavoro completato:

instance_reclaim:
  enabled: true
  prolific:
    preserve_completed_annotations: true
    status_policies:
      TIMED-OUT:
        preserve_completed_annotations: true
      REJECTED:
        preserve_completed_annotations: false

Aggiungi questo blocco alla configurazione precedente. Vale la pena impostare questa distinzione di proposito. Un partecipante andato in timeout di solito ha annotato onestamente finché qualcosa non lo ha interrotto, mentre uno rifiutato ha prodotto un lavoro che hai deciso di non pagare, e tenerlo nel dataset contraddice il rifiuto.

Cosa contiene l'output

Potato scrive file per annotatore sotto output_annotation_dir e, quando export_annotation_format è impostato, un'esportazione periodica sotto <output_annotation_dir>/exports/<format>/. Ogni record esportato contiene l'istanza, l'annotatore e le etichette per nome di schema:

{"instance_id": "t_014", "user_id": "5f2c9a1b3d4e5f6a7b8c9d0e", "labels": {"sentiment": {"positive": "positive"}}, "spans": {}, "links": {}}

Lo user_id è l'ID Prolific del partecipante, perché è il nome utente con cui Potato lo ha creato, ed è questo che ti permette di ricondurre una riga a un invio Prolific per approvarlo o pagare un bonus. Tratta quella colonna come dato identificativo quando pubblichi il dataset.

Fare prima un pilota

Fai lavorare da 5 a 10 partecipanti prima di lanciare lo studio completo, e leggi il loro output invece di guardare solo il tasso di completamento. Due errori costano cari se scoperti dopo. Il primo è un'istruzione ambigua in un modo che non vedi perché il task l'hai scritto tu, e il secondo è un tempo per item molto lontano dalla tua stima, il che significa che il tuo compenso è sbagliato in una direzione o nell'altra.

Fissa il prezzo dello studio in base al tempo mediano del pilota e non al tuo. Mantieni l'interfaccia utilizzabile alla larghezza di un telefono, perché alcuni partecipanti saranno su un telefono qualunque cosa dica la descrizione dello studio. Approva gli invii rapidamente, sia perché le persone aspettano i soldi sia perché il tuo tempo di approvazione è visibile ai futuri partecipanti che decidono se accettare il tuo studio.

Passi successivi

• Sposta un vecchio studio da Mechanical Turk
• Imposta il controllo di qualità più in dettaglio
• Calcola l'accordo tra annotatori sul risultato

Il riferimento completo si trova in Integrazione del crowdsourcing su questo sito, e la documentazione dell'integrazione con Prolific nel repository di Potato copre gli endpoint dell'API di amministrazione dietro il pannello della dashboard. Parti da lì se ti servono la creazione di studi, la sincronizzazione delle qualifiche o screen-out pagati gestiti dal tuo codice.