Psychophysics tasks tutorial

What is this tutorial?

This tutorial explains the experiment files in simple words.

You do not need to understand every line of code. Start by learning the screens that make one trial, then learn which small parts you should edit.

Task paradigms

What happens in one trial?

A trial is one small part of the experiment. In most tasks, one trial shows one image and asks for one response.

Most tasks repeat this same trial many times, once for each image.

The four main screens

How to make the starting screens

Before the real trials start, the experiment usually adds setup screens to the timeline.

let timeline = [];

timeline.push(preload);       // load images before the task starts
timeline.push(fullscreen);    // ask the participant to enter fullscreen
timeline.push(consent_form);  // show consent information
timeline.push(intro_info);    // show basic information
timeline.push(survey);        // ask participant questions
timeline.push(welcome);       // show task instructions

What can I change?

• the instruction text in welcome.

How to make a fixation screen

timeline.push({
    type: 'html-keyboard-response',
    stimulus: '<div style="font-size: 60px;">+</div>',
    choices: jsPsych.NO_KEYS,
    trial_duration: 500
});

This screen shows a plus sign. The participant cannot answer during this screen.

What can I change?

• +: change the fixation symbol.
• font-size: 60px: make the fixation bigger or smaller.
• trial_duration: 500: change how long the screen stays on. Time is in milliseconds. 500 ms = half a second.

How to make an image screen

timeline.push({
    type: 'image-button-response',
    stimulus: images[i],
    stimulus_height: stimulusSize,
    choices: [],
    trial_duration: 100,
    data: { trial_index: i }
});

This screen shows one image from your image list. In 2AFC tasks, the participant sees the image first and answers later.

What can I change?

• images[i]: this means “show the current image.” Usually, do not change this line. Change the image list instead.
• stimulus_height: stimulusSize: controls the image size. Change stimulusSize or visualAngle if you want bigger or smaller images.
• choices: []: means no response buttons on this screen.
• trial_duration: 100: image time. 100 ms = one tenth of a second.

How to make a blank screen

timeline.push({
    type: 'html-keyboard-response',
    stimulus: '',
    choices: jsPsych.NO_KEYS,
    trial_duration: 100
});

This screen shows nothing. It creates a short pause after the image.

What can I change?

• stimulus: '': empty means the screen is blank.
• trial_duration: 100: blank time. Increase it for a longer pause.

How to make response screens

Different task paradigms use different response screens.

2AFC response

Choose between two answers

The participant clicks the left or right answer.

Example code

timeline.push({
    type: 'html-button-response',
    stimulus: '',
    button_html: [lb1, lb2],
    choices: ['left', 'right'],
    trial_duration: 3000
});

Change: lb1 and lb2 to change the labels/images shown as answers. Change trial_duration to give more or less time to answer.

Saves: choice, accuracy, reaction time

Rating response

Move a slider

The participant gives a rating using a slider.

Example code

timeline.push({
    type: 'html-slider-response',
    stimulus: '<p>Choose a position on the slider.</p>',
    labels: ['1', '5'],
    min: 1,
    max: 5,
    step: 1,
    require_movement: true,
    trial_duration: 8000
});

Change: stimulus for the question, min/max for the rating scale, labels for text under the slider, and trial_duration for response time.

Saves: rating, reaction time

N-Back response

Novel or repeated?

The participant says whether the image is new or has appeared before.

Example code

timeline.push({
    type: 'image-button-response',
    stimulus: images[i],
    stimulus_height: stimulusSize,
    choices: ['Novel', 'Repeated'],
    prompt: '<p>Has this image been shown before?</p>',
    trial_duration: 3000,
    stimulus_duration: 200
});

Change: choices to change button text, prompt to change the question, stimulus_duration to change image time, and trial_duration to change total answer time.

Saves: choice, accuracy, reaction time

Important timing words

The most important section to edit

Open a task file and look for this line:

// ===== STUDENTS: EDIT THIS SECTION =====

This section tells the task which images to show and, when needed, which answer is correct.

What can I change?

How to change images in a 2AFC task

Example from obj_recog.html:

let val = [81, 63, 54, 31, 142];
let ch1 = [4, 5, 9, 2, 5];
let ch2 = [0, 3, 2, 1, 7];
let correct_choice = [4, 3, 2, 1, 7];

Read this as:

• val = the image indices shown to the participant.
• ch1 = the answer shown on the left.
• ch2 = the answer shown on the right.
• correct_choice = the correct answer for each image.

Example: test your own 2AFC images

Put your images in:

images/your_experiment_name/

Name them like this:

im0.png
im1.png
im2.png

Then change the image list:

let val = [0, 1, 2];

The task will now show im0.png, im1.png, and im2.png.

How to change images in a Rating task

Example from ratings.html:

let val = [7, 2, 15, 0, 18];

This means the task shows:

im7.jpg
im2.jpg
im15.jpg
im0.jpg
im18.jpg

To test your own images, put them in:

images/your_experiment_name/

Then change val to your image numbers.

How to change images in an N-Back task

Example from n_back.html:

var val = [161, 161, 115];
var correct = [0, 1, 0];

Read this as:

• The first image is im161.png. It is new, so the correct answer is 0.
• The second image is also im161.png. It is repeated, so the correct answer is 1.
• The third image is im115.png. It is new, so the correct answer is 0.

How to use your own images

To test your own images, we suggest using around 20 images. This is enough to try the task without making the experiment too long.

There are three steps:

• Step 1: save your images in an image folder.
• Step 2: choose the task paradigm: 2AFC, Rating, or N-Back.
• Step 3: create a small metadata CSV file that describes the images.

Step 1: save your images

Put your images in a folder inside the images folder. For example:

images/my_experiment/

Name your images with numbers:

im0.png
im1.png
im2.png
im3.png
...

The number in the file name is the image index. For example, im7.png has image index 7.

Step 2: choose your task paradigm

Step 3: create a metadata CSV file

A metadata CSV file is a small table that describes your images. You can make it in Excel, Google Sheets, or Python. Then save it as a .csv file.

Example metadata file for 2AFC

Use this format if the participant must choose between two answers. For 2AFC, you only need to provide the correct answer. The script will automatically create the left and right choices.

The answer numbers can come from this class list:

lb = ['bear','elephant','person','car','dog','apple','chair','plane','bird','zebra']

The first class has index 0, the second class has index 1, and so on:

image_file,image_idx,correct_choice
im0.png,0,4
im1.png,1,3
im2.png,2,6
im3.png,3,9

Read this as:

• im0.png shows image 0. The correct answer is 4, which means dog.
• im1.png shows image 1. The correct answer is 3, which means car.
• im2.png shows image 2. The correct answer is 6, which means chair.
• im3.png shows image 3. The correct answer is 9, which means zebra.

Example metadata file for Rating

Use this format if the participant gives a rating. There is no correct answer.

image_file,image_idx
im0.png,0
im1.png,1
im2.png,2
im3.png,3

Example metadata file for N-Back

Use this format if the participant answers Novel or Repeated. For N-Back, you only need to say which images should be repeated. The script will create the final task order.

image_file,image_idx,repeated
im0.png,0,0
im1.png,1,0
im2.png,2,1
im3.png,3,0
im4.png,4,1

Read this as:

• image_file: the image file name.
• image_idx: the number of the image.
• repeated: whether this image should be repeated later in the task.

By default, the script uses N = 5. This means that a repeated image appears again 5 trials after it first appeared.

// ===== STUDENTS: EDIT THIS SECTION =====

What jsPsych saves automatically

jsPsych saves the participant's data after every trial.

• response: what the participant clicked or selected.
• rt: reaction time.
• stimulus: the image that was shown.

The task can also save extra information, such as whether the answer was correct.

Important: complete the task before closing the window

The CSV file is saved only at the end of the task, after the final thank-you screen appears.

If you close the browser window, refresh the page, or stop the task before the final screen, the CSV data file will not be saved.

Please continue until you see the message saying that the task is complete and the CSV file has been saved.

How data are scored

Example: raw CSV file

This is what the data look like immediately after running the experiment. The raw CSV contains all screens, including preload, fullscreen, instructions, survey questions, fixation screens, image screens, blank screens, and response screens. That is why the file has many rows that are not actual trials.

For analysis, we usually do not want every row. We mainly want the rows where the participant gave an answer.

How do I extract the data?

After collecting CSV files from participants, open the parser notebook for your task paradigm.

Example: extracted CSV file

This is what the data look like after using the parser notebook. The extracted CSV is much easier to read because it keeps only the useful information: one row per real trial, the image shown, the participant's response, the correct answer, and whether the participant was correct.

This cleaned file is the one you should use for plotting results and computing accuracy or average ratings.

What can I change?

input_folder = "data/raw_data_folder"
output_file = "data/extracted_results.csv"

• input_folder: the folder containing the raw CSV files from participants.
• output_file: the name of the clean CSV file you want to create.

Student checklist

• Choose a task paradigm: 2AFC, Rating, or N-Back.
• Put your images in the correct image folder.
• Name your images im0.png, im1.png, etc. Use .jpg if the task expects jpg files.
• Open the task file.
• Find // ===== STUDENTS: EDIT THIS SECTION =====.
• Change the image numbers.
• For 2AFC or N-Back, also change the correct answers.
• Change screen times if needed by editing trial_duration or stimulus_duration.
• Run the task and check the saved CSV file.
• Optional: use manipulate_stimuli.ipynb to create altered versions of your images, such as blurred or noisy images.