Fluxos de trabalho multifásicos

O Potato executa a tarefa de anotação como uma fase de um fluxo de trabalho mais longo. Assim, consentimento, perguntas de triagem, instruções, treinamento e uma pesquisa de saída podem ficar ao redor dela sem uma ferramenta de pesquisa separada.

Um fluxo de anotação no estilo de pesquisa

Fases disponíveis

Os anotadores passam pelas fases habilitadas na ordem que você declarar.

Configuração básica

O bloco phases lista a ordem e aponta cada fase para o seu arquivo:

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

A fase annotation não precisa de file, porque usa os annotation_schemes de nível superior do projeto.

Tipos de fase

Cada fase baseada em arquivo declara um type que diz qual etapa do fluxo ela é. Os valores válidos são consent, prestudy, instructions, training, annotation e poststudy.

Defina type explicitamente. O Potato só o infere quando o nome da fase é ele próprio uma dessas palavras, então uma fase com nome personalizado precisa declarar um:

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

Navegação para trás

O botão Back fica oculto quando não há página anterior, o que inclui a primeira instância de anotação. Para permitir que os anotadores voltem atravessando os limites entre fases:

allow_phase_back_navigation: true

Com a opção desligada, os anotadores ainda podem voltar dentro de uma fase, por exemplo entre instâncias de anotação.

Formato das perguntas de pesquisa

As fases de pesquisa leem um array JSON. Cada pergunta traz um id, o text mostrado ao anotador, um schema que nomeia o widget e suas 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"]}
  }
]

Tipos de schema suportados

radio para uma escolha, checkbox ou multiselect para várias, text para texto livre, number para entrada numérica, likert para uma escala de avaliação e select para uma lista suspensa.

Requisitos de resposta

label_requirement decide quais respostas deixam o anotador continuar:

{
  "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 lista as respostas aceitáveis e required diz se a pergunta precisa ser respondida. Uma pergunta de consentimento em que ninguém pode falhar não registra nada, então coloque a resposta aceitável em right_label em vez de depender da redação.

Perguntas de triagem

A triagem acontece antes da tarefa principal, e é nela que ficam as perguntas de elegibilidade e de perfil:

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

Pesquisas pós-estudo

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

Conjuntos de rótulos integrados

O Potato traz conjuntos de rótulos para as perguntas que a maioria dos estudos repete, para que uma lista de países não precise ser colada na configuração:

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

Os conjuntos disponíveis são country, language, ethnicity e religion.

Campos de resposta livre

Adicione uma caixa de texto opcional a qualquer pergunta com has_free_response. É isso que faz valer a pena oferecer uma opção "Outro":

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

Cabeçalhos de página

O cabeçalho de uma página de pesquisa é definido na fase, e não no arquivo de perguntas:

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

Perguntas condicionais

Perguntas de pesquisa podem aparecer com base em respostas anteriores, de modo que uma pergunta de acompanhamento só é feita quando se aplica. Como as perguntas de pesquisa passam pelo mesmo pipeline dos esquemas de anotação, uma condição referencia outra pergunta pelo seu 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"}
      ]
    }
  }
]

Uma pergunta oculta fica fora da validação de campos obrigatórios, então nunca bloqueia o botão Continue enquanto não está visível.

Vale conhecer três comportamentos. Uma condição pode referenciar uma pergunta de qualquer fase, então uma pergunta pós-estudo pode depender de uma resposta do pré-estudo. Um display_logic inválido, como um operador desconhecido ou uma referência a uma pergunta que não existe em lugar nenhum, falha na inicialização do servidor e não em tempo de execução. E uma fase instructions que aponta para um arquivo .html bruto contorna o pipeline de esquemas, então as condições não se aplicam ali.

Com export_include_phase_data: true, o Potato reavalia no servidor as respostas de cada participante e deixa de fora as respostas a perguntas que ele nunca viu. Consulte Lógica condicional para a referência completa de operadores.

Exemplo 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

A fase de treinamento recebe suas configurações do bloco training de nível superior, enquanto a entrada em phases apenas a posiciona na ordem. Consulte Fase de treinamento para os critérios de aprovação e o formato dos dados.

Configuração legada

O antigo bloco surveyflow ainda funciona e lê as páginas de pesquisa como listas de arquivos .jsonl:

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

Migração

Boas práticas

Mantenha as pesquisas curtas

Cada pergunta extra custa taxa de conclusão, e perguntas demográficas que a análise não usa custam isso sem retorno algum.

Teste o fluxo inteiro

Conclua o fluxo de trabalho você mesmo, em um navegador sem sessão, antes de enviar o link a qualquer pessoa. Consentimento e login são os dois pontos em que um fluxo com defeito falha primeiro e de forma mais silenciosa.

Marque campos obrigatórios com cuidado

Perguntas obrigatórias que poderiam ser opcionais produzem respostas inventadas só para passar da página.

Crowdsourcing

Os códigos de conclusão são configurados com a chave de nível superior completion_code, e não na fase pós-estudo:

completion_code: "POTATO2024"
auto_redirect_on_completion: true
auto_redirect_delay: 5000

Consulte Crowdsourcing para a configuração das plataformas.

Leitura adicional

• Fase de treinamento: qualificação com feedback
• Crowdsourcing: integração com Prolific e MTurk
• Gerenciamento de usuários: listas de acesso e papéis

Para detalhes de implementação, consulte a documentação-fonte.