This document provides instructions and examples for using Psychtoolbox functions in MATLAB and Octave to precisely control stimuli display and response timing in psychological experiments. It demonstrates how to use functions like Screen, KbCheck, KbWait, and KbQueue to control screen display, present visual stimuli, measure reaction times, and record keyboard responses with millisecond precision. Examples show how to set up simple, go/no-go, and choice reaction time experiments to study mental chronometry and measure processing latencies using different task conditions.

1. “Day 3”:
Operating PTB functions on
MATLAB and GNU octave
Psychtoolbox (PTB)
practical course
by Volodymyr B. Bogdanov
vlabogd@yahoo.com
Kyiv/Lyon 2018
“This is really simple!”
ImpAct team, CRNL, Inserm

2. ScreenTiming Keyboard
Simplified experimental design
Inter-trial interval
Stimulus-stimulus interval
Stimulus-feedback interval
Set background
Prepare visual stimulus
Show stimulus
Clear the screen
Feedback time
Feedback quality (the key)
GetSecs
WaitSecs
Screen('OpenWindow‘)
Screen(‘DrawText’)
Screen(‘MakeTexture’)
Screen(‘Flip’)
KbCheck
KbWait
KbQueCheck

3. Good timing is critical !
Jean-Baptiste Mauzaisse
Le Temps montrant les
ruines qu'il amène
…because what we often
do is for studies of
perception, attention,
memory and other
mental processes is
Mental chronometry

4. GetSecs
WaitSecspause
clock/time
MATLAB/
GNU Octave PsychTooolbox
Functions for time measures
BETTER!
But how do we know
that PsychToolbox
functions are better?

5. Comparison of timing functions
% MATLAB
clear t; t1=clock; for i=1:10; t2=clock; t(i)=etime(t2, t1); pause(0.1); end;
% MATLAB + PsychToolbox
clear t; t1=GetSecs; for i=1:10; t2=GetSecs; t(i)=t2-t1; WaitSecs(0.1); end;
d=diff(t(2:end)); % point by point intervals of measured time
e=( max(d)-min(d) )*1000 % difference between maximal and minimal intervals in
milliseconds
% one interval:
t1=clock; pause(0.1); t2=clock; etime(t2, t1)
Loops are useful for a measure of variation in measured time intervals:
Calculation of serial intervals of temporal measures:

6. Keyboard
[ keyIsDown, seconds, keyCode ] = KbCheck
[secs, keyCode, deltaSecs] = KbReleaseWait
[secs, keyCode, deltaSecs] = KbPressWait
[secs, keyCode, deltaSecs] = KbStrokeWait
KbQueueCreate - create the queue.
KbQueueStart - start listening
KbQueueStop - stop listening
KbQueueCheck - check recorded keypresses
KbQueueRelease – delete the created queue
Interrupts script until keyboard input
(checks every 5 ms).
Works for background keypress
collection, good for brief single
keypresses.
If precise timing of the keypress is important, use:
KbCheck
KbWait or KbPressWait
KbQueueXXX
Current status of the keyboard,
used multiple times to create
keyboard status time series.

7. WaitSecs(1); % wait one sec so that all the keys are unpressed
for i=1:100000;
[keyIsDown(i),secs(i),keyCode]=KbCheck; % about 0.1 ms duration
end;
plot(secs-(secs(1)), keyIsDown); % plots status of keyboard against time of the sampling
KbCheck
[keyIsDown, secs, keyCode, deltaSecs] = KbCheck
Key was pressed?
1 – pressed
0 – no
Time of
keypress
256-element logical vector
indicating which key(s)
were pressed
Interval between the
current check and the
previous check
Test for keypresses with a looped KbCheck

8. [secs, keyCode, deltaSecs] = KbWait(devicenumber, forWhat, untilTime)
0 - Listen for key press
1 - Listen for key release
2 - Wait until all keys are released,
THEN wait for a key press
3 - Wait until all keys are released,
THEN wait for a key press
AND subsequent release
time to stop
waiting if no
kypress
KbWait (uses KbCheck)
devicenumber = GetKeyboardIndices
Time of
keypress
256-element logical vector
indicating which key(s)
were pressed
Interval between the
current check and the
previous check
WaitSecs(1);
secs(1)=GetSecs; % time of the start of waiting
disp('A')
[secs(2), keyCode, deltaSecs] = KbWait(0, 0, secs(1)+10);
delay=secs(2)-secs(1) % delay of the keypress
devicenumber
forWhat
untilTime: Start +10 sec

9. By default, all keystrokes are also sent to Matlabs window, generating some ugly
clutter. You can suppress this by calling ListenChar(2), so your MATLAB console
stays nice and clean.
Don't forget to call ListenChar(1) though before the end of your script.
ListenChar
DisableKeysForKbCheck
KbName('UnifyKeyNames') % assign unified keynames to all keys
KbName % press a key to get the name
KbName(‘DownArrow’) % check the index for this keyname
ans =
39
KbName('UpArrow') % check the code for this key
ans =
38
DisableKeysForKbCheck([38 39]);
Specify a vector of keycodes for keys which should be ignored by KbCheck and KbWait.
How to
identify the
key-indices?

10. KbQueue
[pressed, firstPress, firstRelease, lastPress, lastRelease] = KbQueueCheck
Array indicating
when keys were
first pressed
Array indicating
when keys were
first released
Key was pressed?
1 – pressed
0 – no
keyFlags = zeros(1,256); % an array of zeros
keyFlags([37 39])=1; % left and right arrows
KbQueueCreate(0, keyFlags); % initialize the Queue
WaitSecs(1); % wait until all keys are un-pressed
disp('A'); % stim.
secs(1)=GetSecs; % stim. time
KbQueueStart; % start recording
WaitSecs(5); % time for some keypresses
KbQueueStop; % stop recording
[pressed, firstPress, firstRelease, lastPress, lastRelease]=KbQueueCheck;
KbQueueRelease; % delete the created queue
firstPress(firstPress>0)-secs(1) % the post-cue of the first press of the keys
KbQueueCreate(deviceNumber, keyFlags) - create the queue.
KbQueueStart - start listening
KbQueueStop - stop listening
KbQueueCheck - check recorded keypresses
KbQueueRelease – delete the created queue
Selected keys
to acquire

11. Stimulus
Stimulus
KbQueueCheck
KbWait
Stimulus
KbCheck
onset offset
KbWait
Inters-stimulus interval
Inters-stimulus interval
Inters-stimulus interval
Time of response
Time of onset
Time of response
Time series of keyboard status
KbQueueStart

12. Keyboard keypress: 15-20 ms
+ and uncertain delay, which depends on upcoming processes
Mouse keypress: 8-15 ms resolution
Limitations of feedback temporal resolution
The alternative can be the audio-input or specialized keypads,
compatible with Psychtoolbox, e.g. RTBox (300 USD+).
PsychRTBox
http://lobes.osu.edu/rt-box.php

13. WaitSecs
GetSecs
KbName
KbReleaseWait
KbCheck
Screen('Preference'…)
Screen('Screens')
Screen('OpenWindow‘…)
Screen('xtFont', …)
Screen('TextSize', …);
Screen('DrawText', …);
Screen('FillOval', …);
Screen('Flip', …);
Timing
Keyboard
Screen
KbDemo
The KbDemo script has 253 lines of code (with %extensive comments)
Here are few examples of its Psychtoolbox functions:

14. Screen
Set background
Show shapes
Show text
Flip (refresh) the screen
Show textures(images)
Open/play movie
One of the most used function in Psychtoolbox.
It deals with a lot of tasks:
Prepare textures
We will use the most basic
options to build functional
scripts to run experiments
on Mental chronometry

15. Mental Chronometry
Using reaction times to understand cognitive
processes: subtractive method of latency
analysis to measure the time of internal mental
processes (1868).
Franciscus (Franz) Cornelius
Donders
Dutch ophthalmologist. 1818-1889
Detect
Stimulus
Press
Button
Detect
Stimulus
Press
ButtonDiscriminate
Feature
Detect
Stimulus
Press
Button 1
Discriminate
Feature
Choose
Button
Choice Reaction Time (CRT)
Simple Reaction Time task (RT)
Go/No-Go task (GnG)
No
Press
Press
Button 2
RT<GnG<CRT
GnG-RT: discrimination latency
CRT-GnG: response selection latency

17. Write our script for the experiment of Donders
But first we need to know how to set the screen on
whichScreen = max(Screen('Screens')); % list the indexing of the screens
[ window, rect ] = Screen('OpenWindow', whichScreen, [175 175 175]);
% initialize working window on the first screen, gray background
COLOR – [R G B]
red – [255 0 0]
yellow – [255 255 0]
green – [0 255 0]
blue – [0 0 255]
black – [0 0 0]
gray – [175 175 175]
white – [255 255 255]
window
id of the onscreen window
where subsequent graphical
operations will be executed
rect
screen coordinates
(origin at upper left)
[x1 y1 x2 y2]
Screen
x1=0
y1=0
x2
y2
e.g. rect = [0 0 1336 768 ]
width
height

18. Why do we try to catch something?
To avoid freezing!
try
… your Psychtoolbox program
catch X
sca % stops all Psychtoolbox operations
end
This variable contains the error massage and the line of the error

19. DrawDot
HideCursor; % hide cursor
Mouse cursor which stays at the top of
the screen is not nice, so it is better to
remove it at the beginning of the script.
However, we wish to show something
instead, for example, a dot.
centerXY=[rect(3)/2 rect(4)/2];
% XY coordinates of the center of the screen
Screen('DrawDots', window, centerXY, 20, [0 0 0]);
% drawing a big black rectangular dot in the
center of the screen
size, in
pixels
color
This function draws a dot into the
frame back-buffer, which will be exposed at
the frame front-buffer only after the “flip”.

20. 'I was wondering what the mouse-trap
was for,' said Alice. 'It isn't very likely
there would be any mice on the horse's
back.‘
'Not very likely, perhaps,' said the
Knight; 'but, if they do come, I don't
choose to have them running all about.'
Flip
[VBLTimestamp]=Screen('Flip', window);
[VBLTimestamp]=Screen('Flip', window);

21. Time
Stimulus duration - 1 sec.
Stimulus duration - 1 sec.
Inter-stimulus interval (ISI) - 1 : 3 sec.
Keypress acquisition during
2 sec after stimulus onset
Stim. ISI Stim.
Key recorded
The structure of the experiment
2 sec

22. Conditions and inter-stimulus intervals
cond=repmat([1 2], 1, 5); % generate an array of conditions,
1 and 2 repeated 5 times (1 for red, 2 for green)
cond =
1 2 1 2 1 2 1 2 1 2
cond=cond(randperm(10)); % randomize order of conditions
cond =
1 1 1 1 2 2 2 1 2 2
ISI=repmat([0:0.5:2], 1, 2); % inter-stimulus intervals will have 5 specific values
ISI =
0 0.5 1.0 1.5 2.0 0 0.5 1.0 1.5 2.0
ISI=ISI(randperm(10)); % randomize ISI
ISI =
0 1.5 0.5 0 2.0 0.5 1.0 1.5 2.0 1.0
Predefined and randomized

23. RT=-ones(1, 10); % an array of ones
for recording of reaction times
RTkey=-ones(1, 10); % an array of
minus ones for recording of the keys
Prepare the KbCue object and data arrays in advance !
keyFlags = zeros(1,256); % an array of zeros
keyFlags([37 39])=1; % left and right arrows, left for red
KbQueueCreate(0, keyFlags); % initialize the Queue
Always remember the logic of the
White Knight!

24. Screen('DrawDots', window, centerXY, 20,
[250*(cond(i)==1) 250*(cond(i)==2) 0]); % colored dot
Presentation of color conditions in the for loop
Screen('DrawDots', window, centerXY, 20, [0 0 0]); % black dot
Screen(window, 'flip', VBLTimestamp+1);
Timing of the stimulus offset one second post-onset
color, red or green as a function of the cond(i)
[VBLTimestamp]=Screen(window, 'flip');
KbQueueStart; % start recording
Stimulus onset!
VBLTimestamp – the time of the vertical blink (VBL), which is the time of ongoing
screen refresh (see the PTB manual)
for i=1:10;…
end; % trial loop

25. [pressed, firstPress, firstRelease, lastPress, lastRelease]
=KbQueueCheck; % retrieve the created queue and clean it
if pressed==1;
RT(i)=firstPress(firstPress>0)-VBLTimestamp; % the
post-cue of the first press of the keys
RTkey(i)=find(firstPress>0);
end;
Retrieval of the outcome of recording of current trial’s response
Recording of the KbCue after a delay of 1 more second post-offset
WaitSecs(1); % in total waitong for responce up to 2 seconds
KbQueueStop; % stop recording
WaitSecs(0.5); KbQueueStart; WaitSecs(2);
[pressed, firstPress, firstRelease, lastPress, lastRelease]=KbQueueCheck
Reminder (how to test the functioning of KbQueueCheck):

26. Save data each run in a different file
t = clock; % current time
DateString = datestr(t, 'yyyy-mm-dd-HH-MM'); % convert it into a string
filename=['RT_results_', DateString]; % forming a filname string
save(filename, 'RT', 'RTkey', 'cond'); % saving imortant variables into a mat file

27. Analysis of the reaction time data
For the simple reaction time task one can analyze the RT variable, since
there is no "wrong answer". But we pick just RTs > 100 ms, whish rejects
misses (equal to -1)
good_RT=RT(RT>0.100);
n_RT=length(good_RT);
figure
hold on
plot([1:n_RT]/n_RT, good_RT, '.');
plot( [1, n_RT]/n_RT,[mean(good_RT), mean(good_RT)])
Plotting the individual RTs and the mean

28. For Go-NoGo task one picks just the responses of the right key (37) to
the first (red) condition
% 2. Go-NoGo just red
correct=(cond==1)*37; % left arrow for red
RT=RT(correct==RTkey);
Analysis of the Go-NoGo reaction time data
cond = 2 2 2 1 1 1 1 2 1 2
correct = 0 0 0 37 37 37 37 0 37 0
RTkey = -1 -1 -1 37 37 37 37 -1 37 -1
correct==RTkey
0 0 0 1 1 1 1 0 1 0
RT= -1 -1 -1 0,397 0,375 0,415 0,525 -1 0,686 -1
RT(correct==RTkey) = 0.397 0.375 0.415 0.525 0.686
plot([1:n_RT]/n_RT+1, good_RT, 'r.');
plot([1, n_RT]/n_RT+1, [mean(good_RT), mean(good_RT)], 'r')

29. % 3. 2-choise task, correct RTs
correct=(cond==1)*37+(cond==2)*39;
% left arrow for red,
% right arrow for green
RT=RT(correct==RTkey);
For two-choice reaction time task we must pick just the responses of the right key
(37) to the first (red) condition and left key (39) to the second (green) condition.
plot([1:n_RT]/n_RT+2, good_RT, 'r.');
plot([1, n_RT]/n_RT+2, [mean(good_RT), mean(good_RT)],
'r');
Analysis of the two-choice reaction time data

30. Posner letter matching task
Michael I. Posner
Professor Emeritus, Department
of Psychology Member, ION
Posner (1967) recognition of a pair of letters.
The simplest task was the physical match
task.
The next task was the name match task.
The rule match task (whether the two letters
presented both were vowels or consonants)
is the hardest one.
Physical match: AA + Bb – Cd – ef –
~70 ms
Name match: AA + Bb + Cd – ef –
~70 ms
Rule match: AA + Bb + Cd + ef –