The rest of PsyScript exists so that you can execute 'trial' commands, which show one or more stimuli & collect subject responses. You specify the events in a trial using the simple event codes.
This section is a reference to do trial syntax
nb: Understanding do trial is critical to understanding PsyScript: for an introductory tutorial, go here.
Formal Structure of do trial
do trial trialString [given {substitution list}]
trialString is describes the event sequence you want to occur,
The {substitution list} is a list of events that PsyScript will use to "wildcard" place holders in the trial string (wildcard description here).
--The [square brackets ] denote that the given list is optional.
Basic Example:
do trial " !e hello #500 '####' !t "
This will erase the screen, wait half a second, display a mask of 4 hash signs, then start the reaction timer.
nb: the event codes in this string are discussed below
Wildcard Example
do trial "!e ?1 #500 ?2 !t" given {"hello", " ' ##### ' "}
?n specifies a wildcard that will be filled in when the string is used in a trial. PsyScript replaces all instances of ?1 with the first item in the given list, all instances of ?2 are replaced with item 2, and so forth. You can specify any number of wildcards in a predefined event string.
Advanced: to specify wildcard numbers greater than 9, put them in brackets, i.e., ?(15).
Named Wildcards are also supported
So the trial above could also be written:
do trial "!e ?stimWord #500 ?mask !t" given {stimword:"hello", mask:" ' ##### ' "}
note: No responses are accepted before the timer is started. See Start timer
note: Trials stop after the subject makes an acceptable response or when the trial times out, whichever comes first.
You can override this by setting the minimum length of the trial with !l(n) Set set trial length
The string mapped to the response in is stored in subject response.
The amount of time, in ms, since the reaction time timer was started is stored in reaction time.
Trial events are specified by the single-character commands. This leads to trial lines that look somewhat like cartoon characters cursing, but the single characters can be interpreted very quickly by PsyScript and keep the length of trial lines to a minimum.
The commands are listed in this pop-up table and then described below
The commands to draw words, and images, or to play sounds and movies all follow a simple pattern.
By default, if PsyScript sees a single unadorned word in a trial, it assumes you wish to draw that word at the default location (centre screen). To draw multiple words (a string containing white space) explicit that you want text drawn, place the text inside single quotes
Examples
do trial " hello !t"
do trial " 'hello' !t"
Either of these will draw the word "hello" in the centre of the screen
do trial " 'hello tim, you are cool' !t"
This will draw the phase "hello tim, you are cool" in the centre of the screen
do trial " 'hello tim, you are cool' !t"
This will draw hello , then on top of that word, it would draw each additional word all in the centre of the screen
see word wrap for how to draw words sequentially
To draw or play images, sounds, and movies, simply write an "@" (for images), an "$" (for sounds), or a "~" for QuickTime stimuli, followed by the name of the stimulus.
Load and Draw an Image
do trial " @dog !t"
Psyscript will look for an image called "dog" in the default picture folder and will display it on screen
Load and Play a Sound
do trial " $cash_register !t"
This will play the built-in sound "cash_register"
note: Pepper Williams included some simple sounds in the application itself. The provided sounds are "soft_click", "low_tone", "medium_tone", "high_tone", "buzz", "fanfare", and "cash_register". There is a demo script which plays each of these in turn
PsyScript can play sounds that are stored as Macintosh 'snd ' resources, and you refer to these resources by their names.
note: All the sounds in your system file (i.e. "Sosumi") are automagically available
If you want to use custom sounds, you can add them to a resource file using the ResEdit application, which you can get free from apple. You then have to let PsyScript know about the resource file with the open resource command
BUT the easiest way to play sounds is just to treat them like movies (next paragraph down) Just use ~ instead of $ and let Apple's QuickTime engineers figure out how to play it for you.
Load and Play a movie
do trial " ~movingPlaid !t"
This will load and play a movie called "movingPlaid " if found in the default picture folder
You can specify the position of each of these stimulus types (except for sounds) by adding the point at which you want to centre the stimulus in brackets after the stimulus name
Example
do trial " 'hello'(50 150 ) !t"
This will draw the word hello on screen centred at a point 50 pixels in from the left of the screen, and 150 pixels own from the top of the screen.
Note: text must be in single quotes if you want to specify its location
Stimulus Type |
default position |
specified position |
| picture | @xxx | @xxx(x y) |
| QuickTime | ~xxx | ~xxx(x y) |
| sound | $xxx | N/A |
| word(s) | 'xxx' or just xxx | 'xxx'(x y) |
Legacy: you can also specify positions with a single number referring to one of PsyScript's built in position stimuli
Example
set value of position 10 to {50, 150}
do trial "!e #500 'hello'(10)"
Often you want a set of events to occur in between each stimulus sin a trial, for instance, to wait a certain time, then erase the stimulus.
You do this by setting the PsyScript property auto events
Example:
set auto events "#500 !e" -- pause for 2500 ms, then erase screen
do trial " each word will occur for half a second and then be erased and replaced"
You can toggle auto events on and off inside a trial using "!g"
Example:
set auto events "#500 !e"
do trial " + "after this phrase, each word will be erased after 500 ms" !g like these are being now"
Note: the toggle switch is always turned on at the beginning of every trial
*n, *n(x y), *@name
PsyScript can preload stimuli during pauses and then quickly and crisply show them later in the trial.
To pre-load a stimulus inside a pause, simply include the stimulus name(s) (each preceded by an type identifier) in brackets
Example: load two Picts during a pause
do trial " #1000(@lion @frog)"
To actually display the stimuli you have loaded into RAM, just refer to them using an "*" followed by a number referring to the order in which you loaded the stimuli, i.e., *1 *3 *2 would show the first pre-loaded stimulus, followed by the third, and then the second
Example: load two Picts during a pause
do trial " #1000(@lion @frog) *1 'that was a picture of a lion' *2(300 300) 'note how I specified the position for this frog'(50 50 )"
Advanced: to actually draw a loaded image inside a pause, add an asterisk before the identifier character
Legacy: If the character following a '*' is not a number, PsyScript assumes it is a variable name, to be shown as a word stimulus. Thus the following sequence:#250(*@zebra)
do trial " !w you took *reaction time milliseconds"
will display the reaction time for the PREVIOUS trial .
•xxx(x y)
This command draws/plays a stimulus that has been permanently loaded with the load permanent stimulus command. The leading character is •, typed as option-8
A position can be specified just as with showing temporary stimuli. Permanent stimuli are designated by names that you assign when you load them. Most commonly, this will be a mask or a sound that's shown/played on every trial. A position can be specified in the same way as the commands above. Here's a typical sequence in which a Pict is loaded during the ITI, shown, displayed for 250 ms, and replaced by a mask:
!e(l t b r)
To erase the screen, you simply say "!e".
To erase a particular rectangle, just add the left, top, right, and bottom coordinates of the rectangle in brackets after !e
Example
do trial " hello #500 !e 'erased whole screen'(200 25) #1000 !e(50 20 100 30) 'only erased a bit then'(200 50)"
:xxx< a string of events >
To repeat a sequence of events, just surround the sequence in <angle brackets>, preceded by a colon and the number of repeats that you want.
Example
do trial " #1000(@scene1 @scene2 @mask) :20<*1 #100 *3 #100 *2 !t #100 *3 #100> "
You just implemented a change blindness experiment. The trial code (from the RSVP manual) gives 20 repeats of the simple pict1, delay, mask, delay pict2 delay> sequence.
Note: This clever trial line from Pepper Williams starts the timer inside the repeat loop. The trial will terminate as soon as the subject makes a response, but looping over the !t command does not matter as it is only executed once. This ensures a correct reaction time.
!l(n)
The !l(n) command ensures that a trial is at least n milliseconds in duration.
Exampledo trial " !l(5000) @lion !t "
This trial will be 5 seconds long, even if the subject responds after 1 second.
Note: RT time-outs still work as usual
!l also forces PsyScript to keep on executing trial events after a reaction time has occurred, right up until the !l times out.
Example: to ensure that a stimulus is erased even if a subject might respond prior to that time in your trial:
do trial " !l(5000) @lion !t #3000 !e "
This command allows you to force trials to have a certain length and can be useful if you are testing normal and neuropsychological subjects: the controls can respond quickly and then wait, while the NP patients gets plenty of time.
Advanced: If you want trials to begin at predictable intervals, you want the #m command
!t(n)
As soon as this command is encountered, the reaction time timer is started and PsyScript begins looking for a subject response
Note: responses before this event are flushed. So use the !t as soon a response is valid
Advanced: You can add a timeout to a trial by adding a timeout value in parentheses after the !t command
Occasionally, if you have a very complex drawing to assemble you may wish to blank the screen while you create the drawing. PsyScript can do this, currently restricted to 8-bit color mode.
"!h" paints the screen pallet white. "!u" "un-hides" the screen by restoring the pallet.
Example:
do trial " !v !h #100(*@lion) !v !u"
This will hide the screen, load and draw a picture of a lion, and then unhide the screen, revealing our drawing
Note: see how we waited for a vertical retrace either side of the hide/unhide? That stops the screen sheering half way through a refresh as we hide it.
!a
Every trial starts with the mouse cursor hidden. You can unhide the cursor by executing the !a command, and re-hide it by issuing the command again.
Set a PsyScript property within a trial (such as the background color or word size).
!s(xxx yyy)
Most of the time, you can set PsyScript's properties in AppleScript with commands like
set background color to black
set word color to {redValue, greenValue, blueValue}
Sometimes, however, you need to change the state of one of these properties on the fly within a trial. Say to paint a word with each letter in a different color.
TO do this, you simply say !s(propertyName newValue)
Example
set word wrap delimiter to ""
do trial "!w !s(back_color red) R !s(back_color green) G !s(back_color blue) B ''(0)"
set word wrap delimiter to " "
Note: this is quite an advanced trial
First we set the word wrap delimiter (what PsyScript inserts between each word) to "" (empty string)
Then we do trial showing the letters "R", "G", and "B" in three different colors. They appear adjacent because the delimiter is empty.
Then I existed word wrap mode (by drawing a single quoted empty string at a specific position
!w(xxx)
PsyScript defaults to drawing words at a specific location. However, often you may wish for words to occur as they do in normal text - one after the other separated by word wrap delimiter ( a space by default).
Do this in PsyScript by saying "!w" to enter word wrap mode.
You can specify a position to start drawing the text by saying !w(x y). In this case, the position is the bottom left of the first character.
#b
Use #b to allow subject-timing of trials. This causes PsyScript to stop and wait for a space bar press.
Example:
do trial " 'Press space to see the next stimulus' #b !e #100 'thanks for pressing the space bar' "
PsyScript has great timing controls. Most commonly, you want to wait for a certain number of milliseconds to elapse. To do this, you say "#n"
Example: To wait 100 milliseconds
do trial "#100 'we just paused for 100 msec' "
To wait until an interval has elapsed, for instance to ensure that a regular ITI elapses between the start of each trial, set the beginning of the interval with a simple "#". then wait for intervals of this time by saying #ma, where Ann is the size of the wait interval in milliseconds
Example: To enforce an ITI of two seconds
do trial "# 'that zeroed out the interval' !t(0)"
do trial "#m2000 'you will see this 2 seconds after the last trial began' !t(2000)"
Advanced: You can pre-load or even show stimuli during a pause. This is useful for ensuring crisp timing when you cannot be bothered to load the stimuli permanently, or if it will be used only once. See the section on temporary stimuli to learn about this technique
!v, !vn
the "!v" command waits for a “Vertsynch” to be detected. This is the screen refresh pulse of your monitor, and is emitted when electron gun is climbing back up to the top of the screen to begin drawing again. If you can draw new screen material in this interval, it will be in front of the monitor gun, and will appear crisply and "instantaneously" to a viewer.
" !m ... intervening events ... !r(comment) "
Using the mark and report commands, you can find out and/or record exactly how much time a trial operation takes.
!m tells PsyScript to remember the current time, and !r has PsyScript report the time that's elapsed (in milliseconds) since the last !m event. This is saved as a list item in the application property reported time list of string.
Example
do trial "!m #500 hello !v !e good-bye !r(half a second delay plus vsynch and erase and two displays took )"
do trial "!w ' ?1 milliseconds' " given {item -1 of reported time}.
Without special hardware reaction time from keyboards is around 16 ms. USB tends to be worse than old fashioned ADB :-(
It may not matter for your experiment:
Ulrich, R., & Giray, M. (1989) Time resolution of clocks: Effects on reaction time measurement — Good news for bad clocks. British Journal of Mathematical and Statistical Psychology, 42, 1-12).
If it does, use the ActiveWire input or BBox Commands
The !x command provides the ability to wait for an external input
This allows you to synchronization PsyScript execution to an external device (e.g., an MRI scanner or eye-tracker).
The !i command allows for control of the bbox output lines (either the bbox
lights, or attached external devices). The "[do map_light]" command
(see Section 5.2) allows automatic illumination of a bbox light when there is
bbox input; this is most useful for showing registration of a voice trigger
response, but can also be used to light up a light when a bbox button is pushed.
The mapping of inputs to lights is set by the "do map_light" command;
note that turning lights OFF is the responsibility of the programmer (this can
be done by appropriate use of the !i command in the succeeding trial). At the
beginning and the end of an PsyScript experiment, all 8 bbox lines are turned
off.
| MACCS |  |
Documentation | Downloads | FAQ | Mailing List | Last change: |
| Advanced Search |
 Applescript in a Nutshell : A Desktop Quick Reference |
 AppleScript for Applications: Visual QuickStart Guide |
 AppleScript For Dummies |
 Applescript for the Internet Visual Quickstart Guide |
 Applescript Language Guide; English Dialect |
 Danny Goodman's Applescript Handbook |