Test Visual Stimulus Onset Timing using Keyboard Events !?

^{Originally posted on March 6, 2019.}

In this post we look at how to use the MilliKey DeLux light sensor upgrade to test visual stimulus onset timing using PsychoPy Coder by checking for a keyboard event.

The MilliKey DeLux is an affordable and easy to use light sensor attachment for MilliKey response boxes. The MilliKey DeLux can generate light level driven 1000 Hz USB serial or keyboard events that are read by the same experiment software controlling visual stimulus presentation.

In a previous post about Testing PsychoPy event.waitKeys() Event Timing, we demonstrated how to use the MilliKey to test the keyboard event time stamping accuracy of the experiment software. This was achieved by sending USB serial messages from the experiment software instructing the MilliKey to generate keyboard events and then comparing the key press time to the time the serial message was sent. We found that, at least on Windows and Linux, PsychoPy can accurately time stamp MilliKey 1000 Hz keyboard events with one millisecond average delay and sub-millisecond variability.

One of the unique features of the MilliKey DeLux is that it can be configured to generate a letter ‘l’ key press event when the light sensor brightness crosses a trigger threshold level. This allows you to assess visual stimulus onset timing of an experiment by using the standard keyboard event handling functionality of the software being used.

PsychoPy Coder Test Script

Lets start by creating a simple PsychoPy Coder demo that repeatedly:

• clears the screen to black
• draws a white screen
• waits for a keyboard press event
• prints time difference between reported keyboard event and stimulus onset (white screen) times.

#!/usr/bin/env python
# -*- coding: utf-8 -*-
from __future__ import absolute_import, division, print_function
from psychopy import visual, event, core

# Number of dark -> light display change tests to run
test_count = 10

# Create a full screen window and two full screen stim.
win = visual.Window(fullscr=True, screen=0)
white_stim = visual.ShapeStim(win, lineColor='white', fillColor='white',
                              vertices=((-1,-1),(1,-1),(1,1),(-1,1)))
dark_stim = visual.ShapeStim(win, lineColor='black', fillColor='black',
                             vertices=((-1,-1),(1,-1),(1,1),(-1,1)))

# draw / setup both stim
white_stim.draw()
dark_stim.draw()
win.flip()

# Manually press any key to start test
event.waitKeys(timeStamped=True)

print("trial\tRT\tkey_time\tflip_time\tkey")
# run test_count loops
count=0
while count < test_count:
    # Draw black screen and display it for about 0.5 seconds.
    dark_stim.draw()
    win.flip()
    core.wait(0.5)
 # Throw away any possible junk keys
 # prior to changing display 
    event.getKeys()
 
    # Draw white (target) stim and flip to it,
    # getting time flip occurred (stim onset)
    # time from psychopy.
    white_stim.draw()
    ftime = win.flip()

 # Key keyboard event and print time difference between
 # flip() time and keypress time.
    k, ktime = event.waitKeys(timeStamped=True)[0]
    kdelay = ktime - ftime    
    print("%d\t%.6f\t%.6f\t%.6f\t%s"%(count, kdelay, ftime, ktime, k))

    core.wait(0.25)
    count+=1

We have basically created the most simple of manual reaction time tests. Run the above script from PsychoPy Coder and press a key as quickly as you can each time the screen turns white.

For example, running the example and manually pressing the space key, I get output like:

trial	RT	key_time	flip_time	key
0	0.368140	1.687949	2.056089	space
1	0.171302	2.570518	2.741820	space
2	0.197275	3.256913	3.454187	space
3	0.198487	3.967356	4.165843	space
4	0.196070	4.679771	4.875841	space
5	0.215323	5.390571	5.605894	space
6	0.197549	6.118132	6.315682	space
7	0.193179	6.828715	7.021894	space
8	0.166193	7.535785	7.701978	space
9	0.193039	8.214774	8.407813	space

So far this has all been kind of boring right?

What if we could use this exact script to test the visual onset timing of the white screen? Lets do it using the MilliKey DeLux.

MilliKey DeLux Setup

For this test to work we first need to make sure the MilliKey DeLux is configured to:

1. use a sensible threshold level for the monitor being Generate Keyboard Events.
2. auto generate light sensor triggered keyboard events.

Lets do this using the LabHackers’ Device Manager application.

MilliKey DeLux light sensor settings are found on the DeLux tab of the LabHackers’ Device Manager application.

For this example use the following settings:
Trigger Type: ‘Keyboard Event’
Trigger Delay: 5 msec
Enable Background Processing: Checked / True

The Trigger Threshold setting can be set using the auto threshold feature of the Light Sensor Dialog. The following video is a screen capture from a Windows 10 computer running the Labhackers’ Device Manager application. It illustrates using the auto threshold feature to set the light sensor threshold to an appropriate level for the monitor being tested. The MilliKey DeLux hardware, which can not be seen in the video, was placed over the white rectangle of the test dialog on the LCD monitor.

After you have configured the MilliKey DeLux to generate ‘offline’ keyboard events, and have exited the LabHackers’ Device Manager, the MilliKey will generate a ‘l’ key press event 5 milliseconds (Trigger Delay) after screen brightness crosses the threshold level set. Each key press lasts 123 msec, at which time a key release event is sent by the MilliKey.

Note: Once the MilliKey DeLux is armed and ready to create keyboard events, if the light level hitting the is not controlled you may get a bunch of letter ‘l’s being typed on your computer. If you want to abort this test and get the MilliKey to stop generating keyboard events, unplug the MilliKey USB cable from the computer and reconnect it. This turns off the Enable Background Processing setting, which is disabled by default when you first connect the MilliKey to a computer.

Results

For this test we used a Windows 7 computer connected to a CRT monitor running at 60Hz. We used a CRT monitor because there is effectively no delay between when a video card starts a screen retrace and when the top left corner of the CRT monitor starts displaying update. In contrast LCD / TFT monitors all have a response time, which can range between 1 and 10+ msec depending on the monitor model.

trial   RT      key_time        flip_time       key
0       0.004892        4.412357        4.417248        l
1       0.005464        5.188762        5.194226        l
2       0.005237        5.976979        5.982216        l
3       0.005049        6.765145        6.770194        l
4       0.004792        7.553340        7.558132        l
5       0.005583        8.341535        8.347118        l
6       0.005390        9.129753        9.135143        l
7       0.005198        9.917925        9.923123        l
8       0.005766        10.694352       10.700118       l
9       0.005555        11.482574       11.488128       l

Since a CRT monitor was used, the time difference between win.flip() and when the CRT actually starts being updated should be 0.0 msec. Remember that we set the MilliKey DeLux to generate the key press event 5 msec after the stimulus onset was detected by the device hardware, so if win.flip() is accurate, the delay calculated by the test should be 0.0 after we subtract the 5 msec event delay specified in the device settings.

As the following table shows, they are:

It is important to note that using keyboard events as light sensor triggers is only suggested on systems that provide accurate keyboard event timing. Therefore we can not suggest this method for PsychoPy testing on macOS at this time. macOS users should use the Serial event mode, which we will demonstrate in a future post.

Next

The MilliKey DeLux keyboard event mode is very useful for testing stimulus onset timing in experiment software that you know provides accurate keyboard event timing and when you can not, or do not, want to add custom code to your experiment.

If the keyboard event time stamping accuracy of the software being used is poor, or you would rather not get light sensor triggers as keyboard events, then you can use USB Serial events instead. In the next MilliKey DeLux post, we will look at using the Serial trigger type to test stimulus onset timing in a PsychoPy Coder experiment.

Happy Hacking!