Flux de travail multi-phases

Name: Potato
Author: Potato

Construisez des flux de travail d'annotation en plusieurs étapes dans Potato : phases de formation, tâches d'annotation et pages de questionnaire personnalisées, avec consentement et branchements conditionnels.

Potato 2.0 prend en charge des flux de travail d'annotation structurés en plusieurs phases successives : consentement, questionnaire de pré-étude, consignes, formation, annotation et retours de post-étude.

Un flux de travail d'annotation avec questionnaires

Phases disponibles

Phase	Description
`consent`	Recueil du consentement éclairé
`prestudy`	Questionnaires avant annotation (données sociodémographiques, sélection)
`instructions`	Consignes et informations sur la tâche
`training`	Questions d'exercice avec retour
`annotation`	Tâche d'annotation principale (toujours obligatoire)
`poststudy`	Questionnaires et retours après annotation

Configuration de base

Utilisez la section phases de votre configuration :

yaml

phases:
  consent:
    enabled: true
    data_file: "data/consent.json"
 
  prestudy:
    enabled: true
    data_file: "data/demographics.json"
 
  instructions:
    enabled: true
    content: "data/instructions.html"
 
  training:
    enabled: true
    data_file: "data/training.json"
    schema_name: sentiment
    passing_criteria:
      min_correct: 8
 
  # annotation phase is always enabled
 
  poststudy:
    enabled: true
    data_file: "data/feedback.json"

Types de questions

Les phases de questionnaire acceptent les types de questions suivants :

Radio (choix unique)

json

{
  "name": "experience",
  "type": "radio",
  "description": "How much annotation experience do you have?",
  "labels": ["None", "Some (< 10 hours)", "Moderate", "Extensive"],
  "required": true
}

Cases à cocher / choix multiple

json

{
  "name": "languages",
  "type": "checkbox",
  "description": "What languages do you speak fluently?",
  "labels": ["English", "Spanish", "French", "German", "Chinese", "Other"]
}

Saisie de texte

json

{
  "name": "occupation",
  "type": "text",
  "description": "What is your occupation?",
  "required": true
}

Saisie numérique

json

{
  "name": "years_experience",
  "type": "number",
  "description": "Years of professional experience",
  "min": 0,
  "max": 50
}

Échelle de Likert

json

{
  "name": "familiarity",
  "type": "likert",
  "description": "How familiar are you with this topic?",
  "size": 5,
  "min_label": "Not familiar",
  "max_label": "Very familiar"
}

Liste déroulante

json

{
  "name": "country",
  "type": "select",
  "description": "Select your country",
  "labels": ["USA", "Canada", "UK", "Germany", "France", "Other"]
}

Phase de consentement

Recueillez le consentement éclairé avant de commencer :

yaml

phases:
  consent:
    enabled: true
    data_file: "data/consent.json"

consent.json :

json

[
  {
    "name": "consent_agreement",
    "type": "radio",
    "description": "I have read and understood the research consent form and agree to participate.",
    "labels": ["I agree", "I do not agree"],
    "right_label": "I agree",
    "required": true
  }
]

Le champ right_label indique la réponse attendue pour pouvoir continuer.

Questionnaires de pré-étude

Recueillez des données sociodémographiques ou des questions de sélection :

yaml

phases:
  prestudy:
    enabled: true
    data_file: "data/demographics.json"

demographics.json :

json

[
  {
    "name": "age_range",
    "type": "radio",
    "description": "What is your age range?",
    "labels": ["18-24", "25-34", "35-44", "45-54", "55+"],
    "required": true
  },
  {
    "name": "education",
    "type": "radio",
    "description": "Highest level of education completed",
    "labels": ["High school", "Bachelor's degree", "Master's degree", "Doctoral degree", "Other"],
    "required": true
  },
  {
    "name": "english_native",
    "type": "radio",
    "description": "Is English your native language?",
    "labels": ["Yes", "No"],
    "required": true
  }
]

Phase de consignes

Affichez les consignes de la tâche :

yaml

phases:
  instructions:
    enabled: true
    content: "data/instructions.html"

Ou passez le contenu en ligne :

yaml

phases:
  instructions:
    enabled: true
    inline_content: |
      <h2>Task Instructions</h2>
      <p>In this task, you will classify the sentiment of product reviews.</p>
      <ul>
        <li><strong>Positive:</strong> Expresses satisfaction or praise</li>
        <li><strong>Negative:</strong> Expresses dissatisfaction or criticism</li>
        <li><strong>Neutral:</strong> Factual or mixed sentiment</li>
      </ul>

Phase de formation

Des questions d'exercice avec retour (voir Phase de formation pour le détail) :

yaml

phases:
  training:
    enabled: true
    data_file: "data/training.json"
    schema_name: sentiment
    passing_criteria:
      min_correct: 8
      total_questions: 10
    show_explanations: true

Questionnaires de post-étude

Recueillez des retours après l'annotation :

yaml

phases:
  poststudy:
    enabled: true
    data_file: "data/feedback.json"

feedback.json :

json

[
  {
    "name": "difficulty",
    "type": "likert",
    "description": "How difficult was this task?",
    "size": 5,
    "min_label": "Very easy",
    "max_label": "Very difficult"
  },
  {
    "name": "clarity",
    "type": "likert",
    "description": "How clear were the instructions?",
    "size": 5,
    "min_label": "Very unclear",
    "max_label": "Very clear"
  },
  {
    "name": "suggestions",
    "type": "text",
    "description": "Any suggestions for improvement?",
    "textarea": true,
    "required": false
  }
]

Modèles intégrés

Potato fournit des jeux d'étiquettes prédéfinis pour les questions de questionnaire courantes :

Modèle	Étiquettes
`countries`	Liste de pays
`languages`	Langues courantes
`ethnicity`	Options d'origine ethnique
`religion`	Options de religion

Pour utiliser un modèle dans une question :

json

{
  "name": "country",
  "type": "select",
  "description": "Select your country",
  "template": "countries"
}

Champs de réponse libre

Ajoutez une saisie de texte facultative à côté des questions structurées :

json

{
  "name": "topics",
  "type": "checkbox",
  "description": "Which topics interest you?",
  "labels": ["Technology", "Sports", "Politics", "Entertainment"],
  "free_response": true,
  "free_response_label": "Other (please specify)"
}

En-têtes de page

Personnalisez les en-têtes de section du questionnaire :

json

{
  "page_header": "Demographics Survey",
  "questions": [
    {"name": "age", "type": "radio", ...},
    {"name": "gender", "type": "radio", ...}
  ]
}

Exemple complet

yaml

task_name: "Sentiment Analysis Study"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/reviews.json"
 
item_properties:
  id_key: id
  text_key: text
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this review?"
    labels:
      - Positive
      - Negative
      - Neutral
    sequential_key_binding: true
 
# Multi-phase workflow
phases:
  consent:
 
  prestudy:
 
  instructions:
 
  training:
 
  # annotation phase is always enabled
 
  poststudy:
 
# Output
output_annotation_dir: "output/"
output_annotation_format: "json"
 
# User access
allow_all_users: true

Ancienne configuration

L'ancien format de configuration surveyflow reste pris en charge pour la compatibilité ascendante :

yaml

surveyflow:
  enabled: true
  phases:
    - name: pre_survey
      type: survey
      questions: survey_questions.json
    - name: main_annotation
      type: annotation

Nous recommandons cependant de passer au nouveau format phases pour les nouveaux projets.

Bonnes pratiques

1. Gardez les questionnaires courts

Un questionnaire long fait chuter le taux d'achèvement. Ne posez que les questions indispensables.

2. Prévoyez une formation pour les tâches complexes

Les phases de formation améliorent la qualité de l'annotation, surtout sur les tâches qui demandent de la nuance.

3. Fixez des critères de réussite raisonnables

yaml

# Too strict - may exclude good annotators
passing_criteria:
  require_all_correct: true
 
# Better - allows for learning
passing_criteria:
  min_correct: 8
  total_questions: 10

4. Donnez des consignes claires

Mettez des exemples dans votre phase de consignes pour lever les ambiguïtés.

5. Testez le parcours complet

Faites vous-même tout le flux de travail avant le déploiement, pour repérer les problèmes.

6. Utilisez les champs obligatoires avec discernement

Ne marquez une question comme obligatoire que si elle est indispensable : les questions facultatives obtiennent des réponses de meilleure qualité.

Intégration au crowdsourcing

Pour Prolific ou MTurk, configurez les codes de complétion :

yaml

phases:
  poststudy:
    enabled: true
    data_file: "data/feedback.json"
    show_completion_code: true
    completion_code_format: "POTATO-{user_id}-{timestamp}"

Voir Crowdsourcing pour plus de détails.