Flujos de Trabajo Multifase

Potato ejecuta la tarea de anotación como una fase dentro de un flujo de trabajo más largo, de modo que el consentimiento, las preguntas de selección, las instrucciones, el entrenamiento y una encuesta de salida pueden rodearla sin una herramienta de encuestas aparte.

Un flujo de trabajo de anotación tipo encuesta

Fases Disponibles

Los anotadores recorren las fases habilitadas en el orden que declares.

Configuración Básica

El bloque phases define el orden y apunta cada fase a su archivo:

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

La fase annotation no necesita file, porque usa los annotation_schemes de nivel superior del proyecto.

Tipos de Fase

Cada fase basada en un archivo declara un type que indica qué etapa del flujo de trabajo es. Los valores válidos son consent, prestudy, instructions, training, annotation y poststudy.

Define type de forma explícita. Potato solo lo infiere cuando el nombre de la fase es una de esas palabras, así que una fase con un nombre personalizado tiene que declararlo:

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

Navegación hacia Atrás

El botón Back se oculta cuando no hay una página anterior, lo que incluye la primera instancia de anotación. Para que los anotadores puedan retroceder cruzando los límites entre fases:

allow_phase_back_navigation: true

Con esta opción desactivada, los anotadores aún pueden retroceder dentro de una fase, por ejemplo entre instancias de anotación.

Formato de las Preguntas de Encuesta

Las fases de encuesta leen un array JSON. Cada pregunta lleva un id, el text que ve el anotador, un schema que nombra el widget y sus 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 Esquema Compatibles

radio para una sola opción, checkbox o multiselect para varias, text para texto libre, number para entrada numérica, likert para una escala de valoración y select para un menú desplegable.

Requisitos de Etiqueta

label_requirement decide qué respuestas permiten al 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 enumera las respuestas aceptables y required indica si la pregunta debe responderse obligatoriamente. Una pregunta de consentimiento que nadie puede fallar no registra nada, así que pon la respuesta aceptable en right_label en lugar de confiar en la redacción.

Preguntas de Preselección

La preselección se ejecuta antes de la tarea principal, y es donde van las preguntas de elegibilidad y 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}
  }
]

Encuestas Posteriores al Estudio

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 Etiquetas Incorporados

Potato incluye conjuntos de etiquetas para las preguntas que se repiten en la mayoría de los estudios, así que no hace falta pegar una lista de países en la configuración:

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

Los conjuntos disponibles son country, language, ethnicity y religion.

Campos de Respuesta Libre

Añade un cuadro de texto opcional a cualquier pregunta con has_free_response, que es lo que necesita una opción "Otro" para que valga la pena ofrecerla:

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

Encabezados de Página

El encabezado de una página de encuesta se define en la fase y no en el archivo de preguntas:

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

Preguntas Condicionales

Las preguntas de encuesta pueden aparecer según respuestas anteriores, de modo que una pregunta de seguimiento solo se hace cuando corresponde. Como las preguntas de encuesta pasan por el mismo proceso que los esquemas de anotación, una condición hace referencia a otra pregunta por su 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"}
      ]
    }
  }
]

Una pregunta oculta queda excluida de la validación de campos obligatorios, así que nunca bloquea el botón Continue mientras no se muestra.

Conviene conocer tres comportamientos. Una condición puede hacer referencia a una pregunta de cualquier fase, de modo que una pregunta posterior al estudio puede depender de una respuesta previa al estudio. Un display_logic no válido, como un operador desconocido o una referencia a una pregunta que no existe en ninguna parte, falla al arrancar el servidor y no en tiempo de ejecución. Y una fase instructions que apunta a un archivo .html sin procesar se salta el proceso de esquemas, así que las condiciones no se aplican allí.

Con export_include_phase_data: true, Potato vuelve a evaluar en el servidor las respuestas de cada participante y omite las respuestas a preguntas que nunca vio. Consulta Lógica Condicional para la referencia completa de operadores.

Ejemplo 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

La fase de entrenamiento toma su configuración del bloque training de nivel superior, mientras que la entrada en phases solo la sitúa en el orden. Consulta Fase de Entrenamiento para los criterios de aprobación y el formato de datos.

Configuración Heredada

El antiguo bloque surveyflow sigue funcionando y lee las páginas de encuesta como listas de archivos .jsonl:

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

Migración

Mejores Prácticas

Mantén las Encuestas Breves

Cada pregunta adicional reduce la tasa de finalización, y las preguntas demográficas que no se usan en ningún análisis la reducen a cambio de nada.

Prueba el Flujo Completo

Completa tú mismo el flujo de trabajo, en un navegador sin sesión, antes de enviar el enlace a nadie. El consentimiento y el inicio de sesión son los dos puntos donde un flujo defectuoso falla primero y de forma más silenciosa.

Marca los Campos Obligatorios con Cuidado

Las preguntas obligatorias que podrían haber sido opcionales producen respuestas inventadas para poder pasar de página.

Crowdsourcing

Los códigos de finalización se configuran con la clave de nivel superior completion_code, no en la fase posterior al estudio:

completion_code: "POTATO2024"
auto_redirect_on_completion: true
auto_redirect_delay: 5000

Consulta Crowdsourcing para la configuración de la plataforma.

Lectura Adicional

• Fase de Entrenamiento - Cualificación con retroalimentación
• Crowdsourcing - Prolific, SONA y otros paneles
• Gestión de Usuarios - Listas de acceso y roles
• Flujo del experimento - Condiciones, exclusiones y páginas contrabalanceadas
• Importación de encuestas - Cuestionarios de Qualtrics, REDCap, XLSForm y otras herramientas

Para detalles de implementación, consulta la documentación fuente.