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 and time consuming process. 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 both the flexibility and precision that is important to Psychtoolbox users. You can choose between a visual method based in any spreadsheet app (e.g. Microsoft Excel, Apple Pages, Google Sheets, etc.), or a coding method using a MATLAB script. PsychBench's open-source library (MATLAB + Psychtoolbox) comes with a range of stimulus and functionality types that plug into any experiment. You can also add your own stimulus types to the library.

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 run it from the MATLAB command line. You can type help pb_install for more information.

You'll also need...

Windows / macOS / Linux – 64-bit

MATLAB R2017a or later
(R2019a+ for visual method of making experiments, R2021a+ recommended)
PsychBench does not run in GNU Octave.

Psychtoolbox most recent version (free)

Psychtoolbox requires GStreamer (free):
        Windows: GStreamer 64-bit MSVC runtime 1.22.5
        macOS – Intel and ARM: GStreamer runtime 1.22.1
        Linux: (generally already installed)
        Note Homebrew installations of GStreamer will not work.

System requirement details >

Update history >

(Trouble updating?)

In earlier versions, bugs in Google's cloud API may preventing updating (newer versions use a different cloud service). If you get an error using pb_update, please update manually: 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

Visual method

In the visual method lay trials out in one or more tables in any spreadsheet app (Microsoft Excel if you want to use drop-down menus in headings). Columns correspond to properties of objects of various types (e.g. picture, text, sound, keyPress, etc.). Property values are MATLAB values or expressions. You only need to write each distinct row (trial) once, and in any order. Then use one more MATLAB expression to set a list of trials to run through, including any repetition and ordering. Save or export to an Excel file, use the command loadExperiment in MATLAB to load it, and runExperiment to run it.

For example, the two tables below would make an experiment that runs 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 picture file name and response latency for each trial. (This is an extremely minimal example—just enough to see the basic idea! Lots of options not shown here allow efficiently building complex experiments.)

Coding method

You can always use the coding method instead if you prefer. In the coding method make objects, set properties, and define trials line by line in a MATLAB script. You can use for loops through conditions to automate defining trials. For example, this script would build and run the same experiment as above:

Without PsychBench

Just for comparison, here is some compact Psychtoolbox code that would run the same experiment, with the same timing precision and error handling. The difference with/without PsychBench is already noticeable here but it balloons up for more realistic experiments.

Core features

In the visual method make experiments in any spreadsheet app. Options allow for any MATLAB expression, generating combinations, repetition, randomization, dependent expressions, conditional expressions, different trial structures (intros, breaks, syncs, etc.), and more. Alternatively use the coding method in a MATLAB script if you prefer.
Organize experiments in terms of objects from a library of object types. 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.
Sync experiments with external devices like scanners within or across 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, custom shaders, additive blending, 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, etc.
Stereo display by most of the modes available in Psychtoolbox.
Sound playback and recording built on Psychtoolbox's high-precision PortAudio functions.
Various tools and functionality facilitate replication, randomization, system-dependent key names, recording visual stimuli to images/movies, etc.
Core response functionality including recording responses, times and latencies, translating response values, scoring, and more. More specific functionality is in each response handler object type (key press, text, mouse, button box, etc.).
Method of adjustment experiments where the subject can adjust object properties in real time. More specific functionality is in each adjuster object type (key press, mouse, etc.).
Staircase any property of any object using staircase objects (fixed step, QUEST, 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 or custom information, saved in both .mat and .csv files.

Open-source object type library

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

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 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 and have it work with all core functionality (timing, core visual options, staircasing, results output, etc.). You can make a quick type for a limited number of experiments, or you can make a durable type with more flexibility and a fuller interface for other users. 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 object type with other people just by zipping the type's folder and emailing it.

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!

Getting started / Making an experiment >

Tutorial video

All documentation >

PsychBench has been supported by