Gorilla and jsPsych

Using your jsPsych task within a Gorilla experiment has never been easier. If you have existing tasks written in jsPsych, or already use it for building your own tasks, this guide will show you how simple it is to use your jsPsych code in Gorilla.

Importing your jsPsych task

Importing your original jsPsych task into Gorilla can be done in 3 simple steps. You will need:

Your code! Either the contents of the main script tags in your HTML file or the contents of your separate JavaScript file.
Your stimuli.
The jsPsych files required for your task. At the least, this will be the main jsPsych.js file.
About 10 minutes of your time!

Step 1) Create a new jsPsych Code Editor task in Gorilla (1 min)

From inside your project in Gorilla, press Create and then select Code Editor Task. Give your task a name and hit create.

The Code Editor wizard will then ask you what kind of task you want to set up: Select jsPsych starter.

This template is preloaded with the basic script you'll need to get up and running.

Take a look below at the Code snippet showing the basic integration:

import gorilla = require("gorilla/gorilla");

// Make sure to upload the jsPsych files you need to the resources tab.
// This should include the main jsPsych.js, jsPsych.css and likely at least one plugin. 
// In this case, we use the jspsych-html-keyboard-response.js plugin file.
var jsPsych = window['jsPsych'];

gorilla.ready(function(){

	var timeline = []; 

	var hello_trial = {
		type: 'html-keyboard-response',
		stimulus: 'Hello world!'
	}

	timeline.push(hello_trial);

	jsPsych.init({
		display_element: $('#gorilla')[0],
		timeline: timeline,
		on_data_update: function(data){
			gorilla.metric(data);
		},
		on_finish: function(){
			gorilla.finish();
		}
	});
})
                            

Step 2) Add in your timeline (2-10 mins)

We've already set up the Gorilla and jsPsych code basics: importing the main Gorilla module, setting up the .ready function and a basic jsPsych.init function. Now you just need to populate your jsPsych timeline.

Not using the jsPsych timeline? The timeline is a really intuitive system for building your experiment from basic blocks that was introduced in jsPsych 5. You can learn more about it here: https://www.jspsych.org/overview/timeline/

We've already created a timeline variable for you and assigned it in the jsPsych initialisation function. All you need to do is push the trials you require to it. In most cases, this will be as simple as copy pasting your existing code.

/* 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: "

In this experiment, a circle will appear in the center " + "of the screen.

If the circle is blue, " + "press the letter F on the keyboard as fast as you can.

" + "

If the circle is orange, press the letter J " + "as fast as you can.

" + "

"+ "

" + "

Press the F key

" + "

Press the J key

" + "

"+ "

Press any key to begin.

", post_trial_gap: 2000 }; timeline.push(instructions); /*ADD rest of your timeline here*/

Step 3) Add the jsPsych files you need (1 min)

These can all be uploaded in the Resources tab of the toolbox on the left hand side.

Make sure you also add script tag references to them in the head. We've done this part automatically for some of the basic files that most tasks will use

And that's pretty much all there is to it! We've already linked the data collection to Gorilla and the end of the Task with Gorilla's own finish function.

To learn more about how to import your jsPsych Task into the Gorilla Code Editor check out our 'Hello_World' Tutorial here.

Is your task a little more involved?

Depending on how your task works and the additional features it requires, you may need to do a few more things to get everything working fully with Gorilla.

Add in stimuli

In jsPsych, you usually need to provide the file address of your stimuli. For example, 'img/image1.png'. In Gorilla, you'll need to replace this with the URL Gorilla provides that links to where your image is stored.

The first step is to upload all of your stimuli to the stimuli tab. Then, you can retrieve the URL for the stimuli using the command gorilla.stimuliURL('myImage.png'): this would retrieve the URL for the image 'myImage.png'.

We also recommend that you take advantage of jsPsych's image preloading functionality - this will download all of the stimuli your task requires so that they can be instantly accessed during the task. You can see an example here of how to implement this in our jsPsych Tutorial Task 'Simple Reaction Time Task'.

//Adding in Stimuli // URL's for Blue and Orange images: var blueURL = gorilla.stimuliURL('blue.png'); var orangeURL = gorilla.stimuliURL('orange.png'); // We also create an array containing all the URL's for our required stimuli. // This is an important step which will be discussed further below! var images = []; images.push(blueURL); images.push(orangeURL); //Using the URLs Example: /* define instructions trial */ var instructions = { type: "html-keyboard-response", stimulus: "

In this experiment, a circle will appear in the center " + "of the screen.

If the circle is blue, " + "press the letter F on the keyboard as fast as you can.

" + "

If the circle is orange, press the letter J " + "as fast as you can.

" + "

"+ "

" + "

Press the F key

" + "

Press the J key

" + "

"+ "

Press any key to begin.

", post_trial_gap: 2000 }; timeline.push(instructions); /* start the experiment */ jsPsych.init({ display_element: $('#gorilla')[0], timeline: timeline, preload_images: images, show_preload_progress_bar: false, on_data_update: function(data){ gorilla.metric(data); }, on_finish: function() { jsPsych.data.displayData(); } });

Add additional metrics

By default, we've included some of the metrics that jsPsych generates. You can see these in the Metrics tab.

Gorilla Code Editor - Metrics Tab: Image below shows the default metrics available in the jsPsych Starter Project.

If you need to include more than this, you'll need to add new entries to the metrics tab. This way, Gorilla will know it needs to store them and you can assign an easily identifiable column name.

Don't already have a Gorilla account? Sign up now and get start building your jsPsych task today!