• This is an overview of all experiment commands for advanced users

  • This is for those who just want to have a quick overview of all that is possible

  • Links to the more detailed documentation are given throughout

PsyToolkit code consists of sections, such as options, bitmaps, task, and block. Sections must be separate by an empty line.
All text followed by a # is a comment for humans; PsyToolkit ignores it.

Options

Options are not needed. They are typically for advanced use only.

Examples of options. Note that color can be provided in different formats. options that are related to one another are shown together
options
  background color grey
  background color FFFF00
  background color 255 255 0

  mouse on
  mouse off

  startbutton text "your own text"
  loading text "your own text"

  set &my_variable 800
  set &&my_array 2 4 1 2

  var in &my_var
  var out &my_out

  bitmapdir stimuli
  sounddir stimuli
  fontdir stimuli

  fullscreen
  scale
  resolution 1000 800
  frame 1000 800

Stimulus loading

Bitmaps, sounds, fonts, and videos are loaded in separate sections. If you just specify a name without extension, PsyToolkit will use that and find extenion (such as png, jpg, or mp3) itself. You can specify a filename if you want to.

bitmaps
  mystimulus
  otherstimulus filename.jpg
  house http://www.my-website.com/house.png

sounds
  mysound
  myothersound xyz.mp3
  house http://www.my-website.com/music.mp3

fonts
  small arial 10
  normal arial 24
  big arial 60
  times 10
  courier 20

videos
  clip1 https://www.dropbox.com/s/kzo7sx7hkdai16i/beetle.mp4?dl=0
Note that if you do not specify a font, the default font (arial 20) will be used.

Tasks

A task a description of what happens (typically) in one trial. Each task has its own name.

task mytask

Task: Visual Stimuli

bitmap

show bitmap
show bitmap x y

(without x y coordinates, presentation will be in center)
show bitmap my_image
show bitmap my_image 200 100
show bitmap my_image -300 -150

rectangle

show rectangle x y width height
show rectangle x y width height colorname
show rectangle x y width height R G B

(without color, white or previously set default color will be used, see color)
show rectangle 0 0 50 100  green
show rectangle 0 0 50 100  0 255 0
show rectangle 0 0 50 200
When no color is specified, it is either white or as defined previously by color.

circle

show circle x y diameter
show circle x y diameter colorname
show circle x y diameter color

(without color, white or previously set default color will be used, see color)
show circle 0 0 50  red
show circle 0 0 50  255 0 0
show circle 0 0 50

line

show line x1 y2 x2 y2 width R G B
show line x1 y2 x2 y2 width colorname

(Line is drawn beteen x1,y1 and x2,y2)
show line -200 0 200 0  5  green
show line 10 20 200 50  3  0 255 0

Task: clear and clear screen

clear stimulus_number
clear screen

(Stimuli are counted whenever command show is used, first stimulus is 1, second is 2, etc)
clear 2
clear -1
clear screen
Negative numbers indicate the previous stimuli. For example, clear -1 removes the last presented stimuulus

Task: relocate and move

Relocate shows a stimulus at a different location than it currently is. Move shows a stimulus at a different location relative to its current position.

relocate stimulus x y
move stimulus x y
Relocate stimulus 1 to x,y position 100,200
relocate 1 100 200
Move stimulus 10 pixels to the right, but keep vertically the same
move 1 10 0

Task: hide and unhide

Hide removes a stimulus from screen, but can later be shown again with unhide. Hide and clear do essentially the same.

hide stimulus
unhide stimulus
Make a stimulus go on and off several times to attract attention
show rectangle 0 0  50 50
delay 200
hide 1
delay 200
unhide 1
delay 200
hide 1
delay 200
clear 1
Make a stimulus go on and off 10 times to attract attention
show rectangle 0 0  50 50
set $i 0
while $i < 10
  delay 200
  hide 1
  delay 200
  unhide 1
  set $i increase
while-end

Task: color

The color instruction is not necessary at all, but can make some coding somewhat easier. Many people will never use it, because color can be set more direclty within show commands.
color colorname
color ABCDEF
color R G B

(this sets the default drawing color for show rectangle, show circle, and show text)
Color names for use in a number of commands are:
  • red

  • green

  • blue

  • lightblue

  • white

  • black

  • yellow

  • pink

  • purple

  • orange

  • brown

The following command can be used as a shortcut, but it cannot take variables as arguments.
color red
color FF0000
color 255 0 0

Task: Sound and silence

sound soundname
sound soundname loop
silence soundname

(silence stops a sound from being played)
Examples
sound mysound
sound mysound loop
Examples
sound mysound
delay 2000
silence mysound

Task: video

NOTE:

Task: readkey

readkey key ms

key : The correct key as defined by keys
ms : The maximum waiting time in milliseconds

sets PsyToolkit variables: RT, STATUS, KEY
Examples
task my_task
  keys space
  readkey 1 5000

Task: readkeys

Note readkey and readkeys are completely different:

  1. readkey is for getting one key. It is what is used in most experiments.

  2. readkeys is not often used, it allows to enter words, multi-digit numbers, etc.

readkeys "CorrectWord" ms

CorrectWord : The word that people are expected to type in ms : The maximum waiting time in milliseconds

sets PsyToolkit variables: RT, STATUS, WORD (the letters typed in)
  • readkeys option size number : how many letters can be typed maximally.

  • readkeys option show : the typed letters will be shown on screen (starting at screen center)

  • readkeys option show x_position y_position : the typed letters will be shown as indicated by the x/y position

  • readkeys option hide : the typed letters will be not be shown on screen

  • readkeys option space number : The letters will be spaced by this number of pixels

  • readkeys option placeholders image : There will be placeholders in the shape of the indicated image (as defined in bitmaps)

  • readkeys option placeholders Width Height : The placeholders will be rectangles of size Width by Height

Here is an example with some of the options
bitmaps
  empty_box ## an empty rectangle used as letter placeholder

fonts
  my_arial arial 20

task test
  readkeys option size 5
  readkeys option show 100 50
  readkeys option placeholders empty_box
  readkeys font font1
  readkeys "apple" 10000
  save RT STATUS WORD

Task: readmouse

readmouse mousebutton stimulus ms
readmouse ( mousebutton ) stimulus ms ( range stimulus1 stimulus2 )
readmouse ( mousebutton ) stimulus ms ( range array )
readmouse stimulus ms find

mousebutton : Can be l (left mouse button), m, or r. If not used, PsyToolkit checks hovering
find : If used, this makes that hovering on other stimuli than the target not stop
stimulus : The stimulus that if clicked leads to CORRECT
ms : The maximum waiting time in milliseconds

sets PsyToolkit variables: RT, STATUS, KEY
Examples
task my_task
  keys space
  readkey 1 5000
Given differences in computer mice, it is recommended to use the left mouse button.

Task: timestamp

timestamp my_time_name
A timestamp is used to take and store the current time for a while. Used mostly in loops. Typically not used for measuring reaction time, which is stored in RT after readkey, readmouse, drag.

Task: save

PsyToolkit creates a datafile for each participant. Save creates one line of data, you can choose whatever you want to use here in terms of variables or texts, system variables, table entries, etc.

save variable1 variable2 "text" …​
  save RT STATUS
  save BLOCKNAME BLOCKNUMBER RT STATUS &my_var %my_text
  save "rt" RT "status=" STATUS

Task: if, fi, and else

if conditional
PsyToolkit_code
fi
The opposite writing of if is fi. That is why the command fi is used
Only if a response is not correct, then show an error message on screen
if STATUS != CORRECT
  show text "You made an error"
  delay 500
  clear -1
fi
If response is correct, show "well done", otherwise, show error message
if STATUS == CORRECT
  show text "Well done"
else
  show text "You were too slow or pressed the wrong button"
fi
Comparison operators
Operator  Meaning
==        is equal?
!=        is not equal?
<         is smaller?
<=        is smaller or equal?
>         is greater
>=        is greater or equal?
You can also compare arrays this way.

Task: Loops

You can only loop using while. There is no for loop
while conditional
_PsyToolkit_code while-end
Show rectangles as long as variable &i below 400. Increase variable &i in steps of 50
set &i -350
while &i < 400
  show rectangle &i 0  20 20 green
  set &i increase 50
while-end

Task: Table

table tablename
You only need to specify which table is being used in case there is more than one table.
The current TABLEROW is set automatically, but you can override this in the code using tablerow and even change multiple times within one trial

Task: Set local or global numerical variable

This is a very important function for medium and advanced coding
set variable value_or_formula
Local variables start with $ and will be reset to value 0 at beginning of task. Sometimes that can be handy. If not sure, use global variables. All examples below use &.
set &x 10
set &x &y

set &x random 1 10
set &x random 1 10 2
set &x random from 1 2 3 5 7

set &x time-since-start
set &x time-stamp-seconds my_timestamp
set &x time-stamp-milliseconds my_timestamp
set &x timestamp-diff time1 time2

set &x under &x &y up
set &x getx 1
set &x gety 1

set &x increase
set &x increase 2
set &x decrease
set &x decrease 3

set &x expression ( &y + 10 ) * 2

set &x len %my_text
set &x length %my_text
len and length mean the same and get number of characters of a text variable.

Task: Set variable based on calculation on array

set &&a 1 2 3 4 5
set $my_mean &&a mean
set $my_mean &&a median
set $my_sd &&a sd
set $my_sd1 &&a sd1
set $my_sum &&a sum
set $my_min &&a min
set $my_max &&a max
Standard deviation (sd) can be calculated two ways. You can divide by n or by n-1. For the latter, use sd1

Task: Extract variable from arrays

Ways to extract one specific value from an array or based on what is in arrays.

set &[variablename] ## get value from array &&array locate [value] # returns index or 0 if not found &&array remove first &&array remove last &&array remove random &&array remove position &&array use last &&array use first &&array use random &&array use position &&array size

&&array in &&array2 ## count how many of &&array in &&array2
&&array match &&array2 ## count exactly how many match exactly the same position

Task: Set or change array variable

set &&a 1 2 2 3 10

Setting or changing array variables

set &&a 1 2 3

create array based on some values or other variables

1 2 3

set &&a &&other

&&a will be copied from &&other

set &&a range low high

create a sequence of numbers from low to high

set &&a range 2 5 → 2 3 4 5

set &&a append value

add a value to the end of the array

append 4 : 1 2 3 → 1 2 3 4

set &&a prepend value

add a value to the beginning of the array

prepend 4 : 1 2 3 → 4 1 2 3

set &&a clear

&&a will be completely emptied

set &&a sort

the values will be sorted numerically

3 2 4 → 2 3 4

set &&a sort reverse

reverse sort

3 2 4 → 4 3 2

set &&a shuffle no_repeat

randomly order values of an array without any direct repeats

set &&a shuffle no_repeat 1 4

randomly order, but do not repeat and not repeat every 4 items

set &&a remove value value(s)

remove one or more specific values from an array (if existing)

remove value 2 4: 1 2 4 5 → 1 5

set &&a remove first

remove first item from array

set &&a remove last

remove last item from array

set &&a remove position [position]

remove item at specific position

set &&a sample [n] from [&&array]

take one or more values from array at random

set &&a uniq

take out all values which occur more than once

1 1 2 3 → 1 2 3

set &&a value1 times value2

repeat one value (or array) multiple times

3 times 1 2 3 → 1 2 3 1 2 3 1 2 3

Task: Set text variable

set %my_text "Some text"
set %my_text variable
set %my_text text_and_or_variables
set %my_text variable[index]
set %my_text variable[first,last]

set %text1 "PsyToolkit" set %text1 paste "Hello" RT "xyz" &a

Concatenate various variables and texts into text variable
set %my_text "Your speed was " RT " ms"
Various examples of setting a text variable
set %text1 "PsyToolkit"

set %text2 text1[1] -> text2 is "P"
set %text2 text1[-1] -> text2 is "t" (last letter)
set %text2 text1[-2] -> text2 is "i" (second last letter)

set %text2 text1[1,-1] -> text2 is "PsyToolkit" (first to last letter)
set %text2 text1[1,3] -> text2 is "Psy" (letter 1 to letter 3)
set %text2 text1[-3,-1] -> text2 is "kit" (third last to last letter)

Task: rate

rate option pos [x][y]
rate option labels [left_bitmap][right_bitmap]
rate option items [bitmap]
rate option between [pixels]
rate [maxtime] [n_items]

Task: choose

choose option select [bitmap]
choose option minselect [number]
choose option maxselect [number]
choose option exit [bitmap-ok][bitmap][x][y]
choose option sprites
choose option keep
choose [maxtime](stimulus_numbers...)

Task: drag

drag option from [&&array or sequence]
drag option to [&&array or sequence]
drag option snap ([left|center|right][top|center|bottom][no_overlap &&array or sequence])
drag option xlim [number][number]
drag option ylim [number][number]
drag option ghost # TO DO
drag option exit [stimulus]
drag [maxtime]
dragging [maxtime]

Task: progress bar

progress option size [x][y][w][h]
progress option colors [r][g][b][r][g][b]
progress option color1 [r][g][b]
progress option color2 [r][g][b]
### progress option layout [horizontal|vertical]
progress option [between]

Task: delay

Delay just waits for the given time. Time needs to be in milliseconds (ms): 1 second = 1000 ms.

delay ms
Show a rectangle for 1000 ms, then remove it from screen
  show rectangle 0 0 100 100 yellow
  delay 1000
  clear -1

Block

block tablename
Example of various block instructions
block my_block
  pager instruction1 instruction2 instruction3
  message my_bitmap
  message "My message. Press a key"
  text "Press a key" 0 100
  bitmap my_bitmap2
  wait_for_key x
  tasklist
    my_task1 10
    my_task2 10
  end

Block: tasklist

Block: pager

pager can show multiple images and participant can go forward/backward with up/down arrows and end with the key q

Example of pager
  pager instruction1 instruction2 instruction3

Block: message

Examples of all message in a block

Block: text

text "text" x y

  text "In this task, you need to memorize words" 0 -100
  text "Press the space bar to start." 0 0

Block: bitmap

Block: set

You can set global variables similarly as in tasks.

Block: sound/silence

Similar as in tasks. This is nice for background music

block test
  sound my_music loop
block test
  sound my_music
  message my_instruction_with_music
  silence my_music

Block: delay

Block: maxtime

Block: wait_for_key

Block: feedback

Feedback analyses the participants' data file and reports feedback (e.g., about speed, error rate).

Examples of all feedback commands
  set &MyAverage mean c5 ; select c6 == 1 && c1 == BLOCKNUMBER
  text color green
  text color 00FF00
  text color 0 255 0
  text align left
  text align center
  text align right
  text 0 -50 "Some feedback about your performance:"
  text 0 0  &MyAverage ; prefix "Average response time" ; postfix "ms"
  wait_for_key
  wait_for_key space
  wait_for_key mouse
  save BLOCKNUMBER &MyAverage
  xyplot c5 c6 ; select c7 == 1 ; xlabel "trial" ; ylabel "reaction time"
  lineplot c5 c6 ; select c7 == 1 ; colors c2 ; xlabel "trial" ; ylabel "reaction time"

Block: save

You can save variables similarly as in tasks.

Blockorder

Blockorder is used to specify which blocks are used, or more than one blockorder to randomly select one (for counterbalancing)

Two different possible blockorders. PsyToolkit will choose one of them at random each time a participant does the experiment
blockorder
  myblock1
  myblock2
  myblock3

blockorder
  myblock1
  myblock3
  myblock2

User defined variables

There are currently four different types of variables:

Type

Example

What it is used for

Good to know…​

Local variables

$x

Whole numbers

Will be set to 0 at beginning of task

Global variables

&y

Whole numbers

Will keep its values in tasks and blocks

Array variables

&&a

Array of whole numbers

Will keep its values in tasks and blocks

Text variables

%t

A text

Will keep its values in tasks and blocks

You can only set the value of a variable with the set command. See set examples.

PsyToolkit defined variables

PsyToolkit commands make certain variables available. For example, the readkey command wil create the variables RT, KEY, and STATUS.

Reaction time, errors, keys

RT

last response time, from readkey or readmouse

STATUS

from readkey, can be CORRECT, WRONG, or TIMEOUT

KEY

the key that has been pressed in last "readkey" command

WORD

whatever was typed in during last "readkeys" command

Mouse position

MOUSE_X

the X position of the mouse in last readmouse or drag statement (endpoint)

MOUSE_Y

the Y position of the mouse in last readmouse or drag statement (endpoint)

UNDER_MOUSE

the stimulus (bitmap, rectangle) selected in the last readmouse statement

Mouse dragging stimuli

DRAGGED

the stimulus that was being dragged

DRAGGED_ON

the stimulus that it was move on (only with "drag option to")

DRAG_CHANGED

if a stimulus had been moved at all (1 if changed, 0 if not)

DRAG_OLD_X

the stimulus X coordinate when drag started

DRAG_OLD_Y

the stimulus Y coordinate when drag started

DRAG_X

the stimulus X coordinate of (last) dragged stimulus

DRAG_Y

the stimulus Y coordinate of (last) dragged stimulus

Rate specific (to be changed soon)

RATE

The chosen value of rating scale

RATE_RT

The RT of the rating process

RATE_STATUS

1 if rated or 3 if timeout

Keeping track of trials/blocks

BLOCKNUMBER

the number of the current block. Starts with

BLOCKORDER

Is normally 1, but if multiple blockorders defined, gives the number of the randomly chosen blockorder

TASKNAME

the name of the task the trial is in

BLOCKNAME

the name of the current block the trial is in

TABLEROW

randomly chosen once per trial

Counters

TRIALCOUNT

the number of trials so far in any task

SHOW_COUNTER

the last shown stimulus number

There are also a few related to the choose function not further explained here.

Parts

Sometimes you repeat the same piece of code in different parts of your code. Use part to make this easier. This is just to make your code shorter and more readable.

Define it as follows:
part part_name
code
Example defining and then using part
part my_snippet
  show rectangle 0 0 50 50 green
  delay 50
  clear -1

task my_task
  keys space
  part my_snippet
  readkey 1 9999
  save RT

Including separate files

Sometimes you have a big table or many stimuli that you want to put in a separate file. Use include to make this easier. This is just to make your code shorter and more readable.

include filename
Make the file mybitmaps.txt part of your PsyToolkit script
include mybitmaps.txt