The essence of a PsyToolkit experiment

The purpose of the PsyToolkit scripting language is to describe an experiment such that it can be carried out by the computer. In other sections, you can lookup all the available options and commands of the scripting language:

Help on each scripting language feature.
Syntax description.

This section of the documentation explains how the script works in a more abstract way. Once you understand that, you can go on look for specific commands.

TIP:
For beginners: The scripting language allows complex scripts; that said, beginning users do not need to use all the complex features. In fact, you can write a simple script in a few lines without understanding most of the sophisticated features. If you are new to PsyToolkit, you should not get scared by the advanced stuff.

Anatomy of a PsyToolkit script

Defintion of "PsyToolkit script"


A PsyToolkit script is nothing more than a text file, which is
typically saved with the filename extension .psy.  The text file
follows a specific ordering of code; the rules of how the code is
ordered is called a syntax.

Every PsyToolkit script has a number of essential components:

At least one description of the events of a task
At least one description of a block

The task describes the events that happen in a single trial, and a block describes how and when task trials are being selected. There are optional parts of the script that can describe different types of conditions (in the table section), you can tell the script which images and sounds to use as stimuli (in the bitmaps or sounds section), and you can set specific options in the options section.

Below are more details about each of these sections.

Task description

Each experiment has at least one task, but you can have more than one. How many you need depends on the complexity of your experiment. A task describes all the events that happen in one trial of an experimental paradigm.

There are three types of events:

Stimulus events. For example, showing something on the screen.
Response events. For example, wait until a specific key is being pressed.
Control events. That is anything that is not a stimulus or response event. This can be just doing nothing (delays), if..then or while..end calls. Also, it can be the saving on information about the current trial to the hard disk. The latter is necessary if you want to analyze the data.

Example of a task section in a script (# is comment)


task mytask               # the name of the task is "mytask"
  keys z m                # two response buttons are used: z and m
  show bitmap mybitmap    # show a bitmap
  readkey 1 1000          # wait until key is pressed (max 1000 ms)
  clear 1                 # erase the first shown element
  save RT STATUS          # save relevant data to disk

Block description

The block sections tell the computer when to call which tasks. For example, you may have a block of 10 trials.

Example block description


block myblock             # the name of the block is "myblock"
  tasklist                # ask to carry out trials
    mytask 10             # do 10 trials of "mytask"
  end                     # end of lists of tasks.

But, you can do all sorts of other things, such as showing an instruction before the block starts, or calling a command that analyzes the data collected in the block and then shows some feedback to the user.

Also, you can specify exactly what sort of order you want the trials to occur in. You can have a random selection of conditions, random but without immediate repeat, fixed order, etc. In the example above, PsyToolkit will assume that trials are randomly interleaved (assuming there are multiple conditions, which are not defined in this example).

Optional components

There are many optional components. For example, there is an optional options section in which you can specify other than default values, such as a different screen resolution, the use of a special response keyboard, or the location of bitmaps being used.

Further, the optional sections allow you to load bitmaps (or fonts, sounds) into the computer memory. Also, you write a section to define the conditions of a task (this can be done in a table section, see below under "specifying conditions".

These options are all explained in the other parts of the documentation.

The use of variables

Variables are an important part of Psytoolkit. There are different types of variables.

First of all, there are variables that specify information about conditions and responses. For example, the variable RT contains the reaction time of the last pressed button (as recorded by the readkey statement). STATUS contains whether it was an error, or whether the participant was to slow, etc. There are various other variables explained in the scripting reference section.

Second, there are table variables (starting with @). For example, @2 refers to the value of the second column of the table. The row is determined by the trial selection mechanism (see below).

Third, there are timing variables, called timestamps. These can be used to keep track of time. But note, the reaction time of button presses is handled more easily. Timestamps allow for advanced time tracking, and this is not necessary for simple experiments.

Fourth, there are general purpose variables that can be set with the set command. The values are integer values (whole numbers). General purpose variables can be local (for a task only) or global. Again, these are not be necessary for simple experiments.

Specifying experimental conditions

Most experiments have multiple experimental conditions, and in PsyToolkit it easy to code this.

In Psytoolkit, it is easiest to specify the parameters of conditions in a table. A table section has a number of fields. Each row of the table is a condition. If you use a table in a task, the default way of working is that the software automatically chooses a different condition (i.e., table row) randomly each time the trial is being executed.

Table and task example


table mytable
  "condition1" 10 20
  "condition2"  0 100

task mytask
  table mytable
  show text @1 @2 @3  255 255 255
  delay 500
  clear

block myblock
  tasklist
    mytask 10
  end

In the example above, there are two conditions and there is one task. This script will carry out the task 10 times. Each time, the computer will automatically select a table row. The @ variables select the fields of the selected row. If you want to save which table row was being used, you can even access that information, it is saved in the variable TABLEROW.

From here

The above information has explained some of the basics on how to read and write a script. To further understand how this works, it is best to study some of the examples in the example section.