Mehrphasige Workflows

Potato führt die Annotationsaufgabe als eine Phase in einem längeren Workflow aus. Einwilligung, Screening-Fragen, Anweisungen, Training und eine Abschlussbefragung lassen sich so ohne separates Umfragetool um sie herum anordnen.

Ein Survey-Flow-Annotationsworkflow

Verfügbare Phasen

Annotatoren durchlaufen die aktivierten Phasen in der Reihenfolge, die Sie festlegen.

Grundkonfiguration

Der Block phases legt die Reihenfolge fest und verweist jede Phase auf ihre Datei:

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

Die Phase annotation braucht kein file, weil sie die annotation_schemes auf oberster Ebene des Projekts verwendet.

Phasentypen

Jede dateibasierte Phase deklariert einen type, der angibt, welche Stufe des Workflows sie ist. Gültige Werte sind consent, prestudy, instructions, training, annotation und poststudy.

Geben Sie type explizit an. Potato leitet ihn nur ab, wenn der Name der Phase selbst eines dieser Wörter ist. Eine Phase mit eigenem Namen muss ihn daher deklarieren:

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

Zurücknavigation

Die Schaltfläche Back ist ausgeblendet, wenn es keine vorherige Seite gibt, also auch bei der ersten Annotationsinstanz. Damit Annotatoren über Phasengrenzen hinweg zurückgehen können:

allow_phase_back_navigation: true

Ist die Option ausgeschaltet, können Annotatoren innerhalb einer Phase weiterhin zurückgehen, etwa zwischen Annotationsinstanzen.

Format der Umfragefragen

Umfragephasen lesen ein JSON-Array. Jede Frage hat eine id, den text, der dem Annotator angezeigt wird, ein schema, das das Widget benennt, und ihre 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"]}
  }
]

Unterstützte Schematypen

radio für eine Auswahl, checkbox oder multiselect für mehrere, text für Freitext, number für Zahleneingaben, likert für eine Bewertungsskala und select für ein Dropdown.

Antwortanforderungen

label_requirement legt fest, mit welchen Antworten der Annotator fortfahren kann:

{
  "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 listet die zulässigen Antworten auf, und required gibt an, ob die Frage überhaupt beantwortet werden muss. Eine Einwilligungsfrage, bei der niemand scheitern kann, hält nichts fest. Tragen Sie die zulässige Antwort deshalb in right_label ein, statt sich auf die Formulierung zu verlassen.

Screening-Fragen

Das Screening läuft vor der Hauptaufgabe. Dorthin gehören Fragen zur Eignung und zum Hintergrund:

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

Abschlussbefragungen

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

Eingebaute Label-Sätze

Potato liefert Label-Sätze für die Fragen mit, die in den meisten Studien wiederkehren, sodass keine Länderliste in die Konfiguration kopiert werden muss:

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

Verfügbar sind country, language, ethnicity und religion.

Freitextfelder

Mit has_free_response fügen Sie jeder Frage ein optionales Textfeld hinzu. Erst damit lohnt es sich, eine Option „Sonstiges“ anzubieten:

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

Seitenüberschriften

Die Überschrift einer Umfrageseite wird an der Phase festgelegt, nicht in der Fragendatei:

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

Bedingte Fragen

Umfragefragen können abhängig von früheren Antworten erscheinen, sodass eine Folgefrage nur gestellt wird, wenn sie zutrifft. Da Umfragefragen dieselbe Pipeline durchlaufen wie Annotationsschemata, verweist eine Bedingung über deren name auf eine andere Frage:

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

Eine ausgeblendete Frage ist von der Pflichtfeldprüfung ausgenommen und blockiert die Schaltfläche Continue daher nie, solange sie nicht angezeigt wird.

Drei Verhaltensweisen sollten Sie kennen. Eine Bedingung kann auf eine Frage in jeder Phase verweisen, sodass eine Frage der Abschlussbefragung von einer Antwort aus der Vorerhebung abhängen kann. Ungültige display_logic, etwa ein unbekannter Operator oder ein Verweis auf eine Frage, die nirgends existiert, schlägt beim Serverstart fehl und nicht erst zur Laufzeit. Und eine instructions-Phase, die auf eine reine .html-Datei zeigt, umgeht die Schema-Pipeline, weshalb Bedingungen dort nicht greifen.

Mit export_include_phase_data: true wertet Potato die Antworten jedes Teilnehmenden serverseitig erneut aus und lässt Antworten auf Fragen weg, die die Person nie gesehen hat. Die vollständige Operatorenreferenz finden Sie unter Bedingte Logik.

Vollständiges Beispiel

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

Die Trainingsphase bezieht ihre Einstellungen aus dem Block training auf oberster Ebene, während der Eintrag unter phases sie nur in die Reihenfolge einordnet. Bestehenskriterien und Datenformat beschreibt Trainingsphase.

Legacy-Konfiguration

Der ältere Block surveyflow funktioniert weiterhin und liest Umfrageseiten als Listen von .jsonl-Dateien:

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

Migration

Bewährte Vorgehensweisen

Umfragen kurz halten

Jede zusätzliche Frage kostet Abschlussrate, und demografische Fragen, die in der Analyse nicht vorkommen, kosten sie ohne Gegenwert.

Den gesamten Ablauf testen

Durchlaufen Sie den Workflow selbst, in einem Browser ohne Sitzung, bevor Sie den Link verschicken. Einwilligung und Anmeldung sind die beiden Stellen, an denen ein fehlerhafter Workflow zuerst und am unauffälligsten scheitert.

Pflichtfelder mit Bedacht festlegen

Pflichtfragen, die auch optional hätten sein können, erzeugen Antworten, die sich Teilnehmende ausdenken, um über die Seite hinwegzukommen.

Crowdsourcing

Abschlusscodes werden über den Schlüssel completion_code auf oberster Ebene konfiguriert, nicht an der Phase der Abschlussbefragung:

completion_code: "POTATO2024"
auto_redirect_on_completion: true
auto_redirect_delay: 5000

Die Einrichtung der Plattformen beschreibt Crowdsourcing.

Weiterführende Informationen

• Trainingsphase: Qualifikation mit Feedback
• Crowdsourcing: Prolific, SONA und andere Panels
• Benutzerverwaltung: Zugriffslisten und Rollen
• Experimentablauf - Bedingungen, Screen-outs und ausbalancierte Seitenreihenfolge
• Umfrageimport - Fragebögen aus Qualtrics, REDCap, XLSForm und anderen Tools

Implementierungsdetails finden Sie in der Quelldokumentation.