Skip to content
Guías9 min de lectura

Ejecución de estudios de anotación en Prolific

Ejecuta un estudio de anotación de Potato en Prolific con inicio de sesión directo por URL, código de finalización, verificaciones de atención y seguimiento de envíos a través de la API.

Potato Team

Apunta la URL del estudio de Prolific a tu servidor de Potato con ?PROLIFIC_PID={{%PROLIFIC_PID%}}, establece login.type: url_direct y un completion_code que coincida con el código del estudio, y cada participante inicia sesión con su propio ID de Prolific y vuelve a Prolific al terminar.

Prolific es un pool de participantes pensado para estudios académicos, y es la plataforma de crowdsourcing que Potato soporta de forma más completa. Esta guía cubre la configuración que necesita Potato, los ajustes del estudio en el lado de Prolific y el control de calidad que conviene tener listo antes de gastar dinero.

Por qué los investigadores usan Prolific para anotación

Prolific evalúa a sus participantes y les paga a través de la plataforma, de modo que las partes del crowdsourcing que suelen consumir el presupuesto de un estudio se gestionan fuera de tu servidor. Impone una tarifa mínima por hora, filtra a los participantes por criterios demográficos y de idioma, y registra el consentimiento, lo que reduce el papeleo del IRB para un estudio de etiquetado. Mechanical Turk, la comparación habitual, cerró el 30 de septiembre de 2026, y cómo trasladar un estudio fuera de MTurk explica el cambio para los estudios que se realizaban allí.

Qué necesitas antes de empezar

  1. Una cuenta de investigador en Prolific.
  2. Potato ejecutándose en un servidor con una URL HTTPS pública. La guía de despliegue en servidor cubre ese paso.
  3. Una configuración con tus archivos de datos, item_properties y al menos un esquema de anotación.

La configuración que necesita Potato

Cuatro ajustes convierten un proyecto normal de Potato en uno que Prolific puede dirigir. login.url_argument indica el parámetro de URL que lleva el ID de Prolific del participante, completion_code debe coincidir con un código configurado en el estudio de Prolific, y las dos claves de redirección devuelven a los participantes a Prolific en lugar de dejarlos en una página de fin. Las claves de asignación que siguen limitan cuánto trabajo recibe cada participante, y eso es lo que mantiene predecible el costo de un estudio.

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

Elige num_annotators_per_item según lo que pienses hacer con los datos. Tres es la opción habitual cuando vas a reportar acuerdo o tomar la etiqueta mayoritaria, y uno basta cuando un piloto ya ha mostrado que la tarea está bien definida. La guía de acuerdo entre anotadores explica cómo leer el resultado.

Configurar el estudio en Prolific

En el formulario del estudio de Prolific, establece como URL externa del estudio tu servidor de Potato con los marcadores de Prolific en la cadena de consulta:

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

Elige "I'll use URL parameters" en la pregunta sobre cómo se registran los IDs de Prolific y luego configura en el estudio un código de finalización que coincida con completion_code en tu configuración. STUDY_ID y SESSION_ID se guardan en la sesión del participante para su seguimiento posterior.

Un participante que hace clic en el enlace llega a Potato con su ID en la URL. Potato crea una cuenta sin contraseña con ese ID, guía al participante por las fases que hayas configurado y, al terminar, muestra el código de finalización con un botón Return to Prolific que enlaza a https://app.prolific.com/submissions/complete?cc=<code>. Con auto_redirect_on_completion activado, la redirección ocurre sola tras auto_redirect_delay milisegundos.

Escribe el dominio como app.prolific.com. El dominio antiguo app.prolific.co ya no sirve HTTPS, así que una URL de finalización copiada de una guía antigua envía a los participantes a una página muerta después de haber hecho el trabajo.

Consentimiento, instrucciones y encuestas de salida

La mayoría de los estudios con crowdsourcing necesitan algo más que la página de anotación. El bloque phases de Potato coloca el consentimiento, la preselección, las instrucciones y una encuesta posterior alrededor de la fase de anotación, y los participantes las recorren en el orden en que las enumeras:

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

Añade este bloque a la configuración anterior. La fase annotation es la única obligatoria, así que un estudio que no necesita formulario de consentimiento puede omitir todas las demás entradas. Los proyectos más antiguos configuran lo mismo mediante surveyflow, que Potato todavía lee pero ya no recomienda para proyectos nuevos.

Verificaciones de atención

Una verificación de atención es un ítem con una respuesta correcta conocida, mezclado en la cola para que un participante distraído produzca una respuesta incorrecta detectable. Potato las carga desde su propio archivo y no desde tus datos, de modo que las verificaciones quedan fuera de tu 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

Añade este bloque a la configuración anterior. frequency: 10 inserta una verificación cada diez ítems, y min_response_time da por fallida cualquier respuesta que llegue antes de lo que nadie tardaría en leer el ítem, diga lo que diga. El reloj corre en el servidor, desde que envió el ítem hasta que recibió el guardado.

Cada ítem de verificación lleva un id, el texto que ve el participante y la respuesta esperada para cada esquema por nombre:

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

Ajusta block_threshold a la duración de tu estudio. Un participante que falla cinco verificaciones en una tarea de 20 ítems nunca estuvo anotando; uno que falla cinco a lo largo de 300 ítems quizá estuvo cansado durante un tramo, y bloquearlo hace perder el resto de su trabajo.

Seguimiento de un estudio en curso

Establece login.type: prolific y añade un bloque prolific, y Potato consulta la API de Prolific para conocer el estado de los envíos, además del inicio de sesión directo por URL que ya realiza:

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

Añade este bloque a la configuración anterior. El archivo al que apunta contiene el token de la API, así que mantenlo fuera del control de versiones:

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

Con el token configurado, el panel de administración incorpora un panel de Prolific que publica, pausa y detiene el estudio, aprueba o rechaza envíos, paga bonificaciones y muestra por adelantado el costo de añadir plazas. El monitor de carga pausa el estudio cuando los participantes activos alcanzan max_concurrent_sessions y lo reanuda cuando el número baja del 20% de ese máximo. Solo reanuda un estudio que haya pausado él mismo, así que un estudio que pauses a mano en Prolific sigue pausado.

Participantes que abandonan

Prolific marca un envío como RETURNED, TIMED-OUT o REJECTED cuando un participante se va sin terminar. Potato libera los ítems asignados a esos participantes para que otras personas puedan tomarlos, y conserva las anotaciones que ya habían completado. Usa instance_reclaim cuando el motivo deba cambiar lo que ocurre con ese trabajo completado:

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

Añade este bloque a la configuración anterior. Conviene fijar esta distinción de forma deliberada. Un participante que agotó el tiempo normalmente anotó con honestidad hasta que algo lo interrumpió, mientras que uno rechazado produjo trabajo que decidiste no pagar, y mantenerlo en el dataset contradice el rechazo.

Qué contiene la salida

Potato escribe archivos por anotador en output_annotation_dir y, cuando export_annotation_format está definido, una exportación periódica en <output_annotation_dir>/exports/<format>/. Cada registro exportado lleva la instancia, el anotador y las etiquetas por nombre de esquema:

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

El user_id es el ID de Prolific del participante, porque ese es el nombre de usuario con el que Potato lo creó, y eso permite relacionar una fila con un envío de Prolific para aprobarlo o pagar una bonificación. Trata esa columna como dato identificativo cuando publiques el dataset.

Hacer primero un piloto

Ejecuta de 5 a 10 participantes antes de lanzar el estudio completo, y lee su salida en lugar de mirar solo su tasa de finalización. Hay dos fallos que salen caros si se descubren después. El primero es una instrucción ambigua de una forma que no ves porque tú escribiste la tarea, y el segundo es un tiempo por ítem muy distinto de tu estimación, lo que significa que tu tarifa de pago está mal en un sentido o en otro.

Calcula el precio del estudio a partir de la mediana de tiempo del piloto y no de la tuya. Mantén la interfaz usable en el ancho de un teléfono, porque algunos participantes estarán en un teléfono diga lo que diga la descripción del estudio. Aprueba los envíos rápido, porque hay personas esperando el dinero y porque tu tiempo de aprobación es visible para los futuros participantes que deciden si aceptar tu estudio.

Próximos pasos

La referencia completa está en Integración de crowdsourcing en este sitio, y la documentación de la integración con Prolific en el repositorio de Potato cubre los endpoints de la API de administración que hay detrás del panel. Empieza por ahí si necesitas crear estudios, sincronizar calificaciones o pagar screen-outs desde tu propio código.