Introduction

PsyScript is based on the concept that an experiment is a series of trials which in turn are simply a series of events such as the display of sounds, images, movies, or words, and the recording of events such as key and mouse presses.

PsyScript is controlled by Apple's core natural-language scripting technology "AppleScript". PsyScript is therefore both very easy to use and very powerful: for instance you can write scripts to e-mail result files to you, or log them into an online database. You have the ability to control other applications, implement adaptive experimental designs and handle complex structures like arrays and send data and instructions across the world via the Internet etc.

PsyScript also allows you to use the built in microphone as a voice key. It can also control the SMI eye tracker, and talk to the serial port in order to interface with EEG and MR machines.

PsyScript does not, however, include concepts such as "blocks", "conditions", or other psychological experimental notions. Instead it uses the more general programming constructs of lists (which can be lists of trials, blocks, etc.) and repeat structures to loop through these lists. Numerous (and increasing) examples are available to build on and because AppleScript allows you to build "handlers", you can build structured experiments that are easy to read. Because AppleScript is virtually like English: you already understand it quite well.

If you haven't already, take a quick look at the "Getting Familiar with PsyScript" page

Learning To Use PsyScript

The easiest way to understand PsyScript is to play with some experimental files. What do think this script will do?

tell application "PsyScript"
   activate
   reset all
   begin experiment
   do trial " 'hello world (press any key to continue)' "
   end experiment
end tell

You guessed right!: It will display the text "hello world (press any key to continue)" on your screen.

You can go a long way with plain English common sense and judicious use of this manual, the commented example experiments, the experiment library, and example trial strings. However, to become a PsyScript God, it helps to understand some basic concepts about AppleScript.

Understanding Applescript.

Applescript is Apple's core scripting language. Uniquely, it is both easy to read, and extremely powerful, and is a basic element of OS9 and OS-X.

Object Orientation

AppleScript (and PsyScript) are totally object oriented: the best way to think of PsyScript is as like a slightly slow research assistant to whom you send messages about what you would like to happen in an experiment.

Because AppleScript is object-oriented, to get things done you talk to objects and get their responses. PsyScript supports this "object model". So, if you wanted to know what mapping (the "labels" you can attach to responses in PsyScript) was assigned to every one of the currently noticed keys you would type:

tell application "PsyScript"
   get mapping of every key whose noticed is true
end tell

Psyscript will return a list of mapping strings like this: {"no", "yes"} indicating that you have set two keys to be noticed (only presses on these two keys will be recognized) with the labels yes and no.

What you did was ask all the key objects to return the value of their noticed property.

Once you understand the idea of setting and getting the properties of PsyScript objects, you can program many experiments on your own.

Now you are wanting to know "where do I find out what things I can get and set?" Good questions: All the properties that can be got or set are laid out for you in the dictionary ...

The Dictionary

The nouns and verbs that PsyScript understands are shown in its dictionary. To open the PsyScript dictionary, simply drag PsyScript onto the script editor, or choose the "Open Dictionary" Command from the File menu in either Script Editor or Script Debugger.

Do this now, so you have the dictionary open on screen as you read this next section. This is a screen grab from script debugger. If you are using script editor, just select the PsyScript application from the open dictionary menu.

Inside the Dictionary

As you can see, the PsyScript Dictionary is a suite of commands or verbs (like "draw line" and "begin experiment"), and beneath these are (in italics) a suite of classes (like "permanent stimulus" and "key". The commands get stuff done. The three you will use most frequently are "get", "set", and "do trial". Classes have properties, and it is these that you get and set to control how PsyScript behaves.

The key to becoming a PsyScript programmer is not so much reading this manual (though you definitely need it for the trial syntax) but in exploring the dictionary, playing with different commands by just getting the value of classes and seeing what is what.

In particular, spend half an hour browsing the properties of the "application" class: this is where all the action is. In here you see all the things you might need to set, and all the things you can get. For instance, the PsyScript application is where you set the response type, parameters for the voice key, and a range of other things.

You can see that the named objects like clicks and keys have properties. You can also talk to these items, i.e.:

tell application "PsyScript"
   get the pupil size of every eyelink sample whose coordinates = {100, 100}
end tell

Once you understand these simple concepts: that you can address objects - telling them to do things or accessing their properties, then you are well along the way to understanding PsyScript. Now, let's look at an actual experiment.

Note too that AppleScript pretty-prints or highlights your script so you can easily spot errors.

A simple experiment

tell application "PsyScript"

-- this is a simple example
activate
begin experiment
do trial " !e 'hello world' #2000 'you just ran your first trial - press any key' !t "
set theRT to reaction time
end experiment
return theRT

end tell

Let's look at what we have done. The comment syntax in AppleScript is

-- Single line comments are preceded by two dashes
(*
to make a multi-line comment,
enclose it in bracketed asterisks like this
*)

PsyScript has to be the frontmost application during an experiment, hence we started by saying activate.

All experiments have a beginning and an end: so all your experiments will begin and end with begin experiment and end with end experiment.

Inside, we have a core command - do trial. This is what you use to present trials.

do trial uses a very simple but extremely powerful syntax, designed by Pepper Williams, and extended somewhat in PsyScript.

A trial is a series of event symbols separated by spaces. In this case, we have:

1. Erased the screen (!e)
2. Shown a phrase (words enclosed in single quotes)
3. Paused for two seconds (#2000)
4. Shown another phrase
5. Started a reaction timer clock (!t)
6. After you pressed a key, the trial stopped.

Graphically:

You can learn all about this syntax here in the manual or here as a "swat sheet".

The last things we did were to save the reaction time property into a variable "theRT", so that we could do something with it later. We did this by "setting" the variable. To set the value of things, you just say:

set <name of thing> to <value>

AppleScript does not require you to declare variables before you use them, and variable are loosely typed: you can put anything in them, and AppleScript tries hard to coerce things into compatible types.

Do trial is more sophisticated than this, however, and you will usually use this more sophisticated form.

   set myTrial to "!e + #2000 ?1 #800 !t ?2 #500"
   do trial myTrial given {"did you see this?", "########"}

What happens when you execute this? - do trial replaces each occurrence of ?n with the respective item from the “given” list. So the line above is equivalent to:

   do trial "!e + #2000 'did you see this?' #800 !t '########' #500"

do trial is so important, that it has its own section. Read that now

You should also visit the Dictionary page to learn more about the properties that you can set in PsyScript

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