• 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 hash mark (#) is a comment for humans; PsyToolkit ignores it.
If anything is missing or wrong in this file, please email PsyToolkit@gmail.com

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. The example line below is then followed by a number of lines (sometimes many) with the task code.

task mytask

Task: Visual Stimuli

Visual stimuli things you can draw on the screen.

Coordinate system

Each visual stimulus has a position on the screen.

Each position has two arguments, the X (from left to right) and the Y (for up down), similar to the way you have it in mathematical plotting.

Coordinates

Check out more about the coordinate system here

text

show text text
show text text x y
show text text x y colorname
show text text x y R G B

(without x y coordinates, presentation will be in center)
R G B refers to RGB color code (e.g., 255 0 0 for red)
Examples
show text "Hello world!"
show text "Press spacebar to continue" 0 200
show text "Press spacebar to continue" 0 200 green
show text "Thank you"  0 200   0 255 0

set %myWord "Hello"
show text %myWord
You can change the font and size of text. Learn more in the full documentation.

bitmap

How to load stimuli and name them is explained in Stimulus loading

show bitmap name
show bitmap name x y

(without x y coordinates, presentation will be in center)
Make sure bitmaps are "loaded" in experiment
bitmaps
  my_image some_file.png
Examples
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 from where it currently is, 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

This is a rarely used instruction in PsyToolkit examples. 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)
Ready to use 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
The FF0000 is a hexadecimal coding of red (FF or 255), green (0), and blue (0). This is a common notation in computer science and available if you like it.

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)
Make sure to load your sound or put it externally if very large
sounds
  mysound some_sound_file.mp3
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

show video
show video name
show video name x y
show video name x y width height

(without x y coordinates, presentation will be in center)
Make sure to provide video URL
videos
  clip1 https://www.dropbox.com/s/kzo7sx7hkdai16i/beetle.mp4?raw=1
Examples
show video clip1
show video clip1 200 100
show video clip1 -300 -150
show video clip1 0 0 100 100

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

List of all the keys available on all platforms:

  • lettes: a to z

  • numbers: 0 to 9

  • special keys: enter capslock tab space end home insert

  • special keys: escape slash backslash quote comma period

  • arrow keys: up down right left

  • numerical keyboard (keypad): kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9

  • number keyboard: kp_period kp_slash kp_star kp_minus kp_plus kp_enter

The following keys are not availble in the Javascript mode

  • shift keys: lshift rshift

  • control keys: lcontrol rcontrol

  • alt keys: lalt ralt

  • logo keys: lsuper rsuper

Currently, in Javascript any shift, control, alt, or meta (logo) keys are coded as left. This will be fixed in a future version.

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 Lesson here.

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" …​
Examples
  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. In PsyToolkit, there is currently 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

Introduction on blocks in the full documentation

block tablename
Example of a minimal typical block
block my_block
  message "Press a key to start block"
  tasklist
    my_task1 10
  end
Example of more sophisticated block instructions
block my_block
  sound mysound
  pager instruction1 instruction2 instruction3
  silence mysound
  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

Shows one bitmap and waits for space bar (or optionally other key)

Example of a message in a block and waiting for the space bar
  message my_instruction
Example of a message in a block, and waiting for the key "q"
  message my_instruction q

Block: text

This is rarely needed, but gives more flexibility than the "message" instruction.

text "text" x y

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

Block: bitmap

Rarely needed.

You can simply show a bitmap. The difference is that it will not wait for a key. This can be useful in combination with "delay" to show a sequence of images.

Make sure the instructions are defined in the bitmaps section of your

experiment.

bitmaps
  myInstruction1
  myInstruction2
  bitmap myInstruction1
  delay 10s
  bitmap myInstruction2
  wait_for_key space

Block: set

Rarely needed.

You can set global variables similarly as in tasks.

Useful if you need to set specific parameters for a block, such as a maximal response time for a sequence of trials. This works only with global variables that are then also available in the tasks.

task testExp
  keys space
  show text "Press space bar quickly"
  readkey 1 &MyMaxRT
block
  set &MyMaxRT 5000
  tasklist
    testExp 20
  end

Block: sound/silence

Similar as in tasks. This is nice for background music

block test
  sound myIntroMusic
  message Instruction1
  silence myIntroMusic
  sound myTaskMusic
  tasklist
    testExp 10
  end

Block: delay

Rarely needed.

You can ask to delay for a certain number of milliseconds.

  delay 5000

Block: maxtime

Rarely needed.

You can set how long a block lasts maximally. When the time is up, the block will end. You can specify the time in milliseconds, seconds, or minutes.

For minutes, add the letter "m" directly after the number (as in example below). For seconds, the letter "s".

Numbers must be whole numbers. For example, for 5.5 seconds, use 5500.

Example of a maxtime of 10 minutes
  maxtime 10m

Block: wait_for_key

Rarely needed.

If you show a text or bitmap instead of a message, you can ask the block to wait for a specific keypress.

Examples of waiting for keypress
  wait_for_key space
Examples of waiting for mouse click
  wait_for_key mouse

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

Rarely needed.

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

Variables are useful although you can create experiments without them as well.

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

Text arrays

%%s

Array of strings

Will keep its values in tasks and blocks
You can only set or change 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

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

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