Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
# -*- coding: utf-8 -*-
The script is a part of a PsychoPy course which you can learn more about here:
It does require that you have the helper module in the same folder as
the script. Find in the course materials.
Version 2015-05
Free to use for any purpose. Credit is nice but not required.
By Jonas Kristoffer Lindeløv:
This is a template for scripting psychopy experiments while following good
practicies. The template is thoroughly commented in order to explain the code
as well as the rationale of doing it this particular way. The actual code
length without comments and initial variables is just around 80 lines, so it's
not as overwhelming as it might look :-) This script is targeted at psychopy
beginners with a few general purposes: (1) it introduces the basic psychopy
functions you're most likely to need in a full experiment, (2) proposes an
effecient and flexible code structure which you can use as a head-start when
coding most experiments, (3) prevent rookie mistakes in timing and crashes.
This is a silly experiment in which users are asked to indicate the orientation
of a gabor patch. It can show up at different locations and is either preceeded
by a fixation cross indicating it's true position or a false position.
Furthermore, it has various durations. Maybe we want to see the impact of cue
and stimulus duration on identification performance.
Formally the design is factorial: orientation x duration x positions x trueCue.
The important thing is that this experiment incorporates most features that
experiments will use:
* Initial dialogue box
* Display messages and ask questions to participants (intro, instructions,
per-trial-questions etc.). Records reaction time. Also pauses at
regular intervals of trials.
* Nice control of blocks and conditions. Easy to run conditions in multiple
orders to counterbalance possible order effects.
* Accurate timing of stimulus presentation (by monitor frames instead of
milliseconds) and assessment of this timing. Read why this is important
Also accurate timing of keyboard responses.
* Use eye-degrees as units of visual size.
* Save data after each trial to minimize data loss in the event of a crash.
* Easily scalable to complex experiments.
* Note that iohub should be used to get keyboard events in general, but in
this experiment, event is fine since all answers are during wait-periods.
The general coding strategy is to prepare absolutely everything before the
critical data-collection part begins. The purpose is to minimize computational
load and complexity during the actual presentation of the stimuli. As such,
lag and potential errors is minimized prevented during stimulus presentation.
Most of the stuff is done before the welcome screen even hits the participant.
Only a little is left to be done before each trial (change relevant
stimulus parameters for this trial) and this is done before the timing critical
Another general coding strategy is to keep stuff-you-or-others-might-change-often
in dedicated sections. This is the VARIABLES and the RUN EXPERIMENT sections.
This is the stuff that you would usually report in your method's section
(like the ISI, number of trials, question text, sequence of blocks etc.).
The philosophy is to keep function and "content" separate so that you (and
others) may easily adapt the experiment without having to scroll down through
the code to change these variables in a lot of obscure places.
The overall code structure of this template goes like this:
* VARIABLES: variables pertaining to trials and stimulus presentation.
* IMPORT the python modules to be used. The python convention is to import in
the beginning of the script.
* DIALOGUE AND STIMULI: Initiate psychopy stimuli and handy variables. This is
computationally heavy.
* FUNCTIONS: Define functions that does all the stimulus presentation.
* RUN EXPERIMENT: actually execute the experiment, with the instructions and
blocks in any order you'd like.
I've tried to conform to python's PEP8 style guide. See
# Monitor parameters
MON_DISTANCE = 60 # Distance between subject's eyes and monitor
MON_WIDTH = 50 # Width of your monitor in cm
MON_SIZE = [1024, 768] # Pixel-dimensions of your monitor
SAVE_FOLDER = 'templateData' # Log is saved to this folder. The folder is created if it does not exist.
# Stimulus parameters
GABOR_SF = 4 # 4 cycles per degree visual angle
GABOR_SIZE = 5 # in degrees visual angle
FIX_HEIGHT = 1 # Text height of fixation cross
# Timings
FRAMES_FIX = 30 # in frames. ~ 500 ms on 60 Hz
FRAMES_STIM = [6, 9, 12] # in frames. ~ 100, 150 and 200 ms on 60 Hz
FRAMES_MASK = 3 # in frames. ~ 50 ms on 60 Hz
# Condition parameters
REPETITIONS = 2 # number of trials per condition
POSITIONS = [-3, 0, 3] # x-positions
ORIS = {'right': 0, 'left': 90} # Orientations and corresponding responses! values = ORIS.values() and keyboard keys = ORIS.keys()
PAUSE_INTERVAL = 10 # Number of trials between breaks
# Questions and messages
MESSAGE_POS = [0, 3] # [x, y]
MESSAGE_HEIGHT = 1 # Height of the text, still in degrees visual angle
TEXT_BREAK = 'Press any key to continue...' # text of regular break
KEYS_QUIT = ['escape'] # Keys that quits the experiment
Press LEFT if the lines are horizontal.
Press RIGHT if the lines are vertical.
Keep your gaze at the cross at all times."""
This is computationally heavy stuff. Thus we do it in the beginning of our experiment
# Import stuff
import ppc
print 'the physical diameter of the gabor patch should be', ppc.deg2cm(GABOR_SIZE, MON_DISTANCE), 'cm'
print 'the physical size of the fixation cross should be', ppc.deg2cm(FIX_HEIGHT, MON_DISTANCE), 'cm'
from psychopy import core, visual, gui, monitors, sound, event
import random
# Intro-dialogue. Get subject-id and other variables.
# Save input variables in "V" dictionary (V for "variables")
V = {'subject':'', 'condition': ['trueFix', 'falseFix'], 'age':'', 'gender':['male', 'female']}
if not gui.DlgFromDict(V, order=['subject', 'age', 'gender']).OK:
# Stuff
clock = core.Clock() # A clock wich will be used throughout the experiment to time events on a trial-per-trial basis (stimuli and reaction times).
writer = ppc.csvWriter(str(V['subject']), saveFolder=SAVE_FOLDER) # writer.write(trial) will write individual trials with low latency
# Create psychopy window
my_monitor = monitors.Monitor('testMonitor', width=MON_WIDTH, distance=MON_DISTANCE) # Create monitor object from the variables above. This is needed to control size of stimuli in degrees.
win = visual.Window(monitor=my_monitor, units='deg', fullscr=True, allowGUI=False, color='black') # Initiate psychopy Window as the object "win", using the myMon object from last line. Use degree as units!
# Stimuli.
stim_gabor = visual.GratingStim(win, mask='gauss', sf=GABOR_SF, size=GABOR_SIZE) # A gabor patch. Again, units are inherited.
stim_fix = visual.TextStim(win, '+', height=FIX_HEIGHT) # Fixation cross is just the character "+". Units are inherited from Window when not explicitly specified.
stim_text = visual.TextStim(win, pos=MESSAGE_POS, height=MESSAGE_HEIGHT, wrapWidth=999) # Message / question stimulus. Will be used to display instructions and questions.
sound_success = sound.Sound('C', secs=0.1, octave=6) # Obs, ppc.Sound() is much more accurate, but only works on windows.
sound_fail = sound.Sound('C', secs=0.4, octave=4)
def ask(text='', keyList=None):
Ask subject something. Shows question and returns answer (keypress)
and reaction time. Defaults to no text and all keys.
# Draw the TextStims to visual buffer, then show it and reset timing immediately (at stimulus onset)
stim_text.text = text
time_flip = win.flip() # time of core.monotonicClock.getTime() at flip
# Halt everything and wait for (first) responses matching the keys given in the Q object.
if keyList:
keyList += KEYS_QUIT
key, time_key = event.waitKeys(keyList=keyList, timeStamped=True)[0] # timestamped according to core.monotonicClock.getTime() at keypress. Select the first and only answer.
if key in KEYS_QUIT: # Look at first reponse [0]. Quit everything if quit-key was pressed
return key, time_key - time_flip # When answer given, return it.
def make_trial_list(condition):
Return a list of trials (list of dictionaries) in advance of actually displaying them.
A makeTriallList('falseFix') with REPETITIONS=1 could generate a trial list like this::
trial_list = [
{'xpos': 0, 'ori': 90, 'durationReal': '', 'response': '', 'condition': 'falseFix', 'subject': u'nick', 'rt': '', 'no': 0, 'gender': u'male', 'age': u'42', 'score': '', 'fixPos': -3},
{'xpos': -3, 'ori': 90, 'durationReal': '', 'response': '', 'condition': 'falseFix', 'subject': u'nick', 'rt': '', 'no': 1, 'gender': u'male', 'age': u'42', 'score': '', 'fixPos': 0},
{'xpos': -3, 'ori': 0, 'durationReal': '', 'response': '', 'condition': 'falseFix', 'subject': u'nick', 'rt': '', 'no': 2, 'gender': u'male', 'age': u'42', 'score': '', 'fixPos': 3},
{'xpos': 3, 'ori': 0, 'durationReal': '', 'response': '', 'condition': 'falseFix', 'subject': u'nick', 'rt': '', 'no': 3, 'gender': u'male', 'age': u'42', 'score': '', 'fixPos': -3},
{'xpos': 0, 'ori': 0, 'durationReal': '', 'response': '', 'condition': 'falseFix', 'subject': u'nick', 'rt': '', 'no': 4, 'gender': u'male', 'age': u'42', 'score': '', 'fixPos': -3},
{'xpos': 3, 'ori': 90, 'durationReal': '', 'response': '', 'condition': 'falseFix', 'subject': u'nick', 'rt': '', 'no': 5, 'gender': u'male', 'age': u'42', 'score': '', 'fixPos': -3}
Calling trials[0] gives the first trial, trials[1] the 2nd trial etc.
When the experiment executes, it will simply loop over these trials from first to last using
for trial in trial_list:
# do something with the trial here
It is suggested to keep all non-constant information in trials instead of
external variables, "non-constant" being what is not the same for all trials
and all subjects. This is stuff that you want to do statistics on.
Remember, the problem is never too much data - it's too little data.
Note that every trial-dictionary should have the same fields. Note also
that there are placeholders for answers to be collected (e.g. ans and ansTime).
You could use instead of the code below, which
would be great for this simple case. But building your trials like below
is scaleable to more complex cases and you remain in control.
# Factorial design
trial_list = []
for ori in ORIS.values():
for pos in POSITIONS:
for dur in FRAMES_STIM:
for rep in range(REPETITIONS):
# Add a dictionary for every trial
trial_list += [{
'ori': ori,
'xpos': pos,
'fixPos': pos if condition == 'trueFix' else random.choice([x for x in POSITIONS if x is not pos]),
'subject': V['subject'],
'age': V['age'],
'gender': V['gender'],
'condition': condition,
'duration': dur,
'durationReal': '',
'response': '',
'rt': '',
'score': ''
# Randomize order
from random import sample
trial_list = sample(trial_list, len(trial_list))
# Add trial numbers and return
for i, trial in enumerate(trial_list):
trial['no'] = i + 1 # start at 1 instead of 0
return trial_list
def run_condition(condition):
Runs a block of trials. This is the presentation of stimuli,
collection of responses and saving the trial
ask(TEXT_INSTRUCT) # Instruction
# Displays trials. Remember: prepare --> timing critical stuff --> score, save etc.
for trial in make_trial_list(condition):
# Prepare trial here, before entering the time-critical period
stim_gabor.ori = trial['ori']
stim_gabor.pos = [trial['xpos'], 0]
stim_fix.pos = [trial['fixPos'], 0]
# A break at regular interval. Also at the beginning of the experiment
# Show break message when trial['no'] is a multiple of PAUSE_INTERVAL (% is modulus)
if trial['no'] % PAUSE_INTERVAL is 0:
# Fixation cue
for frame in range(FRAMES_FIX):
# Stimulus
for frame in range(trial['duration']):
# Mask
for frame in range(FRAMES_MASK):
for ori in ORIS.values():
stim_gabor.ori = ori
# Get actual duration at offset
win.flip() # blank screen
trial['durationReal'] = clock.getTime()
# Ask question and record responses.
trial['response'], trial['rt'] = ask(' ', ORIS.keys())
trial['score'] = 1 if ORIS[trial['response']] == trial['ori'] else 0 # 1 if key corresponds to the shown orientation if trial['score'] else # feedback
# Save trial
Now it's really simple. You simply execute things using the functions ask and
run_condition. Here we order block types given input from dialogue box
if V['condition'] == 'trueFix':
elif V['condition'] == 'falseFix':