Cómo subir experimentos comportamentales a la web fácil y gratis con jsPsych y Cognition.run
Este es la segunda entrega de una serie de notas relacionadas a la creación de experimentos on line utilizando la biblioteca jsPsych en el lenguaje JavaScript.
Pueden ver la primera entrega acerca de como crear un primer experimento entrando a este link.
En la entrega anterior explicaba por qué considero la biblioteca jsPsych una excelente herramienta para construir experimentos online. Además de las razones estructurales que favorecen al lenguaje JavaScript en lo que respecta a la interacción con el navegador o browser, el hecho de que esté escrito en un lenguaje pensado para internet facilita la interacción con el back-end, es decir, la comunicación con el servidor y todo lo relacionado al manejo de los datos. En este sentido, si bien uno podría desarrollar esta capa oculta del proyecto desde el inicio (por ejemplo usando nodeJs en JavaScript o Django en Python), existen diferentes servicios en internet para evitarnos este proceso y poder enfocarnos en el desarrollo de nuestra tarea experimental. Dentro de este grupo encontramos plataformas como pavlovia, Gorilla o Jatos las cuales son masivamente utilizadas por investigadores de todas partes de mundo.
Este artículo surge de mi experiencia buscando un modo simple de subir un experimento que estaba armando. Gracias al canal de YouTube del creador de jsPsych (Josh de Leeuw), descubrí cognition.run, una alternativa de reciente aparición que viene a resolver todo el detrás de escena de nuestros experimentos de manera muy eficiente y de forma absolutamente gratuita.
Cognition.run es una plataforma creada por el desarrollador Javier Vidal Peña durante la pandemia para simplificar la labor de muchas personas que hacen ciencia alrededor del mundo y necesitan llevar sus experimentos a un formato web. Entre las ventajas de esta plataforma me parece necesario destacar su facilidad de uso, si uno ya tiene su experimento desarrollado en JavaScript utilizando la biblioteca jsPsych, es muy probable que pueda pegar su código y en cuestión de minutos tenerlo funcionando y listo para compartir.
Creando una cuenta en Cognition.run
Luego de ingresar a la página lo primero que tenemos que hacer para poder utilizar el servicio es registrarnos de manera muy sencilla presionando en create account y generando un usuario y contraseña.
Una vez que hayamos confirmado nuestro correo electrónico ya estamos listos para comenzar a utilizar la plataforma yendo a la sección Go to Tasks, allí nos encontraremos con una pantalla que nos permitirá crear nuevas tareas (+ New Task) o clonar alguna de las tareas de ejemplo que ya se encuentran cargadas un poco más abajo en Clone an example task.
Al presionar en el botón para la generación de una nueva tarea nos encontraremos con un campo para rellenar con el nombre que deseamos asignarle a la misma y presionando en configuración avanzada (Advanced configuration) accederemos a un menú desplegable el cual nos permitirá, como su nombre lo indica, tener un control más fino de algunos parámetros como el idioma de nuestra tarea o algunas cuestiones técnicas.
Creando nuestra tarea experimental
Una vez que hayamos realizado las configuraciones que deseemos, podremos presionar en save y seremos dirigidos al panel de control correspondiente a nuestra tarea. El mismo se divide en cuatro partes:
- Link — Se trata del vínculo a nuestra tarea. Lo interesante es que el mismo no cambiará, incluso aunque hagamos modificaciones en nuestro código. Esto resulta de mucha utilidad, ya que solo hace falta compartir ese enlace para que cualquier persona pueda realizar nuestro experimento.
- Design — Nos permite controlar detalladamente las características de nuestro experimento, la forma de mostrarlo y además generar un consentimiento informado para los voluntarios.
- Results — En este apartado vamos a tener acceso a toda la información recolectada durante el experimento.
- Danger zone — Un nombre tan simpático como adecuado, para advertirnos sobre el botón que nos permitirá borrar la tarea y todos los datos que la acompañan.
Sobre el primer y último de los recuadros no hay mucho para agregar, pero vamos a ver en detalle lo que nos ofrencen los otros dos.
Design
En esta sección nos encontramos con las siguientes opciones:
- Configuration — Nos lleva a la pantalla anterior que nos aparecía luego de crear una tarea nueva.
- Source code—Accedemos al editor de código, donde además de subir nuestro experimento hecho en jsPsych, vamos a poder subir los estímulos (si es que presentamos imágenes, sonidos, etc) y acceder a una vista previa del experimento funcionando. En breve explicaremos esto con mayor detalle.
- Informed consent — Se puede definir un consentimiento informado para el experimento. Permite el uso de markdowns para darle estilo.
Consejo personal sobre esta última sección: También podrían agregar ahí los requisito particulares que podría requerir la tarea experimental. Por ejemplo: Uso de computadora de escritorio en lugar de un celular, o de mouse en lugar de un trackpad, etc.
Results
Este apartado nos mostrará los datos obtenidos a partir de la realizaciones de nuestro experimento de la siguiente forma:
Inicialmente se nos presentarán dos opciones para descargarlos: Download CSV, que nos permitirá descargar los datos de todas las realizaciones en ese formato y Download all CSV que hace lo mismo pero solo para las realizaciones donde la persona haya terminado de realizar todo el experimento. Además veremos en pantalla la siguiente información:
- Id — Un código de identificación en orden ascendente para cada una de las veces que fue realizado nuestro experimento comenzando en 1.
- View — Nos permite acceder a más información sobre esa realización del experimento en particular.
- Date — Fecha y hora en formato [día] [mesAño] [horas:minutos:P.M/A.M].
- Status — Finished si la persona completó el experimento, Unfinished si no fue así.
- Download — Link para descargar esa realización del experimento en formato csv.
- Delete — Borra los datos de esa realización.
En particular, si presionamos en la opción view vamos a tener acceso a una pantalla con información de esa corrida del experimento. Incluyendo información del dispositivo del cual se conectó la persona, pre-visualización de los datos, entre otras cosas útiles para ir manteniendo el control a medida de que la gente va realizando nuestra tarea.
Editá tu código y visualizá tu experimento en tiempo real
Una de las maravillas de Cognition (ya se entendió que me encanta, no?) la encontramos al presionar en Source Code en la sección Design de la que ya hablamos. Al hacerlo, tendremos acceso a un editor de código similar a una IDE (como de las que hablamos en el post anterior) donde podremos pegar nuestro código en JavaScript o incluso escribirlo desde cero ahí mismo.
Otras de las de las herramientas de gran valor que nos provee tiene que ver con la posibilidad de visualizar nuestra tarea al ir modificando el código. Es decir que al ir haciendo modificaciones podemos ver como quedaría al presentarla a nuestros voluntarios.
Es importante remarcar cuales son los requsitos para tener un experimento funcionando en Cognition:
- Código en lenguaje JavaScript utilizando la biblioteca jsPsych y, por lo tanto, respetando la estructura que requiere esta (plugins, timeline, etc).
- Cargar todos los archivos extra que requiera nuestro experimento en el apartado External JS/CSS ¿Qué se considera archivos extra? Cualquier biblioteca o código extra en JavaScript o en CSS que no forme parte de la distribución de jsPsych que se esté usando.
Un detalle no menor es que Cognition importará estos archivos en el orden en que fueron cargados, esto puede ser relevante porque algunas veces este orden puede ser relevante para el normal funcionamiento del código.
- Subir los estímulos, ya sean imágenes, videos, clips de audio, etc. Par ellos tenemos la sección Stimuli. Simplemente vamos a browse y agregamos todos los archivos que nuestro experimento requiera.
- Seleccionar la versión de jsPsych en jsPsych version. Ya que por defecto se selecciona la última, probablemente no necesitemos cambiarla, pero podría ser que nuestro código funcione con una versión anterior.
- Por último pero no por eso menos importante, es pertinente remarcar que en la sección Task Code donde colocamos nuestro código hay que poner solo código JavaScript de la tarea experimental, es decir, NO se coloca nada de las bibliotecas que importamos, ni el CSS ni ninguna otra cosa. Para eso está External JS/CSS.
Una vez que configuramos todo, volvemos a la sección correspondiente a nuestro experimento presionando sobre el nombre, seleccionamos el link y lo compartimos con las personas que querramos.
Ejemplo rápido
Para demostrar la sencillez de esta plataforma y su gran utilidad voy a utilizar un ejemplo de la documentación oficial de jsPsych para mostrar lo fácil que es tenerlo funcionando y listo para compartir. Les invito a que luego intenten hacer lo mismo con el experimento que desarrollamos en el post anterior.
La tarea consiste en presionar una tecla para un círculo de color azul y otra tecla para un círculo de color naranja vamos a necesitar estas dos imágenes descargándolas de este link y de este otro (hay que darle botón derecho y presionar guardar como, sin cambiar los nombres de las imágenes).
Este es el código que utilizaríamos para que funcione en nuestra computadora, tal cual aparece en el tutorial de jsPsych:
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych-6.0.5/jspsych.js"></script>
<script src="jspsych-6.0.5/plugins/jspsych-html-keyboard-response.js"></script>
<script src="jspsych-6.0.5/plugins/jspsych-image-keyboard-response.js"></script>
<link href="jspsych-6.0.5/css/jspsych.css" rel="stylesheet" type="text/css"></link>
</head>
<body></body>
<script>
/* create timeline */
var timeline = [];
/* define welcome message trial */
var welcome = {
type: "html-keyboard-response",
stimulus: "Welcome to the experiment. Press any key to begin."
};
timeline.push(welcome);
/* define instructions trial */
var instructions = {
type: "html-keyboard-response",
stimulus: "<p>In this experiment, a circle will appear in the center " +
"of the screen.</p><p>If the circle is <strong>blue</strong>, " +
"press the letter F on the keyboard as fast as you can.</p>" +
"<p>If the circle is <strong>orange</strong>, press the letter J " +
"as fast as you can.</p>" +
"<div style='width: 700px;'>"+
"<div style='float: left;'><img src='img/blue.png'></img>" +
"<p class='small'><strong>Press the F key</strong></p></div>" +
"<div class='float: right;'><img src='img/orange.png'></img>" +
"<p class='small'><strong>Press the J key</strong></p></div>" +
"</div>"+
"<p>Press any key to begin.</p>",
post_trial_gap: 2000
};
timeline.push(instructions);
/* test trials */
var test_stimuli = [
{ stimulus: "img/blue.png", data: { test_part: 'test', correct_response: 'f' } },
{ stimulus: "img/orange.png", data: { test_part: 'test', correct_response: 'j' } }
];
var fixation = {
type: 'html-keyboard-response',
stimulus: '<div style="font-size:60px;">+</div>',
choices: jsPsych.NO_KEYS,
trial_duration: function(){
return jsPsych.randomization.sampleWithoutReplacement([250, 500, 750, 1000, 1250, 1500, 1750, 2000], 1)[0];
},
data: {test_part: 'fixation'}
}
var test = {
type: "image-keyboard-response",
stimulus: jsPsych.timelineVariable('stimulus'),
choices: ['f', 'j'],
data: jsPsych.timelineVariable('data'),
on_finish: function(data){
data.correct = data.key_press == jsPsych.pluginAPI.convertKeyCharacterToKeyCode(data.correct_response);
},
}
var test_procedure = {
timeline: [fixation, test],
timeline_variables: test_stimuli,
repetitions: 5,
randomize_order: true
}
timeline.push(test_procedure);
/* define debrief */
var debrief_block = {
type: "html-keyboard-response",
stimulus: function() {
var trials = jsPsych.data.get().filter({test_part: 'test'});
var correct_trials = trials.filter({correct: true});
var accuracy = Math.round(correct_trials.count() / trials.count() * 100);
var rt = Math.round(correct_trials.select('rt').mean());
return "<p>You responded correctly on "+accuracy+"% of the trials.</p>"+
"<p>Your average response time was "+rt+"ms.</p>"+
"<p>Press any key to complete the experiment. Thank you!</p>";
}
};
timeline.push(debrief_block);
/* start the experiment */
jsPsych.init({
timeline: timeline,
on_finish: function() {
jsPsych.data.displayData();
}
});
</script>
</html>Se trata de un experimento en formato HTML (por eso las etiquetas <html></html> son las más externas) que importa la biblioteca jspsych, los estilos css y dos plugins: html-keyboard-response y también image-keyboard-response. Todo el código pertenece a la distribución oficial de la biblioteca y por lo tanto no deberá ser cargados como archivos externos (para ver una lista completa de los plugins que trae la biblioteca pueden entrar a este enlace).
¿Cómo hacemos para subir el experimento?
Muy sencillo. En función de los pasos que ya vimos a lo largo del artículo:
- Accedemos a nuestra cuenta de Cognition.run
- Creamos una nueva tarea presionando el botón + New Task
- Elegimos un nombre y presionamos en Save
- Clickeamos en Source Code en el apartado Design
- Copiamos nuestro código y lo pegamos en el apartado con fondo negro que se llama Task Code.
¡ATENCIÓN! Es muy importante que solo pegues el código JavaScript, es decir, la parte comprendida entre las etiquetas <script> y</script>, sin incluirlas.
- Si tuviéramos archivos externos tanto de JavaScript como de CSS, los deberíamos subir a External JS/CSS. En este caso no necesitamos ninguno.
- Subimos los estímulos necesarios en el apartado Stimuli, en este caso son dos archivos: blue.png y orange.png.
¡Y eso es todo! Tenemos un experimento funcionando, con un link que podemos enviarle a cualquier persona, que guarda los datos y pueden ser descargados tanto individualmente como todos juntos en un archivo (formato .csv).
El códgo también lo puede encontrar en la carpeta examples de jsPsych como demo-simple-rt-task.html. Además, les dejo el experimento subido para que lo prueben.
Comentarios finales
Debido a que considero primordial que esta reseña sea honesta, este tutorial estaría incompleto si no contara lo que yo veo como desventajas de la plataforma. Por un lado es una herramienta muy nueva y por lo tanto se encuentra en versión beta, lo cual implica un estadío temprano en su desarrollo. Esto podría venir acompañado de una mayor cantidad de errores o bugs (aunque yo todavía no sufrí ninguno utilizándola). Por otro lado no hay una documentación sobre como usarla, lo cual podría dificultar su uso. Lo cierto es que esa ha sido una de las principales razones que me motivaron a escribir este artículo. Finalmente la plataforma solo está en idioma inglés y junto con todos los recursos asociados a jsPsych hace que los hispanoablantes tengamos siempre menor acceso al conocimiento respecto a los angloparlantes.
Para concluir creo que las herramientas siempre dependen de la tarea que uno quiere realizar, por lo tanto la ventaja de usar Cognition dependerá del tipo del diseño experimental, infraestructura y gustos. Lo que me parece necesario es difundir el uso de esta excelente opción que considero sencilla y agradable de usar, poderosa y como si fuera poco, gratuita. Un detalle no menor para aquellas personas que hacemos ciencia en latinoamérica.
Como siempre, me encuentro abierto a sus mensajes, críticas y sugerencias tanto sobre esta como las potenciales entregas subsiguiente de esta serie de artículos sobre la creación de experimentos online.
¡Espero que les resulten de utilidad!
Tip
- Pueden evitar que el experimento guarde datos agregando ‘?demo=true’ (sin las comillas) al final del link (URL) que corresponde a su experimento. Esto puede resultar útil, por ejemplo, si uno quiere probar la tarea muchas veces y no le interesa guardar esa información.
Referencias (en inglés)
- Tutorial del creador de jsPsych sobre la plataforma Cognition. Como ya dije anteriormente, recomiendo su canal con video-tutoriales.
- Presentación de Cognition.run en el foro de jsPsych por parte de su creador Javier Vidal Peña.
- Tomé la idea de la foto de portada de este post sobre la posibilidad de asociar jsPsych y Google Sheets. Lo recomiendo.
