Measuring keyboard response times with 'readkeys'

In the gif image above you see an example of what readkeys can look like (do the demo below to see it for yourself as a real experiment).

Before you go on with this, make sure you understand the basics of writing PsyToolkit experiment scripts. This is a somewhat more sophisticated PsyToolkit feature.

For entering multiline texts, check this textbox instruction.

In some cognitive psychological experiments, you need participant to enter a multiple letters or numbers or words/sentences.

For example, if you do a memory experiment in which people need to remember 5 numbers, you need a way for people to type them in with the keyboard. For this, use readkeys.

Difference between readkey and readkeys:

readkey just waits for exactly one response key, this is often used (see link above)

readkeys lets people type in multiple keys, and also show the letters/numbers directly on the screen

Main command

readkeys is an instruction that is used in a PsyToolkit task.

For it to work well, there are a number of different options that you would provide before using the line with readkeys

In the readkeys instruction, there are 2 "arguments", namely which word (letter or number combinations) needs to be typed in, and second, how long the computer should wait for the typing to be done.

If there is no correct word, you can just use anything for the first argument and then later ignore the system variable STATUS.

You will learn most from just looking at the commented example below.

At the end, the computer will tell you what words was typed in, whether it was a correct or wrong response, and how long it took the particant to type in the response.

Participants finish typing the word/numbers by pressing the ENTER/RETURN key on the keyboard (i.e., the big key you normally use for a new sentence). People can use the DELETE key to remove the already typed.

Note that you only get the RT for finishing entering.

The word "readkeys" refers to the fact that the computer "reads" information from the keyboard. It has nothing todo with human reading behavior.

The letters displayed on screen are always CAPITALS. This may change in future versions.

Basic example of readkeys

In the most basic example of readkeys, we have a simple task. We show a word on the screen, and participants need to type it. On screen, a number of small rectangles, one for each letter/number.

In the example below, the experiment has a table of 5-letter words/numbers and the participatant is asked to type one in. Try it for yourself.

Click here to run a demo of the task

Download the code

The code explained step by step

fonts (1)
  arial 24

table my_words  (2)
  "HELLO"
  "TRUCK"
  "PIZZA"
  "APPLE"
  "12345"

task test  (3)
  table my_words (4)
  show text "Type the word below (followed by return)" -200 -200   0 255 0 (5)
  show text @1 0 -150   0 255 0 (6)
  show rectangle 0 0 20 20   0 255 0 (7)
  text color yellow (8)
  readkeys option size 5 (9)
  readkeys option placeholders 30 30 (10)
  readkeys @1 100000 (11)
  clear screen (12)
  if STATUS == CORRECT (13)
    show text "Well done" (14)
  fi (15)
  if STATUS == WRONG
    show text "You made a mistake"
  fi
  delay 1000
  clear -1
  delay 1000
  save WORD RT STATUS (16)

block test (17)
  tasklist
    test 5 fixed (18)
  end

1	When using readkeys, you need to have a fonts section in your options to tell PsyToolkit what the used letters should look like. Here we use simple Arial font of 24 points
2	We have a table here with 5 different words. One of the words will be chosen each trial.
3	Here we start our task, which we call test. Nothing new so far.
4	We tell PsyToolkit tah we use the table called my_words from which we take the to be shown 5-letter words/numbers.
5	We show an instruction text at top of screen (0 -200) in the color green (0 255 0).
6	We now show the word from the table row that is being used in this specific trial. Note that @1 refers to the row being used by PsyToolkit. The rest of the text line shows where the text is shown (0 -150) and the color green (0 255)
7	Now we show a small rectangle at screen center (0 0) just to capture people’s attention. It is 20x20 pixels and again green
8	Now we say that the color of the text to be shown in the future should be yellow
9	Now readkeys starts. Here we set an option, namely that there are 5 spaces for letters (you can adjust this to your needs)
10	Now we say that we show place holders on screen of 30x30 pixels. This results in the purple rectangle space for the letters.
11	Now we say that we want a word to be typed. First, we say what the correct word is we expect (in our case, it is defined by the first column of our table, that is @1). Then we say we will wait up to 100000 ms (i.e., 100 seconds) for people to finish typing in the word. People finish the word by typing the return key.
12	Now that people are done, we clear the whole screen
13	If the typed word was correct (i.e, STATUS == CORRECT), then do the lines up to the "fi" line
14	Write at screen center "Well done".
15	This indicates the end of the if block. Why fi? fi is the reverse spelling of if.
16	Save the data. The typed letters will be saved by using the variable WORD here. In the output file, word will be put in quotes.
17	The block, this is explained elsewhere.
18	In this example code we use fixed order. All that matters is that the words of the table are chosen in the order of the table. Without this fixed option, they would be randomly chosen.

The complete file

fonts
  arial 24

table my_words
  "HELLO"
  "TRUCK"
  "PIZZA"
  "APPLE"
  "12345"

task test
  table my_words
  show text "Type the word below (followed by return)" 0 -200   0 255 0
  show text @1                      0 -150   0 255 0
  show rectangle 0 0 20 20   0 255 0
  text color yellow
    readkeys option size 5
    readkeys option placeholders 30 30
  readkeys @1 100000
  clear screen
  if STATUS == CORRECT
    show text "Well done"
  fi
  if STATUS == WRONG
    show text "You made a mistake"
  fi
  delay 1000
  clear -1
  delay 1000
  save WORD RT STATUS

block test
  tasklist
    test 5 fixed
  end

Advanced options

Readkeys has more options you can use.

Specific fontname

If you have more than one font in your fonts section (which may happen), then you can specify which font to be used.

Example

readkeys option font my_other_font

Spacing between letters

In the example, there is the same spacing between all letters. You do not need to use that. Instead, the word can just shown as it would normally in a text processor. That is, some letters take less space than others. That is actually the default, so if you want that, you do not need to use the options below.

If you want equal spacing between the letters or numbers, you can specify exactly how far the letters to be typed should be spaced out.

You can specify the number of pixels, the default is 30.

Example

readkeys option space 21

Storing all data

Sometimes, you want to know the reaction time (RT) for each individual letter and you want to know exactly which letters were typed in and then corrected.

There are two system variables in addition to RT and WORD.

The READRTS gives the reaction time for each key press

The READKEYS gives the name of the key press

The simplest way of storing this is to have a separate line for storing these. You then later best use some custom scripting language to analyse your data.

Example

save READRTS
save READKEYS