Skip to content

Многофазные сценарии

Стройте многоэтапные сценарии разметки в Potato — сочетайте фазы обучения, задачи разметки и свои страницы опросов с формами согласия и условным ветвлением.

Potato 2.0 поддерживает структурированные сценарии разметки с несколькими последовательными фазами: согласие, опрос до исследования, инструкции, обучение, разметка и обратная связь после исследования.

A survey-flow annotation workflow — Sequential phases wrap the core annotation task; every phase but annotation is optionalA survey-flow annotation workflow

Доступные фазы

ФазаОписание
consentСбор информированного согласия
prestudyОпросы до разметки (демография, отбор участников)
instructionsИнструкции и сведения о задаче
trainingТренировочные вопросы с обратной связью
annotationОсновная задача разметки (обязательна всегда)
poststudyОпросы и обратная связь после разметки

Базовая конфигурация

Используйте в конфигурации секцию phases:

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"

Типы вопросов в опросах

Фазы опроса поддерживают такие типы вопросов:

Радиокнопки (одиночный выбор)

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

Флажки и мультивыбор

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

Ввод текста

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

Ввод числа

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

Шкала Лайкерта

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

Выпадающий список

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

Фаза согласия

Соберите информированное согласие до начала работы:

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

Поле right_label задаёт ответ, необходимый для продолжения.

Опросы до исследования

Соберите демографию или вопросы для отбора участников:

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

Фаза инструкций

Покажите инструкции к задаче:

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

Или задайте содержимое прямо в конфигурации:

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>

Фаза обучения

Тренировочные вопросы с обратной связью (подробности — в разделе Фаза обучения):

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

Опросы после исследования

Соберите обратную связь после разметки:

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

Встроенные шаблоны

В Potato входят готовые наборы меток для частых вопросов опроса:

ШаблонМетки
countriesСписок стран
languagesРаспространённые языки
ethnicityВарианты этнической принадлежности
religionВарианты вероисповедания

Используйте шаблоны в своих вопросах:

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

Поля свободного ответа

Добавьте необязательный ввод текста рядом со структурными вопросами:

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

Заголовки страниц

Настройте заголовки разделов опроса:

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

Полный пример

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

Устаревшая конфигурация

Более старый формат конфигурации surveyflow всё ещё поддерживается ради обратной совместимости:

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

Тем не менее для новых проектов мы рекомендуем перейти на формат phases.

Рекомендации

1. Держите опросы короткими

Длинные опросы снижают долю завершений. Оставьте только необходимые вопросы.

2. Используйте обучение для сложных задач

Фазы обучения улучшают качество разметки, особенно в задачах с оттенками.

3. Задавайте разумный порог прохождения

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. Пишите понятные инструкции

Добавьте в фазу инструкций примеры, чтобы прояснить ожидания.

5. Пройдите весь сценарий сами

Пройдите весь процесс целиком до запуска, чтобы поймать проблемы заранее.

6. Не злоупотребляйте обязательными полями

Помечайте вопрос обязательным, только если он действительно необходим: у необязательных вопросов качество ответов выше.

Интеграция с краудсорсингом

Для Prolific или MTurk настройте коды завершения:

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

Подробности — в разделе Краудсорсинг.