Psychology/Neuroscience Experiments
in MATLAB Built on Psychtoolbox
MATLAB software built on Psychtoolbox for neuroscience/psychology experiments

Psychtoolbox is a popular MATLAB toolbox for neuroscience and psychology experiments. Building experiments in MATLAB with Psychtoolbox allows a degree of flexibility and precision that is essential in many research niches. However, it can be a technical process, and time consuming even for experienced users. Redundancy is also a problem as reusing stimuli and functionality means refactored code across different experiments, or even reinventing it across labs.

PsychBench is software for MATLAB built on Psychtoolbox. It adds a layer to make building Psychtoolbox-based experiments faster, more accessible, and less redundant. It aims to do this while retaining the precision that is important to Psychtoolbox users. It also allows flexibility for custom stimuli and functionality that can plug into any experiment. PsychBench's open-source library comes with a range of stimuli and functionality, including all the basics as well as niche stimuli possible only with Psychtoolbox.

Download PsychBench beta (free)
for MATLAB with Psychtoolbox – Windows/macOS/Linux

This link downloads the MATLAB function pb_install.m.
Put it in the location where you want to install PsychBench, set your MATLAB current folder to there, and type help pb_install at the MATLAB command line for instructions.

You'll also need...

Windows / macOS / Linux – 64-bit

MATLAB R2017a or later (R2018b+ recommended, mainly tested in R2021a)
PsychBench does not run in GNU Octave.

Psychtoolbox most recent version (free)

GStreamer (free)
        Windows: GStreamer 64-bit MSVC runtime 1.22.1
        macOS (Intel and ARM): GStreamer runtime 1.22.1
        Linux: generally already installed

System requirement details >

Update history >

In versions earlier than 2023.03.26 (180559), a bug in pb_update may prevent updating. If you get a MATLAB error involving fopen/fclose or files being locked, please delete the PsychBench folder, remove it and its subfolders from the MATLAB search path (MATLAB toolbar → Set Path), and reinstall with the most recent version using the download link above.

Experiments

Build and run an experiment in PsychBench by writing a short script. Make objects of various types (.g. picture, text, sound, keyPress, etc.). For each object, you can specify parameters and options by setting properties using dot statements. Lots of properties are possible but for any given experiment you can omit most to leave them at default values.

With PsychBench

The script below would run a (very) simple experiment consisting of two repetitions of three distinct trials, all in random order. In each trial, a picture of an animal shows at a height of 10 degrees visual angle. The picture stops showing when the subject presses any key. Experiment results report which animal was shown (picture file name) and response latency for each trial.

Without PsychBench

Some compact Psychtoolbox code to run the same experiment—with the same timing precision and error handling, and assuming MATLAB imread loads the pictures with no fuss—would be:

The take-away is that with PsychBench you work mainly at the level of stimulus and experiment concepts while much of the technical lifting is automated underneath. Meanwhile the precision of Psychtoolbox is preserved because underneath is Psychtoolbox code.

PsychBench also facilitates modifying experiments and reusing stimuli and functionality across experiments. Changing something just means changing property values or swapping in different objects. Any object works anywhere in any experiment.

Core features

Make objects from a library of types and set their properties using dot statements in a simple script. Any object works anywhere in any experiment.
Set objects to start/end based on times or durations, or on flexible cues like other objects, responses from subject, triggers, etc. Further timing is available through object types like sequence (e.g. for change blindness experiments).
Precise timing and time measurement, including time-buffering stimulus onsets/offsets, and synchronizing across modalities (visual, auditory, etc.). A technical summary of timing processes is here, with more detail available on request.
Sync experiments with external devices like scanners in each trial or for multiple (or all) trials. Set timing relative to sync with zero drift.
Properties all visual objects have allow setting position on screen, drift/movement, layering, rotation, flip, transparency, intensity, contrast, convolution, noise, gamma, and more. More specific functionality is in each object type.
Default units of degrees visual angle for all values relating to distance on screen, including deg, deg/sec (e.g. speed), cycles/deg (e.g. spatial frequency), etc. Optionally use other units like px, cm, proportion of window size.
Stereo display by most of the modes available in Psychtoolbox.
Record any visual stimuli to single image, series of images, or movie files.
Sound playback and recording built on Psychtoolbox's high-precision PortAudio functions.
Core response functionality including recording responses, times and latencies, translating response values, scoring, and more. Device-specific functionality is in response handler object types (key press or text, mouse, button box, etc.).
Build any complex experiment design with the flexibility of a MATLAB script. Automate generating conditions and combinations of conditions across factors. Repeat, order, and block trials. Include intros, training trials, syncs, breaks, etc. PsychBench includes little helper tools for replication, randomization, and balancing.
Method of adjustment experiments where the subject can adjust object properties in real time. Device-specific functionality is in adjuster object types (keyboard, mouse, etc.).
Staircase any property of any object using staircase objects (fixed step, QUEST, etc.). Set staircase parameters, interleave multiple staircases, exclude trials from staircases, etc.
Test any experiment by running it in auto-response mode to simulate a subject run unattended.
Quit and save an experiment run and resume it later to split it across multiple sessions.
Customizable experiment results output drawing from any object properties and labels, saved for MATLAB and in .csv for other apps.

Open-source object type library

PsychBench comes with a library of open-source object types (MATLAB + Psychtoolbox).

We add new object types regularly. Please contact us with requests.

Visual

Auditory

Response handlers

Adjusters

Other

Custom code

If the library doesn't have the stimuli or function you need for an experiment, you can write your own code in MATLAB + Psychtoolbox. The approach is to write it as a new object type—this allows you to use the code anywhere in any experiment as well as have it work with all core functionality (timing, core visual options, staircasing, results output, etc.). You can make a quick type for your own use, or you can invest more time to make a durable type which has more flexibility and a fuller interface for an open range of users. PsychBench's element type framework facilitates the process. All the standard types that come with PsychBench are open source, so you can use them as examples and/or build off them.

Sharing object types

You can share an element type with other people by zipping the type's folder and sending it. To add a type you have received, just copy its folder into your local element types folder, then call pb_addPath to refresh PsychBench.

You can also contribute a type to the library that comes with PsychBench. If you would like to do this, please contact us. We would be happy to credit you. And thank-you!

Watch an introductory tutorial (~ 25 min) >

Watch the VSS 2022 Zoom talk (~ 5 min) >

Read the Getting Started >

PsychBench has been supported by