Flux de travail multi-phases

Potato traite la tâche d'annotation comme une phase d'un flux de travail plus long. Consentement, questions de présélection, consignes, formation et questionnaire de sortie peuvent donc l'entourer sans outil de questionnaire séparé.

Un flux de travail d'annotation avec questionnaires

Phases disponibles

Les annotateurs parcourent les phases activées dans l'ordre que vous déclarez.

Configuration de base

Le bloc phases donne l'ordre et associe chaque phase à son fichier :

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 phase annotation n'a pas besoin de file, car elle utilise les annotation_schemes de premier niveau du projet.

Types de phase

Chaque phase fondée sur un fichier déclare un type qui indique à quelle étape du flux elle correspond. Les valeurs valides sont consent, prestudy, instructions, training, annotation et poststudy.

Indiquez type explicitement. Potato ne le déduit que si le nom de la phase est lui-même l'un de ces mots ; une phase au nom personnalisé doit donc en déclarer un :

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

Retour en arrière

Le bouton Back est masqué lorsqu'il n'y a pas de page précédente, ce qui inclut la première instance d'annotation. Pour permettre aux annotateurs de revenir en arrière d'une phase à l'autre :

allow_phase_back_navigation: true

Lorsque cette option est désactivée, les annotateurs peuvent toujours revenir en arrière à l'intérieur d'une phase, par exemple entre instances d'annotation.

Format des questions de questionnaire

Les phases de questionnaire lisent un tableau JSON. Chaque question comporte un id, le text présenté à l'annotateur, un schema qui désigne le widget, et ses 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"]}
  }
]

Types de schéma pris en charge

radio pour un choix unique, checkbox ou multiselect pour plusieurs, text pour du texte libre, number pour une saisie numérique, likert pour une échelle d'évaluation et select pour une liste déroulante.

Exigences sur les réponses

label_requirement détermine quelles réponses permettent à l'annotateur de continuer :

{
  "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 liste les réponses acceptables et required indique si la question doit recevoir une réponse. Une question de consentement à laquelle personne ne peut échouer ne recueille rien : placez la réponse acceptable dans right_label au lieu de compter sur la formulation.

Questions de présélection

La présélection a lieu avant la tâche principale, et c'est là que se placent les questions d'éligibilité et de profil :

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}
  }
]

Questionnaires de fin d'étude

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"
  }
]

Jeux d'étiquettes intégrés

Potato fournit des jeux d'étiquettes pour les questions que la plupart des études reprennent, ce qui évite de coller une liste de pays dans la configuration :

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

Les jeux disponibles sont country, language, ethnicity et religion.

Champs de réponse libre

Ajoutez une zone de texte facultative à n'importe quelle question avec has_free_response. C'est ce qui donne un intérêt aux options « Autre » :

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

En-têtes de page

L'en-tête d'une page de questionnaire se règle sur la phase, et non dans le fichier de questions :

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

Questions conditionnelles

Une question de questionnaire peut s'afficher selon les réponses précédentes, de sorte qu'une question de suivi n'est posée que lorsqu'elle s'applique. Comme les questions de questionnaire passent par le même pipeline que les schémas d'annotation, une condition fait référence à une autre question par son 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"}
      ]
    }
  }
]

Une question masquée est exclue de la validation des champs obligatoires ; elle ne bloque donc jamais le bouton Continue tant qu'elle n'est pas affichée.

Trois comportements sont à connaître. Une condition peut faire référence à une question de n'importe quelle phase, si bien qu'une question de fin d'étude peut dépendre d'une réponse de pré-étude. Un display_logic invalide, par exemple un opérateur inconnu ou une référence à une question qui n'existe nulle part, échoue au démarrage du serveur et non à l'exécution. Enfin, une phase instructions qui pointe vers un fichier .html brut contourne le pipeline des schémas, et les conditions ne s'y appliquent donc pas.

Avec export_include_phase_data: true, Potato réévalue côté serveur les réponses de chaque participant et exclut les réponses aux questions qu'il n'a jamais vues. Voir Logique conditionnelle pour la référence complète des opérateurs.

Exemple complet

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 phase de formation tire ses réglages du bloc training de premier niveau, tandis que l'entrée dans phases se contente de la placer dans l'ordre. Voir Phase de formation pour les critères de réussite et le format des données.

Ancienne configuration

L'ancien bloc surveyflow fonctionne toujours et lit les pages de questionnaire sous forme de listes de fichiers .jsonl :

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

Migration

Bonnes pratiques

Gardez les questionnaires courts

Chaque question supplémentaire fait baisser le taux d'achèvement, et les questions sociodémographiques que l'analyse n'utilise pas le font baisser pour rien.

Testez le flux complet

Faites vous-même tout le flux de travail, dans un navigateur sans session, avant d'envoyer le lien à qui que ce soit. Le consentement et la connexion sont les deux endroits où un flux défaillant échoue en premier, et le plus discrètement.

Choisissez avec soin les champs obligatoires

Une question rendue obligatoire alors qu'elle aurait pu rester facultative produit des réponses inventées pour passer la page.

Crowdsourcing

Les codes de complétion se configurent avec la clé de premier niveau completion_code, et non sur la phase de fin d'étude :

completion_code: "POTATO2024"
auto_redirect_on_completion: true
auto_redirect_delay: 5000

Voir Crowdsourcing pour la configuration des plateformes.

Pour aller plus loin

• Phase de formation : qualification avec retour
• Crowdsourcing : intégration Prolific et MTurk
• Gestion des utilisateurs : listes d'accès et rôles

Pour les détails d'implémentation, voir la documentation source.