jspsych-gabor-stimulus-plugin

This project aims to provide a jsPsych plugin for generating gabor patch stimuli. Once it reaches reasonable stability, test coverage and usability, it will be proposed to the jsPsych team for integration into the main codebase.

How to use

Install

For now, the plugin can be installed from npm:

$ yarn add @kogpsy/jspsych-gabor-stimulus-plugin

Example

// Import plugin and config type
import GaborStimulusPlugin from '@kogpsy/jspsych-gabor-stimulus-plugin';

// ...

// Define configuration object
const config = {
  stimulus: {
    size: 200,
    rotation: 45,
  },
  fixation_cross: {
    size: 20,
    weight: 4,
    color: 'white',
  },
};

// Push the plugin to the timeline
timeline.push({
  type: GaborStimulusPlugin,
  config: config,
});

This will produce the following result:

TypeScript

There is a type available for the configuration object which is exported as GaborStimulusPluginConfig by the plugin. It can be used to make configuring more convenient and robust.

Configuration reference

The configuration object allows broad control over how the gabor patch generated. You can control the stimulus itself using the stimulus key, the aperture using the aperture key, the background using the background key, a possible fixation cross using the fixationCross key, stimulus timing using the timing key and the possible keyboard responses using the choices key:

const conf: GaborStimulusPluginConfig = {
  stimulus: {
    // ...
  },
  aperture: {
    // ...
  }
  background: {
    // ...
  }
  fixation_cross: {
    // ...
  },
  timing: {
    // ...
  },
  choices: [/* ... */]
};

Each of these keys takes an object which is explored in the following.

stimulus

The stimulus itself consists of alternating white and black lines. The transitions between the colors are smooth and follow a sinusoidal curve.

You can control the appearance of the stimulus using a multitude of parameters:

aperture

The stimulus above is rendered using a square-shaped SVG element. A traditional gabor patch is circular with smooth edges. This is achieved using an aperture and blurring it.

You can control the aperture radius and blur using these parameters:

fixation_cross

There is the possibility to display a fixation cross in the middle of the stimulus. To do so, add a fixationCrosskey to the configuration object.

You can also control how it looks with the following parameters:

background

There are different background types available. You can control the type by setting the value uf the type key on the background object to one of the strings shown below. Depending on the type, different, further configuration options are available.

• type: "css-color"
• type: "image"
• type: "animation"

The configuration options for each type are presented in the following:

type: "css-color"

This is the default background type, with the color parameter set to transparent resulting in a transparent background.

type: "image"

type: "animation"

timing

The timing of the stimulus and trial is pretty flexible. Stimulus timing corresponds to how long the stimulus itself (gabor patch and background) is displayed, while trial timing corresponds to how long responses are captured.

These options are available:

Capturing keyboard responses

As most of jsPsych's plugins, this plugin can capture keyboard responses. To control the allowed keys, the choices array is used (which is not part of the configuration object). To allow the F and the J keys, for example, set the value of the choices key like that:

timeline.push({
  type: GaborStimulusPlugin,
  config: yourConfigObject,
  choices: ['f', 'j'],
});

As for valid key codes, this plugin follows the conventions of other jsPsych plugins. The jsPsych documentation on the KeyBoardResponsePlugin states the following:

Keys should be specified as characters (e.g., 'a', 'q', ' ', 'Enter', 'ArrowDown') - see this page and this page (event.key column) for more examples.

Per default, no keys are allowed.

A more complete example

This is a more complete example demonstrating how to use many of the options discussed above. The backgroundFrames array is generated using the integrated background noise generator (see below).

const gaborConf = {
  stimulus: {
    size: 300,
    density: 6,
    opacity: 1,
    phase_offset: 0,
    rotation: 45,
    blend_mode: 'overlay',
  },
  aperture: {
    radius: 100,
    blur: 25,
  },
  background: {
    type: 'animation',
    frames: backgroundFrames,
    fps: 10,
  },
  fixation_cross: {
    size: 30,
    weight: 5,
    color: 'white',
  },
  choices: [], // No keys
  timing: {
    trial_duration: 250,
    response_ends_trial: false,
  },
};

This will result in a stimulus looking like that (with the background being animated, of course):

Integrated background noise generator

This plugin comes with an integrated background noise generated used to generate either single images with random noise or multiple frames used to animate the background.

You can import and use the generator functions like this:

import {
  generateNoise,
  generateNoiseFrames,
} from '@kogpsy/jspsych-gabor-stimulus-plugin';

// Generate a single background image (the parameters correspond to its width
// and height)
const noisyBackgroundImage = generateNoise(300, 300);

// Generate multiple background frames (the parameters correspond to their width
// and height, as well as the number of frames)
const noisyBackgroundFrames = generateNoiseFrames(300, 300, 20);

Data saved by the plugin

The following data are collected:

• response: The key pressed by the participant
• rt: The reaction time