Flussi di Lavoro Multi-Fase

Potato esegue il compito di annotazione come una fase di un flusso di lavoro più lungo. Consenso, domande di screening, istruzioni, addestramento e un questionario di uscita possono quindi stare intorno ad esso senza uno strumento di survey separato.

Un flusso di annotazione in stile sondaggio

Fasi Disponibili

Gli annotatori attraversano le fasi abilitate nell'ordine che dichiari.

Configurazione di Base

Il blocco phases elenca l'ordine e associa ogni fase al suo file:

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

La fase annotation non ha bisogno di file, perché usa gli annotation_schemes di primo livello del progetto.

Tipi di Fase

Ogni fase basata su file dichiara un type che indica a quale stadio del flusso corrisponde. I valori validi sono consent, prestudy, instructions, training, annotation e poststudy.

Imposta type in modo esplicito. Potato lo deduce solo quando il nome della fase è esso stesso una di quelle parole, quindi una fase con un nome personalizzato deve dichiararne uno:

phases:
  order: [intro, consent, instructions, annotation, feedback]
 
  intro:
    type: prestudy          # custom name, so type is required
    file: surveyflow/intro.json
 
  consent:
    type: consent
    file: surveyflow/consent.json
 
  feedback:
    type: poststudy         # custom name, so type is required
    file: surveyflow/feedback.json

Navigazione all'Indietro

Il pulsante Back è nascosto quando non esiste una pagina precedente, il che include la prima istanza di annotazione. Per consentire agli annotatori di tornare indietro attraverso i confini tra le fasi:

allow_phase_back_navigation: true

Con l'opzione disattivata, gli annotatori possono comunque tornare indietro all'interno di una fase, per esempio tra istanze di annotazione.

Formato delle Domande di Survey

Le fasi di survey leggono un array JSON. Ogni domanda contiene un id, il text mostrato all'annotatore, uno schema che indica il widget e le sue choices:

[
  {
    "id": "consent_1",
    "text": "I certify that I am at least 18 years of age.",
    "schema": "radio",
    "choices": ["I agree", "I disagree"],
    "label_requirement": {"right_label": ["I agree"]}
  },
  {
    "id": "consent_2",
    "text": "I have read and understood the information above.",
    "schema": "radio",
    "choices": ["Yes", "No"],
    "label_requirement": {"right_label": ["Yes"]}
  }
]

Tipi di Schema Supportati

radio per una sola scelta, checkbox o multiselect per più scelte, text per testo libero, number per input numerico, likert per una scala di valutazione e select per un menu a discesa.

Requisiti sulle Risposte

label_requirement stabilisce quali risposte permettono all'annotatore di proseguire:

{
  "id": "age_check",
  "text": "Are you at least 18 years old?",
  "schema": "radio",
  "choices": ["Yes", "No"],
  "label_requirement": {
    "right_label": ["Yes"],
    "required": true
  }
}

right_label elenca le risposte accettabili e required indica se la domanda deve ricevere una risposta. Una domanda di consenso che nessuno può sbagliare non registra nulla, quindi inserisci la risposta accettabile in right_label invece di affidarti alla formulazione.

Domande di Pre-selezione

La pre-selezione si svolge prima del compito principale ed è il posto delle domande su idoneità e background:

phases:
  order: [prestudy, annotation]
  prestudy:
    type: prestudy
    file: surveyflow/prescreening.json

[
  {
    "id": "1",
    "text": "What is your native language?",
    "schema": "select",
    "use_predefined_labels": "language",
    "label_requirement": {"required": true}
  },
  {
    "id": "2",
    "text": "How familiar are you with this topic?",
    "schema": "likert",
    "choices": ["Not at all", "Slightly", "Moderately", "Very", "Extremely"],
    "label_requirement": {"required": true}
  }
]

Survey Post-studio

phases:
  order: [annotation, poststudy]
  poststudy:
    type: poststudy
    file: surveyflow/demographics.json

[
  {
    "id": "gender",
    "text": "What gender do you most closely identify with?",
    "schema": "radio",
    "choices": ["Male", "Female", "Non-binary", "Prefer not to say"],
    "label_requirement": {"required": true}
  },
  {
    "id": "feedback",
    "text": "Please share any feedback about this study (optional)",
    "schema": "text"
  }
]

Set di Etichette Integrati

Potato include set di etichette per le domande che la maggior parte degli studi ripete, così non serve incollare un elenco di paesi nella configurazione:

{"id": "country", "text": "Select your country", "schema": "select", "use_predefined_labels": "country"}

I set disponibili sono country, language, ethnicity e religion.

Campi a Risposta Libera

Aggiungi una casella di testo opzionale a qualsiasi domanda con has_free_response. È ciò che rende utile offrire un'opzione "Altro":

{
  "id": "gender",
  "text": "What is your gender?",
  "schema": "radio",
  "choices": ["Woman", "Man", "Non-binary", "Prefer not to disclose", "Prefer to self-describe"],
  "has_free_response": {"instruction": "Please specify:"},
  "label_requirement": {"required": true}
}

Intestazioni di Pagina

L'intestazione di una pagina di survey si imposta sulla fase, non nel file delle domande:

phases:
  prestudy:
    type: prestudy
    file: surveyflow/consent.json
    header: "Please answer all consent questions"

Domande Condizionali

Le domande di survey possono comparire in base alle risposte precedenti, così una domanda di approfondimento viene posta solo quando è pertinente. Poiché le domande di survey passano per la stessa pipeline degli schemi di annotazione, una condizione fa riferimento a un'altra domanda tramite il suo name:

[
  {
    "name": "prior_experience",
    "annotation_type": "radio",
    "description": "Have you previously worked on a text-annotation task?",
    "labels": ["Yes", "No"],
    "label_requirement": {"required": true}
  },
  {
    "name": "experience_details",
    "annotation_type": "text",
    "description": "Please briefly describe your previous annotation experience.",
    "label_requirement": {"required": true},
    "display_logic": {
      "show_when": [
        {"schema": "prior_experience", "operator": "equals", "value": "Yes"}
      ]
    }
  }
]

Una domanda nascosta è esclusa dalla validazione dei campi obbligatori, quindi non blocca mai il pulsante Continue finché non è visibile.

Tre comportamenti meritano attenzione. Una condizione può fare riferimento a una domanda di qualsiasi fase, quindi una domanda post-studio può dipendere da una risposta pre-studio. Un display_logic non valido, come un operatore sconosciuto o un riferimento a una domanda che non esiste da nessuna parte, fallisce all'avvio del server e non durante l'esecuzione. Infine, una fase instructions che punta a un file .html grezzo aggira la pipeline degli schemi, quindi lì le condizioni non si applicano.

Con export_include_phase_data: true, Potato rivaluta lato server le risposte di ogni partecipante e tralascia le risposte alle domande che non ha mai visto. Consulta Logica Condizionale per il riferimento completo degli operatori.

Esempio Completo

annotation_task_name: "Sentiment Analysis Study"
task_dir: "."
port: 8000
 
data_files:
  - "data/reviews.json"
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this review?"
    labels:
      - Positive
      - Negative
      - Neutral
    sequential_key_binding: true
 
phases:
  order: [consent, prestudy, instructions, training, annotation, poststudy]
 
  consent:
    type: consent
    file: phases/consent.json
 
  prestudy:
    type: prestudy
    file: phases/demographics.json
 
  instructions:
    type: instructions
    file: phases/instructions.html
 
  training:
    type: training
    file: phases/training_questions.json
 
  poststudy:
    type: poststudy
    file: phases/exit_survey.json
 
training:
  enabled: true
  data_file: phases/training_questions.json
  passing_criteria:
    min_correct: 3
  allow_retry: true
 
allow_phase_back_navigation: false
 
output_annotation_dir: "output/"
export_annotation_format: "jsonl"
 
user_config:
  allow_all_users: true

La fase di addestramento prende le sue impostazioni dal blocco training di primo livello, mentre la voce in phases si limita a collocarla nell'ordine. Consulta Fase di Addestramento per i criteri di superamento e il formato dei dati.

Configurazione Legacy

Il vecchio blocco surveyflow funziona ancora e legge le pagine di survey come elenchi di file .jsonl:

surveyflow:
  on: true
  order:
    - pre_annotation
    - post_annotation
  pre_annotation:
    - surveyflow/consent.jsonl
    - surveyflow/demographics.jsonl
  post_annotation:
    - surveyflow/exit_survey.jsonl

Migrazione

Best Practice

Mantieni Brevi le Survey

Ogni domanda in più abbassa il tasso di completamento, e le domande demografiche che l'analisi non usa lo abbassano senza alcun vantaggio.

Prova l'Intero Flusso

Completa tu stesso il flusso di lavoro, in un browser senza sessione, prima di inviare il link a chiunque. Consenso e login sono i due punti in cui un flusso difettoso fallisce per primo e in modo più silenzioso.

Scegli con Cura i Campi Obbligatori

Le domande obbligatorie che avrebbero potuto essere opzionali producono risposte inventate per superare la pagina.

Crowdsourcing

I codici di completamento si configurano con la chiave di primo livello completion_code, non sulla fase post-studio:

completion_code: "POTATO2024"
auto_redirect_on_completion: true
auto_redirect_delay: 5000

Consulta Crowdsourcing per la configurazione delle piattaforme.

Approfondimenti

• Fase di Addestramento: qualificazione con feedback
• Crowdsourcing: Prolific, SONA e altri panel
• Gestione Utenti: liste di accesso e ruoli
• Flusso dell'esperimento - Condizioni, esclusioni e pagine controbilanciate
• Importazione di questionari - Questionari da Qualtrics, REDCap, XLSForm e altri strumenti

Per i dettagli di implementazione, consulta la documentazione sorgente.