• 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
The resolution notation can also include an x, such as resolution 1000x800.

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

There are two ways to play sounds, namely sound files (such as MP3) or sound waves.

Play sound files

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

Play sound waves

sound freq type hz duration
type : The type of wave, choose from sine, square, triangle, or sawtooth
hz : The Herz sound frequency
duration : duration in milliseconds

sets PsyToolkit variables: RT, STATUS, KEY

sound freq [sine|square|triangle|sawtooth] [hz] [duration]

Examples
   sound freq sine 500 2000
   sound freq triangle 600 1000

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: textbox

Note textbox allows text entry, including special characters, such as Chinese. It is ideal for longer texts or lists.

Example of textbox using all parameters
task my_task
  show text "Enter words" 0 -280
  show rectangle 300 250 100 100 green
  textbox new 0 0 500 400 white blue 30 arial
  readmouse l 2 99999 range 2 2
  set %%my_list textbox
  save %%my_list
  textbox 1 clear

INFO: The textbox instruction is followed either by new or by a number. Currently, that number needs to be 1, and that refers to the one textbox on screen.

You can aslo set the text shown in the box, this is good for longer texts being shown (for shorter texts, you best use show text…​).

textbox 1 text "Some longer text..."

You can stop people from entering text by using lock as follows:

textbox 1 lock
textbox 1 text "Some longer text..."
The textbox will always on top of all other stimuli. You remove the textbox from screen as follows: 
textbox 1 clear

Details documentation: textbox

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

set &x duration my_sound
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

A task list looks as follows in the simplest situation

block my_block
  tasklist
    TASKNAME NUMBER_TRIALS
  end

Whereby TASKNAME is the name of the task, and the NUMBER_TRIALS is the number of trials you want the task to be done in this block.

Useful extra options after the number of trials:

  • equal : Ensures each condition (as defined in table rows) is done same time as other conditions. When choosing this, there will be no repeats of the same trial by default

  • no_repeat : Do not repeat trials

  • all_before_repeat : Do not repeat any condition before another one has been done

  • fixed : do the trials in the order of the table rows. This even can be done when there are multiple blocks

Example of equal
block my_block
  tasklist
    my_task1 10 equal
  end

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
---

== Block: delay

== Block: maxtime

== Block: wait_for_key

== Block: feedback

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

.Examples of all feedback commands
[source]
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

link:syntax.html#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
[source]

blockorder myblock1 myblock2 myblock3

blockorder myblock1 myblock3 myblock2

== User defined variables

There are currently four different types of variables:

[cols="10,3,20,20"]
|===
|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
|===

TIP: You can only set the value of a variable with the set command. See xref:set[set examples].

== PsyToolkit defined variables

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

[cols="2,10"]
|===
2+| 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
2+| 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
2+| 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
2+|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
2+|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
2+|Counters
|TRIALCOUNT  | the number of trials so far in any task
|SHOW_COUNTER | the last shown stimulus number
|===

TIP: There are also a few related to the
link:syntax.html#task-choose[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.

[sidebar]
--
NOTE: Define it as follows: +
part _part_name_ +
_code_ +

--

.Example defining and then using part
[source]

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.

[sidebar]
--
NOTE: include _filename_
--

.Make the file mybitmaps.txt part of your PsyToolkit script
[source]

include mybitmaps.txt