PsyScript — Trials Reference

by


TRIALS

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.

The “do trial” Command

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

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

Simple Display Commands

How to load and play stimuli

Control Commands

Timing

Simple Display Commands

Load and then immediately draw/play a stimulus:

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

Specifying a Location:

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

Summary

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

Auto Events

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

Pre-loaded Stimuli

Showing Temporary Stimuli

*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

#250(*@zebra)

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:

do trial ”
!w you took *reaction time milliseconds”

will display the reaction
time for the PREVIOUS trial .

Draw/play a permanently-loaded stimulus:

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

Erase the screen

!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)”

Control Commands

Loop a series of events:

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

Set trial length

!l(n)

The !l(n) command ensures that a trial is at least n milliseconds in duration.

Example

do 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

Start the reaction time
timer:

!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

Show or hide the screen

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.

Show/hide the cursor

    !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).

Set a PsyScript property inside a trial:

!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

Set the word wrap 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.

Timing Control

Wait for space bar press

#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’ “

Pause for a time or until an interval has elapsed

        #, #n, #ma

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

Wait for a screen refresh to occur

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

Wait until the subject is fixating a certain location
(Eyelink only)

Mark and report time elapsed between events

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

Wait on an external input

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

Leave a Comment