Video Notes
jsPsych is a JavaScript library for creating behavioral experiments that run in a web browser. jsPsych is widely used in psychological research, cognitive science, and other fields that require the presentation of stimuli and collection of responses from participants.
To get started with jsPsych, we’ll build a simplified Lexical Decision Task where a participant will be shown a series of characters and they will have to indicate whether those characters make up a valid word.
Below is an outline of the flow of the experiment:
Setup
Create a new directory at psy1903/docs/projects/lexical-decision.
Within this directory, create two files:
-
index.html
-
experiment.js
Within index.html, place this code:
<!DOCTYPE html>
<html>
<head>
<title>Lexical Decision Task</title>
<link href=data:, rel=icon>
<script src='https://unpkg.com/jspsych'></script>
<script src='https://unpkg.com/@jspsych/plugin-html-keyboard-response'></script>
<script src='experiment.js'></script>
<link href='https://unpkg.com/jspsych/css/jspsych.css' rel='stylesheet' type='text/css'>
</head>
<body></body>
</html>
Within experiment.js, place this code:
let jsPsych = initJsPsych();
Open this new project in your browser via your local server: http://localhost:3000/projects/lexical-decision (swap 3000 for whatever port number your server is running on).
You should see a blank white page and - most importantly - no errors or other output in the web inspector console.
Key points to observe about the index.html file:
- It imports the jsPsych library from an external CDN (Content Delivery Network) unpkg.com.
- It imports the jsPsych plugin html-keyboard-response, also from unpkg.com.
- It imports the local experiment.js file where you’ll write your code that utilizes the functionality within the jsPsych library.
- It imports a jsPsych CSS file (jspsych.css) from unpkg.com, which provides some baseline styling for experiments. Later we’ll talk more about CSS and customizing styles.
Within the experiment.js file, we have a single line of code that initializes a new jsPsych experiment:
let jsPsych = initJsPsych();
Every experiment you design will start this way. The fact that this line works and does not produce any errors in the browser indicates that you have successfully connected the jsPsych library to your page.
With setup behind us, let’s dig into the details of using jsPsych and start fleshing out the details of our experiment.
Experiment structure
A typical experiment will have these three sections:
-
Welcome - Introduces the participant to the experiment and provides instructions.
-
Conditions - Display different stimulus/conditions and collect responses from the participant. This portion of the experiment typically happens on a loop for as many iterations as necessary for a given experiment.
-
Debrief - Thanks the participant and lets them know the experiment is complete.
In jsPsych, each section is commonly referred to as a trial.
Timeline
All jsPsych experiments are structured around a timeline which is simply an array that contains the different trials of our experiment.
To begin, initialize a variable called timeline to an empty array by adding the following line to experiment.js:
// Create timeline
let timeline = [];
Plugins
To add trials to our experiment, we will choose from a list of what jsPsych calls plugins.
You can see a full list of available plugins here....
You can read a general overview about plugin usage here...
To create a simple welcome trial we will use the html-keyboard-response plugin which will allow us to display some HTML content with instructions, and wait for the participant to press a key to begin the experiment. As you saw in our initial setup, we set up our index.html file so that it imports this plugin via this line:
<script src='https://unpkg.com/@jspsych/plugin-html-keyboard-response'></script>
You will need to add an import statement like this for any jsPsych plugin you use in your experiment.
Using the plugin
The way we use jsPsych plugins is by creating an object with parameters to configure the plugin. There are parameters that are available for all plugins, as well as plugin-specific parameters which you can learn about on a plugin’s documentation page, e.g.: html-keyboard-response Parameters.
Using this information we can create a welcomeTrial object with the parameters type, stimulus, and choices:
// Define a welcome trial using jsPsych’s jsPsychHtmlKeyboardResponse plugin
let welcomeTrial = {
// Indicate the plugin type we’re using
type: jsPsychHtmlKeyboardResponse,
// What stimulus to display on the screen
stimulus: `
<h1>Welcome to the Lexical Decision Task!</h1>
<p>You are about to see a series of characters.</p>
<p>If the characters make up a word, press the F key.</p>
<p>If the characters do not make up a word, press the J key.</p>
<p>Press SPACE to begin.</p>
`,
// Listen for the SPACE key to be pressed to proceed
choices: [' '],
};
With our welcome trial defined, we can add it to our timeline array using the push method:
timeline.push(welcomeTrial);
And then invoke the run method on our jsPsych instance, passing it the timeline to run:
jsPsych.run(timeline);
Refreshing your page in the browser, you should now see:
If you press the SPACE key as instructed, the experiment will proceed to a blank screen, which happens because we haven’t yet programmed anything else in our timeline beyond the welcome trial.
Next...
With this basic skeleton of an experiment set up, we can dig deeper and iterate through condition trials which will be the core of our experiment...
Code so far
// Initialize the jsPsych library
let jsPsych = initJsPsych();
// Define the timeline as an empty array where we will add all our trials
let timeline = [];
// Define a welcome trial using jsPsych’s jsPsychHtmlKeyboardResponse plugin
let welcomeTrial = {
// Indicate the plugin type we’re using
type: jsPsychHtmlKeyboardResponse,
// What content to display on the screen
stimulus: `
<h1>Welcome to the Lexical Decision Task!</h1>
<p>You are about to see a series of characters.</p>
<p>If the characters make up a word, press the F key.</p>
<p>If the characters do not make up a word, press the J key.</p>
<p>Press SPACE to begin.</p>
`,
// Listen for the SPACE key to be pressed to proceed
choices: [' '],
};
// Add the welcome trial to our timeline
timeline.push(welcomeTrial);
// Run the experiment
jsPsych.run(timeline);
