Psyscript references

This section gives a short explanation of all commands in the psyscripting language, often with short examples.

Contents

section options
section bitmaps
section sounds
section fonts
section videos
section table
section task
section block
section message

SECTION bitmaps

The bitmaps command lets you define a number of bitmaps you want to use in your experiment. Bitmaps can be of common formats, png, jpg, bmp and some more.

The bitmaps line has no parameters, and is followed by lines describing the bitmap, each bitmap having a name and a file description.

Don't put anything is quotes, and don't use spaces in the descriptions or in the filenames.

If you don't add a filename, it assume that a filename exists with the extension .png (as in the example, it assumes a file justthis.png exists).

SECTION fonts

A font is a technical description of how characters should be presented on screen. PsyToolkit uses truetype fonts.




You can either put your fonts in your own experiment folder, or you can use the system fonts. If you do the latter, you should ensure that the font is available if you move the experiment to a different computer, or if you give it to a colleague or student!

The fonts command lets you define a number of fonts you want to use in your experiment for the show text calls. The way of referring to fonts is like it is with bitmaps. Fonts need to be true type fonts. You should also set the font size

SECTION videos

The videos command lets you define a number of videos you want to use in your experiment for the show video calls. The way of referring to videos is like it is with bitmaps. Videos need to be in MPEG format.

SECTION task

Task lets you describe task types in your experiment. You need at least one task. Task is followed by a name for the task (no spaces!). Task just defines one or more tasks, but does not yet run them. It is possible (but useless) to have tasks which are never executed. Tasks are similar to functions in a (C) program. Tasks can be complex and include variables and conditional calls (using an if statement).

A task line has one parameter (its name) and is followed by lines describing events in the task.

An empty line indicates the end of the task.

The following events are available:

c

You can add one line of c code following the c command

c-begin / c-end

Between c-begin and c-end you can put real C language code. Only for very advanced users.

c-file

Include a C file. Only for very advanced users.

cedrus

You must use the cedrus option to be able to use this command. Read a key from the cedrus keyboard. The first argument is readkey to indicate that you want to read a key. The 2nd argument is the correct key; the 3rd is the maximum response time. There are several other commands as well.

ultra

You must use the ultra option to be able to use this command. Ultra refers to the self-build keyboard for the parallel port. In essence, it is very similar to Cedrus, except that there is no clear and reset option.

clear

To erase a stimulus you put on the screen with show, you can erase with clear. The call clear takes at least one parameter. The number corresponds to the count of show calls. For example, if you want to erase a particular bitmap which was shown as the second show event in your task, use "clear 2". Alternatively, you can use negative referal numbers to refer to preceding stimuli: -1 refers to the last presented bitmap! The bitmap counter is reset every trial!




Rarely, you want to clear the whole screen. This is not recommended for time critical things, because it can be slower that changing small parts of the screen. Sometimes you want to clear the whole screen at the beginning or end of trial. You can use "clear screen" to do so. You can also use this in blocks.

delay

This pauses the program for the specified number of milliseconds. You will need this function often, for example, if you want to show a stimulus for a specific time interval, or for waiting between trials.

draw

draw has one parameter, on or off. If draw is off, all followed show commands will wait with actual drawing of stimuli until the draw is set to on. This is helpful if you want to present several stimuli simultaneously.

end

End the task trial here, or end the task list following this trial. This command is practical if you want to end the trial, or if there is a reason to end the task list, for example, because the participant has reached a certain criterion.

error

Just one line, error, specifies that this trial should be considered to be an error. You will typically put this within a conditional statement.

font

If you have defined fonts and want to switch to a different font in your next show text call, set font, followed by the font name as defined in your font section. If you only have one font loaded, you do not need this command, because PsyToolkit will know which font to use.

iolab

You must use the cedrus option to be able to use this command. For the options, please read the iolab hardware manual to find initial settings for the voicekey, if needed. Voicekey responses should be read using the "iolab readkey" command.

keystatus

Checks the keyboard. This function does not wait for a keypress. All it does is check whether a key had been pressed, and if so, store the value in the variable KEY. The key must be defined with the keys statement.

This command is for more advanced used. For waiting for a key, use readkey.

keys

Keys describes which keys of the PC keyboard are being used. In an experiment where you want to use left or right button presses, you can use the left or right shift keys. Even though one key press is asked for per trial, you have to define all the keys which the subject can choose from. Special keys have special names. The numbers of the keypad also have special names

mouse

Per default, the mouse cursor is not visible. But you can use the mouse in your experiment. You can show the mouse, you can hide it, and you even put the mouse at a special location.

mousestatus

Similar to keystatus, this checks the mouse. It checks the position and whether a key has been pressed. The left key is 'l', the middle key 'm'2, and the right key 'r'.

nap

This is an advanced command. You only need this under special circumstances, for example in while loops in which you are checking for input from devices. All "nap" does is to wait for 1/2 a millisecond (and in that waiting time, nap gives control back to the kernel to do other stuff).

readkey

Reads a key from the keyboard. Readkey stores information in various variables. The variables do not change until the next readkey call:

• RT
  Response time (time it took to push key down)
• TT
  Total response time (time it took to push key down and release it)
• KEY
  The key (number) of the key pressed
• STATUS
  The status (CORRECT/WRONG/TIMEOUT)

readmouse

Similar to readkey, but useful for mouse responses. You can check whether a certain bitmap was being pressed. The first argument is which mouse button should be pressed (l/m/r for left,right,middle). This argument is optional. If not given, the "readmouse" function will check whether the mousepointer is moved over the selected bitmap. The second argument is the bitmap that needs to be touched (note: this is the first argument if you do not say whether l/m/r need to be clicked!). And the final argument is the maximum response time. This function sets the variables KEY, STATUS, MOUSE_X and MOUSY, and RT.

save

This function saves variable names. It can be used anywhere in the task, and it can be used multiple times.

The variables are temporarily saved in RAM (technical detail: it is saved as /dev/shm/data). Only at the end of the experimental session, the data will be transferred to the harddisk.

There are a whole bunch of special variables that are handy in the save line. One of them is the variable RT, which is the reaction time of the last response recorded with readkey. Other variables that are (hopefully) self explanatory are: TABLEROW, BLOCKNAME, STATUS.

send_egi

(Only for use with Electrical Geodesics, Inc. EEG system) Send a label via IP to the EGI EEG NetStation computer. Arguments one and two are a code (maximally four letters), and a label (maximally 256 letters). Do not put the code or label in quotes! The third argument is the duration of the event (although this is irrelevant for the timing of psytoolkit). None of the arguments can be variables (as defined with the set command). The latter is a limitation that should be overcome later.

set

This gives you the opportunity to set a value. Set is followed by a name, which you can invent as you please (no spaces!) and then by an assignment.

set is a simple function. You cannot do exactly the same you would expect from a flexible language like c. But then, it enables you a couple of really useful things.

You can set a variable to the value of another variable, of course.

set is necessary for choosing random parameters. set can choose a random value into a variable which you can use in other events, and which you can save to disk such that you know which random value was chosen in a particular trial.

The $ or & indicates a local or global variable. A global variable can be set in block sections as well, and maintains its value across trials and tasks.

You can use it to do special things with time data.

Further, you can set a variable to a c expression.

Finally, you can set a variable to the time in ms since the start of the experiment. This can help to find out how long things in your experiment take.



Variables which have been set, can be saved with the "save" command.

show

To show something on the screen, you use the show command, followed by a number of parameters. The first parameters is the type of stimulus, bitmap, text, or rectangle.

XPOS and YPOS specify the position of stimuli on the screen. Specify a number in accordance with the chosen coordinate system. Or use CENTER or simply C for choosing the screen centered position (for X and/or Y). Per default, coordinates are cartesian with 0,0 being the top left corner. The option centerzero make 0,0 the center of the screen. In polar, 0,0 is the screen and the coordinates are in 1/100th of a degree.

show bitmap

Show a bitmap as defined in your bitmap section. You need at least the parameter specifying which bitmap you want to display. Optionally, you can specify the X-Y coordinates. The X-Y coordinates are where the center of the bitmap will be.

show text

Show some text. If your first argument is a string (in quotes) this will be shown, but you can also refer to a table variable. Per default, you will get a white text at screen center. Optionally you can set the x y coordinates. You can also add the last 3 parameters for red/green/blue description of the font color. Make sure you always use the right type of quotes! (" instead of ').

The font is set by the font command, and cannot be changed from within the show call. For different font sizes, you must put different fonts in the font section.

show rectangle

Displays a simple rectangle. X/Y refers to the center of the rectangle. You have to give 7 parameters, the x y coordinates, the width and height, and the red/green/blue values. Red green and blue values range from 0 to 255.

sprite

The sprite command is used for presenting moving and changing stimuli. For example, if you want to move a stimulus around, or if you want to switch a stimulus on or off, sprites are more convenient than bitmaps. There are various examples (sprites-basics) that explain how to use it.

One of the essential features of sprites is that sprites will keep moving even when waiting during a delay or when waiting for a key press. If you want to update sprites yourself during a loop without a delay or a keypress, you can call "sprites update" to keep the sprites moving (see example sprites-basics/follow-mouse.psy).

Like bitmaps, sprites are referred to by numbers starting from 1. The first thing to do is to create a sprite. Once it is created, you can display it, move it, give it speed and direction, and change its shape.

The following example (assuming there is a bitmap red_ball), will move the sprite from position 0,0 to 100,5 at a speed of 3 pixels per framerate.




If you are not sure about the number a sprite creation gives you, you can ask to put the number in a variable. The following example does exactly the same as the one above, except that the sprite number is put into variable $x.




Once created, sprites will no stop to exist. This makes it possible to keep stimuli moving for whole blocks, not just in trials. If you want to create a sprite only once, you need to make sure it gets creates only once, as is shown in the next example:

task moving_stimulus if &alreadycreated == 0 sprite $x create red_ball # this will be number 1 set &alreadycreated 1 fi sprite $x display sprite $x move to 100 50 3 delay 10000 # sprite 1 (=$x) will keep moving during delay

block myblock set &alreadycreated 0 # global variable tasklist moving_stimulus 10 end

table

Determines which table to use for the task. Even if there is only one table, you still need to specify the name of the table. It recommended to have this statement as the first statement in your task. The table should be described in a table section.

timestamp

Timestamps are a special sort of variable. When you say "timestamp x" the timestamp variable x will contain the time (in milliseconds) when you called the timestamp function. These variables are different than the variables you can use in the "set" function, do not mix them up! Under "nap" you will see a sophisticated example.

You can get the actual time passed since 1/1/1970 using set (see example).




You can also get the time passed since 1/1/1970 using set in milliseconds.

ttl

If the psytoolkit program has to communicate with another machine, such as an EEG recorder, you can send electronic signals over the parallel port. Make sure you have the right cable! If no parallel port cable is attached to the computer, this command has no effect.

Send a value over the parallel port. This can be one byte.

SECTION sounds

Same idea as for bitmaps, but now you describe sounds, if you need to use some. Common sound formats are supported, including wav,ogg,mp3

SECTION options

You can set general options. If you don't use options you will use the default settings.

fontdir,datadir,bitmapdir,sounddir,videodir let you give directory paths which will be preceded to the associated defined bitmaps, sounds etc. For example, if you bitmapdir is /data/bmp, then this value will precede the file in the bitmap description.

window lets you run the experiment in a window instead of in full screen. This is good for testing. Note that the full screen mode is the default mode in Linux, unless you run in test mode. In the Java version, the windowed version is the default.

fullscreen The opposite of window. This option is primarily meant for the Java version, but it also allows you to run the Linux version in fullscreen when running in test mode.

resolution sets the resolution of the experiment. This default resolution is 800x600.

transparency on enables the use of transparency in bitmaps. By default, this is off. You want this for overlapping see through bitmaps.

render lets you set the way SDL draws the screen. This is an advanced topic that you do not need to worry about unless you really want to. In short, the OS graphics system has different ways of drawing the screen, and PsyToolkit enables one to use those different ways, rather than deciding for you how the screen is drawn. In practice there are only minor differences. There are currently two ways to render, the default way (which is the same as in versions before 1.2.0) and using double buffering. Using "render doublebuffer" is recommended for working with moving stimuli. In the future, "render opengl" will allow you to use the OpenGL capacities of your computer if available.

ESSENTIAL: The speed of moving sprites is based on various factors. Speed depends on the screen update frequency and on the rendering type (on some systems, double buffering is takes more time than default buffering, this is not due to the time it takes to draw, but due to more complex issues of how graphics cards draw screens). It just means that if you use experiments on different systems, you might have slightly different sprite moving speeds.

version will only allow to compile a script with the corresponding psycc version. This is practical if you have multiple versions of psycc installed, and when you just want to make sure that the code runs. This is a recommended option.

screensize and screendistance let you set the dimensions of the screen and the eye-screen distance. Units are in millimeters. These numbers are necessary if you want to use the option coordinates polar or if you want to use the report stimulus size command line option. If you use a polar coordinate system (which is rare), all xy coordinates should be specified in 100ths of degrees (thus 100 = 1 degree, 200 = 2 degrees of visual angle).

vsync_off does not wait for synchronization of the vsync. This is handy for testing, since the experiment does not need the root permission during compilation.

centerzero assumes that 0,0 refers to the center of the screen, and not to the top-left point of the screen. In general, centerzero seems to make script writing a bit easier, so it is recommended.

egi with the host ipname or ipaddress and the (optional) ip port sets up a connection to the Electrical Geodesics, Inc System.

escape makes it possible to end the program to by pressing the escape key. Please notice that the computer only tests whether the escape button has been pressed at the end of each trial. Hence, if you use this option, and if you want to break out your experiment, you have to hold the escape button (or whatever button you use for escaping) for the duration of at least one trial.

mouse enables to show the mouse (the only useful value is "on")

parallelport is for advanced coding of the parallel port (for reading or writing of the parallel port (in or out)

pcidio24 is for advanced coding of the pcidio24 port

cedrus indicates that you have attached a Cedrus keyboard. Optionally, you can specify a model. If you specify a model, the script will only run with that model. That strictness is only necessary in case you want to force people to use a specific Cedrus keypad.

iolab indicates that you have attached the IoLab device. Optionally, you can specify the voicekey parameters (see psycc -s)

variable lets you set a global variable. This can be handy if you want to test an experimental parameter (e.g., intertrial interval) to a certain values. You should not use the & sign, but when referring to it in the code, you should use the & sign, as it is a global variable. If you do not use the variable, this option will just be ignored.

executable The filename of the executable program. Per default, this is experiment, but it can be set with the command line option -o and with this option. NOTE: The -o option will override this option.

SECTION block

Blocks are the parts of the experiment that actually do stuff (tasks are doing stuff, but they need to be called from within blocks in order to be done!). Blocks do not necessarily call tasks, they can also be used just to set some global variables or just to show some information.

Block is a part that calls the tasks. You can have as many different blocks as you want. You can specify how many times you want to repeat a block. Every block can have a number of sub-components:




Altogether, you can make fairly complex things with these options. Basically, what you probably want is to start with a bitmap, giving instructions. You may want to have the instructions at least a certain time (you can use a delay command), and then wait until the subject presses a particular key (default is spacebar). Then you want to have tasks running. After that you may put up a bitmap again, something like "thank you" or "well done".

You can even access the data with the system command. You can for example make a short analysis whether the subject worked well or not, create a custom bitmap and show that! Use the bitmap_from_file for this.

bitmap

Just specify a bitmap. One parameter, namely the ID as specified in the bitmaps section. The bitmap will be presented centrally. The bitmap syntax in blocks is different than in tasks.

bitmap_from_file

One parameters, the filename (with or without full path). The bitmap will be presented centrally.

clear screen

Like in the task, you can use clear screen to clear the whole screen.

continue_repeat_keys

This is a control statement that waits for feedback from the participant. Argument 1 is the key to be pressed to continue to the next block. Argument 2 is the key to be pressed to repeat the same block.

This is handy for training blocks that can be repeated until the subject feels ready.

maxtime

The maximum duration of a block. For example, if you think that participants can do the 100 trials of your task list within 5 minutes, but that some exceptional people will need more time than that, because they are slower or make more errors, you can limit the total duration with this command.

message

Show a message (parameter 1: a bitmap) and wait for a key (parameter 2: a key code).

The message call can be used within and outside blocks. It is basically a combinations of bitmap and wait_for_key. The first parameter is the bitmap (as specified under bitmaps), and the seconds parameter is optional (if not given, it waits for spacebar).

pager

The parameters are bitmaps (up to a maximum of 100). The pager allows people to flip through bitmaps (backwards and forwards, as with a pager such as "less"). This is very practical if you want to show instructions, which often do not fit on one screen. The keys to go forward are space, page down, and down (arrow), the keys to go backward are page up, up (arrow). Once done, the user must press the q button to quite to paging.

sound

Play a sound, just one parameter (the sound ID)

delay

One parameter, wait a number of ms. Must be a fixed number.

tasklist

The tasklist command is one of the essential commands in the block section. Following it, there will be lines describing the various task you want to use. Make sure you end with the "end" line (see example).

Tasklist determines which task will be done, and optionally, how trials of that task are chosen. In case you use a table in your task, trials will be chosen randomly from that table by default. Alternatively, you can give the tasklist command one parameter, that is "fixed", and the trials will be chosen from the table one by one, starting with the first row. Once the last row has been reached, it will start over again.

The tasklist instruction should only be used once in a block.

Specify at least how many trials should be performed. Per default, it does not matter whether the outcome of trials is an error or not. If you want a number of correct trials, you have to set in the task description what counts as an error (see the "error" command). The error command sets a flag. You can specify the number of correct trials to be done with the keyword "correct". After the correct keyword, you must specify the maximum numbers of trials for the block. The allcorrect statement asks you to do all trials correct and to start counting from zero if even just one error is made (but no more than the maximum.

Note I: If you have an allcorrect statement in your tasklist BUT NO error statement, then the compiler will give you an error message

Note II: You may wonder why would you need to keep track of the correctness of a trial with the error statement! The reason is that normally, the STATUS value CORRECT means really that a trial has been correctly performed. However, there are options. For example, if you want to have a delay in which the subject is NOT SUPPOSED TO PRESS any key, then you can use a readkey statement; only if the STATUS gets the TIMEOUT value, the trial was correct. To make such tricks possible, it was decided to use the error statement. The error statement is ONLY RELEVANT to the allcorrect statement; without the allcorrect statement, you are not required to use the error statement.

Note III: The no_repeat option ensures that a trial is not repeated immediately.






IMPORTANT: Except for readkey, Psyscript does not count a trial as an error unless it is explicitly coded in the task description. If you want to use error dependent functionality in blocks, you need to use the "error" statement

There are more trial selection sophisticated features. The example "trialselection" explains and demonstrates them in more detail.

system

You can call an external program that does something. This makes sense in combination with the bitmap_from_file command. For example, after a block of data collection, you can analyze the data and make a plot and show it as feedback. This is in the IOR example in the examples part of this website.

wait_for_key

Waits for space bar press or for a specific key if specified

set

Like set in the task, you can set variable names. In the block section, you can only set global variables (they start with the ampersand). See set in the task section for more details.

SECTION message

Message are often necessary at the beginning and end of an experiment. For example, you might have a welcome screen asking participants to switch off the mobile phone. And you might have a message at the end telling participants that they are done with the experiment. You can do this easy with the message section, which basically has only one line (and should be followed by an empty line). Note that a message line can also be used with a block (see block for that).

SECTION table

Tables can be used to describe trials. A table has rows and columns. If you have more than one condition in your task, you can describe the various trial parameters with the entries of a table. Each time a task is being performed, the code will automatically choose one of the rows of a table (given there is a table). How rows can be selected can be set with the tasklist command.