In a memory experiment, you might want to do the following:

  1. Show people some objects

  2. Let the objects disappear

  3. Show some items and ask participant to click those she remembered

There are other experiments where you want to have the opportunity for people to select objects this way, for example in visual search experiments.

This is a fairly common situation. You also want that when people select an item erroneously, they can undo their selection and choose something else instead (clicking a second time will undo, try it yourself in the demo below). You might also want to set the minumum and maximum number of items one can select.

This is all very simple to do with the choose function in PsyToolkit experiments.

Running the code

First run the experiment to see what it does.

Click here to run a demo of the task

Download the code

The PsyToolkit code

# in this task, a 3x3 grid is shown with 9 possible places (counted
# from position 1 to position 9). You need to remember the locations
# of the 3 crosses. When the question marks appear, you need to select
# the 3 original locations based on your memory.

bitmaps
  instruction
  frame
  cross
  question
  selector
  welldone
  errorfeedback
  exitbitmap1
  exitbitmap2

# in the table, first the three positions (1-9) and then their actual x,y coordinates

table places
  1 2 3   -200 -200   0 -200     200 -200
  2 4 6      0 -200   -200 0     200 0
  4 5 9   -200  0     0 0        200 200
  1 7 9   -200 -200   -200 200   200 200

task memorize
  table places
  mouse hide
  show bitmap frame
  show bitmap cross @4 @5
  show bitmap cross @6 @7
  show bitmap cross @8 @9
  #-----------------------------
  delay 1000 # memorize the crosses
  #-----------------------------
  show bitmap question -200 -200 # position 1 , stimulus 5
  show bitmap question    0 -200 # position 2
  show bitmap question  200 -200 # position 3
  show bitmap question -200    0 # position 4
  show bitmap question    0    0 # position 5
  show bitmap question  200    0 # position 6
  show bitmap question -200  200 # position 7
  show bitmap question    0  200 # position 8
  show bitmap question  200  200 # position 9 , stimulus 13
  #-----------------------------
  mouse show
  choose option exit exitbitmap1 exitbitmap2 350 250
  choose option minselect 3
  choose option maxselect 3
  choose option select selector
  choose 99999 5 13
  #-----------------------------
  # CHOSEN_1 etc start at value 5 (5th bitmap shown)
  # It is easier if they start with 1 for table comparison
  set $x1 expression CHOSEN_1 - 4
  set $x2 expression CHOSEN_2 - 4
  set $x3 expression CHOSEN_3 - 4
  #-----------------------------
  if $x1 == @1 and $x2 == @2 and $x3 == @3
    show bitmap welldone
  fi
  if $x1 != @1 or $x2 != @2 or $x3 != @3
    show bitmap errorfeedback
  fi
  delay 2000
  clear screen
  save RT CHOSEN_N CHOSEN_1 CHOSEN_2 CHOSEN_3

block test
  message instruction
  tasklist
    memorize 3 fixed
  end

Code explained bit by bit

Below, the different sections are explained one by one.

Lines starting with the #-sign are human-readable comments. Below they are not included.

Telling the computer which bitmaps to use

This task uses 8 different bitmaps. For each, there is a corresponding file ending with the PNG extension. PsyToolkit figures out which filename to load, for example, for instruction it will assume there is a file instruction.png, etc.

For the exit button, we have exitbitmap1 (bright green, meaning the participant is allowed to exit) and exitbitmap2 (darkgreen, meaning the participant does not yet have selected the needed number of objects). 
bitmaps
  instruction
  frame
  cross
  question
  selector
  welldone
  errorfeedback
  exitbitmap1
  exitbitmap2

Defining the 4 experimental conditions

You do not always need a table, but it makes life easier. In short, a table defines the different conditions. Each line represents a condition. Because there are 4 lines in this table, there are thus 4 different conditions.

In this example, there are 9 different colums, each of which can be referred to with the @ sign. @1 refers to the first column, @2 to the second, etc.

Here is what the 9 columns stand for in this example (you can have as many columns as you like).

For this to understand, you need to know that there is a 3x3 grid on the screen with positions counting from 1 (top left) to 9 (bottom right). The three to-be-remembered crosses are in 3 of these 9 positions.

  1. The first position of the grid where a cross is

  2. The second position of the grid where a cross is

  3. The third position of the grid where a cross is

  4. The X-position of the 1st stimulus

  5. The Y-position of the 1st stimulus

  6. The X-position of the 2nd stimulus

  7. The Y-position of the 2nd stimulus

  8. The X-position of the 3rd stimulus

  9. The Y-position of the 3rd stimulus

The computer selects one line on each trial when the task is being run through. Because the option fixed is later used (see block below), the computer will start with the first line and go down one each trial (i.e., fixed order). 
table places
  1 2 3   -200 -200   0 -200     200 -200
  2 4 6      0 -200   -200 0     200 0
  4 5 9   -200  0     0 0        200 200
  1 7 9   -200 -200   -200 200   200 200

The task

A task is a crucial element of an experiment. A task has a name (here memorize) and there are multiple instructions, one on each line. The various parts of the task are described in detail below. The first line is the name.

Naming the task and some initial stuff

Below, we tell the computer that the task is called memorize and that this task uses the table called "places", as defined above.

task memorize
  table places

showing stimuli

In this task, we hide the mouse (mouse hide) when the participant see the to-be-memorized locations. This so that the participant cannot go to the to-be-memorized positions with the mouse, which would make the task easier to do.

We then show 4 stimuli simultaneously. We put the show instructions between draw off and draw on. This makes that the computer puts them all 4 on the screen exactly at the same time. Basically, draw off tells the computer to stop actually drawing the stimuli until draw on. Then they all 4 come on screen exactly at the same time.

  mouse hide
  show bitmap frame
  show bitmap cross @4 @5
  show bitmap cross @6 @7
  show bitmap cross @8 @9

Now we show the to-be-memorized stimuli for 1000 ms and then draw question marks in all 9 positions of the grid. Note that each shown stimulus has a number. Given that the we have already shown 4 stimuli before, we are now about to show the fifth (until the 13th).

Also note that the stimuli between draw off and draw on will be shown exactly at the same time. Basically, draw off tells the computer, "do not draw anything until I say draw on".

  delay 1000 # memorize
  show bitmap question -200 -200
  show bitmap question    0 -200
  show bitmap question  200 -200
  show bitmap question -200    0
  show bitmap question    0    0
  show bitmap question  200    0
  show bitmap question -200  200
  show bitmap question    0  200
  show bitmap question  200  200

Using the choose instruction

Now we show the mouse again. We set some choose options:

choose option exit exitbitmap1 exitbitmap2 350 250 tells the computer where to show the "exit" button, its two different possible looks (the first one is the one when the participant has selected the correct number of objects). The XY position 350,250 is where the exit bitmap is shown.

choose option minselect 3 We say that we want minimally 3 objects to be selected (if not, the exitbitmap2 is shown)

choose option maxselect 3 We say that we want maximally 3 objects to be selected

choose option select selector We say which bitmap to shown over a selected object when a location is selected

choose 99999 5 13 tells the computer to let the participant select bitmaps (those with numbers 5 to 13) for up to 99999 ms (which is more than a minute). Note that we show the mouse beforehand, because it was hidden before.

 mouse show
 choose option exit exitbitmap1 exitbitmap2 350 250
 choose option minselect 3
 choose option maxselect 3
 choose option select selector
 choose 99999 5 13
The nice thing of choose is that objects can be selected and deselected (by clicking a second time).

Recalculating some variables

The choose instruction creates variables. CHOSEN_1, CHOSEN_2, and CHOSEN_3 refer to the bitmap numbers selected. Because they start from 6 (the 6th bitmap is the first of the grid position) it is nice to subtract 5 of them, that way we have the exact grid position numbers between 1 and 9. We save that in three new variables called $x1, $x2, and $x3.

  set $x1 expression CHOSEN_1 - 4
  set $x2 expression CHOSEN_2 - 4
  set $x3 expression CHOSEN_3 - 4

Checking correctness of responses

Now we simply check if the chosen bitmaps are those as expected.

chosen will put them in numerical order, starting with the lowest, even when that was not the first clicked one. 
  if $x1 == @1 and $x2 == @2 and $x3 == @3
    show bitmap welldone
  fi
  if $x1 != @1 or $x2 != @2 or $x3 != @3
    show bitmap errorfeedback
  fi

coming to the end

We create some delay and then clear the screen.

  delay 2000
  clear screen

saving data to file

We now save the data in a file. We could alternatively have saved $x1 etc, but this is just for example reasons.

  save RT CHOSEN_N CHOSEN_1 CHOSEN_2 CHOSEN_3

The block

The last part is the block. Blocks are crucially important. This is actually where the code starts, so to speak. This block here has a sequence as follows:

  • A message, showing the bitmap instruction

A message instruction shows a bitmap and then waits for a key press on the space bar. You can have multple messages in a block. For example, you could have a thank you message after the task list.

  • A tasklist, which calls the task my_task exactly 3 times.

You can have more than one task, but here we have just one. The different conditions, etc, are being handled by my_task.
The fixed option makes that each condition defined in the table is used in a fixed order, starting with the first line. 
block test
  message instruction
  tasklist
    memorize 3 fixed
  end