Skip to content
Guides9 min read

Executando estudos de anotação no Prolific

Execute um estudo de anotação do Potato no Prolific com login direto pela URL, código de conclusão, verificações de atenção e monitoramento de envios pela API.

Potato Team

Aponte a URL do estudo no Prolific para o seu servidor do Potato com ?PROLIFIC_PID={{%PROLIFIC_PID%}}, defina login.type: url_direct e um completion_code igual ao código do estudo, e cada participante entra com o próprio ID do Prolific e é enviado de volta ao Prolific ao terminar.

O Prolific é um grupo de participantes criado para estudos acadêmicos, e é a plataforma de crowdsourcing que o Potato suporta de forma mais completa. Este guia cobre a configuração de que o Potato precisa, os ajustes do estudo no lado do Prolific e o controle de qualidade que vale a pena ter pronto antes de gastar dinheiro.

Por que pesquisadores usam o Prolific para anotação

O Prolific faz a triagem dos participantes e os paga pela própria plataforma, então as partes do crowdsourcing que costumam consumir o orçamento de um estudo ficam fora do seu servidor. Ele exige um valor mínimo por hora, filtra participantes por critérios demográficos e de idioma e registra o consentimento, o que encurta a papelada do comitê de ética (IRB) para um estudo de rotulagem. A contrapartida é o custo por resposta em comparação com o Mechanical Turk, e o guia de implantação no MTurk cobre essa plataforma se você precisar dela.

O que você precisa antes de começar

  1. Uma conta de pesquisador no Prolific.
  2. O Potato rodando em um servidor com uma URL HTTPS pública. O guia de implantação em servidor cobre essa etapa.
  3. Uma configuração com seus arquivos de dados, item_properties e pelo menos um esquema de anotação.

A configuração de que o Potato precisa

Quatro ajustes transformam um projeto comum do Potato em um que o Prolific consegue conduzir. login.url_argument nomeia o parâmetro de URL que traz o ID do Prolific do participante, completion_code precisa corresponder a um código configurado no estudo do Prolific, e as duas chaves de redirecionamento mandam os participantes de volta ao Prolific em vez de deixá-los em uma página de encerramento. As chaves de atribuição logo abaixo limitam quanto trabalho cada participante recebe, e é isso que mantém o custo de um estudo previsível.

yaml
annotation_task_name: "Sentiment Annotation Study"
task_description: "Classify the sentiment of short text snippets. This task takes about five minutes."
 
# Participants are logged in from the PROLIFIC_PID URL parameter
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
# Must match a completion code configured on the Prolific study
completion_code: "C1ABCDEF"
auto_redirect_on_completion: true
auto_redirect_delay: 5000
 
# Keep participants on task
hide_navbar: true
jumping_to_id_disabled: true
 
# Each participant labels 20 items; each item is labeled by 3 participants
assignment_strategy: random
max_annotations_per_user: 20
num_annotators_per_item: 3
 
data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: text
 
output_annotation_dir: annotation_output/prolific-study/
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true
  users: []
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment expressed in this text?"
    labels:
      - name: positive
      - name: neutral
      - name: negative
    sequential_key_binding: true
    label_requirement:
      required: true

Defina num_annotators_per_item de acordo com o que você pretende fazer com os dados. Três é a escolha habitual quando você vai reportar concordância ou usar o rótulo da maioria, e um basta depois que um piloto mostrou que a tarefa está bem definida. O guia de concordância entre anotadores explica como ler o resultado.

Configurando o estudo no Prolific

No formulário do estudo no Prolific, defina a URL externa do estudo como o seu servidor do Potato, com os marcadores do Prolific na query string:

text
https://your-server.com/?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}

Escolha "I'll use URL parameters" na pergunta sobre como os IDs do Prolific são registrados e depois configure no estudo um código de conclusão igual ao completion_code da sua configuração. STUDY_ID e SESSION_ID são gravados na sessão do participante para acompanhamento posterior.

Um participante que clica no link chega ao Potato com o próprio ID na URL. O Potato cria uma conta sem senha com esse ID, conduz o participante pelas fases que você configurou e, ao final, mostra o código de conclusão com um botão Return to Prolific que aponta para https://app.prolific.com/submissions/complete?cc=<code>. Com auto_redirect_on_completion definido, o redirecionamento acontece sozinho depois de auto_redirect_delay milissegundos.

Escreva o domínio como app.prolific.com. O domínio antigo app.prolific.co não serve mais HTTPS, então uma URL de conclusão copiada de um guia antigo manda os participantes para uma página morta depois que eles fizeram o trabalho.

Consentimento, instruções e questionários de saída

A maioria dos estudos de crowdsourcing precisa de mais do que a página de anotação. O bloco phases do Potato coloca consentimento, triagem, instruções e um questionário pós-estudo em torno da fase de anotação, e os participantes passam por eles na ordem em que você os lista:

yaml
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

Adicione este bloco à configuração acima. A fase annotation é a única obrigatória, então um estudo que não precisa de formulário de consentimento pode deixar de fora todas as outras entradas. Projetos mais antigos configuram a mesma coisa por meio de surveyflow, que o Potato ainda lê mas não recomenda mais para projetos novos.

Verificações de atenção

Uma verificação de atenção é um item com resposta correta conhecida, misturado à fila para que um participante desatento produza uma resposta errada detectável. O Potato carrega essas verificações de um arquivo próprio, e não dos seus dados, então elas ficam fora do seu dataset:

yaml
attention_checks:
  enabled: true
  items_file: "data/attention_checks.json"
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    block_threshold: 5

Adicione este bloco à configuração acima. frequency: 10 insere uma verificação a cada dez itens, e min_response_time reprova uma resposta que chega mais rápido do que qualquer pessoa conseguiria ler o item, seja qual for o conteúdo dela. O relógio roda no servidor, do momento em que ele enviou o item ao momento em que recebeu o salvamento.

Cada item de verificação traz um id, o texto que o participante vê e a resposta esperada para cada esquema, por nome:

json
[
  {
    "id": "attn_001",
    "text": "Please select 'positive' for this item to verify you are reading carefully.",
    "expected_answer": {"sentiment": "positive"}
  }
]

Ajuste block_threshold ao tamanho do seu estudo. Um participante que falha em cinco verificações em uma tarefa de 20 itens nunca estava anotando; um que falha em cinco ao longo de 300 itens pode ter ficado cansado por um trecho, e bloqueá-lo faz você perder o resto do trabalho dele.

Monitorando um estudo em andamento

Defina login.type: prolific e adicione um bloco prolific, e o Potato consulta a API do Prolific para saber o status dos envios, além do login direto pela URL que ele já faz:

yaml
login:
  type: prolific
  url_argument: PROLIFIC_PID
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "C1ABCDEF"

Adicione este bloco à configuração acima. O arquivo para o qual ele aponta guarda o token da API, então mantenha-o fora do controle de versão:

yaml
# configs/prolific_config.yaml
token: "your-prolific-api-token"
study_id: "your-study-id"
workload_checker: true
max_concurrent_sessions: 30
workload_checker_period: 300

Com o token configurado, o painel de administração ganha um painel do Prolific que publica, pausa e encerra o estudo, aprova ou rejeita envios, paga bônus e mostra antes o custo de adicionar vagas. O monitor de carga pausa o estudo quando os participantes ativos chegam a max_concurrent_sessions e o retoma quando a contagem cai abaixo de 20% desse máximo. Ele só retoma um estudo que ele mesmo pausou, então um estudo que você pausa manualmente no Prolific continua pausado.

Participantes que desistem

O Prolific marca um envio como RETURNED, TIMED-OUT ou REJECTED quando um participante sai sem terminar. O Potato libera os itens atribuídos a esses participantes para que outras pessoas possam pegá-los, e mantém as anotações que eles já tinham concluído. Use instance_reclaim quando o motivo deve mudar o que acontece com esse trabalho concluído:

yaml
instance_reclaim:
  enabled: true
  prolific:
    preserve_completed_annotations: true
    status_policies:
      TIMED-OUT:
        preserve_completed_annotations: true
      REJECTED:
        preserve_completed_annotations: false

Adicione este bloco à configuração acima. Vale a pena definir essa distinção de propósito. Um participante que estourou o tempo geralmente anotou com honestidade até algo interrompê-lo, enquanto um rejeitado produziu um trabalho que você decidiu não pagar, e mantê-lo no dataset contradiz a rejeição.

O que a saída contém

O Potato grava arquivos por anotador em output_annotation_dir e, quando export_annotation_format está definido, uma exportação periódica em <output_annotation_dir>/exports/<format>/. Cada registro exportado traz a instância, o anotador e os rótulos por nome de esquema:

json
{"instance_id": "t_014", "user_id": "5f2c9a1b3d4e5f6a7b8c9d0e", "labels": {"sentiment": {"positive": "positive"}}, "spans": {}, "links": {}}

O user_id é o ID do Prolific do participante, porque esse é o nome de usuário com que o Potato o criou, e é isso que permite relacionar uma linha a um envio do Prolific para aprovação ou bônus. Trate essa coluna como dado identificável ao publicar o dataset.

Fazendo um piloto primeiro

Rode de 5 a 10 participantes antes de lançar o estudo completo e leia a saída deles, em vez de olhar só a taxa de conclusão. Duas falhas saem caras se descobertas depois. A primeira é uma instrução ambígua de um jeito que você não enxerga porque foi você quem escreveu a tarefa, e a segunda é um tempo por item muito distante da sua estimativa, o que significa que o seu valor de pagamento está errado para um lado ou para o outro.

Defina o preço do estudo pela mediana de tempo do piloto, e não pela sua. Mantenha a interface usável na largura de um celular, porque alguns participantes estarão em um celular, diga o que disser a descrição do estudo. Aprove os envios rapidamente, porque as pessoas estão esperando o dinheiro e porque o seu tempo de aprovação fica visível para futuros participantes que decidem se aceitam o seu estudo.

Próximos passos

A referência completa está em Integração com crowdsourcing neste site, e a documentação da integração com o Prolific no repositório do Potato cobre os endpoints da API de administração por trás do painel. Comece por ali se você precisa criar estudos, sincronizar qualificações ou pagar screen-outs a partir do seu próprio código.