PsychoPy Psychology Software For Python Psycho Py 1.78.00 Manual

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 243 [warning: Documents this large are best viewed by clicking the View PDF Link!]

PsychoPy - Psychology software for
Python
Release 1.78.00
Jonathan Peirce
August 02, 2013
CONTENTS
1 Overview 3
1.1 Features .................................................. 3
1.2 Hardware Integration ........................................... 4
1.3 System requirements ........................................... 4
2 Contributing to the project 5
2.1 Why make it free? ............................................ 5
2.2 How do I contribute changes? ...................................... 5
2.3 Contribute to the Forum (mailing list) .................................. 5
3 Credits 7
3.1 Developers ................................................ 7
3.2 Support .................................................. 7
3.3 Funding .................................................. 7
4 Installation 9
4.1 Overview ................................................. 9
4.2 Recommended hardware ......................................... 9
4.3 Windows ................................................. 9
4.4 Mac OS X ................................................ 10
4.5 Linux ................................................... 10
5 Dependencies 11
5.1 Essential packages ............................................ 11
5.2 Suggested packages ........................................... 12
6 Getting Started 13
7 Builder 15
7.1 A first program .............................................. 15
7.2 Getting beyond Hello .......................................... 17
8 Builder-to-coder 19
9 Coder 21
10 General issues 23
10.1 Monitor Center .............................................. 23
10.2 Units for the window and stimuli .................................... 24
10.3 Color spaces ............................................... 25
i
10.4 Preferences ................................................ 28
10.5 Data outputs ............................................... 29
10.6 Gamma correcting a monitor ....................................... 31
10.7 Timing Issues and synchronisation .................................... 33
11 Builder 39
11.1 Builder concepts ............................................. 40
11.2 Routines ................................................. 41
11.3 Flow ................................................... 41
11.4 Components ............................................... 44
11.5 Experiment settings ........................................... 56
11.6 Defining the onset/duration of components ............................... 57
11.7 Generating outputs (datafiles) ...................................... 58
11.8 Common Mistakes (aka Gotcha’s) .................................... 58
11.9 Compiling a Script ............................................ 59
11.10 Set up your monitor properly ...................................... 60
11.11 Future developments ........................................... 60
12 Coder 61
12.1 Basic Concepts .............................................. 61
12.2 PsychoPy Tutorials ............................................ 65
13 Troubleshooting 73
13.1 The application doesn’t start ....................................... 73
13.2 I run a Builder experiment and nothing happens ............................. 74
13.3 Manually turn off the viewing of output ................................. 74
13.4 Use the source (Luke?) .......................................... 74
13.5 Cleaning preferences and app data .................................... 74
14 Recipes (“How-to”s) 77
14.1 Adding external modules to Standalone PsychoPy ........................... 77
14.2 Animation ................................................ 78
14.3 Scrolling text ............................................... 78
14.4 Fade-in / fade-out effects ......................................... 78
14.5 Building an application from your script ................................. 79
14.6 Builder - providing feedback ....................................... 80
14.7 Builder - terminating a loop ....................................... 81
14.8 Installing PsychoPy in a classroom (administrators) ........................... 82
14.9 Generating formatted strings ....................................... 84
14.10 Coder - interleave staircases ....................................... 84
14.11 Making isoluminant stimuli ....................................... 85
14.12 Adding a web-cam ............................................ 86
15 Frequently Asked Questions (FAQs) 89
15.1 Why is the bits++ demo not working? .................................. 89
15.2 Can PsychoPy run my experiment with sub-millisecond timing? .................... 89
16 Resources (e.g. for teaching) 91
16.1 P4N .................................................... 91
16.2 Youtube tutorials ............................................. 91
16.3 Lecture materials (Builder) ........................................ 91
16.4 Lecture materials (Coder) ........................................ 91
16.5 Previous events .............................................. 92
17 Reference Manual (API) 93
ii
17.1 psychopy.core - basic functions (clocks etc.) ............................ 93
17.2 psychopy.visual - many visual stimuli .............................. 95
17.3 psychopy.data - functions for storing/saving/analysing data .................... 146
17.4 psychopy.contrib.opensslwrap Encryption (beta) ...................... 162
17.5 psychopy.event - for keypresses and mouse clicks ......................... 167
17.6 psychopy.filters - helper functions for creating filters ...................... 169
17.7 psychopy.gui - create dialogue boxes ................................ 172
17.8 psychopy.hardware - hardware interfaces ............................. 173
17.9 psychopy.info - functions for getting information about the system ................ 186
17.10 psychopy.logging - control what gets logged ........................... 187
17.11 psychopy.microphone - Capture and analyze sound ....................... 189
17.12 psychopy.misc - miscellaneous routines for converting units etc .................. 194
17.13 psychopy.monitors - for those that don’t like Monitor Center .................. 197
17.14 psychopy.parallel - functions for interacting with the parallel port ............... 202
17.15 psychopy.serial - functions for interacting with the serial port .................. 204
17.16 psychopy.sound - play various forms of sound ........................... 204
17.17 psychopy.web - Web methods .................................... 205
17.18 Indices and tables ............................................ 207
18 For Developers 209
18.1 Using the repository ........................................... 209
18.2 Adding documentation .......................................... 212
18.3 Adding a new Builder Component .................................... 213
18.4 Style-guide for coder demos ....................................... 215
18.5 Adding a new Menu Item ........................................ 217
19 PsychoPy Experiment file format (.psyexp) 219
19.1 Parameters ................................................ 219
19.2 Settings .................................................. 219
19.3 Routines ................................................. 220
19.4 Components ............................................... 220
19.5 Flow ................................................... 220
19.6 Names .................................................. 220
20 Glossary 223
21 Indices 225
Python Module Index 227
Index 229
iii
iv
PsychoPy - Psychology software for Python, Release 1.78.00
Contents:
CONTENTS 1
PsychoPy - Psychology software for Python, Release 1.78.00
2 CONTENTS
CHAPTER
ONE
OVERVIEW
PsychoPy is an open-source package for running experiments in Python (a real and free alternative to Matlab). Psy-
choPy combines the graphical strengths of OpenGL with the easy Python syntax to give scientists a free and simple
stimulus presentation and control package. It is used by many labs worldwide for psychophysics, cognitive neuro-
science and experimental psychology.
Because it’s open source, you can download it and modify the package if you don’t like it. And if you make changes
that others might use then please consider giving them back to the community via the mailing list. PsychoPy has been
written and provided to you absolutely for free. For it to get better it needs as much input from everyone as possible.
1.1 Features
There are many advantages to using PsychoPy, but here are some of the key ones
• Simple install process
•Huge variety of stimuli (see screenshots) generated in real-time:
–linear gratings, bitmaps constantly updating
–radial gratings
–random dots
–movies (DivX, mov, mpg...)
–text (unicode in any truetype font)
–shapes
–sounds (tones, numpy arrays, wav, ogg...)
• Platform independent - run the same script on Win, OS X or Linux
• Flexible stimulus units (degrees, cm, or pixels)
•Coder interface for those that like to program
•Builder interface for those that don’t
• Input from keyboard, mouse, microphone or button boxes
• Multi-monitor support
• Automated monitor calibration (for supported photometers)
3
PsychoPy - Psychology software for Python, Release 1.78.00
1.2 Hardware Integration
PsychoPy supports communication via serial ports, parallel ports and compiled drivers (dlls and dylibs), so it can talk to any hardware that your computer can! Interfaces are prebuilt for;
• Spectrascan PR650, PR655, PR670
• Minolta LS110, LS100
• Cambridge Research Systems Bits++
• Cedrus response boxes (RB7xx series)
1.3 System requirements
Although PsychoPy runs on a wide variety of hardware, and on Windows, OS X or Linux, it really does benefit from
a decent graphics card. Get an ATI or nVidia card that supports OpenGL 2.0. Avoid built-in Intel graphics chips (e.g.
GMA 950)
4 Chapter 1. Overview
CHAPTER
TWO
CONTRIBUTING TO THE PROJECT
PsychoPy is an open-source, community-driven project. It is written and provided free out of goodwill by people that
make no money from it and have other jobs to do. The way that open-source projects work is that users contribute
back some of their time.
2.1 Why make it free?
It has taken, literally, thousands of hours of programming to get PsychoPy where it is today and it is provided absolutely
for free. Without somone working on it full time (which would mean charging you for it) the only way for the software
to keep getting better is if people contribute back to the project.
Please, please, please make the effort to give a little back to this project. If you found the documentation hard to
understand then think about how you would have preferred it to be written and contribute it.
2.2 How do I contribute changes?
For simple changes, and for users that aren’t so confident with things like version control systems then just send your
changes to the mailing list.
If you want to make more substantial changes then its often good to discuss them first on the developers mailing list.
The ideal model, is to contribute via the repository on github. There is more information on that in the For Developers
section of the documentation.
2.3 Contribute to the Forum (mailing list)
The easiest way to help the project is to write to the forum (mailing list) with suggestions and solutions.
For documentation suggestions please try to provide actual replacement text. You, as a user, are probably better placed
to write this than the actual developers (they know too much to write good docs)!
If you’re having problems, e.g. you think you may have found a bug:
• take a look at the Troubleshooting and Common Mistakes (aka Gotcha’s) first
• submit a message with as much information as possible about your system and the problem
• please try to be precise. Rather than say “It didn’t work” try to say what what specific form of “not
working” you found (did the stimulus not appear? or it appeared but poorly rendered? or the whole
application crashed?!)
5
PsychoPy - Psychology software for Python, Release 1.78.00
• if there is an error message, try to provide it completely
If you had problems and worked out how to fix things, even if it turned out the problem was your own lack of under-
standing, please still contribute the information. Others are likely to have similar problems. Maybe the documentation
could be clearer, or your email to the forum will be found by others googling for the same problem.
To make your message more useful you should, please try to:
• provide info about your system and PsychoPy version(e.g. the output of the sysInfo demo in coder). A lot
of problems are specific to a particular graphics card or platform
• provide a minimal example of the breaking code (if you’re writing scripts)
6 Chapter 2. Contributing to the project
CHAPTER
THREE
CREDITS
3.1 Developers
PsychoPy was initially created and maintained by Jon Peirce but has many contributors to the code:
Jeremy Gray, Yaroslav Halchenko, Erik Kastman, Mike MacAskill, William Hogman, Jonas Lindeløv,
Ariel Rokem, Dave Britton, Gary Strangman, C Luhmann, Sol Simpson, Hiroyuki Sogo
You can see details of contributions on Ohloh.net and there’s a visualisation of PsychoPy’s development history on
youtube.
PsychoPy also stands on top of a large number of other developers’ work. It wouldn’t be possible to write this package
without the preceding work of those that wrote the Dependencies
3.2 Support
Software projects aren’t just about code. A great deal of work is done by the community in terms of support-
ing each other. Jeremy Gray, Mike MacAskill, Jared Roberts and Jonas Lindelov particularly stand out in doing
a fantastic job of answering other users’ questions. You can see the most active posters on the users list here:
https://groups.google.com/forum/#!aboutgroup/psychopy-users
3.3 Funding
The PsychoPy project has attracted small grants from the HEA Psychology Network and Cambridge Research Systems
. Thanks to those organisations for their support.
Jon is paid by The University of Nottingham (which allows him to spend time on this) and his grants from the BBSRC
and Wellcome Trust have also helped the development PsychoPy.
7
PsychoPy - Psychology software for Python, Release 1.78.00
8 Chapter 3. Credits
CHAPTER
FOUR
INSTALLATION
4.1 Overview
PsychoPy can be installed in three main ways:
•As an application: The “Stand Alone” versions include everything you need to create and run experiments.
When in doubt, choose this option.
•As libraries: PsychoPy and the libraries it depends on can also be installed individually, providing greater
flexibility. This option requires managing a python environment.
•As source code: If you want to customize how PsychoPy works, consult the developer’s guide for installation
and work-flow suggestions.
When you start PsychoPy for the first time, a Configuration Wizard will retrieve and summarize key system settings.
Based on the summary, you may want to adjust some preferences to better reflect your environment. In addition, this
is a good time to unpack the Builder demos to a location of your choice. (See the Demo menu in the Builder.)
If you get stuck or have questions, please email the mailing list.
If all goes well, at this point your installation will be complete! See the next section of the manual, Getting started.
4.2 Recommended hardware
The minimum requirement for PsychoPy is a computer with a graphics card that supports OpenGL. Many newer
graphics cards will work well. Ideally the graphics card should support OpenGL version 2.0 or higher. Certain visual
functions run much faster if OpenGL 2.0 is available, and some require it (e.g. ElementArrayStim).
If you already have a computer, you can install PsychoPy and the Configuration Wizard will auto-detect the card and
drivers, and provide more information. It is inexpensive to upgrade most desktop computers to an adequate graphics
card. High-end graphics cards can be very expensive but are only needed for vision research (and high-end gaming).
If you’re thinking of buying a laptop for running experiments, avoid the built-in Intel graphics chips (e.g. GMA
950). The drivers are crummy and performance is poor; graphics cards on laptops are more difficult to exchange. Get
something with nVidia or ATI chips instead. Some graphics cards that are known to work with PsychoPy can be found
here; that list is not exhaustive, many cards will also work.
4.3 Windows
Once installed, you’ll now find a link to the PsychoPy application in > Start > Progams > PsychoPy2. Click that and
the Configuration Wizard should start.
9
PsychoPy - Psychology software for Python, Release 1.78.00
The wizard will try to make sure you have reasonably current drivers for your graphics card. You may be directed
to download the latest drivers from the vendor, rather than using the pre-installed windows drivers. If necessary, get
new drivers directly from the graphics card vendor; don’t rely on Windows updates. The windows-supplied drivers are
buggy and sometimes don’t support OpenGL at all.
The StandAlone installer adds the PsychoPy folder to your path, so you can run the included version of python from
the command line. If you have your own version of python installed as well then you need to check which one is run
by default, and change your path according to your personal preferences.
4.4 Mac OS X
There are different ways to install PsychoPy on a Mac that will suit different users. Almost all Mac’s come with a
suitable video card by default.
• Intel Mac users (with OS X v10.7 or higher; 10.5 and 10.6 might still work) can simply download the standalone
application bundle (the dmg file) and drag it to their Applications folder. (Installing it elsewhere should work
fine too.)
• Users of macports can install PsychoPy and all its dependencies simply with:
sudo port install py25-psychopy
(Thanks to James Kyles.)
• For PPC Macs (or for Intel Mac users that want their own custom python for running PsychoPy) you need to
install the dependencies and PsychoPy manually. The easiest way is to use the Enthought Python Distribution
(see Dependencies, below).
• You could alternatively manually install the ‘framework build’ of python and the dependencies (see below). One
advantage to this is that you can then upgrade versions with:
sudo easy_install -N -Z -U psychopy
4.5 Linux
Debian systems: PsychoPy is in the Debian packages index so you can simply do:
sudo apt-get install psychopy
Ubuntu (and other Debian-based distributions):
1. Add the following sources in Synaptic, in the Configuration > Repository dialog box, under “Other software”:
deb http://neuro.debian.net/debian karmic main contrib non-free
deb-src http://neuro.debian.net/debian karmic main contrib non-free
2. Then follow the ‘Package authentification’ procedure described in http://neuro.debian.net/
3. Then install the psychopy package under Synaptic or through sudo apt-get install psychopy which will install
all dependencies.
(Thanks to Yaroslav Halchenko for the Debian and NeuroDebian package.)
non-Debian systems: You need to install the dependencies below. Then install PsychoPy:
$ sudo easy_install psychopy
...
Downloading http://psychopy.googlecode.com/files/PsychoPy-1.75.01-py2.7.egg
10 Chapter 4. Installation
CHAPTER
FIVE
DEPENDENCIES
Like many open-source programs, PsychoPy depends on the work of many other people in the form of libraries.
5.1 Essential packages
Python: If you need to install python, or just want to, the easiest way is to use the Enthought Python Distribution,
which is free for academic use. Be sure to get a 32-bit version. The only things it misses are avbin,pyo, and flac.
If you want to install each library individually rather than use the simpler distributions of packages above then you can
download the following. Make sure you get the correct version for your OS and your version of Python. easy_install
will work for many of these, but some require compiling from source.
•python (32-bit only, version 2.6 or 2.7; 2.5 might work, 3.x will not)
•avbin (movies) On mac: 1) Download version 5 from google (not a higher version). 2) Start terminal, type sudo
mkdir -p /usr/local/lib . 3) cd to the unpacked avbin directory, type sh install.sh . 4) Start or restart PsychoPy,
and from PsychoPy’s coder view shell, this should work: from pyglet.media import avbin . If you run a script
and get an error saying ‘NoneType’ object has no attribute ‘blit’, it probably means you did not install version
5.
•setuptools
•numpy (version 0.9.6 or greater)
•scipy (version 0.4.8 or greater)
•pyglet (version 1.1.4, not version 1.2)
•wxPython (version 2.8.10 ro 2.8.11, not 2.9)
•Python Imaging Library (sudo easy_install PIL)
•matplotlib (for plotting and fast polygon routines)
•lxml (needed for loading/saving builder experiment files)
•openpyxl (for loading params from xlsx files)
•pyo (sound, version 0.6.2 or higher, compile with —-no-messages)
These packages are only needed for Windows:
•pywin32
•winioport (to use the parallel port)
•inpout32 (an alternative method to using the parallel port on Windows)
11
PsychoPy - Psychology software for Python, Release 1.78.00
•inpoutx64 (to use the parallel port on 64-bit Windows)
These packages are only needed for Linux:
•pyparallel (to use the parallel port)
5.2 Suggested packages
In addition to the required packages above, additional packages can be useful to PsychoPy users, e.g. for controlling
hardware and performing specific tasks. These are packaged with the Standalone versions of PsychoPy but users with
their own custom Python environment need to install these manually. Most of these can be installed with easy_install.
General packages:
• psignifit for bootstrapping and other resampling tests
• pyserial for interfacing with the serial port
• parallel python (aka pp) for parallel processing
•flac audio codec, for working with google-speech
Specific hardware interfaces:
•pynetstation to communicate with EGI netstation. See notes on using egi (pynetstation)
• ioLabs toolbox
• labjack toolbox
For developers:
•pytest and coverage for running unit tests
•sphinx for building documentation
12 Chapter 5. Dependencies
CHAPTER
SIX
GETTING STARTED
As an application, PsychoPy has two main views: the Builder view, and the Coder view. It also has a underlying API
that you can call directly.
1. Builder. You can generate a wide range of experiments easily from the Builder using its intuitive, graphical
user interface (GUI). This might be all you ever need to do. But you can always compile your experiment
into a python script for fine-tuning, and this is a quick way for experienced programmers to explore some of
PsychoPy’s libraries and conventions.
2. Coder. For those comfortable with programming, the Coder view provides a basic code editor with syntax
highlighting, code folding, and so on. Importantly, it has its own output window and Demo menu. The demos
illustrate how to do specific tasks or use specific features; they are not whole experiments. The Coder tutorials
should help get you going, and the API reference will give you the details.
The Builder and Coder views are the two main aspects of the PsychoPy application. If you’ve installed the StandAlone
version of PsychoPy on MS Windows then there should be an obvious link to PsychoPy in your > Start > Programs. If
you installed the StandAlone version on Mac OS X then the application is where you put it (!). On these two platforms
you can open the Builder and Coder views from the View menu and the default view can be set from the preferences.
On linux, you can start PsychoPy from a command line, or make a launch icon (which can depend on the desktop and
distro). If the PsychoPy app is started with flags —-coder (or -c), or —-builder (or -b), then the preferences will be
overridden and that view will be created as the app opens.
For experienced python programmers, its possible to use PsychoPy without ever opening the Builder or Coder. Install
the PsychoPy libraries and dependencies, and use your favorite IDE instead of the Coder.
13
PsychoPy - Psychology software for Python, Release 1.78.00
14 Chapter 6. Getting Started
CHAPTER
SEVEN
BUILDER
When learning a new computer language, the classic first program is simply to print or display “Hello world!”. Lets
do it.
7.1 A first program
Start PsychoPy, and be sure to be in the Builder view.
• If you have poked around a bit in the Builder already, be sure to start with a clean slate. To get a new Builder
view, type Ctrl-N on Windows or Linux, or Cmd-N on Mac.
•Click on a Text component
15
PsychoPy - Psychology software for Python, Release 1.78.00
and a Text Properties dialog will pop up.
• In the Text field, replace the default text with your message. When you run the program, the text you type here
will be shown on the screen.
• Click OK (near the botton of the dialog box). (Properties dialogs have a link to online help—an icon at the
bottom, near the OK button.)
• Your text component now resides in a routine called trial. You can click on it to view or edit it. (Components,
Routines, and other Builder concepts are explained in the Builder documentation.)
•Back in the main Builder, type Ctrl-R (Windows, Linux) or Cmd-R (Mac), or use the mouse to click the Run icon.
16 Chapter 7. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
Assuming you typed in “Hello world!”, your screen should have looked this this (briefly):
If nothing happens or it looks wrong, recheck all the steps above; be sure to start from a new Builder view.
What if you wanted to display your cheerful greeting for longer than the default time?
• Click on your Text component (the existing one, not a new one).
• Edit the Stop duration (s) to be 3.2; times are in seconds.
• Click OK.
• And finally Run.
When running an experiment, you can quit by pressing the escape key (this can be configured or disabled). You can
quit PsychoPy from the File menu, or typing Ctrl-Q /Cmd-Q.
7.2 Getting beyond Hello
To do more, you can try things out and see what happens. You may want to consult the Builder documentation. Many
people find it helpful to explore the Builder demos, in part to see what is possible, and especially to see how different
things are done.
A good way to develop your own first PsychoPy experiment is to base it on the Builder demo that seems closest. Copy
it, and then adapt it step by step to become more and more like the program you have in mind. Being familiar with the
Builder demos can only help this process.
You could stop here, and just use the Builder for creating your experiments. It provides a lot of the key features that
people need to run a wide variety of studies. But it does have its limitations. When you want to have more complex
designs or features, you’ll want to investigate the Coder. As a segue to the Coder, lets start from the Builder, and see
how Builder programs work.
7.2. Getting beyond Hello 17
PsychoPy - Psychology software for Python, Release 1.78.00
18 Chapter 7. Builder
CHAPTER
EIGHT
BUILDER-TO-CODER
Whenever you run a Builder experiment, PsychoPy will first translate it into python code, and then execute that code.
To get a better feel for what was happening “behind the scenes” in the Builder program above:
• In the Builder, load or recreate your “hello world” program.
•Instead of running the program, explicitly convert it into python: Type F5, or click the Compile icon:
The view will automatically switch to the Coder, and display the python code. If you then save and run this code, it
would look the same as running it directly from the Builder.
It is always possible to go from the Builder to python code in this way. You can then edit that code and run it as a
python program. However, you cannot go from code back to a Builder representation.
To switch quickly between Builder and Coder views, you can type Ctrl-L /Cmd-L.
19
PsychoPy - Psychology software for Python, Release 1.78.00
20 Chapter 8. Builder-to-coder
CHAPTER
NINE
CODER
Being able to inspect Builder-generated code is nice, but its possible to write code yourself, directly. With the Coder
and various libraries, you can do virtually anything that your computer is capable of doing, using a full-featured
modern programming language (python).
For variety, lets say hello to the Spanish-speaking world. PsychoPy knows Unicode (UTF-8).
If you are not in the Coder, switch to it now.
• Start a new code document: Ctrl-N /Cmd-N.
• Type (or copy & paste) the following:
from psychopy import visual, core
win =visual.Window()
msg =visual.TextStim(win, text=u"\u00A1Hola mundo!")
msg.draw()
win.flip()
core.wait(1)
win.close()
• Save the file (the same way as in Builder).
• Run the script.
Note that the same events happen on-screen with this code version, despite the code being much simpler than the code
generated by the Builder. (The Builder actually does more, such as prompt for a subject number.)
Coder Shell
The shell provides an interactive python interpreter, which means you can enter commands here to try them out. This
provides yet another way to send your salutations to the world. By default, the Coder’s output window is shown at the
bottom of the Coder window. Click on the Shell tab, and you should see python’s interactive prompt, >>>:
PyShell in PsychoPy - type some commands!
Type "help", "copyright", "credits" or "license" for more information.
>>>
At the prompt, type:
>>> print u"\u00A1Hola mundo!"
You can do more complex things, such as type in each line from the Coder example directly into the Shell window,
doing so line by line:
21
PsychoPy - Psychology software for Python, Release 1.78.00
>>> from psychopy import visual, core
and then:
>>> win =visual.Window()
and so on—watch what happens each line::
>>> msg =visual.TextStim(win, text=u"\u00A1Hola mundo!")
>>> msg.draw()
>>> win.flip()
and so on. This lets you try things out and see what happens line-by-line (which is how python goes through your
program).
22 Chapter 9. Coder
CHAPTER
TEN
GENERAL ISSUES
These are issues that users should be aware of, whether they are using Builder or Coder views.
10.1 Monitor Center
PsychoPy provides a simple and intuitive way for you to calibrate your monitor and provide other information about
it and then import that information into your experiment.
Information is inserted in the Monitor Center (Tools menu), which allows you to store information about multiple
monitors and keep track of multiple calibrations for the same monitor.
For experiments written in the Builder view, you can then import this information by simply specifying the name of
the monitor that you wish to use in the Experiment settings dialog. For experiments created as scripts you can retrieve
the information when creating the Window by simply naming the monitor that you created in Monitor Center. e.g.:
from psychopy import visual
win =visual.Window([1024,768], mon=’SonyG500’)
Of course, the name of the monitor in the script needs to match perfectly the name given in the Monitor Center.
10.1.1 Real world units
One of the particular features of PsychoPy is that you can specify the size and location of stimuli in units that are
independent of your particular setup, such as degrees of visual angle (see Units for the window and stimuli). In order
for this to be possible you need to inform PsychoPy of some characteristics of your monitor. Your choice of units
determines the information you need to provide:
Units Requires
‘norm’ (normalised to widht/height) n/a
‘pix’ (pixels) Screen width in pixels
‘cm’ (centimeters on the screen) Screen width in pixels and screen width in cm
‘deg’ (degrees of visual angle) Screen width (pixels), screen width (cm) and distance (cm)
10.1.2 Calibrating your monitor
PsychoPy can also store and use information about the gamma correction required for your monitor. If you have
a Spectrascan PR650 (other devices will hopefully be added) you can perform an automated calibration in which
PsychoPy will measure the necessary gamma value to be applied to your monitor. Alternatively this can be added
manually into the grid to the right of the Monitor Center. To run a calibration, connect the PR650 via the serial port
and, immediately after turning it on press the Find PR650 button in the Monitor Center.
23
PsychoPy - Psychology software for Python, Release 1.78.00
Note that, if you don’t have a photometer to hand then there is a method for determining the necessary gamma value
psychophysically included in PsychoPy (see gammaMotionNull and gammaMotionAnalysis in the demos menu).
The two additional tables in the Calibration box of the Monitor Center provide conversion from DKL and LMS colour
spaces to RGB.
10.2 Units for the window and stimuli
One of the key advantages of PsychoPy over many other experiment-building software packages is that stimuli can be
described in a wide variety of real-world, device-independent units. In most other systems you provide the stimuli at
a fixed size and location in pixels, or percentage of the screen, and then have to calculate how many cm or degrees of
visual angle that was.
In PsychoPy, after providing information about your monitor, via the Monitor Center, you can simply specify your
stimulus in the unit of your choice and allow PsychoPy to calculate the appropriate pixel size for you.
Your choice of unit depends on the circumstances. For conducting demos, the two normalised units (‘norm’ and
‘height’) are often handy because the stimulus scales naturally with the window size. For running an experiment it’s
usually best to use something like ‘cm’ or ‘deg’ so that the stimulus is a fixed size irrespective of the monitor/window.
For all units, the centre of the screen is represented by coordinates (0,0), negative values mean down/left, positive
values mean up/right.
10.2.1 Height units
With ‘height’ units everything is specified relative to the height of the window (note the window, not the screen).
As a result, the dimensions of a screen with standard 4:3 aspect ratio will range (-0.6667,-0.5) in the bottom left to
(+0.6667,+0.5) in the top right. For a standard widescreen (16:10 aspect ratio) the bottom left of the screen is (-0.8,-
0.5) and top-right is (+0.8,+0.5). This type of unit can be useful in that it scales with window size, unlike Degrees of
visual angle or Centimeters on screen, but stimuli remain square, unlike Normalised units units. Obviously it has the
disadvantage that the location of the right and left edges of the screen have to be determined from a knowledge of the
screen dimensions. (These can be determined at any point by the Window.size attribute.)
Spatial frequency: cycles per stimulus (so will scale with the size of the stimulus).
Requires : No monitor information
10.2.2 Normalised units
In normalised (‘norm’) units the window ranges in both x and y from -1 to +1. That is, the top right of the window
has coordinates (1,1), the bottom left is (-1,-1). Note that, in this scheme, setting the height of the stimulus to be 1.0,
will make it half the height of the window, not the full height (because the window has a total height of 1:-1 = 2!).
Also note that specifying the width and height to be equal will not result in a square stimulus if your window is not
square - the image will have the same aspect ratio as your window. e.g. on a 1024x768 window the size=(0.75,1) will
be square.
Spatial frequency: cycles per stimulus (so will scale with the size of the stimulus).
Requires : No monitor information
10.2.3 Centimeters on screen
Set the size and location of the stimulus in centimeters on the screen.
24 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
Spatial frequency: cycles per cm
Requires : information about the screen width in cm and size in pixels
Assumes : pixels are square. Can be verified by drawing a stimulus with matching width and height and verifying that
it is in fact square. For a CRT this can be controlled by setting the size of the viewable screen (settings on the monitor
itself).
10.2.4 Degrees of visual angle
Use degrees of visual angle to set the size and location of the stimulus. This is, of course, dependent on the distance
that the participant sits from the screen as well as the screen itself, so make sure that this is controlled, and remember
to change the setting in Monitor Center if the viewing distance changes.
Spatial frequency: cycles per degree
Requires : information about the screen width in cm and pixels and the viewing distance in cm
Assumes : that pixels are square (see above) and that all parts of the screen are a constant distance from the eye
(ie that the screen is curved!). This (clearly incorrect assumption) is common to most studies that report the size of
their stimulus in degrees of visual angle. The resulting error is small at moderate eccentricities (a 0.2% error in size
calculation at 3 deg eccentricity) but grows as stimuli are placed further from the centre of the screen (a 2% error at 10
deg). For studies of peripheral vision this should be corrected for. PsychoPy also makes no correction for the thickness
of the screen glass, which refracts the image slightly.
10.2.5 Pixels on screen
You can also specify the size and location of your stimulus in pixels. Obviously this has the disadvantage that sizes
are specific to your monitor (because all monitors differ in pixel size).
Spatial frequency: ‘cycles per pixel‘ (this catches people out but is used to be in keeping with the other units.
If using pixels as your units you probably want a spatial frequency in the range 0.2-0.001 (i.e. from 1 cycle every 5
pixels to one every 100 pixels).
Requires : information about the size of the screen (not window) in pixels, although this can often be deduce from the
operating system if it has been set correctly there.
Assumes: nothing
10.3 Color spaces
The color of stimuli can be specified when creating a stimulus and when using setColor() in a variety of ways. There
are three basic color spaces that PsychoPy can use, RGB, DKL and LMS but colors can also be specified by a name
(e.g. ‘DarkSalmon’) or by a hexadecimal string (e.g. ‘#00FF00’).
examples:
stim =visual.PatchStim(win, color=[1,-1,-1], colorSpace=’rgb’)#will be red
stim.setColor(’Firebrick’)#one of the web/X11 color names
stim.setColor(’#FFFAF0’)#an off-white
stim.setColor([0,90,1], colorSpace=’dkl’)#modulate along S-cone axis in isoluminant plane
stim.setColor([1,0,0], colorSpace=’lms’)#modulate only on the L cone
stim.setColor([1,1,1], colorSpace=’rgb’)#all guns to max
stim.setColor([1,0,0])#this is ambiguous - you need to specify a color space
10.3. Color spaces 25
PsychoPy - Psychology software for Python, Release 1.78.00
10.3.1 Colors by name
Any of the web/X11 color names can be used to specify a color. These are then converted into RGB space by PsychoPy.
These are not case sensitive, but should not include any spaces.
10.3.2 Colors by hex value
This is really just another way of specifying the r,g,b values of a color, where each gun’s value is given by two
hexadecimal characters. For some examples see this chart. To use these in PsychoPy they should be formatted as a
string, beginning with #and with no spaces. (NB on a British Mac keyboard the # key is hidden - you need to press
Alt-3)
10.3.3 RGB color space
This is the simplest color space, in which colors are represented by a triplet of values that specify the red green and
blue intensities. These three values each range between -1 and 1.
Examples:
• [1,1,1] is white
• [0,0,0] is grey
• [-1,-1,-1] is black
• [1.0,-1,-1] is red
• [1.0,0.6,0.6] is pink
The reason that these colors are expressed ranging between 1 and -1 (rather than 0:1 or 0:255) is that many experiments,
particularly in visual science where PsychoPy has its roots, express colors as deviations from a grey screen. Under
that scheme a value of -1 is the maximum decrement from grey and +1 is the maximum increment above grey.
Note that Psychopy will use your monitor calibration to linearize this for each gun. E.g., 0 will be halfway between
the minimum luminance and maximum luminance for each gun, if your monitor gammaGrid is set correctly.
10.3.4 HSV color space
Another way to specify colors is in terms of their Hue, Saturation and ‘Value’ (HSV). For a description of the color
space see the Wikipedia HSV entry. The Hue in this case is specified in degrees, the saturation ranging 0:1 and the
‘value’ also ranging 0:1.
Examples:
• [0,1,1] is red
• [0,0.5,1] is pink
• [90,1,1] is cyan
• [anything, 0, 1] is white
• [anything, 0, 0.5] is grey
• [anything, anything,0] is black
Note that colors specified in this space (like in RGB space) are not going to be the same another monitor; they are
device-specific. They simply specify the intensity of the 3 primaries of your monitor, but these differ between monitors.
As with the RGB space gamma correction is automatically applied if available.
26 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
10.3.5 DKL color space
To use DKL color space the monitor should be calibrated with an appropriate spectrophotometer, such as a PR650.
In the Derrington, Krauskopf and Lennie 1color space (based on the Macleod and Boynton 2chromaticity diagram)
colors are represented in a 3-dimensional space using spherical coordinates that specify the elevation from the isolu-
minant plane, the azimuth (the hue) and the contrast (as a fraction of the maximal modulations along the cardinal axes
of the space).
In PsychoPy these values are specified in units of degrees for elevation and azimuth and as a float (ranging -1:1) for
the contrast.
Note that not all colours that can be specified in DKL colour space can be reproduced on a monitor. Here is a movie
plotting in DKL space (showing cartesian coordinates, not spherical coordinates) the gamut of colors available on an
example CRT monitor.
Examples:
• [90,0,1] is white (maximum elevation aligns the color with the luminance axis)
• [0,0,1] is an isoluminant stimulus, with azimuth 0 (S-axis)
• [0,45,1] is an isoluminant stimulus,with an oblique azimuth
1Derrington, A.M., Krauskopf, J., & Lennie, P. (1984). Chromatic Mechanisms in Lateral Geniculate Nucleus of Macaque. Journal of Physiol-
ogy, 357, 241-265.
2MacLeod, D. I. A. & Boynton, R. M. (1979). Chromaticity diagram showing cone excitation by stimuli of equal luminance. Journal of the
Optical Society of America, 69(8), 1183-1186.
10.3. Color spaces 27
PsychoPy - Psychology software for Python, Release 1.78.00
10.3.6 LMS color space
To use LMS color space the monitor should be calibrated with an appropriate spectrophotometer, such as a PR650.
In this color space you can specify the relative strength of stimulation desired for each cone independently, each with
a value from -1:1. This is particularly useful for experiments that need to generate cone isolating stimuli (for which
modulation is only affecting a single cone type).
10.4 Preferences
10.4.1 General settings
winType: PsychoPy can use one of two ‘backends’ for creating windows and drawing; pygame and pyglet. Here you
can set the default backend to be used.
units: Default units for windows and visual stimuli (‘deg’, ‘norm’, ‘cm’, ‘pix’). See Units for the window and stimuli.
Can be overidden by individual experiments.
fullscr: Should windows be created full screen by default? Can be overidden by individual experiments.
allowGUI: When the window is created, should the frame of the window and the mouse pointer be visible. If set to
False then both will be hidden.
10.4.2 Application settings
These settings are common to all components of the application (Coder and Builder etc)
largeIcons: Do you want large icons (on some versions of wx on OS X this has no effect)
defaultView: Determines which view(s) open when the PsychoPy app starts up. Default is ‘last’, which fetches the
same views as were open when PsychoPy last closed.
runScripts: Don’t ask. ;-) Just leave this option as ‘process’ for now!
allowModuleImports (only used by win32): Allow modules to be imported at startup for analysis by source assis-
tant. This will cause startup to be slightly slower but will speedup the first analysis of a script.
10.4.3 Coder settings
outputFont: a list of font names to be used in the output panel. The first found on the system will be used
fontSize (in pts): an integer between 6 and 24 that specifies the size of fonts
codeFontSize = integer(6,24, default=12)
outputFontSize = integer(6,24, default=12)
showSourceAsst: Do you want to show the source assistant panel (to the right of the Coder view)? On windows this
provides help about the current function if it can be found. On OS X the source assistant is of limitted use and
is disabled by default.
analysisLevel: If using the source assistant, how much depth should PsychoPy try to analyse the current script? Lower
values may reduce the amount of analysis performed and make the Coder view more responsive (particularly
for files that import many modules and sub-modules).
analyseAuto: If using the source assistant, should PsychoPy try to analyse the current script on every save/load of the
file? The code can be analysed manually from the tools menu
28 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
showOutput: Show the output panel in the Coder view. If shown all python output from the session will be output
to this panel. Otherwise it will be directed to the original location (typically the terminal window that called
PsychoPy application to open).
reloadPrevFiles: Should PsychoPy fetch the files that you previously had open when it launches?
10.4.4 Builder settings
reloadPrevExp (default=False): for the user to add custom components (comma-separated list)
componentsFolders: a list of folder pathnames that can hold additional custom components for the Builder view
hiddenComponents: a list of components to hide (eg, because you never use them)
10.4.5 Connection settings
proxy: The proxy server used to connect to the internet if needed. Must be of the form http://111.222.333.444:5555
autoProxy: PsychoPy should try to deduce the proxy automatically (if this is True and autoProxy is successful then
the above field should contain a valid proxy address).
allowUsageStats: Allow PsychoPy to ping a website at when the application starts up. Please leave this set to True.
The info sent is simply a string that gives the date, PsychoPy version and platform info. There is no cost to
you: no data is sent that could identify you and PsychoPy will not be delayed in starting as a result. The aim
is simple: if we can show that lots of people are using PsychoPy there is a greater chance of it being improved
faster in the future.
checkForUpdates: PsychoPy can (hopefully) automatically fetch and install updates. This will only work for minor
updates and is still in a very experimental state (as of v1.51.00).
10.4.6 Key bindings
There are many shortcut keys that you can use in PsychoPy. For instance did you realise that you can indent or outdent
a block of code with Ctrl-[ and Ctrl-] ?
10.5 Data outputs
There are a number of different forms of output that PsychoPy can generate, depending on the study and your preferred
analysis software. Multiple file types can be output from a single experiment (e.g. Excel data file for a quick browse,
Log file to check for error mesages and PsychoPy data file (.psydat) for detailed analysis)
10.5.1 Log file
Log files are actually rather difficult to use for data analysis but provide a chronological record of everything that
happened during your study. The level of content in them depends on you. See Logging data for further information.
10.5.2 PsychoPy data file (.psydat)
This is actually a TrialHandler or StairHandler object that has been saved to disk with the python cPickle
module.
10.5. Data outputs 29
PsychoPy - Psychology software for Python, Release 1.78.00
These files are designed to be used by experienced users with previous experience of python and, probably, matplotlib.
The contents of the file can be explored with dir(), as any other python object.
These files are ideal for batch analysis with a python script and plotting via matplotlib. They contain more information
than the Excel or csv data files, and can even be used to (re)create those files.
Of particular interest might be the attributes of the Handler:
extraInfo the extraInfo dictionary provided to the Handler during its creation
trialList the list of dictionaries provided to the Handler during its creation
data a dictionary of 2D numpy arrays. Each entry in the dictionary represents a type of data (e.g.
if you added ‘rt’ data during your experiment using ~psychopy.data.TrialHandler.addData then
‘rt’ will be a key). For each of those entries the 2D array represents the condition number and
repeat number (remember that these start at 0 in python, unlike matlab(TM) which starts at 1)
For example, to open a psydat file and examine some of its contents with:
from psychopy.misc import fromFile
datFile =fromFile(’fileName.psydat’)
#get info (added when the handler was created)
print datFile.extraInfo
#get data
print datFile.data
#get list of conditions
conditions =datFile.trialList
for condN, condition in enumerate(conditions):
print condition, datFile.data[’response’][condN], numpy.mean(datFile.data[’response’][condN])
Ideally, we should provide a demo script here for fetching and plotting some data feel (free to contribute).
10.5.3 Long-wide data file
This form of data file is the default data output from Builder experiments as of v1.74.00. Rather than summarising
data in a spreadsheet where one row represents all the data from a single condition (as in the summarised data format),
in long-wide data files the data is not collapsed by condition, but written chronologically with one row representing
one trial (hence it is typically longer than summarised data files). One column in this format is used for every single
piece of information available in the experiment, even where that information might be considered redundant (hence
the format is also ‘wide’).
Although these data files might not be quite as easy to read quickly by the experimenter, they are ideal for import and
analysis under packages such as R, SPSS or Matlab.
10.5.4 Excel data file
Excel 2007 files (.xlsx) are a useful and flexible way to output data as a spreadsheet. The file format is open and
supported by nearly all spreadsheet applications (including older versions of Excel and also OpenOffice). N.B. because
.xlsx files are widely supported, the older Excel file format (.xls) is not likely to be supported by PsychoPy unless a
user contributes the code to the project.
Data from PsychoPy are output as a table, with a header row. Each row represents one condition (trial type) as given
to the TrialHandler. Each column represents a different type of data as given in the header. For some data, where
there are multiple columns for a single entry in the header. This indicates multiple trials. For example, with a standard
data file in which response time has been collected as ‘rt’ there will be a heading rt_raw with several columns, one
for each trial that occured for the various trial types, and also an rt_mean heading with just a single column giving the
mean reaction time for each condition.
30 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
If you’re creating experiments by writing scripts then you can specify the sheet name as well as file name for Excel file
outputs. This way you can store multiple sessions for a single subject (use the subject as the filename and a date-stamp
as the sheetname) or a single file for multiple subjects (give the experiment name as the filename and the participant
as the sheetname).
Builder experiments use the participant name as the file name and then create a sheet in the Excel file for each loop of
the experiment. e.g. you could have a set of practice trials in a loop, followed by a set of main trials, and these would
each receive their own sheet in the data file.
10.5.5 Delimited text files (.dlm, .csv)
For maximum compatibility, especially for legacy analysis software, you can choose to output your data as a delimitted
text file. Typically this would be comma-separated values (.csv file) or tab-delimited (.dlm file). The format of those
files is exactly the same as the Excel file, but is limited by the file format to a single sheet.
10.6 Gamma correcting a monitor
Monitors typically don’t have linear outputs; when you request luminance level of 127, it is not exactly half the
luminance of value 254. For experiments that require the luminance values to be linear, a correction needs to be put
in place for this nonlinearity which typically involves fitting a power law or gamma (γ) function to the monitor output
values. This process is often referred to as gamma correction.
PsychoPy can help you perform gamma correction on your monitor, especially if you have one of the supported
photometers/spectroradiometers.
There are various different equations with which to perform gamma correction. The simple equation (10.1) is assumed
by most hardware manufacturers and gives a reasonable first approximation to a linear correction. The full gamma
correction equation (10.3) is more general, and likely more accurate especially where the lowest luminance value of the
monitor is bright, but also requires more information. It can only be used in labs that do have access to a photometer
or similar device.
10.6.1 Simple gamma correction
The simple form of correction (as used by most hardware and software) is this:
L(V) = a+kV γ(10.1)
where Lis the final luminance value, Vis the requested intensity (ranging 0 to 1), a,kand γare constants for the
monitor.
This equation assumes that the luminance where the monitor is set to ‘black’ (V=0) comes entirely from the surround
and is therefore not subject to the same nonlinearity as the monitor. If the monitor itself contributes significantly to a
then the function may not fit very well and the correction will be poor.
The advantage of this function is that the calibrating system (PsychoPy in this case) does not need to know anything
more about the monitor than the gamma value itself (for each gun). For the full gamma equation (10.3), the system
needs to know about several additional variables. The look-up table (LUT) values required to give a (roughly) linear
luminance output can be generated by:
LUT (V) = V1/γ (10.2)
where Vis the entry in the LUT, between 0 (black) and 1 (white).
10.6. Gamma correcting a monitor 31
PsychoPy - Psychology software for Python, Release 1.78.00
10.6.2 Full gamma correction
For very accurate gamma correction PsychoPy uses a more general form of the equation above, which can separate
the contribution of the monitor and the background to the lowest luminance level:
L(V) = a+ (b+kV )γ(10.3)
This equation makes no assumption about the origin of the base luminance value, but requires that the system knows
the values of band kas well as γ.
The inverse values, required to build the LUT are found by:
LUT (V) = ((1 −V)bγ+V(b+k)γ)1/γ −b
k(10.4)
This is derived below, for the interested reader. ;-)
And the associated luminance values for each point in the LUT are given by:
L(V) = a+ (1 −V)bγ+V(b+k)γ
10.6.3 Deriving the inverse full equation
The difficulty with the full gamma equation (10.3) is that the presence of the bvalue complicates the issue of calculating
the inverse values for the LUT. The simple inverse of (10.3) as a function of output luminance values is:
LUT (L) = ((L−a)1/γ −b)
k(10.5)
To use this equation we need to first calculate the linear set of luminance values, L, that we are able to produce the
current monitor and lighting conditions and then deduce the LUT value needed to generate that luminance value.
We need to insert into the LUT the values between 0 and 1 (to use the maximum range) that map onto the linear range
from the minimum, m, to the maximum Mpossible luminance. From the parameters in (10.3) it is clear that:
m=a+bγ(10.6)
M=a+ (b+k)γ
Thus, the luminance value, Lat any given point in the LUT, V, is given by
L(V) = m+ (M−m)V
=a+bγ+ (a+ (b+k)γ−a−bγ)V
=a+bγ+ ((b+k)γ−bγ)V
=a+ (1 −V)bγ+V(b+k)γ
(10.7)
where Vis the position in the LUT as a fraction.
Now, to generate the LUT as needed we simply take the inverse of (10.3):
LUT (L) = (L−a)1/γ −b
k(10.8)
and substitute our L(V)values from (10.7):
LUT (V) = (a+ (1 −V)bγ+V(b+k)γ−a)1/γ −b
k
=((1 −V)bγ+V(b+k)γ)1/γ −b
k
(10.9)
32 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
10.6.4 References
10.7 Timing Issues and synchronisation
One of the key requirements of experimental control software is that it has good temporal precision. PsychoPy aims to
be as precise as possible in this domain and can achieve excellent results depending on your experiment and hardware.
It also provides you with a precise log file of your experiment to allow you to check the precision with which things
occurred. Some general considerations are discussed here and there are links with Specific considerations for specific
designs.
Something that people seem to forget (not helped by the software manufacturers that keep talking about their sub-
millisecond precision) is that the monitor, keyboard and human participant DO NOT have anything like this sort of
precision. Your monitor updates every 10-20ms depending on frame rate. If you use a CRT screen then the top is
drawn before the bottom of the screen by several ms. If you use an LCD screen the whole screen can take around
20ms to switch from one image to the next. Your keyboard has a latency of 4-30ms, depending on brand and system.
So, yes, PsychoPy’s temporal precision is as good as most other equivalent applications, for instance the duration for
which stimuli are presented can be synchronised precisely to the frame, but the overall accuracy is likely to be severely
limited by your experimental hardware. To get very precise timing of responses etc, you need to use specialised
hardware like button boxes and you need to think carefully about the physics of your monitor.
Warning: The information about timing in PsychoPy assumes that your graphics card is capable of synchronising
with the monitor frame rate. For integrated Intel graphics chips (e.g. GMA 945) under Windows, this is not true
and the use of those chips is not recommended for serious experimental use as a result. Desktop systems can have
a moderate graphics card added for around £30 which will be vastly superior in performance.
10.7.1 Specific considerations for specific designs
Non-slip timing for imaging
For most behavioural/psychophysics studies timing is most simply controlled by setting some timer (e.g. a Clock())
to zero and waiting until it has reached a certain value before ending the trial. We might call this a ‘relative’ timing
method, because everything is timed from the start of the trial/epoch. In reality this will cause an overshoot of some
fraction of one screen refresh period (10ms, say). For imaging (EEG/MEG/fMRI) studies adding 10ms to each trial
repeatedly for 10 minutes will become a problem, however. After 100 stimulus presentations your stimulus and scanner
will be de-synchronised by 1 second.
There are two ways to get around this:
1. Time by frames If you are confident that you aren’t dropping frames then you could base your timing on frames
instead to avoid the problem.
2. Non-slip (global) clock timing The other way, which for imaging is probably the most sensible, is to arrange
timing based on a global clock rather than on a relative timing method. At the start of each trial you add the
(known) duration that the trial will last to a global timer and then wait until that timer reaches the necessary
value. To facilitate this, the PsychoPy (e.g. a Clock()) was given a new add() method as of version 1.74.00
and a CountdownTimer() was also added.
The non-slip method can only be used in cases where the trial is of a known duration at its start. It cannot, for example,
be used if the trial ends when the subject makes a response, as would occur in most behavioural studies.
10.7. Timing Issues and synchronisation 33
PsychoPy - Psychology software for Python, Release 1.78.00
Non-slip timing from the Builder
(new feature as of version 1.74.00)
When creating experiments in the Builder, PsychoPy will attempt to identify whether a particular Routine has a known
endpoint in seconds. If so then it will use non-slip timing for this Routine based on a global countdown timer called
routineTimer. Routines that are able to use this non-slip method are shown in green in the Flow, whereas Routines
using relative timing are shown in red. So, if you are using PsychoPy for imaging studies then make sure that all the
Routines within your loop of epochs are showing as green. (Typically your study will also have a Routine at the start
waiting for the first scanner pulse and this will use relative timing, which is appropriate).
Detecting dropped frames
Occasionally you will drop frames if you:
• try to do too much drawing
• do it in an innefficient manner (write poor code)
• have a poor computer/graphics card
Things to avoid:
• recreating textures for stimuli
• building new stimuli from scratch (create them once at the top of your script and then change them using
stim.setOri(ori)(),stim.setPos([x,y]...)
Turn on frame time recording
The key sometimes is knowing if you are dropping frames. PsychoPy can help with that by keeping track of frame
durations. By default, frame time tracking is turned off because many people don’t need it, but it can be turned on any
time after Window creation setRecordFrameIntervals(), e.g.:
from psychopy import visual win = visual.Window([800,600]) win.setRecordFrameIntervals(True)
Since there are often dropped frames just after the system is initialised, it makes sense to start off with a fixation period,
or a ready message and don’t start recording frame times until that has ended. Obviously if you aren’t refreshing the
window at some point (e.g. waiting for a key press with an unchanging screen) then you should turn off the recording
of frame times or it will give spurious results.
Warn me if I drop a frame
The simplest way to check if a frame has been dropped is to get PsychoPy to report a warning if it thinks a frame was
dropped:
from psychopy import visual, logging
win =visual.Window([800,600])
win.setRecordFrameIntervals(True)
win._refreshThreshold=1/85.0+0.004 #i’ve got 85Hz monitor and want to allow 4ms tolerance
#set the log module to report warnings to the std output window (default is errors only)
logging.console.setLevel(logging.WARNING)
34 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
Show me all the frame times that I recorded
While recording frame times, these are simply appended, every frame to win.frameIntervals (a list). You can simply
plot these at the end of your script using pylab:
import pylab
pylab.plot(win.frameIntervals)
pylab.show()
Or you could save them to disk. A convenience function is provided for this:
win.saveFrameIntervals(fileName=None, clear=True)
The above will save the currently stored frame intervals (using the default filename, ‘lastFrameIntervals.log’) and then
clears the data. The saved file is a simple text file.
At any time you can also retrieve the time of the /last/ frame flip using win.lastFrameT (the time is synchronised with
logging.defaultClock so it will match any logging commands that your script uses).
‘Blocking’ on the VBI
As of version 1.62 PsychoPy ‘blocks’ on the vertical blank interval meaning that, once Window.flip() has been called,
no code will be executed until that flip actually takes place. The timestamp for the above frame interval measure-
ments is taken immediately after the flip occurs. Run the timeByFrames demo in Coder to see the precision of these
measurements on your system. They should be within 1ms of your mean frame interval.
Note that Intel integrated graphics chips (e.g. GMA 945) under win32 do not sync to the screen at all and so blocking
on those machines is not possible.
Reducing dropped frames
There are many things that can affect the speed at which drawing is achieved on your computer. These include, but are
probably not limited to; your graphics card, CPU, operating system, running programs, stimuli, and your code itself.
Of these, the CPU and the OS appear to make rather little difference. To determine whether you are actually dropping
frames see Detecting dropped frames.
Things to change on your system:
1. make sure you have a good graphics card. Avoid integrated graphics chips, especially Intel integrated chips and
especially on laptops (because on these you don’t get to change your mind so easily later). In particular, try to
make sure that you card supports OpenGL 2.0
2. shut down as many programs, including background processes. Although modern processors are fast and often have multiple cores, substantial disk/memory accessing can cause frame drops
• anti-virus auto-updating (if you’re allowed)
• email checking software
• file indexing software
• backup solutions (e.g. TimeMachine)
• Dropbox
• Synchronisation software
10.7. Timing Issues and synchronisation 35
PsychoPy - Psychology software for Python, Release 1.78.00
Writing optimal scripts
1. run in full-screen mode (rather than simply filling the screen with your window). This way the OS doesn’t have
to spend time working out what application is currently getting keyboard/mouse events.
2. don’t generate your stimuli when you need them. Generate them in advance and then just modify them later
with the methods like setContrast(), setOrientation() etc...
3. calls to the following functions are comparatively slow; they require more cpu time than most other functions and then have to send a large amount of data to the graphics card. Try to use these methods in inter-trial intervals. This is especially true when you need to load an image from disk too as the texture.
(a) PatchStim.setTexture()
(b) RadialStim.setTexture()
(c) TextStim.setText()
4. if you don’t have OpenGL 2.0 then calls to setContrast, setRGB and setOpacity will also be slow, because they
also make a call to setTexture(). If you have shader support then this call is not necessary and a large speed
increase will result.
5. avoid loops in your python code (use numpy arrays to do maths with lots of elements)
6. if you need to create a large number (e.g. greater than 10) similar stimuli, then try the ElementArrayStim
Possible good ideas
It isn’t clear that these actually make a difference, but they might).
1. disconnect the internet cable (to prevent programs performing auto-updates?)
2. on Macs you can actually shut down the Finder. It might help. See Alex Holcombe’s page here
3. use a single screen rather than two (probably there is some graphics card overhead in managing double the
number of pixels?)
Comparing Operating Systems under PsychoPy
This is an attempt to quantify the ability of PsychoPy draw without dropping frames on a variety of hardware/software.
The following tests were conducted using the script at the bottom of the page. Note, of course that the hardware fully
differs between the Mac and Linux/Win systems below, but that both are standard off-the-shelf machines.
All of the below tests were conducted with ‘normal’ systems rather than anything that had been specifically optimised:
• the machines were connected to network
• did not have anti-virus turned off (except Ubuntu had no antivirus)
• they even all had dropbox clients running
• linux was the standard (not ‘realtime’ kernel)
No applications were actively being used by the operator while tests were run.
In order to test drawing under a variety of processing loads the test stimulus was one of:
• a single drifting Gabor
• 500 random dots continuously updating
• 750 random dots continuously updating
36 Chapter 10. General issues
PsychoPy - Psychology software for Python, Release 1.78.00
• 1000 random dots continuously updating
Common settings:
• Monitor was a CRT 1024x768 100Hz
• all tests were run in full screen mode with mouse hidden
System Differences:
• the iMac was lower spec than the win/linux box and running across two monitors (necessary in order to
connect to the CRT)
• the win/linux box ran off a single monitor
Each run below gives the number of dropped frames out of a run of 10,000 (2.7 mins at 100Hz).
_ Win XP Win Seven Mac OSX 10.6 Ubuntu 11.10
_ (SP3) Enterprise Snow Leopard
Gabor 0 5 0 0
500-dot RDK 0 5 54 3
750-dot RDK 21 7 aborted 1174
1000-dot RDK 776 aborted aborted aborted
GPU Radeon 5400 Radeon 5400 Radeon 2400 Radeon 5400
GPU driver Catalyst 11.11 Catalyst 11.11 Catalyst 11.11
CPU Core Duo 3GHz Core Duo 3GHz Core Duo 2.4GHz Core Duo 3GHz
RAM 4GB 4GB 2GB 4GB
I’ll gradually try to update these tests to include:
• longer runs (one per night!)
• a faster Mac
• a real-time linux kernel
10.7. Timing Issues and synchronisation 37
PsychoPy - Psychology software for Python, Release 1.78.00
38 Chapter 10. General issues
CHAPTER
ELEVEN
BUILDER
Building experiments in a GUI
You can now see a youtube PsychoPy tutorial showing you how to build a simple experiment in the Builder interface
Note: The Builder view is now (at version 1.75) fairly well-developed and should be able to construct a wide variety
of studies. But you should still check carefully that the stimuli and response collection are as expected.
Contents:
39
PsychoPy - Psychology software for Python, Release 1.78.00
11.1 Builder concepts
11.1.1 Routines and Flow
The Builder view of the PsychoPy application is designed to allow the rapid development of a wide range of experi-
ments for experimental psychology and cognitive neuroscience experiments.
The Builder view comprises two main panels for viewing the experiment’s Routines (upper left) and another for
viewing the Flow (lower part of the window).
An experiment can have any number of Routines, describing the timing of stimuli, instructions and responses. These
are portrayed in a simple track-based view, similar to that of video-editing software, which allows stimuli to come on
go off repeatedly and to overlap with each other.
The way in which these Routines are combined and/or repeated is controlled by the Flow panel. All experiments
have exactly one Flow. This takes the form of a standard flowchart allowing a sequence of routines to occur one after
another, and for loops to be inserted around one or more of the Routines. The loop also controls variables that change
between repetitions, such as stimulus attributes.
11.1.2 Example 1 - a reaction time experiment
For a simple reaction time experiment there might be 3 Routines, one that presents instructions and waits for a keypress,
one that controls the trial timing, and one that thanks the participant at the end. These could then be combined in the
Flow so that the instructions come first, followed by trial, followed by the thanks Routine, and a loop could be inserted
so that the Routine repeated 4 times for each of 6 stimulus intensities.
11.1.3 Example 2 - an fMRI block design
Many fMRI experiments present a sequence of stimuli in a block. For this there are multiple ways to create the
experiment: * We could create a single Routine that contained a number of stimuli and presented them sequentially,
followed by a long blank period to give the inter-epoch interval, and surround this single Routine by a loop to control
the blocks. * Alternatively we could create a pair of Routines to allow presentation of a) a single stimulus (for 1 sec)
and b) a blank screen, for the prolonged period. With these Routines we could insert pair of loops, one to repeat the
stimulus Routine with different images, followed by the blank Routine, and another to surround this whole set and
control the blocks.
11.1.4 Demos
There are a couple of demos included with the package, that you can find in their own special menu. When you load
these the first thing to do is make sure the experiment settings specify the same resolution as your monitor, otherwise
the screen can appear off-centred and strangely scaled.
Stroop demo
This runs a digital demonstration of the Stroop effect 1. The experiment presents a series of coloured words written
in coloured ‘inks’. Subjects have to report the colour of the letters for each word, but find it harder to do so when the
letters are spelling out a different (incongruous) colour. Reaction times for the congruent trials (where letter colour
matches the written word) are faster than for the incongruent trials.
From this demo you should note:
1Stroop, J.R. (1935). “Studies of interference in serial verbal reactions”. Journal of Experimental Psychology 18: 643-662.
40 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
• How to setup a trial list in a .csv or .xlsx file
• How to record key presses and reaction times (using the resp Component in trial Routine)
• How to change a stimulus parameter on each repetition of the loop. The text and rgb values of the word
Component are based on thisTrial, which represents a single iteration of the trials loop. They have been
set to change every repeat (don’t forget that step!)
• How to present instructions: just have a long-lasting TextStim and then force end of the Routine when a
key is pressed (but don’t bother storing the key press).
Psychophysics Staircase demo
This is a mini psychophysics experiment, designed to find the contrast detection threshold of a gabor i.e. find the
contrast where the observer can just see the stimulus.
From this demo you should note:
• The opening dialog box requires the participant to enter the orientation of the stimulus, the required fields
here are determined by ‘Experiment Info’ in ‘Preferences’ which is a python dictionary. This information
is then entered into the stimulus parameters using ‘$expInfo[’ori’]’
• The phase of the stimulus is set to change every frame and its value is determined by the value of tri-
alClock.getTime()*2. Every Routine has a clock associated with it that gets reset at the beginning of the
iteration through the Routine. There is also a globalClock that can be used in the same way. The phase
of a Patch Component ranges 0-1 (and wraps to that range if beyond it). The result in this case is that the
grating drifts at a rate of 2Hz.
• The contrast of the stimulus is determined using an adaptive staircase. The Staircase methods are different
to those used for a loop which uses predetermined values. An important thing to note is that you must
define the correct answer.
11.2 Routines
An experiment consists of one or more Routines. A Routine might specify the timing of events within a trial or the
presentation of instructions or feedback. Multiple Routines can then be combined in the Flow, which controls the
order in which these occur and the way in which they repeat.
To create a new Routine, use the Experiment menu. The display size of items within a routine can be adjusted (see the
View menu).
Within a Routine there are a number of components. These components determine the occurrence of a stimulus, or the
recording of a response. Any number of components can be added to a Routine. Each has its own line in the Routine
view that shows when the component starts and finishes in time, and these can overlap.
For now the time axis of the Routines panel is fixed, representing seconds (one line is one second). This will hopefully
change in the future so that units can also be number of frames (more precise) and can be scaled up or down to allow
very long or very short Routines to be viewed easily. That’s on the wishlist...
11.3 Flow
In the Flow panel a number of Routines can be combined to form an experiment. For instance, your study may have a
Routine that presented initial instructions and waited for a key to be pressed, followed by a Routine that presented one
trial which should be repeated 5 times with various different parameters set. All of this is achieved in the Flow panel.
You can adjust the display size of the Flow panel (see View menu).
11.2. Routines 41
PsychoPy - Psychology software for Python, Release 1.78.00
11.3.1 Adding Routines
The Routines that the Flow will use should be generated first (although their contents can be added or altered at any
time). To insert a Routine into the Flow click the appropriate button in the left of the Flow panel or use the Experiment
menu. A dialog box will appear asking which of your Routines you wish to add. To select the location move the mouse
to the section of the flow where you wish to add it and click on the black disk.
11.3.2 Loops
Loops control the repetition of Routines and the choice of stimulus parameters for each. PsychoPy can generate the
next trial based on the method of constants or using an adaptive staircase. To insert a loop use the button on the left of
the Flow panel, or the item in the Experiment menu of the Builder. The start and end of a loop is set in the same way
as the location of a Routine (see above). Loops can encompass one or more Routines and other loops (i.e. they can be
nested).
As with components in Routines, the loop must be given a name, which must be unique and made up of only alpha-
numeric characters (underscores are allowed). I would normally use a plural name, since the loop represents multiple
repeats of something. For example, trials,blocks or epochs would be good names for your loops.
It is usually best to use trial information that is contained in an external file (.xlsx or .csv). When inserting a loop into
the flow you can browse to find the file you wish to use for this. An example of this kind of file can be found in the
Stroop demo (trialTypes.xlsx). The column names are turned into variables (in this case text, letterColor, corrAns and
congruent), these can be used to define parameters in the loop by putting a $ sign before them e.g. $text.
As the column names from the input file are used in this way they must have legal variable names i.e. they must be
unique, have no punctuation or spaces (underscores are ok) and must not start with a digit.
Method of Constants
Selecting a loop type of random,sequential, or fullRandom will result in a method of constants experiment, whereby
the types of trials that can occur are predetermined. That is, the trials cannot vary depending on how the subject has
responded on a previous trial. In this case, a file must be provided that describes the parameters for the repeats. This
should be an Excel 2007 (xlsx) file or a comma-separated-value (csv ) file in which columns refer to parameters that
are needed to describe stimuli etc and rows one for each type of trial. These can easily be generated from a spreadsheet
package like excel. (Note that csv files can also be generated using most text editors, as long as they allow you to save
the file as “plain text”; other output formats will not work, including “rich text”.) The top row should be a row of
headers: text labels describing the contents of the respective columns. (Headers must also not include spaces or other
characters other than letters, numbers or underscores and must not be the same as any variable names used elsewhere
in your experiment.) For example, a file containing the following table:
ori text corrAns
0 aaa left
90 aaa left
0 bbb right
90 bbb right
would represent 4 different conditions (or trial types, one per line). The header line describes the parameters in the 3
columns: ori, text and corrAns. It’s really useful to include a column called corrAns that shows what the correct key
press is going to be for this trial (if there is one).
If the loop type is sequential then, on each iteration through the Routines, the next row will be selected in the order
listed in the file. Under a random order, the next row will be selected at random (without replacement); it can only be
selected again after all the other rows have also been selected. nReps determines how many repeats will be performed
(for all conditions). The total number of trials will be the number of conditions (= number of rows in the file, not
counting the header row) times the number of repetitions, nReps. With the fullRandom option, the entire list of trials
42 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
including repetitions is used in random order, allowing the same item to appear potentially many times in a row, and
to repeat without necessarily having done all of the other trials. For example, with 3 repetitions, a file of trial types
like this:
letter
a
b
c
could result in the following possible sequences. sequential could only ever give one sequence with this order: [a b c
a b c a b c]. random will give one of 216 different orders (= 3! * 3! * 3! = nReps * (nTrials!) ), for example: [b a c a
b c c a b]. Here the letters are effectively in sets of (abc) (abc) (abc), and randomization is only done within each set,
ensuring (for example) that there are at least two a’s before the subject sees a 3rd b. Finally, fullRandom will return
one of 362,880 different orders (= 9! = (nReps * nTrials)! ), such as [b b c a a c c a b], which random never would.
There are no longer mini-blocks or “sets of trials” within the longer run. This means that, by chance, it would also be
possible to get a very un-random-looking sequence like [a a a b b b c c c].
It is possible to achieve any sequence you like, subject to any constraints that are logically possible. To do so, in the
file you specify every trial in the desired order, and the for the loop select sequential order and nReps=1.
Staircase methods
The loop type staircase allows the implementation of adaptive methods. That is, aspects of a trial can depend on (or
“adapt to”) how a subject has responded earlier in the study. This could be, for example, simple up-down staircases
where an intensity value is varied trial-by-trial according to certain parameters, or a stop-signal paradigm to assess
impulsivity. For this type of loop a ‘correct answer’ must be provided from something like a Keyboard Component.
Various parameters for the staircase can be set to govern how many trials will be conducted and how many correct or
incorrect answers make the staircase go up or down.
Accessing loop parameters from components
The parameters from your loops are accessible to any component enclosed within that loop. The simplest (and default)
way to address these variables is simply to call them by the name of the parameter, prepended with $to indicate that
this is the name of a variable. For example, if your Flow contains a loop with the above table as its input trial types
file then you could give one of your stimuli an orientation $ori which would depend on the current trial type being
presented. Example scenarios:
1. You want to loop randomly over some conditions in a loop called trials. Your conditions are stored in a csv file
with headings ‘ori’, ‘text’, ‘corrAns’ which you provide to this loop. You can then access these values from any
component using $ori,$text, and $corrAns
2. You create a random loop called blocks and give it an excel file with a single column called movieName listing
filenames to be played. On each repeat you can access this with $movieName
3. You create a staircase loop called stairs. On each trial you can access the current value in the staircase with
$thisStair
Note: When you set a component to use a parameter that will change (e.g on each repeat through the loop) you should
remember to change the component parameter from ‘constant‘ to ‘set every repeat‘ or ‘set every frame‘ or it
won’t have any effect!
11.3. Flow 43
PsychoPy - Psychology software for Python, Release 1.78.00
Reducing namespace clutter (advanced)
The downside of the above approach is that the names of trial parameters must be different between every loop, as
well as not matching any of the predefined names in python, numpy and PsychoPy. For example, the stimulus called
movie cannot use a parameter also called movie (so you need to call it movieName). An alternative method can be used
without these restrictions. If you set the Builder preference unclutteredNamespace to True you can then access the
variables by referring to parameter as an attribute of the singular name of the loop prepended with this. For example,
if you have a loop called trials which has the above file attached to it, then you can access the stimulus ori with
$thisTrial.ori. If you have a loop called blocks you could use $thisBlock.corrAns.
Now, although the name of the loop must still be valid and unique, the names of the parameters of the file do not have
the same requirements (they must still not contain spaces or punctuation characters).
11.4 Components
Routines in the Builder contain any number of components, which typically define the parameters of a stimulus or an
input/output device.
The following components are available, as at version 1.65, but further components will be added in the future includ-
ing Parallel/Serial ports and other visual stimuli (e.g. GeometricStim).
11.4.1 Aperture Component
This component can be used to filter the visual display, as if the subject is looking at it through an opening. Currently
only circular apertures are supported. Moreover, only one aperture is enabled at a time. You can’t “double up”: a
second aperture takes precedence.
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start [float or integer] The time that the apperture should start having its effect. See Defining the onset/duration of
components for details.
stop : When the apperture stops having its effect. See Defining the onset/duration of components for details.
pos [[X,Y]] The position of the centre of the aperture, in the units specified by the stimulus or window.
size [integer] The size controls how big the aperture will be, in pixels, default = 120
units [pix] What units to use (currently only pix).
See Also:
API reference for Aperture
11.4.2 Code Component
The Code Component can be used to insert short pieces of python code into your experiments. This might be create a
variable that you want for another Component, to manipulate images before displaying them, to interact with hardware
for which there isn’t yet a pre-packaged component in PsychoPy (e.g. writing code to interact with the serial/parallel
ports). See code uses below.
Be aware that the code for each of the components in your Routine are executed in the order they appear on the Routine
display (from top to bottom). If you want your Code Component to alter a variable to be used by another component
immediately, then it needs to be above that component in the view. You may want the code not to take effect until next
44 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
frame however, in which case put it at the bottom of the Routine. You can move Components up and down the Routine
by right-clicking on their icons.
Within your code you can use other variables and modules from the script. For example, all routines have a stopwatch-style Clock associated with them, which gets reset at the beginning of that repeat of the routine. So if you have a Routine called trial, there will be a Clock called trialClock and so you can get the time (in sec) from the beginning of the trial by using::
currentT = trialClock.getTime()
To see what other variables you might want to use, and also what terms you need to avoid in your chunks of code,
compile your script before inserting the code object and take a look at the contents of that script.
Note that this page is concerned with Code Components specifically, and not all cases in which you might use python
syntax within the Builder. It is also possible to put code into a non-code input field (such as the duration or text of
aText Component). The syntax there is slightly different (requiring a $to trigger the special handling, or \$ to avoid
triggering special handling). The syntax to use within a Code Component is always regular python syntax.
Parameters
The parameters of the Code Component simply specify the code that will get executed at 5 different points within the
experiment. You can use as many or as few of these as you need for any Code Component:
Begin Experiment: Things that need to be done just once, like importing a supporting module, initialis-
ing a variable for later use.
Begin Routine: Certain things might need to be done just once at the start of a Routine e.g. at the
beginning of each trial you might decide which side a stimulus will appear
Each Frame: Things that need to updated constantly, throughout the experiment. Note that these will
be exectued exactly once per video frame (on the order of every 10ms), to give dynamic displays.
Static displays do not need to be updated every frame.
End Routine: At the end of the Routine (eg. the trial) you may need to do additional things, like checking
if the participant got the right answer
End Experiment: Use this for things like saving data to disk, presenting a graph(?), or resetting hardware
to its original state.
Example code uses
1. Set a random location for your target stimulus
There are many ways to do this, but you could add the following to the Begin Routine section of a Code Component at
the top of your Routine. Then set your stimulus position to be $targetPos and set the correct answer field of a Keyboard
Component to be $corrAns (set both of these to update on every repeat of the Routine).:
if random()>0.5:
targetPos=[-2.0,0.0]#on the left
corrAns=’left’
else:
targetPos=[+2.0,0.0]#on the right
corrAns=’right’
2. Create a patch of noise
As with the above there are many different ways to create noise, but a simple method would be to add the following to
the Begin Routine section of a Code Component at the top of your Routine. Then set the image as $noiseTexture.:
11.4. Components 45
PsychoPy - Psychology software for Python, Release 1.78.00
noiseTexture =random.rand(128,128)*2.0-1
3. Send a feedback message at the end of the experiment
Create a Code Component with this in the Begin Experiment field:
expClock =core.Clock()
and with this in the End Experiment field:
print "Thanks for participating - that took %.2f minutes in total" %(expClock.getTime()/60.0)
(or you could create a Text Component with that as contents rather than printing it).
4. End a loop early.
Code components can also be used to control the end of a loop. See examples in Recipes:builderTerminateLoops.
What variables are available to use?
The most complete way to find this out for your particular script is to compile it and take a look at what’s in there.
Below are some options that appear in nearly all scripts. Remember that those variables are Python objects and can
have attributes of their own. You can find out about those attributes using:
dir(myObject)
Common PsychoPy variables:
• expInfo: This is a Python Dictionary containing the information from the starting dialog box. e.g. That generally
includes the ‘participant’ identifier. You can access that in your experiment using exp[’participant’]
• t: the current time (in seconds) measured from the start of this Routine
• frameN: the number of /completed/ frames since the start of the Routine (=0 in the first frame)
• win: the Window that the experiment is using
Your own variables:
• anything you’ve created in a Code Component is available for the rest of the script. (Sometimes you might need
to define it at the beginning of the experiment, so that it wil be available throughout.)
• the name of any other stimulus or the parameters from your file also exist as variables.
• most Components have a status attribute, which is useful to determine whether a stimulus has NOT_STARTED,
STARTED or FINISHED. For example, to play a tone at the end of a Movie Component (of unknown duration)
you could set start of your tone to have the ‘condition’
myMovieName.status==FINISHED
Selected contents of the numpy library and numpy.random are imported by default. The entire numpy library is
imported as np, so you can use a several hundred maths functions by prepending things with ‘np.’:
•random() ,randint() ,normal() ,shuffle() options for creating arrays of random numbers.
•sin(),cos(),tan(), and pi: For geometry and trig. By default angles are in radians, if you want the cosine of
an angle specified in degrees use cos(angle*180/pi), or use numpy’s conversion functions, rad2deg(angle) and
deg2rad(angle).
46 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
•linspace(): Create an array of linearly spaced values.
•log(),log10(): The natural and base-10 log functions, respectively. (Its a lowercase-L in log).
•sum(),len(): For the sum and length of a list or array. To find an average, its better to use average() (due to the
potential for integer division issues with sum()/len() ).
•average(),sqrt(),std(): For average (mean), square root, and standard deviation, respectively. Note: Be sure
that the numpy standard deviation formula is the one you want!
• np.______: Many math-related features are available through the complete numpy libraries, which are available
within psychopy builder scripts as ‘np.’. For example, you could use np.hanning(3) or np.random.poisson(10,
10) in a code component.
11.4.3 Dots (RDK) Component
The Dots Component allows you to present a Random Dot Kinematogram (RDK) to the participant of your study.
These are fields of dots that drift in different directions and subjects are typically required to identify the ‘global
motion’ of the field.
There are many ways to define the motion of the signal and noise dots. In PsychoPy the way the dots are configured
follows Scase, Braddick & Raymond (1996). Although Scase et al (1996) show that the choice of algorithm for your
dots actually makes relatively little difference there are some potential gotchas. Think carefully about whether each
of these will affect your particular case:
•limited dot lifetimes: as your dots drift in one direction they go off the edge of the stimulus and are replaced
randomly in the stimulus field. This could lead to a higher density of dots in the direction of motion providing
subjects with an alternative cue to direction. Keeping dot lives relatively short prevents this.
•noiseDots=’direction’: some groups have used noise dots that appear in a random location on each frame
(noiseDots=’location’). This has the disadvantage that thenoise dots not only have a random direction but also
a random speed (whereas signal dots have a constant speed and constant direction)
•signalDots=’same’: on each frame the dots constituting the signal could be the same as on the previous frame or
different. If ‘different’, participants could follow a single dot for a long time and calculate its average direction
of motion to get the ‘global’ direction, because the dots would sometimes take a random direction and sometimes
take the signal direction.
As a result of these, the defaults for PsychoPy are to have signalDots that are from a ‘different’ population, noise dots
that have random ‘direction’ and a dot life of 3 frames.
Parameters
name : Everything in a PsychoPy experiment needs a unique name. The name should contain only letters, numbers
and underscores (no puncuation marks or spaces).
start : The time that the stimulus should first appear. See Defining the onset/duration of components for details.
stop : Governs the duration for which the stimulus is presented. See Defining the onset/duration of components for
details.
units [None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the Window will be used. See Units for
the window and stimuli for explanation of other options.
nDots [int] number of dots to be generated
fieldPos [(x,y) or [x,y]] specifying the location of the centre of the stimulus.
fieldSize [a single value, specifying the diameter of the field] Sizes can be negative and can extend beyond the window.
11.4. Components 47
PsychoPy - Psychology software for Python, Release 1.78.00
fieldShape : Defines the shape of the field in which the dots appear. For a circular field the nDots represents the
average number of dots per frame, but on each frame this may vary a little.
dotSize Always specified in pixels
dotLife [int] Number of frames each dot lives for (-1=infinite)
dir [float (degrees)] Direction of the signal dots
speed [float] Speed of the dots (in units per frame)
signalDots : If ‘same’ then the signal and noise dots are constant. If different then the choice of which is signal and
which is noise gets randomised on each frame. This corresponds to Scase et al’s (1996) categories of RDK.
noiseDots [‘direction’, ‘position’ or ‘walk’] Determines the behaviour of the noise dots, taken directly from Scase
et al’s (1996) categories. For ‘position’, noise dots take a random position every frame. For ‘direction’ noise
dots follow a random, but constant direction. For ‘walk’ noise dots vary their direction every frame, but keep a
constant speed.
See Also:
API reference for DotStim
11.4.4 Keyboard Component
The Keyboard component can be used to collect responses from a participant.
By not storing the key press and checking the forceEndTrial box it can be used simply to end a Routine
Parameters
Name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
Start [float or integer] The time that the keyboard should first get checked. See Defining the onset/duration of com-
ponents for details.
Stop : When the keyboard is no longer checked. See Defining the onset/duration of components for details.
Force end routine If this box is checked then the Routine will end as soon as one of the allowed keys is pressed.
Allowed keys A list of allowed keys can be specified here, e.g. [’m’,’z’,‘1’,‘2’], or the name of a variable holding
such a list. If this box is left blank then any key that is pressed will be read. Only allowed keys count as having
been pressed; any other key will not be stored and will not force the end of the Routine. Note that key names
(even for number keys) should be given in single quotes, separated by commas. Cursor control keys can be
accessed with ‘up’, ‘down’, and so on; the space bar is ‘space’. To find other special keys, run the Coder Input
demo, “what_key.py”, press the key, and check the Coder output window.
Store Which key press, if any, should be stored; the first to be pressed, the last to be pressed or all that have been
pressed. If the key press is to force the end of the trial then this setting is unlikely to be necessary, unless
two keys happen to be pressed in the same video frame. The response time will also be stored if a keypress
is recorded. This time will be taken from the start of keyboard checking (e.g. if the keyboard was initiated 2
seconds into the trial and a key was pressed 3.2s into the trials the response time will be recorded as 1.2s).
Store correct Check this box if you wish to store whether or not this key press was correct. If so then fill in the
next box that defines what would consitute a correct answer e.g. left, 1 or $corrAns (note this should not be
in inverted commas). This is given as Python code that should return True (1) or False (0). Often this correct
answer will be defined in the settings of the Loops.
48 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
Discard previous Check this box to ensure that only key presses that occur during this keyboard checking period are
used. If this box is not checked a keyboard press that has occured before the start of the checking period will be
interpreted as the first keyboard press. For most experiments this box should be checked.
See Also:
API reference for event
11.4.5 Microphone Component
Please note: This is a new component, and is subject to change.
The microphone component provides a way to record sound during an experiment. To do so, specify the starting time
relative to the start of the routine (see start below) and a stop time (= duration in seconds). A blank duration evaluates
to recording for 0.000s.
The resulting sound files are saved in .wav format (at 48000 Hz, 16 bit), one file per recording. The files appear in a
new folder within the data directory (the subdirectory name ends in _wav). The file names include the unix (epoch)
time of the onset of the recording with milliseconds, e.g., mic-1346437545.759.wav.
It is possible to stop a recording that is in progress by using a code component. Every frame, check for a condition
(such as key ‘q’, or a mouse click), and call the .stop() method of the microphone component. The recording will
end at that point and be saved. For example, if mic is the name of your microphone component, then in the code
component, do this on Each frame:
if event.getKeys([’q’]):
mic.stop()
Parameters
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start [float or integer] The time that the stimulus should first play. See Defining the onset/duration of components for
details.
stop (duration):The length of time (sec) to record for. An expected duration can be given for visualisation purposes.
See Defining the onset/duration of components for details; note that only seconds are allowed.
See Also:
API reference for AudioCapture
11.4.6 Mouse Component
The Mouse component can be used to collect responses from a participant. The coordinates of the mouse location are
given in the same coordinates as the Window, with (0,0) in the centre.
Scenarios
This can be used in various ways. Here are some scenarios (email the list if you have other uses for your mouse):
Use the mouse to record the location of a button press
11.4. Components 49
PsychoPy - Psychology software for Python, Release 1.78.00
Use the mouse to control stimulus parameters Imgine you want to use your mouse to make your ‘patch’_ bigger or
smaller and save the final size. Call your mouse ‘mouse’, set it to save its state at the end of the trial and set the
button press to end the Routine. Then for the size setting of your Patch stimulus insert $mouse.getPos()[0] to
use the x position of the mouse to control the size or $mouse.getPos()[1] to use the y position.
Tracking the entire path of the mouse during a period
Parameters
Name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start : The time that the mouse should first be checked. See Defining the onset/duration of components for details.
stop : When the mouse is no longer checked. See Defining the onset/duration of components for details.
Force End Routine on Press If this box is checked then the Routine will end as soon as one of the mouse buttons is
pressed.
Save Mouse State How often do you need to save the state of the mouse? Every time the subject presses a mouse
button, at the end of the trial, or every single frame? Note that the text output for cases where you store the
mouse data repeatedly per trial (e.g. every press or every frame) is likely to be very hard to interpret, so you may
then need to analyse your data using the psydat file (with python code) instead. Hopefully in future releases the
output of the text file will be improved.
Time Relative To Whenever the mouse state is saved (e.g. on button press or at end of trial) a time is saved too. Do
you want this time to be relative to start of the Routine, or the start of the whole experiment?
See Also:
API reference for mouse
11.4.7 Movie Component
The Movie component allows movie files to be played from a variety of formats (e.g. mpeg, avi, mov).
The movie can be positioned, rotated, flipped and stretched to any size on the screen (using the Units for the window
and stimuli given).
Parameters
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start : The time that the stimulus should first appear. See Defining the onset/duration of components for details.
stop : Governs the duration for which the stimulus is presented (if you want to cut a movie short). Usually you can
leave this blank and insert the Expected duration just for visualisation purposes. See Defining the onset/duration
of components for details.
movie [string] The filename of the movie, including the path. The path can be absolute or relative to the location of
the experiment (.psyexp) file.
pos [[X,Y]] The position of the centre of the stimulus, in the units specified by the stimulus or window
ori [degrees] Movies can be rotated in real-time too! This specifies the orientation of the movie in degrees.
size [[sizex, sizey] or a single value (applied to both x and y)] The size of the stimulus in the given units of the
stimulus/window.
50 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
units [deg, cm, pix, norm, or inherit from window] See Units for the window and stimuli
See Also:
API reference for MovieStim
11.4.8 Patch (image) Component
The Patch stimulus allows images to be presented in a variety of forms on the screen. It allows the combination of an
image, which can be a bitmap image from a variety of standard file formats, or a synthetic repeating texture such as a
sinusoidal grating. A transparency mask can also be control the shape of the image, and this can also be derived from
either a second image, or mathematical form such as a Gaussian.
Patches can have their position, orientation, size and other settings manipulated on a frame-by-frame basis. There is a
performance advantage (in terms of milliseconds) to using images which are square and powers of two (32, 64, 128,
etc.), however this is slight and would not be noticed in the majority of experiments.
Parameters
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start : The time that the stimulus should first appear. See Defining the onset/duration of components for details.
stop : Governs the duration for which the stimulus is presented. See Defining the onset/duration of components for
details.
image [a filename, a standard name (‘sin’, ‘sqr’) or a numpy array of dimensions NxNx1 or NxNx3] This specifies
the image that will be used as the texture for the visual patch. The image can be repeated on the patch (in either
x or y or both) by setting the spatial frequency to be high (or can be stretched so that only a subset of the image
appears by setting the spatial frequency to be low). Filenames can be relative or absolute paths and can refer to
most image formats (e.g. tif, jpg, bmp, png, etc.).
If this is set to none, the patch will be a flat colour.
mask [a filename, a standard name (‘gauss’, ‘circle’) or a numpy array of dimensions NxNx1] The mask can define
the shape (e.g. circle will make the patch circular) or something which overlays the patch e.g. noise.
ori [degrees] The orientation of the entire patch (texture and mask) in degrees.
pos [[X,Y]] The position of the centre of the stimulus, in the units specified by the stimulus or window
size [[sizex, sizey] or a single value (applied to x and y)] The size of the stimulus in the given units of the stimu-
lus/window. If the mask is a Guassian then the size refers to width at 3 standard devations on either side of the
mean (i.e. sd=size/6)
units [deg, cm, pix, norm, or inherit from window] See Units for the window and stimuli
Advanced Settings
colour : See Color spaces
colour space [rgb, dkl or lms] See Color spaces
SF [[SFx, SFy] or a single value (applied to x and y)] The spatial frequency of the texture on the patch. The units
are dependent on the specified units for the stimulus/window; if the units are deg then the SF units will be
cycles/deg, if units are norm then the SF units will be cycles per stimulus. If this is set to none then only one
cycle will be displayed.
11.4. Components 51
PsychoPy - Psychology software for Python, Release 1.78.00
phase [single float or pair of values [X,Y]] The position of the texture within the mask, in both X and Y. If a single
value is given it will be applied to both dimensions. The phase has units of cycles (rather than degrees or
radians), wrapping at 1. As a result, setting the phase to 0,1,2... is equivalent, causing the texture to be centered
on the mask. A phase of 0.25 will cause the image to shift by half a cycle (equivalent to pi radians). The
advantage of this is that is if you set the phase according to time it is automatically in Hz.
Texture Resolution [an integer (power of two)] Defines the size of the resolution of the texture for standard textures
such as sin,sqr etc. For most cases a value of 256 pixels will suffice, but if stimuli are going to be very small
then a lower resolution will use less memory.
interpolate : If linear is selected then linear interpolation will be applied when the image is rescaled to the appropriate
size for the screen. Nearest will use a nearest-neighbour rule.
See Also:
API reference for PatchStim
11.4.9 Polygon (shape) Component
(added in version 1.78.00)
The Polygon stimulus allows you to present a wide range of regular geometric shapes. The basic control comes from setting the number of vertices:
• 2 vertices give a line
• 3 give a triangle
• 4 give a rectangle etc
• a large number will approximate a circle/ellipse
The size parameter takes two values. For a line only the first is used (then use ori to specify the orientation). For
triangles and rectangles the size specifies the height and width as expected. Note that for pentagons upwards, however,
the size determines the width/height of the ellipse on which the vertices will fall, rather than the width/height of the
vertices themselves (slightly smaller typically).
Parameters
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
nVertices : integer
The number of vertices for your shape (2 gives a line, 3 gives a triangle,... a large number results in a
circle/ellipse)
fill settings:
Control the color inside the shape. If you set this to None then you will have a transparent shape (the line
will remain)
line settings:
Control color and width of the line. The line width is always specified in pixels - it does not honour the
units parameter.
size [[w,h]] See note above
start : The time that the stimulus should first appear. See Defining the onset/duration of components for details.
52 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
stop : Governs the duration for which the stimulus is presented. See Defining the onset/duration of components for
details.
ori [degrees] The orientation of the entire patch (texture and mask) in degrees.
pos [[X,Y]] The position of the centre of the stimulus, in the units specified by the stimulus or window
units [deg, cm, pix, norm, or inherit from window] See Units for the window and stimuli
See Also:
API reference for Polygon API reference for Rect API reference for ShapeStim #for arbitrary vertices
11.4.10 RatingScale Component
A rating scale is used to collect a numeric rating or a choice from a few alternatives, via the mouse, the keyboard, or
both. Both the response and time taken to make it are returned.
A given routine might involve an image (patch component), along with a rating scale to collect the response. A routine
from a personality questionaire could have text plus a rating scale.
Three common usage styles are enabled on the first settings page: ‘visual analog scale’: the subject uses the
mouse to position a marker on an unmarked line
‘category choices’: choose among verbal labels (categories, e.g., “True, False” or “Yes, No, Not sure”)
‘scale description’: used for numeric choices, e.g., 1 to 7 rating
Complete control over the display options is available as an advanced setting, ‘customize_everything’.
Properties
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start : The time that the stimulus should first appear. See Defining the onset/duration of components for details.
stop : The duration for which the stimulus is presented. See Defining the onset/duration of components for details.
visualAnalogScale [checkbox] If this is checked, a line with no tick marks will be presented using the ‘glow’ marker,
and will return a rating from 0.00 to 1.00 (quasi-continuous). This is intended to bias people away from thinking
in terms of numbers, and focus more on the visual bar when making their rating. This supercedes either choices
or scaleDescription.
category choices [string] Instead of a numeric scale, you can present the subject with words or phrases to choose
from. Enter all the words as a string. (Probably more than 6 or so will not look so great on the screen.) Spaces
are assumed to separate the words. If there are any commas, the string will be interpreted as a list of words or
phrases (possibly including spaces) that are separated by commas.
scaleDescription : Brief instructions, reminding the subject how to interpret the numerical scale, default = “1 = not
at all ... extremely = 7”
low [str] The lowest number (bottom end of the scale), default = 1. If its not an integer, it will be converted to
lowAnchorText (see Advanced).
high [str] The highest number (top end of the scale), default = 7. If its not an integer, it will be converted to highAn-
chorText (see Advanced).
11.4. Components 53
PsychoPy - Psychology software for Python, Release 1.78.00
Advanced settings
single click : If this box is checked the participant can only click the scale once and their response will be stored. If
this box is not checked the participant must accept their rating before it is stored.
startTime [float or integer] The time (relative to the beginning of this Routine) that the rating scale should first appear.
forceEndTrial : If checked, when the subject makes a rating the routine will be ended.
size [float] The size controls how big the scale will appear on the screen. (Same as “displaySizeFactor”.) Larger than
1 will be larger than the default, smaller than 1 will be smaller than the default.
pos [[X,Y]] The position of the centre of the stimulus, in the units specified by the stimulus or window. Default is
centered left-right, and somewhat lower than the vertical center (0, -0.4).
duration : The maximum duration in seconds for which the stimulus is presented. See duration for details. Typically,
the subject’s response should end the trial, not a duration. A blank or negative value means wait for a very long
time.
storeRatingTime: Save the time from the beginning of the trial until the participant responds.
storeRating: Save the rating that was selected
lowAnchorText [str] Custom text to display at the low end of the scale, e.g., “0%”; overrides ‘low’ setting
highAnchorText [str] Custom text to display at the low end of the scale, e.g., “100%”; overrides ‘high’ setting
customize_everything [str] If this is not blank, it will be used when initializing the rating scale just as it would
be in a code component (see RatingScale). This allows access to all the customizable aspects of a rating
scale, and supercedes all of the other RatingScale settings in the dialog panel. (This does not affect: startTime,
forceEndTrial, duration, storeRatingTime, storeRating.)
See Also:
API reference for RatingScale
11.4.11 Sound Component
Parameters
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start [float or integer] The time that the stimulus should first play. See Defining the onset/duration of components for
details.
stop : For sounds loaded from a file leave this blank and then give the Expected duration below for visualisation
purposes. See Defining the onset/duration of components for details.
sound : This sound can be described in a variety of ways:
• a number can specify the frequency in Hz (e.g. 440)
• a letter gives a note name (e.g. “C”) and sharp or flat can also be added (e.g. “Csh” “Bf”)
• a filename, which can be a relative or absolute path (mid, wav, ogg and mp3 are supported).
See Also:
API reference for Sound
54 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
11.4.12 Static Component
(Added in Version 1.78.00)
The Static Component allows you to have a period where you can preload images or perform other time-consuming
operations that not be possible while the screen is being updated.
Typically a static period would be something like an inter-trial or inter-stumulus interval (ITI/ISI). During this period
you should not have any other objects being presented that are being updated (this isn’t checked for you - you have
to make that check yourself), but you can have components being presented that are themselves static. For instance a
fixation point never changes and so it can be presented during the static period (it will be presented and left on-screen
while the other updates are being made).
Any stimulus updates can be made to occur during any static period defined in the experiment (it does not have to be
in the same Routine). This is done in the updates selection box- once a static preiod exists it will show up here as
well as the standard options of constant and every repeat etc. Many parameter updates (e.g. orientation are made so
quickly that using the static period is of no benefit but others, most notably the loading of images from disk, can take
substantial periods of time and these should always be performed during a static period to ensure good timing.
If the updates that have been requested were not completed by the end of the static period (ie there was a timing
overshoot) then you will receive a warning to that effect. In this case you either need a longer static period to perform
the actions or you need to reduce the time required for the action (e.g. use an image with fewer pixels).
Parameters
name : Everything in a PsychoPy experiment needs a unique name. The name should contain only letters, numbers
and underscores (no puncuation marks or spaces).
start : The time that the static period begins. See Defining the onset/duration of components for details.
stop : The time that the static period ends. See Defining the onset/duration of components for details.
custom code : After running the component updates (which are defined in each component, not here) any code in-
serted here will also be run
See Also:
API reference for StaticPeriod
11.4.13 Text Component
This component can be used to present text to the participant, either instructions or stimuli.
name [string] Everything in a PsychoPy experiment needs a unique name. The name should contain only letters,
numbers and underscores (no puncuation marks or spaces).
start : The time that the stimulus should first appear. See Defining the onset/duration of components for details.
stop : The duration for which the stimulus is presented. See Defining the onset/duration of components for details.
color : See Color spaces
color space [rgb, dkl or lms] See Color spaces
ori [degrees] The orientation of the stimulus in degrees.
pos [[X,Y]] The position of the centre of the stimulus, in the units specified by the stimulus or window
height [integer or float] The height of the characters in the given units of the stimulus/window. Note that nearly all
actual letters will occupy a smaller space than this, depending on font, character, presence of accents etc. The
width of the letters is determined by the aspect ratio of the font.
11.4. Components 55
PsychoPy - Psychology software for Python, Release 1.78.00
units [deg, cm, pix, norm, or inherit from window] See Units for the window and stimuli
opacity : Vary the transparency, from 0.0 = invisible to 1.0 = opaque
flip : Whether to mirror-reverse the text: ‘horiz’ for left-right mirroring, ‘vert’ for up-down mirroring. The flip can
be set dynamically on a per-frame basis by using a variable, e.g., $mirror, as defined in a code component or
conditions file and set to either ‘horiz’ or ‘vert’.
See Also:
API reference for TextStim
11.4.14 Entering parameters
Most of the entry boxes for Component parameters simply receive text or numeric values or lists (sequences of values
surrounded by square brackets) as input. In addition, the user can insert variables and code into most of these, which
will be interpreted either at the beginning of the experiment or at regular intervals within it.
To indicate to PsychoPy that the value represents a variable or python code, rather than literal text, it should be preceded
by a $. For example, inserting intensity into the text field of the Text Component will cause that word literally to be
presented, whereas $intensity will cause python to search for the variable called intensity in the script.
Variables associated with Loops can also be entered in this way (see Accessing loop parameters from components for
further details). But it can also be used to evaluate arbitrary python code.
For example:
•$random(2) will generate a pair of random numbers
•$”yn”[randint()] will randomly choose the first or second character (y or n)
•$globalClock.getTime() will insert the current time in secs of the globalClock object
•$[sin(angle), cos(angle)] will insert the sin and cos of an angle (e.g. into the x,y coords of a stimulus)
11.4.15 How often to evaluate the variable/code
If you do want the parameters of a stimulus to be evaluated by code in this way you need also to decide how often it
should be updated. By default, the parameters of Components are set to be constant; the parameter will be set at the
beginning of the experiment and will remain that way for the duration. Alternatively, they can be set to change either
on every repeat in which case the parameter will be set at the beginning of the Routine on each repeat of it. Lastly
many parameters can even be set on every frame, allowing them to change constantly on every refresh of the screen.
11.5 Experiment settings
The settings menu can be accessed by clicking the icon at the top of the window. It allows the user to set various
aspects of the experiment, such as the size of the window to be used or what information is gathered about the subject
and determine what outputs (data files) will be generated.
11.5.1 Settings
Show info dlg: If this box is checked then a dialog will appear at the beginning of the experiment allowing the
Experiment Info to be changed.
56 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
Experiment Info: This is a python dictionary object that stores information about the current experiment (up to 7
fields can be used). This information will be saved with any data files and so can be used for storing informa-
tion about the current run of the study. The information stored here can also be used within the experiment.
For example, if the Experiment Info was {‘participant’:’jwp’, ‘ori’:10} then Builder Components could access
ExpInfo[’ori’] to retrieve the orientation set here. Obviously this is a useful way to run essentially the same
experiment, but with different conditions set at run time.
Save Excel file: If this box is checked an Excel data file (.xlsx) will be stored.
Save csv file: If this box is checked a comma separated variable (.csv) will be stored.
Save psydat file: If this box is checked a :ref: psydatFile will be stored. This is a Python specific format (.pickle files)
which contains more information that .xlsx or .csv files that can be used with data analysis and plotting scripts
written in Python. Whilst you may not wish to use this format it is recommended that you always save a copy
as it contains a complete record of the experiment at the time of data collection.
Save log file A log file provides a record of what occurred during the experiment in chronological order, including
information about any errors or warnings that may have occurred.
Logging level How much detail do you want to be output to the log file, if it is being saved. The lowest level is error,
which only outputs error messages; warning outputs warnings and errors; info outputs all info, warnings and
errors; debug outputs all info that can be logged. This system enables the user to get a great deal of information
while generating their experiments, but then reducing this easily to just the critical information needed when
actually running the study. If your experiment is not behaving as you expect it to, this is an excellent place to
begin to work out what the problem is.
Monitor The name of the monitor calibration. Must match one of the monitor names from Monitor Center.
Screen: If multiple screens are available (and if the graphics card is not an intel integrated graphics chip) then the
user can choose which screen they use (e.g. 1 or 2).
Full-screen window: If this box is checked then the experiment window will fill the screen (overriding the window
size setting and using the size that the screen is currently set to in the operating system settings).
Window size: The size of the window in pixels, if this is not to be a full-screen window.
Units The default units of the window (see Units for the window and stimuli). These can be overridden by individual
Components.
11.6 Defining the onset/duration of components
As of version 1.70.00, the onset and offset times of stimuli can be defined in several ways.
Start and stop times can be entered in terms of seconds (time (s)), by frame number (frameN) or or in relation to
another stimulus (condition). Condition would be used to make Components start or stop depending on the status of
something else, for example when a sound has finished. Duration can also be varied using a Code Component.
If you need very precise timing (particularly for very brief stimuli for instance) then it is best to control your on-
set/duration by specifying the number of frames the stimulus will be presented for.
Measuring duration in seconds (or milliseconds) is not very precise because it doesn’t take into account the fact that
your monitor has a fixed frame rate. For example if the screen has a refresh rate of 60Hz you cannot present your
stimulus for 120ms; the frame rate would limit you to 116.7ms (7 frames) or 133.3ms (8 frames). The duration of a
frame (in seconds) is simply 1/refresh rate in Hz.
Condition would be used to make Components start or stop depending on the status of something else, for example
when a movie has finished. Duration can also be varied using a code component.
In cases where PsychoPy cannot determine the start/endpoint of your Component (e.g. because it is a variable) you can
enter an ‘Expected’ start/duration. This simply allows components with variable durations to be drawn in the Routine
11.6. Defining the onset/duration of components 57
PsychoPy - Psychology software for Python, Release 1.78.00
window. If you do not enter the approximate duration it will not be drawn, but this will not affect experimental
performance.
For more details of how to achieve good temporal precision see Timing Issues and synchronisation
11.6.1 Examples
• Use time(s) or frameN and simply enter numeric values into the start and duration boxes.
• Use time(s) or frameN and enter a numeric value into the start time and set the duration to a variable name by
preceeding it with a $ as described here. Then set expected time to see an approximation in your routine
• Use condition to cause the stimulus to start immediately after a movie component called myMovie, by entering
$myMovie.status==FINISHED into the start time.
11.7 Generating outputs (datafiles)
There are 4 main forms of output file from PsychoPy:
• Excel 2007 files (.xlsx) see Excel Data Files for more details
• text data files (.csv or .dlm) see Delimited Text Files for more details
• binary data files (.psydat) see PsychoPy Data Files for more details
• log files (.log) see Log Files for more details
11.8 Common Mistakes (aka Gotcha’s)
11.8.1 General Advice
• Python and therefore Psychopy is CASE SENSITIVE
• To use a dollar sign ($) for anything other than to indicate a code snippet for example in a Text Component,
precede it with a backslash \$ (the backslash won’t be printed)
• Have you entered your the settings for your monitor? If you are using degrees as a unit of measurement and
have not entered your monitor settings, the size of stimuli will not be accurate.
• If your experiment is not behaving in the way that you expect. Have you looked at the log file? This can point
you in the right direction ? Did you know you can change the type of information that is stored in the log file in
preferences by changing the logging level.
• Have you tried compiling the script and running it. Does this produce a particular error message that points you
at a particular problem area? You can also change things in a more detailed way in the coder view and if you are
having problems, reading through the script can highlight problems. Reading a compiled script can also help
with the creation of a Code Component
11.8.2 My stimulus isn’t appearing, there’s only the grey background
• Have you checked the size of your stimulus? If it is 0.5x0.5 pixels you won’t be able to see it!
• Have you checked the position of your stimulus? Is it positioned off the screen?
58 Chapter 11. Builder
PsychoPy - Psychology software for Python, Release 1.78.00
11.8.3 The loop isn’t using my Excel spreadsheet
• Have you remembered to specify the file you want to use when setting up the loop?
• Have you remembered to add the variables proceeded by the $ symbol to you stimuli?
11.8.4 I just want a plain square, but it’s turning into a grating
• If you don’t want your stimulus to have a texture, you need Image to be None
11.8.5 The code snippet I’ve entered doesn’t do anything
• Have you remembered to put a $ symbol at the beginning (this isn’t necessary, and should be avoided in a Code
Component)?
• A dollar sign as the first character of a line indicates to PsychoPy that the rest of the line is code. It does not
indicate a variable name (unlike in perl or php). This means that if you are, for example, using variables to
determine position, enter $[x,y]. The temptation is to use [$x,$y], which will not work.
11.8.6 My stimulus isn’t changing as I progress through the loop
• Have you changed the setting for the variable that you want to change to ‘change every repeat’ (or ‘change every
frame’)?
11.8.7 I’m getting the error message AttributeError: ‘unicode object has no at-
tribute ‘XXXX’
• This type of error is usually caused by a naming conflict. Whilst we have made every attempt to make sure that
these conflicts produce a warning message it is possible that they may still occur.
• The most common source of naming conflicts in an external file which has been imported to be used in a loop
i.e. .xlsx, .csv.
• Check to make sure that all of the variable names are unique. There can be no repeated variable names anywhere
in your experiment.
11.8.8 The window opens and immediately closes
• Have you checked all of your variable entries are accepted commands e.g. gauss but not Gauss
• If you compile your experiment and run it from the coder window what does the error message say? Does it
point you towards a particular variable which may be incorrectly formatted?
If you are having problems getting the application to run please see Troubleshooting
11.9 Compiling a Script
If you click the compile script icon this will display the script for your experiment in the Coder window.
This can be used for debugging experiments, entering small amounts of code and learning a bit about writing scripts
amongst other things.
11.9. Compiling a Script 59
PsychoPy - Psychology software for Python, Release 1.78.00
The code is fully commented and so this can be an excellent introduction to writing your own code.
11.10 Set up your monitor properly
It’s a really good idea to tell PsychoPy about the set up of your monitor, especially the size in cm and pixels and its
distance, so that PsychoPy can present your stimuli in units that will be consistent in another lab with a different set
up (e.g. cm or degrees of visual angle).
You should do this in Monitor Center which can be opened from Builder by clicking on the icon that shows two
monitors. In Monitor Center you can create settings for multiple configurations, e.g. different viewing distances or
different physical devices and then select the appropriate one by name in your experiments or scripts.
Having set up your monitor settings you should then tell PsychoPy which of your monitor setups to use for this
experiment by going to the Experiment settings dialog.
11.11 Future developments
The builder view still has a few rough edges, but is hopefully fairly usable. Here are some of the ways I hope it will
improve:
• More components. Several of the stimuli and events that PsychoPy can handle don’t currently show up as
components in the builder view, but they can be added easily (take a look inside the components directory to see
how easy it is to create a component).
• Dialogue entry validation. Dialogue boxes currently allow you to type almost anything into their windows. The
only current checking is that a name is given to the component and that this is unique. More checking is needed
to reduce errors.
• Similar to the above, I hope to add suggested entries to go into dialogs, as a form of help. e.g. on right-clicking
an entry box, say for stimulus orientation, a context menu should appear with ideas including numeric values,
known local variables (e.g. “thisTrial.rgb”, based on the existing loops in the Flow) and global variable ideas
(e.g. “frameN*360”)
• Better code output. I hope that the builder output code will illustrate best practice for precise timing and stimulus
presentation (it will probably always take more lines than a man-made script, but it should be at least as precise).
At the moment that isn’t the case. e.g. The builder should strongly recommend an interval between trials where
only static stimuli are drawn (e.g. fixation) and update components for this trial in that interval.
60 Chapter 11. Builder
CHAPTER
TWELVE
CODER
Note: These do not teach you about Python per se, and you are recommended also to learn about that (Python has
many excellent tutorials for programmers and non-programmers alike). In particular, dictionaries, lists and numpy
arrays are used a great deal in most PsychoPy experiments.
You can learn to use the scripting interface to PsychoPy in several ways, and you should probably follow a combination
of them:
•Basic Concepts: some of the logic of PsychoPy scripting
•PsychoPy Tutorials: walk you through the development of some semi-complete experiments
• demos: in the demos menu of Coder view. Many and varied
• use the Builder to compile a script and see how it works
• check the Reference Manual (API) for further details
• ultimately go into PsychoPy and start examining the source code. It’s just regular python!
12.1 Basic Concepts
12.1.1 Presenting Stimuli
Note: Before you start, tell PsychoPy about your monitor(s) using the Monitor Center. That way you get to use units
(like degrees of visual angle) that will transfer easily to other computers.
Stimulus objects
Python is an ‘object-oriented’ programming language, meaning that Most stimuli in PsychoPy are represented by
python objects, with various associated methods and information.
Typically you should create your stimulus once, at the beginning of the script, and then change it as you need to later
using set____() commands. For instance, create your text and then change its color any time you like:
from psychopy import visual, core
win=visual.Window([400,400])
message =visual.TextStim(win, text=’hello’)
message.setAutoDraw(True)#automatically draw every frame
win.flip()
61
PsychoPy - Psychology software for Python, Release 1.78.00
core.wait(2.0)
message.setText(’world’)#change properties of existing stim
win.flip()
core.wait(2.0)
Timing
There are various ways to measure and control timing in PsychoPy:
• using frame refresh periods (most accurate, least obvious)
• checking the time on Clock objects
• using core.wait() commands (most obvious, least flexible/accurate)
Using core.wait(), as in the above example, is clear and intuitive in your script. But it can’t be used while something
is changing. For more flexible timing, you could use a Clock() object from the core module:
from psychopy import visual, core
#setup stimulus
win=visual.Window([400,400])
gabor =visual.PatchStim(win, tex=’sin’, mask=’gauss’,sf=5, name=’gabor’)
gabor.setAutoDraw(True)#automatically draw every frame
gabor.autoLog=False#or we’ll get many messages about phase change
clock =core.Clock()
#let’s draw a stimulus for 2s, drifting for middle 0.5s
while clock.getTime()<2.0:#clock times are in seconds
if 0.5<=clock.getTime()<1.0:
gabor.setPhase(0.1,’+’)#increment by 10th of cycle
win.flip()
Clocks are accurate to around 1ms (better on some platforms), but using them to time stimuli is not very accurate
because it fails to account for the fact that one frame on your monitor has a fixed frame rate. In the above, the stimulus
does not actually get drawn for exactly 0.5s (500ms). If the screen is refreshing at 60Hz (16.7ms per frame) and the
getTime() call reports that the time has reached 1.999s, then the stimulus will draw again for a frame, in accordance
with the while loop statement and will ultimately be displayed for 2.0167s. Alternatively, if the time has reached
2.001s, there will not be an extra frame drawn. So using this method you get timing accurate to the nearest frame
period but with little consistent precision. An error of 16.7ms might be acceptable to long-duration stimuli, but not to
a brief presentation. It also might also give the false impression that a stimulus can be presented for any given period.
At 60Hz refresh you can not present your stimulus for, say, 120ms; the frame period would limit you to a period of
116.7ms (7 frames) or 133.3ms (8 frames).
As a result, the most precise way to control stimulus timing is to present them for a specified number of frames. The
frame rate is extremely precise, much better than ms-precision. Calls to Window.flip() will be synchronised to the
frame refresh; the script will not continue until the flip has occured. As a result, on most cards, as long as frames are
not being ‘dropped’ (see Detecting dropped frames) you can present stimuli for a fixed, reproducible period.
Note: Some graphics cards, such as Intel GMA graphics chips under win32, don’t support frame sync. Avoid
integrated graphics for experiment computers wherever possible.
Using the concept of fixed frame periods and flip() calls that sync to those periods we can time stimulus presentation
extremely precisely with the following:
62 Chapter 12. Coder
PsychoPy - Psychology software for Python, Release 1.78.00
from psychopy import visual, core
#setup stimulus
win=visual.Window([400,400])
gabor =visual.PatchStim(win, tex=’sin’, mask=’gauss’,sf=5,
name=’gabor’, autoLog=False)
fixation =visual.PatchStim(win, tex=None, mask=’gauss’,sf=0, size=0.02,
name=’fixation’, autoLog=False)
clock =core.Clock()
#let’s draw a stimulus for 2s, drifting for middle 0.5s
for frameN in range(200):#for exactly 200 frames
if 10<=frameN<150:#present fixation for a subset of frames
fixation.draw()
if 50<=frameN<100:#present stim for a different subset
gabor.setPhase(0.1,’+’)#increment by 10th of cycle
gabor.draw()
win.flip()
Using autoDraw
Stimuli are typically drawn manually on every frame in which they are needed, using the draw() function. You can
also set any stimulus to start drawing every frame using setAutoDraw(True) or setAutoDraw(False). If you use these
commands on stimuli that also have autoLog=True, then these functions will also generate a log message on the frame
when the first drawing occurs and on the first frame when it is confirmed to have ended.
12.1.2 Logging data
TrialHandler and StairHandler can both generate data outputs in which responses are stored, in relation to the stimulus
conditions. In addition to those data outputs, PsychoPy can created detailed chronological log files of events during
the experiment.
Log levels and targets
Log messages have various levels of severity: ERROR, WARNING, DATA, EXP, INFO and DEBUG
Multiple targets can also be created to receive log messages. Each target has a particular critical level and receives all
logged messages greater than that. For example, you could set the console (visual output) to receive only warnings
and errors, have a central log file that you use to store warning messages across studies (with file mode append), and
another to create a detailed log of data and events within a single study with level=INFO:
from psychopy import logging
logging.console.setLevel(logging.WARNING)
#overwrite (mode=’w’) a detailed log of the last run in this dir
lastLog=logging.LogFile("lastRun.log", level=logging.INFO, mode=’w’)
#also append warnings to a central log file
centralLog=logging.LogFile("c:/psychopyExps.log", level=logging.WARNING, mode=’a’)
Updating the logs
For performance purposes log files are not actually written when the log commands are ‘sent’. They are stored in a
stack and processed automatically when the script ends. You might also choose to force a flush of the logged messages
manually during the experiment (e.g. during an inter-trial interval):
12.1. Basic Concepts 63
PsychoPy - Psychology software for Python, Release 1.78.00
from psychopy import log
...
logging.flush()#write messages out to all targets
This should only be necessary if you want to see the logged information as the experiment progresses.
AutoLogging
New in version 1.63.00
Certain events will log themselves automatically by default. For instance, visual stimuli send log messages every
time one of their parameters is changed, and when autoDraw is toggled they send a message that the stimulus has
started/stopped. All such log messages are timestamped with the frame flip on which they take effect. To avoid
this logging, for stimuli such as fixation points that might not be critical to your analyses, or for stimuli that change
constantly and will flood the logging system with messages, the autoLogging can be turned on/off at initialisation of
the stimulus and can be altered afterwards with .setAutoLog(True/False)
Manual methods
In addition to a variety of automatic logging messages, you can create your own, of various levels. These can be
timestamped immediately:
from psychopy import logging
logging.log(level=logging.WARN, msg=’something important’)
logging.log(level=logging.EXP, msg=’something about the conditions’)
logging.log(level=logging.DATA, msg=’something about a response’)
logging.log(level=logging.INFO, msg=’something less important’)
There are additional convenience functions for the above: logging.warn(‘a warning’) etc.
For stimulus changes you probably want the log message to be timestamped based on the frame flip (when the stimulus
is next presented) rather than the time that the log message is sent:
from psychopy import logging, visual
win =visual.Window([400,400])
win.flip()
logging.log(level=logging.EXP, msg=’sent immediately’)
win.logOnFlip(level=logging.EXP, msg=’sent on actual flip’)
win.flip()
Using a custom clock for logs
New in version 1.63.00
By default times for log files are reported as seconds after the very beginning of the script (often it takes a few seconds
to initialise and import all modules too). You can set the logging system to use any given core.Clock object
(actually, anything with a getTime() method):
from psychopy import core, logging
globalClock=core.Clock()
logging.setDefaultClock(globalClock)
64 Chapter 12. Coder
PsychoPy - Psychology software for Python, Release 1.78.00
12.1.3 Handling Trials and Conditions
TrialHandler
This is what underlies the random and sequential loop types in Builder, they work using the method of constants. The
trialHandler presents a predetermined list of conditions in either a sequential or random (without replacement) order.
see TrialHandler for more details.
StairHandler
This generates the next trial using an adaptive staircase. The conditions are not predetermined and are generated based
on the participant’s responses.
Staircases are predominately used in psychophysics to measure the discrimination and detection thresholds. However
they can be used in any experiment which varies a numeric value as a result of a 2 alternative forced choice (2AFC)
response.
The StairHandler systematically generates numbers based on staircase parameters. These can then be used to define a
stimulus parameter e.g. spatial frequency, stimulus presentation duration. If the participant gives the incorrect response
the number generated will get larger and if the participant gives the correct response the number will get smaller.
see StairHandler for more details
12.2 PsychoPy Tutorials
12.2.1 Tutorial 1: Generating your first stimulus
A tutorial to get you going with your first stimulus display.
Know your monitor
PsychoPy has been designed to handle your screen calibrations for you. It is also designed to operate (if possible) in
the final experimental units that you like to use e.g. degrees of visual angle.
In order to do this PsychoPy needs to know a little about your monitor. There is a GUI to help with this (select
MonitorCenter from the tools menu of PsychoPyIDE or run ...site-packages/monitors/MonitorCenter.py).
In the MonitorCenter window you can create a new monitor name, insert values that describe your monitor and run
calibrations like gamma corrections. For now you can just stick to the [testMonitor] but give it correct values for your
screen size in number of pixels and width in cm.
Now, when you create a window on your monitor you can give it the name ‘testMonitor’ and stimuli will know how
they should be scaled appropriately.
Your first stimulus
Building stimuli is extremely easy. All you need to do is create a Window, then some stimuli. Draw those stimuli,
then update the window. PsychoPy has various other useful commands to help with timing too. Here’s an example.
Type it into a coder window, save it somewhere and press run.
12.2. PsychoPy Tutorials 65
PsychoPy - Psychology software for Python, Release 1.78.00
1from psychopy import visual, core #import some libraries from PsychoPy
2
3#create a window
4mywin =visual.Window([800,600],monitor="testMonitor", units="deg")
5
6#create some stimuli
7grating =visual.PatchStim(win=mywin, mask="circle", size=3,\
8pos=[-4,0], sf=3)
9fixation =visual.PatchStim(win=mywin, size=0.5, pos=[0,0], sf=0, rgb=-1)
10
11 #draw the stimuli and update the window
12 grating.draw()
13 fixation.draw()
14 mywin.update()
15
16 #pause, so you get a chance to see it!
17 core.wait(5.0)
Note: For those new to Python. Did you notice that the grating and the fixation stimuli both call PatchStim
but have different arguments? One of the nice features about python is that you can select which arguments to set.
PatchStim has over 15 arguments that can be set, but the others just take on default values if they aren’t needed.
That’s a bit easy though. Let’s make the stimulus move, at least! To do that we need to create a loop where we change
the phase (or orientation, or position...) of the stimulus and then redraw. Add this code in place of the drawing code
above:
for frameN in range(200):
grating.setPhase(0.05,’+’)#advance phase by 0.05 of a cycle
grating.draw()
fixation.draw()
mywin.update()
That ran for 200 frames (and then waited 5 seconds as well). Maybe it would be nicer to keep updating until the user
hits a key instead. Thats easy to add too. In the first line add event to the list of modules you’ll import. Then replace
the line:
for frameN in range(200)
with the line:
while True: #this creates a never-ending loop
Then, within the loop (make sure it has the same indentation as the other lines) add the lines:
if len(event.getKeys())>0:break
event.clearEvents()
the first line counts how many keys have been pressed since the last frame. If more than zero are found then we break
out of the never-ending loop. The second line clears the event buffer and should always be called after you’ve collected
the events you want (otherwise it gets full of events that we don’t care about like the mouse moving around etc...).
Your finished script should look something like this:
1from psychopy import visual, core, event #import some libraries from PsychoPy
2
3#create a window
4mywin =visual.Window([800,600],monitor="testMonitor", units="deg")
5
66 Chapter 12. Coder
PsychoPy - Psychology software for Python, Release 1.78.00
6#create some stimuli
7grating =visual.PatchStim(win=mywin, mask=’circle’, size=3, pos=[-4,0], sf=3)
8fixation =visual.PatchStim(win=mywin, size=0.2, pos=[0,0], sf=0, rgb=-1)
9
10 #draw the stimuli and update the window
11 while True:#this creates a never-ending loop
12 grating.setPhase(0.05,’+’)#advance phase by 0.05 of a cycle
13 grating.draw()
14 fixation.draw()
15 mywin.flip()
16
17 if len(event.getKeys())>0:break
18 event.clearEvents()
19
20 #cleanup
21 mywin.close()
22 core.quit()
There are several more simple scripts like this in the demos menu of the Coder and Builder views and many more to
download. If you’re feeling like something bigger then go to Tutorial 2: Measuring a JND using a staircase procedure
which will show you how to build an actual experiment.
12.2.2 Tutorial 2: Measuring a JND using a staircase procedure
This tutorial builds an experiment to test your just-noticeable-difference (JND) to orientation, that is it determines
the smallest angular deviation that is needed for you to detect that a gabor stimulus isn’t vertical (or at some other
reference orientation). The method presents a pair of stimuli at once with the observer having to report with a key
press whether the left or the right stimulus was at the reference orientation (e.g. vertical).
You can download the full code here. Note that the entire experiment is constructed of less than 100 lines of
code, including the initial presentation of a dialogue for parameters, generation and presentation of stimuli, running
the trials, saving data and outputing a simple summary analysis for feedback. Not bad, eh?
There are a great many modifications that can be made to this code, however this example is designed to demonstrate
how much can be achieved with very simple code. Modifying existing is an excellent way to begin writing your own
scripts, for example you may want to try changing the appearance of the text or the stimuli.
Get info from the user
The first lines of code import the necessary libraries. We need lots of the psychopy components for a full experiment,
as well as python’s time library (to get the current date) and numpy (which handles various numerical/mathematical
functions):
from psychopy import core, visual, gui, data, misc, event
import time,numpy,random
The try:...except:... lines allow us to try and load a parameter file from a previous run of the experiment. If
that fails (e.g. because the experiment has never been run) then create a default set of parameters. These are easy to
store in a python dictionary that we’ll call expInfo:
try:#try to get a previous parameters file
expInfo =misc.fromFile(’lastParams.pickle’)
except:#if not there then use a default set
expInfo ={’observer’:’jwp’,’refOrientation’:0}
expInfo[’dateStr’]=data.getDateStr() #add the current time
12.2. PsychoPy Tutorials 67
PsychoPy - Psychology software for Python, Release 1.78.00
The last line adds the current date to whichever method was used.
So having loaded those parameters, let’s allow the user to change them in a dialogue box (which we’ll call dlg). This
is the simplest form of dialogue, created directly from the dictionary above. the dialogue will be presented immediately
to the user and the script will wait until they hit OK or Cancel.
If they hit OK then dlg.OK=True, in which case we’ll use the updated values and save them straight to a parameters
file (the one we try to load above).
If they hit Cancel then we’ll simply quit the script and not save the values.
dlg =gui.DlgFromDict(expInfo, title=’simple JND Exp’, fixed=[’dateStr’])
if dlg.OK:
misc.toFile(’lastParams.pickle’, expInfo)#save params to file for next time
else:
core.quit()#the user hit cancel so exit
Setup the information for trials
We’ll create a file to which we can output some data as text during each trial (as well as outputting a binary file at
the end of the experiment). We’ll create a filename from the subject+date+”.csv” (note how easy it is to concatenate
strings in python just by ‘adding’ them). csv files can be opened in most spreadsheet packages. Having opened a text
file for writing, the last line shows how easy it is to send text to this target document.
fileName =expInfo[’observer’]+expInfo[’dateStr’]
dataFile =open(fileName+’.csv’,’w’)#a simple text file with ’comma-separated-values’
dataFile.write(’targetSide,oriIncrement,correct\n’)
PsychoPy allows us to set up an object to handle the presentation of stimuli in a staircase procedure, the
StairHandler. This will define the increment of the orientation (ie. how far it is from the reference orienta-
tion). The staircase can be configured in many ways, but we’ll set it up to begin with an increment of 20deg (very
detectable) and home in on the 80% threshold value. We’ll step up our increment every time the subject gets a wrong
answer and step down if they get three right answers in a row. The step size will also decrease after every 2 reversals,
starting with an 8dB step (large) and going down to 1dB steps (smallish). We’ll finish after 50 trials.
staircase =data.StairHandler(startVal =20.0,
stepType =’db’, stepSizes=[8,4,4,2,2,1,1],
nUp=1, nDown=3,#will home in on the 80% threshold
nTrials=1)
Build your stimuli
Now we need to create a window, some stimuli and timers. We need a ~psychopy.visual.Window in which to draw
our stimuli, a fixation point and two ~psychopy.visual.PatchStim stimuli (one for the target probe and one as the foil).
We can have as many timers as we like and reset them at any time during the experiment, but I generally use one to
measure the time since the experiment started and another that I reset at the beginning of each trial.
#create window and stimuli
win =visual.Window([800,600],allowGUI=True, monitor=’testMonitor’, units=’deg’)
foil =visual.PatchStim(win, sf=1, size=4, mask=’gauss’, ori=expInfo[’refOrientation’])
target =visual.PatchStim(win, sf=1, size=4, mask=’gauss’, ori=expInfo[’refOrientation’])
fixation =visual.PatchStim(win, color=-1, colorSpace=’rgb’, tex=None, mask=’circle’,size=0.2)
#and some handy clocks to keep track of time
globalClock =core.Clock()
trialClock =core.Clock()
68 Chapter 12. Coder
PsychoPy - Psychology software for Python, Release 1.78.00
Once the stimuli are created we should give the subject a message asking if they’re ready. The next two lines create a
pair of messages, then draw them into the screen and then update the screen to show what we’ve drawn. Finally we
issue the command event.waitKeys() which will wait for a keypress before continuing.
message1 =visual.TextStim(win, pos=[0,+3],text=’Hit a key when ready.’)
message2 =visual.TextStim(win, pos=[0,-3],
text="Then press left or right to identify the %.1f deg probe." %expInfo[’refOrientation’])
message1.draw()
message2.draw()
fixation.draw()
win.flip()#to show our newly drawn ’stimuli’
#pause until there’s a keypress
event.waitKeys()
Control the presentation of the stimuli
OK, so we have everything that we need to run the experiment. The following uses a for-loop that will iterate over
trials in the experiment. With each pass through the loop the staircase object will provide the new value for the
intensity (which we will call thisIncrement). We will randomly choose a side to present the target stimulus using
numpy.random.random(), setting the position of the target to be there and the foil to be on the other side of the
fixation point.
for thisIncrement in staircase: #will step through the staircase
#set location of stimuli
targetSide=random.choice([-1,1]) #will be either +1(right) or -1(left)
foil.setPos([-5*targetSide, 0])
target.setPos([5*targetSide, 0]) #in other location
Then set the orientation of the foil to be the reference orientation plus thisIncrement, draw all the stimuli (in-
cluding the fixation point) and update the window.
#set orientation of probe
foil.setOri(expInfo[’refOrientation’]+thisIncrement)
#draw all stimuli
foil.draw()
target.draw()
fixation.draw()
win.flip()
Wait for presentation time of 500ms and then blank the screen (by updating the screen after drawing just the fixation
point).
core.wait(0.5)#wait 500ms; but use a loop of x frames for more accurate timing in fullscreen
# eg, to get 30 frames: for f in xrange(30): win.flip()
#blank screen
fixation.draw()
win.flip()
Get input from the subject
Still within the for-loop (note the level of indentation is the same) we need to get the response from the subject. The
method works by starting off assuming that there hasn’t yet been a response and then waiting for a key press. For
each key pressed we check if the answer was correct or incorrect and assign the response appropriately, which ends
the trial. We always have to clear the event buffer if we’re checking for key presses like this
12.2. PsychoPy Tutorials 69
PsychoPy - Psychology software for Python, Release 1.78.00
thisResp=None
while thisResp==None:
allKeys=event.waitKeys()
for thisKey in allKeys:
if thisKey==’left’:
if targetSide==-1: thisResp =1#correct
else: thisResp = -1#incorrect
elif thisKey==’right’:
if targetSide== 1: thisResp =1#correct
else: thisResp = -1#incorrect
elif thisKey in [’q’,’escape’]:
core.quit() #abort experiment
event.clearEvents() #must clear other (eg mouse) events - they clog the buffer
Now we must tell the staircase the result of this trial with its addData() method. Then it can work out whether the
next trial is an increment or decrement. Also, on each trial (so still within the for-loop) we may as well save the data
as a line of text in that .csv file we created earlier.
staircase.addData(thisResp)
dataFile.write(’%i,%.3f,%i\n’%(targetSide, thisIncrement, thisResp))
core.wait(1)
Output your data and clean up
OK! We’re basically done! We’ve reached the end of the for-loop (which occured because the staircase terminated)
which means the trials are over. The next step is to close the text data file and also save the staircase as a binary file
(by ‘pickling’ the file in Python speak) which maintains a lot more info than we were saving in the text file.
#staircase has ended
dataFile.close()
staircase.saveAsPickle(fileName) #special python binary file to save all the info
While we’re here, it’s quite nice to give some immediate feedback to the user. Let’s tell them the the intensity values
at the all the reversals and give them the mean of the last 6. This is an easy way to get an estimate of the threshold,
but we might be able to do a better job by trying to reconstruct the psychometric function. To give that a try see the
staircase analysis script of Tutorial 3.
Having saved the data you can give your participant some feedback and quit!
#give some output to user in the command line in the output window
print ’reversals:’
print staircase.reversalIntensities
print ’mean of final 6 reversals = %.3f’%(numpy.average(staircase.reversalIntensities[-6:]))
#give some on screen feedback
feedback1 =visual.TextStim(win, pos=[0,+3],
text=’mean of final 6 reversals = %.3f’%
(numpy.average(staircase.reversalIntensities[-6:])))
feedback1.draw()
fixation.draw()
win.flip()
event.waitKeys() #wait for participant to respond
win.close()
core.quit()
70 Chapter 12. Coder
PsychoPy - Psychology software for Python, Release 1.78.00
12.2.3 Tutorial 3: Analysing data in Python
You could simply output your data as tab- or comma-separated text files and analyse the data in some spreadsheet
package. But the matplotlib library in Python also allows for very neat and simple creation of publication-quality
plots.
This script shows you how to use a couple of functions from PsychoPy to open some data files
(psychopy.gui.fileOpenDlg()) and create a psychometric function out of some staircase data
(psychopy.data.functionFromStaircase()).
Matplotlib is then used to plot the data.
Note: Matplotlib and pylab. Matplotlib is a python library that has similar command syntax to most of the plotting
functions in Matlab(tm). In can be imported in different ways; the import pylab line at the beginning of the script
is the way to import matploblib as well as a variety of other scientific tools (that aren’t striclty to do with plotting per
se).
1#This analysis script takes one or more staircase datafiles as input
2#from a GUI. It then plots the staircases on top of each other on
3#the left and a combined psychometric function from the same data
4#on the right
5
6from psychopy import data, gui, misc, core
7import pylab
8
9#Open a dialog box to select files from
10 files =gui.fileOpenDlg(’.’)
11 if not files:
12 core.quit()
13
14 #get the data from all the files
15 allIntensities, allResponses =[],[]
16 for thisFileName in files:
17 thisDat =misc.fromFile(thisFileName)
18 allIntensities.append( thisDat.intensities )
19 allResponses.append( thisDat.data )
20
21 #plot each staircase
22 pylab.subplot(121)
23 colors =’brgkcmbrgkcm’
24 lines, names =[],[]
25 for fileN, thisStair in enumerate(allIntensities):
26 #lines.extend(pylab.plot(thisStair))
27 #names = files[fileN]
28 pylab.plot(thisStair, label=files[fileN])
29 #pylab.legend()
30
31 #get combined data
32 combinedInten, combinedResp, combinedN =\
33 data.functionFromStaircase(allIntensities, allResponses, 5)
34 #fit curve - in this case using a Weibull function
35 fit =data.FitFunction(’weibullTAFC’,combinedInten, combinedResp, \
36 guess=[0.2,0.5])
37 smoothInt =pylab.arange(min(combinedInten), max(combinedInten), 0.001)
38 smoothResp =fit.eval(smoothInt)
39 thresh =fit.inverse(0.8)
40 print thresh
12.2. PsychoPy Tutorials 71
PsychoPy - Psychology software for Python, Release 1.78.00
41
42 #plot curve
43 pylab.subplot(122)
44 pylab.plot(smoothInt, smoothResp, ’-’)
45 pylab.plot([thresh, thresh],[0,0.8],’--’); pylab.plot([0, thresh],\
46 [0.8,0.8],’--’)
47 pylab.title(’threshold = %0.3f’%(thresh))
48 #plot points
49 pylab.plot(combinedInten, combinedResp, ’o’)
50 pylab.ylim([0,1])
51
52 pylab.show()
72 Chapter 12. Coder
CHAPTER
THIRTEEN
TROUBLESHOOTING
Regretably, PsychoPy is not bug-free. Running on all possible hardware and all platforms is a big ask. That said, a
huge number of bugs have been resolved by the fact that there are literally 1000s of people using the software that
have contributed either bug reports and/or fixes.
Below are some of the more common problems and their workarounds, as well as advice on how to get further help.
13.1 The application doesn’t start
You may find that you try to launch the PsychoPy application, the splash screen appears and then goes away and
nothing more happens. What this means is that an error has occured during startup itself.
Commonly, the problem is that a preferences file is somehow corrupt. To fix that see Cleaning preferences and app
data, below.
If resetting the preferences files doesn’t help then we need to get to an error message in order to work out why the
application isn’t starting. The way to get that message depends on the platform (see below).
Windows users (starting from the Command Prompt):
1. Did you get an error message that “This application failed to start because the application configuration is
incorrect. Reinstalling the application may fix the problem”? If so that indicates you need to update your .NET
installation to SP1 .
2. open a DOS Command Prompt (terminal):
(a) go to the Windows Start menu
(b) select Run... and type in cmd <Return>
3. paste the following into that window (Ctrl-V doesn’t work but you can right-click and select Paste). Replace
VERSION with your version number (e.g. 1.61.03):
"C:\Program Files\PsychoPy2\python.exe" "C:\Program Files\PsychoPy2\Lib\site-packages\PsychoPy-VERSION-py2.6.egg\psychopy\app\psychopyApp.py"
4. when you hit <return> you will hopefully get a moderately useful error message that you can Contribute to the
Forum (mailing list)
Mac users:
1. open the Console app (open spotlight and type console)
2. if there are a huge number of messages there you might find it easiest to clear them (the brush icon) and
then start PsychoPy again to generate a new set of messages
73
PsychoPy - Psychology software for Python, Release 1.78.00
13.2 I run a Builder experiment and nothing happens
An error message may have appeared in a dialog box that is hidden (look to see if you have other open windows
somewhere).
An error message may have been generated that was sent to output of the Coder view:
1. go to the Coder view (from the Builder>View menu if not visible)
2. if there is no Output panel at the bottom of the window, go to the View menu and select Output
3. try running your experiment again and see if an error message appears in this Output view
If you still don’t get an error message but the application still doesn’t start then manually turn off the viewing of
the Output (as below) and try the above again.
13.3 Manually turn off the viewing of output
Very occasionally an error will occur that crashes the application after the application has opened the Coder Output
window. In this case the error message is still not sent to the console or command prompt.
To turn off the Output view so that error messages are sent to the command prompt/terminal on startup, open your
appData.cfg file (see Cleaning preferences and app data), find the entry:
[coder]
showOutput =True
and set it to showOutput = False (note the capital ‘F’).
13.4 Use the source (Luke?)
PsychoPy comes with all the source code included. You may not think you’re much of a programmer, but have a go at
reading the code. You might find you understand more of it than you think!
To have a look at the source code do one of the following:
• when you get an error message in the Coder click on the hyperlinked error lines to see the relevant code
•on Windows
–go to Program FilesPsychoPy2Libsite-packagesPsychopy
–have a look at some of the files there
•on Mac
–right click the PscyhoPy app and select Show Package Contents
–navigate to Contents/Resources/lib/python2.6/psychopy
13.5 Cleaning preferences and app data
Every time you shut down PsychoPy (by normal means) your current preferences and the state of the application (the
location and state of the windows) are saved to disk. If PsychoPy is crashing during startup you may need to edit those
files or delete them completely.
74 Chapter 13. Troubleshooting
PsychoPy - Psychology software for Python, Release 1.78.00
On OS X and linux the files are:
~/.psychopy2/appData.cfg
~/.psychopy2/userPrefs.cfg
On windows they are:
${DOCS AND SETTINGS}\{USER}\Application Data\psychopy2\appData.cfg
${DOCS AND SETTINGS}\{USER}\Application Data\psychopy2\userPrefs.cfg
The files are simple text, which you should be able to edit in any text editor. Particular changes that you might need to
make:
If the problem is that you have a corrupt experiment file or script that is trying and failing to load on startup, you
could simply delete the appData.cfg file. Please also Contribute to the Forum (mailing list) a copy of the file that isn’t
working so that the underlying cause of the problem can be investigated (google first to see if it’s a known issue).
13.5. Cleaning preferences and app data 75
PsychoPy - Psychology software for Python, Release 1.78.00
76 Chapter 13. Troubleshooting
CHAPTER
FOURTEEN
RECIPES (“HOW-TO”S)
Below are various tips/tricks/recipes/how-tos for PsychoPy. They involve something that is a little more involved than
you would find in FAQs, but too specific for the manual as such (should they be there?).
14.1 Adding external modules to Standalone PsychoPy
You might find that you want to add some additional Python module/package to your Standalone version of PsychoPy.
To do this you need to:
• download a copy of the package (make sure it’s for Python 2.7 on your particular platform)
• unzip/open it into a folder
• add that folder to the path of PsychoPy by one of the methods below
Avoid adding the entire path (e.g. the site-packages folder) of separate installation of Python, because that may contain
conflicting copies of modules that PsychoPy is also providing.
14.1.1 Using preferences
As of version 1.70.00 you can do this using the PsychoPy preferences/general. There you will find preference for
paths which can be set to a list of strings e.g. ‘[’/Users/jwp/code’, ‘~/code/thirdParty’]
These only get added to the Python path when you import psychopy (or one of the psychopy packages) in your script.
14.1.2 Adding a .pth file
An alternative is to add a file into the site-packages folder of your application. This file should be pure text and have
the extenstion .pth to indicate to Python that it adds to the path.
On win32 the site-packages folder will be something like:
c:/Program Files/PsychoPy2/lib/site-packages
On OS X you need to right-click the application icon, select ‘Show Package Contents’ and then navigate down to
Contents/Resources/lib/python2.6. Put your .pth file here, next to the various libraries.
The advantage of this method is that you don’t need to do the import psychopy step. The downside is that when you
update PsychoPy to a new major release you’ll need to repeat this step (patch updates won’t affect it though).
77
PsychoPy - Psychology software for Python, Release 1.78.00
14.2 Animation
General question: How can I animate something?
Conceptually, animation just means that you vary some aspect of the stimulus over time. So the key idea is to draw
something slightly different on each frame. This is how movies work, and the same principle can be used to create
scrolling text, or fade-in / fade-out effects, and the like.
(copied & pasted from the email list; see the list for people’s names and a working script.)
14.3 Scrolling text
Key idea: Vary the position of the stimulus across frames.
Question: How can I produce scrolling text (like html’s <marquee behavior = “scroll” > directive)?
Answer: PsychoPy has animation capabilities built-in (it can even produce and export movies itself (e.g. if you want
to show your stimuli in presentations)). But here you just want to animate stimuli directly.
e.g. create a text stimulus. In the ‘pos’ (position) field, type:
[frameN, 0]
and select “set every frame” in the popup button next to that field.
Push the Run button and your text will move from left to right, at one pixel per screen refresh, but stay at a fixed
y-coordinate. In essence, you can enter an arbitrary formula in the position field and the stimulus will be-redrawn at a
new position on each frame. frameN here refers to the number of frames shown so far, and you can extend the formula
to produce what you need.
You might find performance issues (jittering motion) if you try to render a lot of text in one go, in which case you may
have to switch to using images of text.
I wanted my text to scroll from right to left. So if you keep your eyes in the middle of the screen the next word to read
would come from the right (as if you were actually reading text). The original formula posted above scrolls the other
way. So, you have to put a negative sign in front of the formula for it to scroll the other way. You have to change the
units to pixel. Also, you have to make sure you have an end time set, otherwise it just flickers. I also set my letter
height to 100 pixels. The other problem I had was that I wanted the text to start blank and scroll into the screen. So, I
wrote
[2000-frameN, 0]
and this worked really well.
14.4 Fade-in / fade-out effects
Key idea: vary the opacity of the stimulus over frames.
Question: I’d like to present an image with the image appearing progressively and disappearing progressively too.
How to do that?
Answer: The Patch stimulus has an opacity field. Set the button next to it to be “set every frame” so that its value can
be changed progressively, and enter an equation in the box that does what you want.
e.g. if your screen refresh rate is 60 Hz, then entering:
frameN/120
78 Chapter 14. Recipes (“How-to”s)
PsychoPy - Psychology software for Python, Release 1.78.00
would cycle the opacity linearly from 0 to 1.0 over 2s (it will then continue incrementing but it doesn’t seem to matter
if the value exceeds 1.0).
Using a code component might allow you to do more sophisticated things (e.g. fade in for a while, hold it, then fade
out). Or more simply, you just create multiple successive Patch stimulus components, each with a different equation
or value in the opacity field depending on their place in the timeline.
14.5 Building an application from your script
A lot of people ask how they can build a standalone application from their Python script. Usually this is because they
have a collaborator and want to just send them the experiment.
In general this is not advisable - the resulting bundle of files (single file on OS X) will be on the order of 100Mb
and will not provide the end user with any of the options that they might need to control the task (for example,
Monitor Center won’t be provided so they can’t to calibrate their monitor). A better approach in general is to get your
collaborator to install the Standalone PsychoPy on their own machine, open your script and press run. (You don’t send
a copy of Microsoft Word when you send someone a document - you expect the reader to install it themself and open
the document).
Nonetheless, it is technically possible to create exe files on windows, and Ricky Savjani (savjani at bcm.edu) has
kindly provided the following instructions for how to do it. A similar process might be possible on OS X using py2app
- if you’ve done that then feel free to contribute the necessary script or instructions
14.5.1 Using py2exe to build an executable
Instructions:
1. Download and install py2exe (http://www.py2exe.org/)
2. Develop your Psychopy script as normal
3. Copy this setup.py file into the same director as your script
4. Change the Name of progName variable in this file to the Name of your desired executable program name
5. use cmd (or bash, terminal, etc.) and run the following in the directory of your the two files: python
setup.py py2exe
6. Open the ‘dist’ directory and run your executable
A example setup.py script:
# Created 8-09-2011
# Ricky Savjani
# (savjani at bcm.edu)
#import necessary packages
from distutils.core import setup
import os,matplotlib
import py2exe
#the name of your .exe file
progName =’MultipleSchizophrenia.py’
#Initialize Holder Files
preference_files =[]
app_files =[]
my_data_files=matplotlib.get_py2exe_datafiles()
14.5. Building an application from your script 79
PsychoPy - Psychology software for Python, Release 1.78.00
#define which files you want to copy for data_files
for files in os.listdir(’C:\\Program Files\\PsychoPy2\\Lib\\site-packages\\PsychoPy-1.65.00-py2.6.egg\\psychopy\\preferences\\’):
f1 =’C:\\Program Files\\PsychoPy2\\Lib\\site-packages\\PsychoPy-1.65.00-py2.6.egg\\psychopy\\preferences\\’+files
preference_files.append(f1)
#if you might need to import the app files
#for files in os.listdir(’C:\\Program Files\\PsychoPy2\\Lib\\site-packages\\PsychoPy-1.65.00-py2.6.egg\\psychopy\\app\\’):
# f1 = ’C:\\Program Files\\PsychoPy2\\Lib\\site-packages\\PsychoPy-1.65.00-py2.6.egg\\psychopy\\app\\’ + files
# app_files.append(f1)
#all_files = [("psychopy\\preferences", preference_files),("psychopy\\app", app_files), my_data_files[0]]
#combine the files
all_files =[("psychopy\\preferences", preference_files), my_data_files[0]]
#define the setup
setup(
console=[progName],
data_files =all_files,
options ={
"py2exe":{
"skip_archive":True,
"optimize":2
}
}
)
14.6 Builder - providing feedback
If you’re using the Builder then the way to provide feedback is with a Code Component to generate an appropriate
message (and then a Text Component to present that message). PsychoPy will be keeping track of various aspects of
the stimuli and responses for you throughout the experiment and the key is knowing where to find those.
The following examples assume you have a Loop called trials, containing a Routine with a Keyboard Component
called key_resp. Obviously these need to be adapted in the code below to fit your experiment.
Note: The following generate strings use python ‘formatted strings’. These are very powerful and flexible but a little
strange when you aren’t used to them (they contain odd characters like %.2f). See Generating formatted strings for
more info.
14.6.1 Feedback after a trial
This is actually demonstrated in the demo, ExtendedStroop (in the Builder>demos menu, unpack the demos and then
look in the menu again. tada!)
If you have a Keyboard Component called key_resp then, after every trial you will have te folowing variables:
key_resp.keys #a python list of keys pressed
key_resp.rt #the time to the first key press
key_resp.corr #None, 0 or 1, if you are using ’store correct’
To create your msg, insert the following into the ‘start experiment‘ section of the Code Component:
80 Chapter 14. Recipes (“How-to”s)
PsychoPy - Psychology software for Python, Release 1.78.00
msg=’doh!’#if this comes up we forgot to update the msg!
and then insert the following into the Begin Routine section (this will get run every repeat of the routine):
if len(key_resp.keys)<1:
msg="Failed to respond"
elif resp.corr:#stored on last run routine
msg="Correct! RT=%.3f"%(resp.rt)
else:
msg="Oops! That was wrong"
14.6.2 Feedback after a block
In this case the feedback routine would need to come after the loop (the block of trials) and the message needs to use
the stored data from the loop rather than the key_resp directly. Accessing the data from a loop is not well documented
but totally possible.
In this case, to get all the keys pressed in a numpy array:
trials.data[’key_resp.keys’]#numpy array with size=[ntrials,ntypes]
If you used the ‘Store Correct’ feature of the Keyboard Component (and told psychopy what the correct answer was)
you will also have a variable:
#numpy array storing whether each response was correct (1) or not (0)
trials.data[’resp.corr’]
So, to create your msg, insert the following into the ‘start experiment‘ section of the Code Component:
msg=’doh!’#if this comes up we forgot to update the msg!
and then insert the following into the Begin Routine section (this will get run every repeat of the routine):
nCorr =trials.data[’key_resp.corr’].sum() #.std(), .mean() also available
meanRt =trials.data[’key_resp.rt’].mean()
msg ="You got %i trials correct (rt=%.2f)" %(nCorr,meanRt)
14.6.3 Draw your message to the screen
Using one of the above methods to generate you msg in a Code Component, you then need to present it to the participant
by adding a Text Component to your feedback Routine and setting its text to $msg.
Warning: The Text Component needs to be below the Code Component in the Routine (because it needs to be
updated after the code has been run) and it needs to set every repeat.
14.7 Builder - terminating a loop
People often want to terminate their Loops before they reach the designated number of trials based on subjects’
responses. For example, you might want to use a Loop to repeat a sequence of images that you want to continue until
a key is pressed, or use it to continue a training period, until a criterion performance is reached.
To do this you need a Code Component inserted into your routine. All loops have an attribute called finished which is
set to True or False (in Python these are really just other names for 1and 0). This finished property gets checked on
each pass through the loop. So the key piece of code to end a loop called trials is simply:
14.7. Builder - terminating a loop 81
PsychoPy - Psychology software for Python, Release 1.78.00
trials.finished=True #or trials.finished=1 if you prefer
Of course you need to check the condition for that with some form of if statement.
Example 1: You have a change-blindness study in which a pair of images flashes on and off, with intervening blanks,
in a loop called presentationLoop. You record the key press of the subject with a Keyboard Component called resp1.
Using the ‘ForceEndTrial’ parameter of resp1 you can end the current cycle of the loop but to end the loop itself you
would need a Code Component. Insert the following two lines in the End Routine parameter for the Code Component,
which will test whether more than zero keys have been pressed:
if len(resp1.keys)>0:
presentationLoop.finished=1
Example 2: Sometimes you may have more possible trials than you can actually display. By default, a loop will
present all possible trials (nReps * length-of-list). If you only want to present the first 10 of all possible trials, you can
use a code component to count how many have been shown, and then finish the loop after doing 10.
This example assumes that your loop is named ‘trials’. You need to add two things, the first to initialize the count, and
the second to update and check it.
Begin Experiment:
myCount =0
Begin Routine:
myCount =myCount +1
if myCount >10:
trials.finished =True
Note: In Python there is no end to finish an if statement. The content of the if or of a for-loop is determined by
the indentation of the lines. In the above example only one line was indented so that one line will be executed if the
statement evaluates to True.
14.8 Installing PsychoPy in a classroom (administrators)
For running PsychoPy in a classroom environment it is probably preferrable to have a ‘partial’ network installation.
The PsychoPy library features frequent new releases, including bug fixes and you want to be able to update machines
with these new releases. But PsychoPy depends on many other python libraries (over 200Mb in total) that tend not
to change so rapidly, or at least not in ways critical to the running of experiments. If you install the whole PsychoPy
application on the network then all of this data has to pass backwards and forwards, and starting the app will take even
longer than normal.
The basic aim of this document is to get to a state whereby;
• Python and the major dependencies of PsychoPy are installed on the local machine (probably a disk image to be
copied across your lab computers)
• PsychoPy itself (only ~2Mb) is installed in a network location where it can be updated easily by the administrator
• a file is created in the installation that provides the path to the network drive location
• Start-Menu shortcuts need to be set to point to the local Python but the remote PsychoPy application launcher
Once this is done, the vast majority of updates can be performed simply by replacing the PsychoPy library on the
network drive.
82 Chapter 14. Recipes (“How-to”s)
PsychoPy - Psychology software for Python, Release 1.78.00
14.8.1 1. Install dependencies locally
Download the lastest version of the Standalone PsychoPy distribution, and run as administrator. This will install a
copy of Python and many dependencies to a default location of
C:\Program Files\PsychoPy2\
14.8.2 2. Move the PsychoPy to the network
You need a network location that is going to be available, with read-only access, to all users on your machines. You
will find all the contents of PsychoPy itself at something like this (version dependent obviously):
C:\Program Files\PsychoPy2\Lib\site-packages\PsychoPy-1.70.00-py2.6.egg
Move that entire folder to your network location and call it psychopyLib (or similar, getting rid of the version-specific
part of the name). Now the following should be a valid path:
<NETWORK_LOC>\psychopyLib\psychopy
14.8.3 3. Update the Python path
The Python installation (in C:\Program Files\PsychoPy2) needs to know about the network location. If Python finds a
text file with extension .pth anywhere on its existing path then it will add to the path any valid paths it finds in the file.
So create a text file that has one line in it:
<NETWORK_LOC>\psychopyLib
You can test if this has worked. Go to C:\Program Files\PsychoPy2 and double-click on python.exe. You should get a
Python terminal window come up. Now try:
>>> import psychopy
If psychopy is not found on the path then there will be an import error. Try adjusting the .pth file, restarting python.exe
and importing again.
14.8.4 4. Update the Start Menu
The shortcut in the Windows Start Menu will still be pointing to the local (now non-existent) PsychoPy library. Right-
click it to change properties and set the shortcut to point to something like:
"C:\Program Files\PsychoPy2\pythonw.exe" "<NETWORK_LOC>\psychopyLib\psychopy\\app\psychopyApp.py"
You probably spotted from this that the PsychoPy app is simply a Python script. You may want to update the file
associations too, so that .psyexp and .py are opened with:
"C:\Program Files\PsychoPy2\pythonw.exe" "<NETWORK_LOC>\psychopyLib\psychopy\app\psychopyApp.py" "%1"
Lastly, to make the shortcut look pretty, you might want to update the icon too. Set the icon’s location to:
"<NETWORK_LOC>\psychopyLib\psychopy\app\Resources\psychopy.ico"
14.8.5 5. Updating to a new version
Fetch the latest .zip release. Unpack it and replace the contents of <NETWORK_LOC>\psychopyLib\ with the contents
of the zip file.
14.8. Installing PsychoPy in a classroom (administrators) 83
PsychoPy - Psychology software for Python, Release 1.78.00
14.9 Generating formatted strings
A formatted string is a variable which has been converted into a string (text). In python the specifics of how this is
done is determined by what kind of variable you want to print.
Example 1: You have an experiment which generates a string variable called text. You want to insert insert this variable
into a string so you can print it. This would be achieved with the following code:
message =’The result is %s’%(text)
This will produce a variable message which if used in a text object would print the phrase ‘The result is’ followed by
the variable text. In this instance %s is used as the variable being entered is a string. This is a marker which tells the
script where the variable should be entered. %text tells the script which variable should be entered there.
Multiple formatted strings (of potentially different types) can be entered into one string object:
longMessage =’Well done %s that took %0.3f seconds’ %(info[’name’], time)
Some of the handy formatted string types:
>>> x=5
>>> x1=5124
>>> z=’someText’
>>> ’show %s’%(z)
’show someText’
>>> ’%0.1f’%(x) #will show as a float to one decimal place
’5.0’
>>> ’%3i’%(x) #an integer, at least 3 chars wide, padded with spaces
’ 5’
>>> ’%03i’%(x) #as above but pad with zeros (good for participant numbers)
’005’
See the python documentation for a more complete list.
14.10 Coder - interleave staircases
Often psychophysicists using staircase procedures want to interleave multiple staircases, either with different start
points, or for different conditions.
There is now a class, psychopy.data.MultiStairHandler to allow simple access to interleaved staircases of
either basic or QUEST types. That can also be used from the Loops in the Builder. The following method allows the
same to be created in your own code, for greater options.
The method works by nesting a pair of loops, one to loop through the number of trials and another to loop across the
staircases. The staircases can be shuffled between trials, so that they do not simply alternate.
Note: Note the need to create a copy of the info. If you simply do thisInfo=info then all your staircases will end up
pointing to the same object, and when you change the info in the final one, you will be changing it for all.
from psychopy import visual, core, data, event
from numpy.random import shuffle
import copy,time #from the std python libs
#create some info to store with the data
info={}
info[’startPoints’]=[1.5,3,6]
84 Chapter 14. Recipes (“How-to”s)
PsychoPy - Psychology software for Python, Release 1.78.00
info[’nTrials’]=10
info[’observer’]=’jwp’
win=visual.Window([400,400])
#---------------------
#create the stimuli
#---------------------
#create staircases
stairs=[]
for thisStart in info[’startPoints’]:
#we need a COPY of the info for each staircase
#(or the changes here will be made to all the other staircases)
thisInfo =copy.copy(info)
#now add any specific info for this staircase
thisInfo[’thisStart’]=thisStart #we might want to keep track of this
thisStair =data.StairHandler(startVal=thisStart,
extraInfo=thisInfo,
nTrials=50, nUp=1, nDown=3,
minVal =0.5, maxVal=8,
stepSizes=[4,4,2,2,1,1])
stairs.append(thisStair)
for trialN in range(info[’nTrials’]):
shuffle(stairs) #this shuffles ’in place’ (ie stairs itself is changed, nothing returned)
#then loop through our randomised order of staircases for this repeat
for thisStair in stairs:
thisIntensity =thisStair.next()
print ’start=%.2f, current=%.4f’%(thisStair.extraInfo[’thisStart’], thisIntensity)
#---------------------
#run your trial and get an input
#---------------------
keys =event.waitKeys() #(we can simulate by pushing left for ’correct’)
if ’left’ in keys: wasCorrect=True
else: wasCorrect =False
thisStair.addData(wasCorrect) #so that the staircase adjusts itself
#this trial (of all staircases) has finished
#all trials finished
#save data (separate pickle and txt files for each staircase)
dateStr =time.strftime("%b_%d_%H%M", time.localtime())#add the current time
for thisStair in stairs:
#create a filename based on the subject and start value
filename ="%s start%.2f %s"%(thisStair.extraInfo[’observer’], thisStair.extraInfo[’thisStart’], dateStr)
thisStair.saveAsPickle(filename)
thisStair.saveAsText(filename)
14.11 Making isoluminant stimuli
From the mailing list (see there for names, etc):
Q1: How can I create colours (RGB) that are isoluminant?
A1: The easiest way to create isoluminant stimuli (or control the luminance content) is to create the stimuli in DKL
14.11. Making isoluminant stimuli 85
PsychoPy - Psychology software for Python, Release 1.78.00
space and then convert them into RGB space for presentation on the monitor.
More details on DKL space can be found here: http://www.psychopy.org/general/colours.html and conversions be-
tween DKL and RGB can be found here: http://www.psychopy.org/api/misc.html
Q2. There’s a difference in luminance between my stimuli. How could I correct for that?
I’m running an experiment where I manipulate color chromatic saturation, keeping luminance constant. I’ve coded the
colors (red and blue) in rgb255 for 6 saturation values (10%, 20%, 3?%, 40%, 50%, 60%, 90%) using a conversion
from HSL to RGB color space.
Note that we don’t possess spectrophotometers such as PR650 in our lab to calibrate each color gun. I’ve calibrated the
gamma of my monitor psychophysically. Gamma was set to 1.7 (threshold) for gamm(lum), gamma(R), gamma(G),
gamma(B). Then I’ve measured the luminance of each stimuli with a Brontes colorimeter. But there’s a difference in
luminance between my stimuli. How could I correct for that?
A2. Without a spectroradiometer you won’t be able to use the color spaces like DKL which are designed to help this
sort of thing.
If you don’t care about using a specific colour space though you should be able to deduce a series of isoluminant colors
manually, because the luminance outputs from each gun should sum linearly. e.g. on my monitor:
maxR=46cd/m2
maxG=114
maxB=15
(note that green is nearly always brightest)
So I could make a 15cd/m2 stimulus using various appropriate fractions of those max values (requires that the screen
is genuinely gamma-corrected):
R=0, G=0, B=255
R=255*15/46, G=0, B=0
R=255*7.5/46, G=255*15/114, B=0
Note that, if you want a pure fully-saturated blue, then you’re limited by the monitor to how bright you can make your
stimulus. If you want brighter colours your blue will need to include some of the other guns (similarly for green if you
want to go above the max luminance for that gun).
A2.1. You should also consider that even if you set appropriate RGB values to display your pairs of chromatic stimuli
at the same luminance that they might still appear different, particularly between observers (and even if your light
measurement device says the luminance is the same, and regardless of the colour space you want to work in). To make
the pairs perceptually isoluminant, each observer should really determine their own isoluminant point. You can do this
with the minimum motion technique or with heterochromatic flicker photometry.
14.12 Adding a web-cam
From the mailing list (see there for names, etc):
“I spent some time today trying to get a webcam feed into my psychopy proj, inside my visual.window. The solution
involved using the opencv module, capturing the image, converting that to PIL, and then feeding the PIL into a
SimpleImageStim and looping and win.flipping. Also, to avoid looking like an Avatar in my case, you will have to
change the default decoder used in PIL fromstring to utilize BGR instead of RGB in the decoding. I thought I would
save some time for people in the future who might be interested in using a webcam feed for their psychopy project.
All you need to do is import the opencv module into psychopy (importing modules was well documented by psychopy
online) and integrate something like this into your psychopy script.”
86 Chapter 14. Recipes (“How-to”s)
PsychoPy - Psychology software for Python, Release 1.78.00
from psychopy import visual, event, core
import Image,time,pylab,cv,numpy
mywin =visual.Window(allowGUI=False, monitor=’testMonitor’, units=’norm’,colorSpace=’rgb’,color=[-1,-1,-1], fullscr=True)
mywin.setMouseVisible(False)
capture =cv.CaptureFromCAM(0)
img =cv.QueryFrame(capture)
pi =Image.fromstring("RGB", cv.GetSize(img), img.tostring(), "raw","BGR",0,1)
print pi.size
myStim =visual.PatchStim(win=mywin, tex=pi, pos=[0,0.5], size =[0.6,0.6], opacity =1.0, units =’norm’)
myStim.setAutoDraw(True)
while True:
img =cv.QueryFrame(capture)
pi =Image.fromstring("RGB", cv.GetSize(img), img.tostring(), "raw","BGR",0,1)
myStim.setTex(pi)
mywin.flip()
theKey =event.getKeys()
if len(theKey) != 0:
break
14.12. Adding a web-cam 87
PsychoPy - Psychology software for Python, Release 1.78.00
88 Chapter 14. Recipes (“How-to”s)
CHAPTER
FIFTEEN
FREQUENTLY ASKED QUESTIONS
(FAQS)
15.1 Why is the bits++ demo not working?
So far PsychoPy supports bits++ only in the bits++ mode (rather than mono++ or color++). In this mode, a code (the
T-lock code) is written to the lookup table on the bits++ device by drawing a line at the top of the window. The most
likely reason that the demo isn’t working for you is that this line is not being detected by the device, and so the lookup
table is not being modified. Most of these problems are actually nothing to do with PsychoPy /per se/, but to do with
your graphics card and the CRS bits++ box itself.
There are a number of reasons why the T-lock code is not being recognised:
• the bits++ device is in the wrong mode. Open the utility that CRS supply and make sure you’re in the right
mode. Try resetting the bits++ (turn it off and on).
• the T-lock code is not fully on the screen. If you create a window that’s too big for the screen or badly positioned
then the code will be broken/not visible to the device.
• the T-lock code is on an ‘odd’ pixel.
• the graphics card is doing some additional filtering (win32). Make sure you turn off any filtering in the advanced
display properties for your graphics card
• the gamma table of the graphics card is not set to be linear (but this should normally be handled by PsychoPy,
so don’t worry so much about it).
• you’ve got a Mac that’s performing temporal dithering (new macs, around 2009). Apple have come up with a
new, very annoying idea, where they continously vary the pixel values coming out of the graphics card every
frame to create additional intermediate colours. This will break the T-lock code on 1/2-2/3rds of frames.
15.2 Can PsychoPy run my experiment with sub-millisecond timing?
This question is common enough and complex enough to have a section of the manual all of its own. See Timing Issues
and synchronisation
89
PsychoPy - Psychology software for Python, Release 1.78.00
90 Chapter 15. Frequently Asked Questions (FAQs)
CHAPTER
SIXTEEN
RESOURCES (E.G. FOR TEACHING)
There are a number of further resources to help learn/teach about PsychoPy.
16.1 P4N
There will be a 3-day workshop in April 2014 at Nottingham University, taught by Jon Peirce. It won’t be only about
PsychoPy, but about Python for science more generally and focussing on coding rather than using the Builder interface.
You can see further information here
16.2 Youtube tutorials
There is now a youtube PsychoPy tutorial showing how to build a basic experiment in the Builder interface. That’s a
great way to get started; build your own complete experiment in 15 minutes flat!
There’s also a subtitled version of the stroop video tutorial (Thanks Kevin Cole for doing that!)
16.3 Lecture materials (Builder)
At School of Psychology, University of Nottingham, PsychoPy is now used for all first year practical class teaching.
The classes that comprise that first year course are provided below. They were created partially with funding from the
former Higher Education Academy Psychology Network. Note that the materials here will be updated frequently as
they are further developed (e.g. to update screenshots etc) so make sure you have the latest version of them!
PsychoPy_pracs_2011v2.zip (21MB) (last updated: 15 Dec 2011)
The GestaltReVision group (Leuven) wiki covering PsychoPy (some Builder info and a great tutorial for
Python/PsychoPy coding of experiments).
If you also use PsychoPy for your lectures then please let us know so that we can link to your materials/course from
here too!
16.4 Lecture materials (Coder)
Gary Lupyan runs a class on programming experiments using Python/PsychoPy and makes his lecture materials avail-
able on this wiki
91
PsychoPy - Psychology software for Python, Release 1.78.00
Also the GestaltReVision group (Leuven) wiki has lots of great information taking you from basic programming to
advanced techniques.
16.5 Previous events
•VSS
•Yale, 21-23 July : The first ever dedicated PsychoPy workshop/conference was at Yale, 21-23 July 2011. Thanks
Jeremy for organising!
• EPS Satellite workshop, 8 July 2011
•BPS Maths Stats and Computing Section workshop (Dec 2010):
92 Chapter 16. Resources (e.g. for teaching)
CHAPTER
SEVENTEEN
REFERENCE MANUAL (API)
Contents:
17.1 psychopy.core - basic functions (clocks etc.)
Basic functions, including timing, rush (imported), quit
psychopy.core.getTime()
Get the current time since psychopy.core was loaded.
Version Notes: Note that prior to PsychoPy 1.77.00 the behaviour of getTime() was platform dependent (on OSX
and linux it was equivalent to psychopy.core.getAbsTime() whereas on windows it returned time since
loading of the module, as now)
psychopy.core.getAbsTime()
Return unix time (i.e., whole seconds elapsed since Jan 1, 1970).
This uses the same clock-base as the other timing features, like getTime(). The time (in seconds) ignores the
time-zone (like time.time() on linux). To take the timezone into account, use int(time.mktime(time.gmtime())).
Absolute times in seconds are especially useful to add to generated file names for being unique, informative (=
a meaningful time stamp), and because the resulting files will always sort as expected when sorted in chrono-
logical, alphabetical, or numerical order, regardless of locale and so on.
Version Notes: This method was added in PsychoPy 1.77.00
psychopy.core.wait(secs,hogCPUperiod=0.2)
Wait for a given time period.
If secs=10 and hogCPU=0.2 then for 9.8s python’s time.sleep function will be used, which is not especially
precise, but allows the cpu to perform housekeeping. In the final hogCPUperiod the more precise method of
constantly polling the clock is used for greater precision.
If you want to obtain key-presses during the wait, be sure to use pyglet and to hogCPU for the entire time, and
then call psychopy.event.getKeys() after calling wait()
If you want to suppress checking for pyglet events during the wait, do this once::
core.checkPygletDuringWait = False
and from then on you can do:: core.wait(sec)
This will preserve terminal-window focus during command line usage.
class psychopy.core.Clock
A convenient class to keep track of time in your experiments. You can have as many independent clocks as you
like (e.g. one to time responses, one to keep track of stimuli...)
93
PsychoPy - Psychology software for Python, Release 1.78.00
This clock is identical to the MonotonicClock except that it can also be reset to 0 or another value at any
point.
add(t)
Add more time to the clock’s ‘start’ time (t0).
Note that, by adding time to t0, you make the current time appear less. Can have the effect that getTime()
returns a negative number that will gradually count back up to zero.
e.g.:
timer = core.Clock()
timer.add(5)
while timer.getTime()<0:
#do something
reset(newT=0.0)
Reset the time on the clock. With no args time will be set to zero. If a float is received this will be the new
time on the clock
class psychopy.core.CountdownTimer(start=0)
Similar to a Clock except that time counts down from the time of last reset
Typical usage:
timer = core.CountdownTimer(5)
while timer.getTime() > 0: # after 5s will become negative
#do stuff
getTime()
Returns the current time left on this timer in secs (sub-ms precision)
class psychopy.core.MonotonicClock(start_time=None)
A convenient class to keep track of time in your experiments using a sub-millisecond timer.
Unlike the Clock this cannot be reset to arbitrary times. For this clock t=0 always represents the time that the
clock was created.
Don’t confuse this class with core.monotonicClock which is an instance of it that got created when Psy-
choPy.core was imported. That clock instance is deliberately designed always to return the time since the
start of the study.
Version Notes: This class was added in PsychoPy 1.77.00
getLastResetTime()
Returns the current offset being applied to the high resolution timebase used by Clock.
getTime()
Returns the current time on this clock in secs (sub-ms precision)
class psychopy.core.StaticPeriod(screenHz=None,win=None,name=’StaticPeriod’)
A class to help insert a timing period that includes code to be run.
Typical usage:
fixation.draw()
win.flip()
ISI =StaticPeriod(screenHz=60)
ISI.start(0.5)#start a period of 0.5s
stim.setImage(’largeFile.bmp’)#could take some time
ISI.complete() #finish the 0.5s, taking into account one 60Hz frame
stim.draw()
94 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
win.flip() #the period takes into account the next frame flip
#time should now be at exactly 0.5s later than when ISI.start() was called
Parameters
•screenHz – the frame rate of the monitor (leave as None if you don’t want this accounted
for)
•name – if a visual.Window is given then StaticPeriod will also pause/restart frame interval
recording
•name – give this StaticPeriod a name for more informative logging messages
complete()
Completes the period, using up whatever time is remaining with a call to wait()
Returns 1 for success, 0 for fail (the period overran)
start(duration)
Start the period. If this is called a second time, the timer will be reset and starts again
17.2 psychopy.visual - many visual stimuli
To control the screen and visual stimuli for experiments
17.2.1 Window
class psychopy.visual.Window(size=(800,600),pos=None,color=(0,0,0),colorSpace=’rgb’,
rgb=None,dkl=None,lms=None,fullscr=None,allowGUI=None,
monitor={},bitsMode=None,winType=None,units=None,
gamma=None,blendMode=’avg’,screen=0,viewScale=None,view-
Pos=None,viewOri=0.0,waitBlanking=True,allowStencil=False,
stereo=False,name=’window1’)
Used to set up a context in which to draw objects, using either PyGame (python’s SDL binding) or pyglet.
The pyglet backend allows multiple windows to be created, allows the user to specify which screen to use (if
more than one is available, duh!) and allows movies to be rendered.
Pygame has fewer bells and whistles, but does seem a little faster in text rendering. Pygame is used for all sound
production and for monitoring the joystick.
Parameters
size [(800,600)] Size of the window in pixels (X,Y)
pos [None or (x,y)] Location of the window on the screen
rgb [[0,0,0]] Color of background as [r,g,b] list or single value. Each gun can take values
betweeen -1 and 1
fullscr [None, True or False] Better timing can be achieved in full-screen mode
allowGUI [None, True or False (if None prefs are used)] If set to False, window will be drawn
with no frame and no buttons to close etc...
winType [None, ‘pyglet’, ‘pygame’] If None then PsychoPy will revert to user/site preferences
monitor [None, string or a ~psychopy.monitors.Monitor object] The monitor to be used during
the experiment
17.2. psychopy.visual - many visual stimuli 95
PsychoPy - Psychology software for Python, Release 1.78.00
units [None, ‘height’ (of the window), ‘norm’ (normalised),’deg’,’cm’,’pix’] Defines the default
units of stimuli drawn in the window (can be overridden by each stimulus) See Units for the
window and stimuli for explanation of options.
screen [0, 1 (or higher if you have many screens)] Specifies the physical screen that stimuli will
appear on (pyglet winType only)
viewScale [None or [x,y]] Can be used to apply a custom scaling to the current units of the
Window.
viewPos [None, or [x,y]] If not None, redefines the origin for the window
viewOri [0or any numeric value] A single value determining the orientation of the view in degs
waitBlanking [None, True or False.] After a call to flip() should we wait for the blank before
the script continues
gamma : Monitor gamma for linearisation (will use Bits++ if possible). Overrides monitor
settings
bitsMode [None, ‘fast’, (‘slow’ mode is deprecated).] Defines how (and if) the Bits++ box will
be used. ‘fast’ updates every frame by drawing a hidden line on the top of the screen.
allowStencil [True or False] When set to True, this allows operations that use the OpenGL
stencil buffer (notably, allowing the class:~psychopy.visual.Aperture to be used).
stereo [True or False] If True and your graphics card supports quad buffers then this will be
enabled. You can switch between left and right-eye scenes for drawing operations using
setBuffer()
note Preferences. Some parameters (e.g. units) can now be given default values in the
user/site preferences and these will be used if None is given here. If you do specify a
value here it will take precedence over preferences.
callOnFlip(function,*args,**kwargs)
Call a function immediately after the next .flip() command.
The first argument should be the function to call, the following args should be used exactly as you would
for your normal call to the function (can use ordered arguments or keyword arguments as normal).
e.g. If you have a function that you would normally call like this:
pingMyDevice(portToPing, channel=2, level=0)
then you could call callOnFlip() to have the function call synchronized with the frame flip like this:
win.callOnFlip(pingMyDevice, portToPing, channel=2, level=0)
clearBuffer()
Clear the back buffer (to which you are currently drawing) without flipping the window. Useful if you
want to generate movie sequences from the back buffer without actually taking the time to flip the window.
close()
Close the window (and reset the Bits++ if necess).
flip(clearBuffer=True)
Flip the front and back buffers after drawing everything for your frame. (This replaces the win.update()
method, better reflecting what is happening underneath).
win.flip(clearBuffer=True)#results in a clear screen after flipping win.flip(clearBuffer=False)#the screen
is not cleared (so represent the previous screen)
96 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
fps()
Report the frames per second since the last call to this function (or since the window was created if this is
first call)
getMovieFrame(buffer=’front’)
Capture the current Window as an image. This can be done at any time (usually after a .flip() command).
Frames are stored in memory until a .saveMovieFrames(filename) command is issued. You can issue
getMovieFrame() as often as you like and then save them all in one go when finished.
The back buffer will return the frame that hasn’t yet been ‘flipped’ to be visible on screen but has the
advantage that the mouse and any other overlapping windows won’t get in the way. The default front
buffer is to be called immediately after a win.flip() and gives a complete copy of the screen at the window’s
coordinates.
logOnFlip(msg,level,obj=None)
Send a log message that should be time-stamped at the next .flip() command.
Parameters
• msg: the message to be logged
• level: the level of importance for the message
•obj (optional): the python object that might be associated with this message if
desired
saveFrameIntervals(fileName=None,clear=True)
Save recorded screen frame intervals to disk, as comma-separated values.
Parameters
fileName [None or the filename (including path if necessary) in which to store the data.] If None then
‘lastFrameIntervals.log’ will be used.
saveMovieFrames(fileName,mpgCodec=’mpeg1video’,fps=30,clearFrames=True)
Writes any captured frames to disk. Will write any format that is understood by PIL (tif, jpg, bmp, png...)
Parameters
filename: name of file, including path (required) The extension at the end of the file de-
termines the type of file(s) created. If an image type (e.g. .png) is given, then multiple
static frames are created. If it is .gif then an animated GIF image is created (although
you will get higher quality GIF by saving PNG files and then combining them in dedi-
cated image manipulation software, such as GIMP). On Windows and Linux .mpeg files
can be created if pymedia is installed. On OS X .mov files can be created if the pyobjc-
frameworks-QTKit is installed.
Unfortunately the libs used for movie generation can be flaky and poor quality. As for
animated GIFs, better results can be achieved by saving as individual .png frames and then
combining them into a movie using software like ffmpeg.
mpgCodec: the code to be used by pymedia if the filename ends in .mpg
fps: the frame rate to be used throughout the movie only for quicktime (.mov) movies
clearFrames: set this to False if you want the frames to be kept for additional calls to
saveMovieFrames
Examples:
17.2. psychopy.visual - many visual stimuli 97
PsychoPy - Psychology software for Python, Release 1.78.00
myWin.saveMovieFrames(’frame.tif’)#writes a series of static frames as frame001.tif, frame002.tif etc...
myWin.saveMovieFrames(’stimuli.mov’, fps=25)#on OS X only
myWin.saveMovieFrames(’stimuli.gif’)#not great quality animated gif
myWin.saveMovieFrames(’stimuli.mpg’)#not on OS X
setBuffer(buffer,clear=True)
Choose which buffer to draw to (‘left’ or ‘right’).
Requires the Window to be initialised with stereo=True and requires a graphics card that supports quad
buffering (e,g nVidia Quadro series)
PsychoPy always draws to the back buffers, so ‘left’ will use GL_BACK_LEFT This then needs to be
flipped once both eye’s buffers have been rendered.
Typical usage:
win = visual.Window(...., stereo=True)
while True:
win.setBuffer(’left’,clear=True) #clear may not actually be needed
#do drawing for left eye
win.setBuffer(’right’, clear=True)
#do drawing for right eye
win.flip()
setColor(color,colorSpace=None,operation=’‘)
Set the color of the window.
NB This command sets the color that the blank screen will have on the next clear operation. As a result it
effectively takes TWO flip() operations to become visible (the first uses the color to create the new screen,
the second presents that screen to the viewer).
See Color spaces for further information about the ways to specify colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.
myStim.setColor([1.0,-1.0,-1.0], ‘rgb’)#a red color in rgb space myS-
tim.setColor([0.0,45.0,1.0], ‘dkl’) #DKL space with elev=0, azimuth=45 myS-
tim.setColor([0,0,255], ‘rgb255’) #a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].
myStim.setColor(255, ‘rgb255’) #all guns o max
colorSpace : string or None
98 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1, ‘rgb’, ‘*’) #multiply the color by -1 (which in this space in-
verts the contrast) thisStim.setColor([10,0,0], ‘dkl’, ‘+’)#raise the elevation from the
isoluminant plane by 10 deg
setGamma(gamma)
Set the monitor gamma, using Bits++ if possible
setMouseVisible(visibility)
Sets the visibility of the mouse cursor.
If Window was initilised with noGUI=True then the mouse is initially set to invisible, otherwise it will
initially be visible.
Usage: setMouseVisible(False) setMouseVisible(True)
setRGB(newRGB)
Deprecated: As of v1.61.00 please use setColor() instead
setRecordFrameIntervals(value=True)
To provide accurate measures of frame intervals, to determine whether frames are being dropped. The
intervals are the times between calls to .flip(). Set to True only during the time-critical parts of the script.
Set this to False while the screen is not being updated, i.e., during any slow, non-frame-time-critical
sections of your code, including inter-trial-intervals, event.waitkeys(),core.wait(), or image.setImage().
see also: Window.saveFrameIntervals()
setScale(units,font=’dummyFont’,prevScale=(1.0,1.0))
This method is called from within the draw routine and sets the scale of the OpenGL context to map
between units. Could potentially be called by the user in order to draw OpenGl objects manually in each
frame.
The units can be ‘height’ (multiples of window height), ‘norm’(normalised), ‘pix’(pixels), ‘cm’ or
‘stroke_font’. The font parameter is only used if units=’stroke_font’
17.2.2 Aperture
class psychopy.visual.Aperture(win,size,pos=(0,0),ori=0,nVert=120,shape=’circle’,
units=None,name=’‘,autoLog=True)
Restrict a stimulus visibility area to a basic shape (circle, square, triangle)
When enabled, any drawing commands will only operate on pixels within the Aperture. Once disabled, subse-
quent draw operations affect the whole screen as usual.
See demos/stimuli/aperture.py for example usage
Author 2011, Yuri Spitsyn 2011, Jon Peirce added units options, Jeremy Gray added shape &
orientation
disable()
Disable the Aperture. Any subsequent drawing operations will not be affected by the aperture until re-
enabled.
17.2. psychopy.visual - many visual stimuli 99
PsychoPy - Psychology software for Python, Release 1.78.00
enable()
Enable the aperture so that it is used in future drawing operations
NB. The Aperture is enabled by default, when created.
setOri(ori,needReset=True,log=True)
Set the orientation of the Aperture
setPos(pos,needReset=True,log=True)
Set the pos (centre) of the Aperture
setSize(size,needReset=True,log=True)
Set the size (diameter) of the Aperture
17.2.3 BufferImageStim
class psychopy.visual.BufferImageStim(win,buffer=’back’,rect=(-1,1,1,-1),sqPower2=False,
stim=(),interpolate=True,flipHoriz=False,
flipVert=False,mask=’None’,pos=(0,0),name=’‘,
autoLog=True)
Take a “screen-shot” (full or partial), save to a ImageStim()-like RBGA object.
The class returns a screen-shot, i.e., a single collage image composed of static elements, ones that you want to
treat as effectively a single stimulus. The screen-shot can be of the visible screen (front buffer) or hidden (back
buffer).
BufferImageStim aims to provide fast rendering, while still allowing dynamic orientation, position, and opacity.
Its fast to draw but slow to init (like ImageStim). There is no support for dynamic depth.
You specify the part of the screen to capture (in norm units), and optionally the stimuli themselves (as a list of
items to be drawn). You get a screenshot of those pixels. If your OpenGL does not support arbitrary sizes, the
image will be larger, using square powers of two if needed, with the excess image being invisible (using alpha).
The aim is to preserve the buffer contents as rendered.
Checks for OpenGL 2.1+, or uses square-power-of-2 images.
Status: seems to work on Mac, but limitations: - Screen units are not properly sorted out, would be better to
allow pix too - Not tested on Windows, Linux, FreeBSD
Example:
# define lots of stimuli, make a list:
mySimpleImageStim = ...
myTextStim = ...
stimList = [mySimpleImageStim, myTextStim]
# draw stim list items & capture (slow; see EXP log for time required):
screenshot = visual.BufferImageStim(myWin, stim=stimList)
# render to screen (very fast, except for the first draw):
while <conditions>:
screenshot.draw() # fast; can vary .ori, ._position, .opacity
other_stuff.draw() # dynamic
myWin.flip()
See coder Demos > stimuli > bufferImageStim.py for a demo, with timing stats.
Author
• 2010 Jeremy Gray
100 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Parameters
win : AWindow object (required)
buffer : the screen buffer to capture from, default is ‘back’ (hidden). ‘front’ is the buffer in
view after win.flip()
rect : a list of edges [left, top, right, bottom] defining a screen rectangle which is the area to
capture from the screen, given in norm units. default is fullscreen: [-1, 1, 1, -1]
stim : a list of item(s) to be drawn to the back buffer (in order). The back buffer is first cleared
(without the win being flip()ed), then stim items are drawn, and finally the buffer (or part of
it) is captured. Each item needs to have its own .draw() method, and have the same window
as win.
interpolate : whether to use interpolation (default = True, generally good, especially if you
change the orientation)
sqPower2 :
• False (default) = use rect for size if OpenGL = 2.1+
• True = use square, power-of-two image sizes
flipHoriz : horizontally flip (mirror) the captured image, default = False
flipVert : vertically flip (mirror) the captured image; default = False
name [string] The name of the object to be using in log messages about this stim
draw(win=None)
Draws the BufferImage on the screen, similar to ImageStim .draw(). Allows dynamic position, size, ro-
tation, mirroring, and opacity. Limitations / bugs: not sure what happens with shaders & self._updateList()
setFlipHoriz(newVal=True,log=True)
If set to True then the image will be flipped horiztonally (left-to-right). Note that this is relative to the
original image, not relative to the current state.
setFlipVert(newVal=True,log=True)
If set to True then the image will be flipped vertically (top-to-bottom). Note that this is relative to the
original image, not relative to the current state.
setTex(tex,interpolate=True,log=True)
(This is not typically called directly.)
17.2.4 Circle
class psychopy.visual.Circle(win,radius=0.5,edges=32,**kwargs)
Creates a Circle with a given radius as a special case of a ShapeStim
(New in version 1.72.00)
Circle accepts all input parameters that ~psychopy.visual.ShapeStim accept, except for vertices and closeShape.
Parameters
win : AWindow object (required)
edges [float or int (default=32)] Specifies the resolution of the polygon that is approximating
the circle.
radius [float, int, tuple, list or 2x1 array] Radius of the Circle (distance from the center to
the corners). If radius is a 2-tuple or list, the values will be interpreted as semi-major and
semi-minor radii of an ellipse.
17.2. psychopy.visual - many visual stimuli 101
PsychoPy - Psychology software for Python, Release 1.78.00
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘)
For ShapeStim use setLineColor() or setFillColor()
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
102 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setEdges(edges)
Set the number of edges to a new value
setFillColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape fill. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
Note that shapes where some vertices point inwards will usually not ‘fill’ correctly.
setFillRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setFillColor()
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setLineColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape edge. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
setLineRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setLineColor()
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setRadius(radius,log=True)
Changes the radius of the Polygon. If radius is a 2-tuple or list, the values will be interpreted as semi-major
and semi-minor radii of an ellipse.
setSize(value,operation=’‘,log=True)
Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s
vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
setVertices(value=None,operation=’‘,log=True)
Set the xy values of the vertices (relative to the centre of the field). Values should be:
•an array/list of Nx2 coordinates.
17.2. psychopy.visual - many visual stimuli 103
PsychoPy - Psychology software for Python, Release 1.78.00
17.2.5 CustomMouse
class psychopy.visual.CustomMouse(win,newPos=None,visible=True,leftLimit=None,
topLimit=None,rightLimit=None,bottomLimit=None,
showLimitBox=False,clickOnUp=False,pointer=None)
Class for more control over the mouse, including the pointer graphic and bounding box.
Seems to work with pyglet or pygame. Not completely tested.
Known limitations: - only norm units are working - getRel() always returns [0,0] - mouseMoved() is always
False; maybe due to self.mouse.visible == False -> held at [0,0] - no idea if clickReset() works
Author: Jeremy Gray, 2011
Class for customizing the appearance and behavior of the mouse.
Use a custom mouse for extra control over the pointer appearance and function. Its probably slower to render
than the regular system mouse. Create your visual.Window before creating a CustomMouse.
Parameters
win [required, visual.Window] the window to which this mouse is attached
visible [True or False] makes the mouse invisbile if necessary
newPos [None or [x,y]] gives the mouse a particular starting position (pygame or pyglet)
leftLimit : left edge of a virtual box within which the mouse can move
topLimit : top edge of virtual box
rightLimit : right edge of virtual box
bottomLimit : lower edge of virtual box
showLimitBox [default is False] display the boundary of the area within which the mouse can
move.
pointer : The visual display item to use as the pointer; must have .draw() and setPos() methods.
If your item has .setOpacity(), you can alter the mouse’s opacity.
clickOnUp [when to count a mouse click as having occured] default is False, record a click
when the mouse is first pressed down. True means record a click when the mouse button is
released.
Note CustomMouse is a new feature, and subject to change. setPos() does not work yet. getRel()
returns [0,0] and mouseMoved() always returns False.clickReset() may not be working.
draw()
Draw mouse (if its visible), show the limit box, update the click count.
getClicks()
Return the number of clicks since the last reset
getPos()
Returns the mouse’s current position. Influenced by changes in .getRel(), constrained to be in its virtual
box.
getVisible()
Return the mouse’s visibility state
resetClicks()
Set click count to zero
setLimit(leftLimit=None,topLimit=None,rightLimit=None,bottomLimit=None)
Set the mouse’s bounding box by specifying the edges.
104 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
setPointer(pointer)
Set the visual item to be drawn as the mouse pointer.
setPos(pos)
Not implemented yet. Place the mouse at a specific position.
setVisible(visible)
Make the mouse visible or not (pyglet or pygame).
17.2.6 DotStim
class psychopy.visual.DotStim(win,units=’‘,nDots=1,coherence=0.5,fieldPos=(0.0,0.0),field-
Size=(1.0,1.0),fieldShape=’sqr’,dotSize=2.0,dotLife=3,dir=0.0,
speed=0.5,rgb=None,color=(1.0,1.0,1.0),colorSpace=’rgb’,opac-
ity=1.0,contrast=1.0,depth=0,element=None,signalDots=’same’,
noiseDots=’direction’,name=’‘,autoLog=True)
This stimulus class defines a field of dots with an update rule that determines how they change on every call to
the .draw() method.
This single class can be used to generate a wide variety of dot motion types. For a review of possible types
and their pros and cons see Scase, Braddick & Raymond (1996). All six possible motions they describe can be
generated with appropriate choices of the signalDots (which determines whether signal dots are the ‘same’ or
‘different’ on each frame), noiseDots (which determines the locations of the noise dots on each frame) and the
dotLife (which determines for how many frames the dot will continue before being regenerated).
The default settings (as of v1.70.00) is for the noise dots to have identical velocity but random direction and
signal dots remain the ‘same’ (once a signal dot, always a signal dot).
For further detail about the different configurations see Dots (RDK) Component in the Builder Components
section of the documentation.
If further customisation is required, then the DotStim should be subclassed and its _update_dotsXY and _new-
DotsXY methods overridden.
Parameters
win : aWindow object (required)
units [None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the Window will be
used. See Units for the window and stimuli for explanation of other options.
nDots [int] number of dots to be generated
fieldPos [(x,y) or [x,y]] specifying the location of the centre of the stimulus.
fieldSize [(x,y) or [x,y] or single value (applied to both dimensions)] Sizes can be negative and
can extend beyond the window.
fieldShape [‘sqr’ or ‘circle’] Defines the envelope used to present the dots
dotSize specified in pixels (overridden if element is specified)
dotLife [int] Number of frames each dot lives for (default=3, -1=infinite)
dir [float (degrees)] direction of the coherent dots
speed [float] speed of the dots (in units/frame)
signalDots [‘same’ or ‘different’] If ‘same’ then the signal and noise dots are constant. If dif-
ferent then the choice of which is signal and which is noise gets randomised on each frame.
This corresponds to Scase et al’s (1996) categories of RDK.
17.2. psychopy.visual - many visual stimuli 105
PsychoPy - Psychology software for Python, Release 1.78.00
noiseDots [‘direction’, ‘position’ or ‘walk’] Determines the behaviour of the noise dots, taken
directly from Scase et al’s (1996) categories. For ‘position’, noise dots take a random po-
sition every frame. For ‘direction’ noise dots follow a random, but constant direction. For
‘walk’ noise dots vary their direction every frame, but keep a constant speed.
color:
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
colorSpace:
The color space controlling the interpretation of the color See Color spaces
opacity [float (default= 1.0 )] 1.0 is opaque, 0.0 is transparent
contrast: float (default= 1.0 )How far the stimulus deviates from the middle grey. Contrast
can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).
depth:
The depth argument is deprecated and may be removed in future versions. Depth is
controlled simply by drawing order.
element [None or a visual stimulus object] This can be any object that has a .draw() method
and a .setPos([x,y]) method (e.g. a GratingStim, TextStim...)!! See ElementAr-
rayStim for a faster implementation of this idea.
name [string] The name of the object to be using during logged messages about this stimulus
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
106 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.:
myStim.setColor([1.0,-1.0,-1.0], ’rgb’)#a red color in rgb space
myStim.setColor([0.0,45.0,1.0], ’dkl’)#DKL space with elev=0, azimuth=45
myStim.setColor([0,0,255], ’rgb255’)#a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].:
myStim.setColor(255,’rgb255’)#all guns o max
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color:
17.2. psychopy.visual - many visual stimuli 107
PsychoPy - Psychology software for Python, Release 1.78.00
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1,’rgb’,’*’)#multiply the color by -1 (which in this space inverts the contrast)
thisStim.setColor([10,0,0], ’dkl’,’+’)#raise the elevation from the isoluminant plane by 10 deg
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDepth(newDepth,operation=’‘,log=True)
setDir(val,op=’‘,log=True)
Change the direction of the signal dots (units in degrees)
setFieldCoherence(val,op=’‘,log=True)
Change the coherence (%) of the DotStim. This will be rounded according to the number of dots in the
stimulus.
setFieldPos(val,op=’‘,log=True)
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setSize(newSize,operation=’‘,units=None,log=True)
Set the stimulus size [X,Y] in the specified (or inherited) units
setSpeed(val,op=’‘,log=True)
Change the speed of the dots (in stimulus units per second)
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
108 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
17.2.7 ElementArrayStim
class psychopy.visual.ElementArrayStim(win,units=None,fieldPos=(0.0,0.0),fieldSize=(1.0,
1.0),fieldShape=’circle’,nElements=100,sizes=2.0,
xys=None,rgbs=None,colors=(1.0,1.0,1.0),col-
orSpace=’rgb’,opacities=1.0,depths=0,fieldDepth=0,
oris=0,sfs=1.0,contrs=1,phases=0,elementTex=’sin’,
elementMask=’gauss’,texRes=48,interpolate=True,
name=’‘,autoLog=True)
This stimulus class defines a field of elements whose behaviour can be independently controlled. Suitable
for creating ‘global form’ stimuli or more detailed random dot stimuli. This stimulus can draw thousands of
elements without dropping a frame, but in order to achieve this performance, uses several OpenGL extensions
only available on modern graphics cards (supporting OpenGL2.0). See the ElementArray demo.
Parameters
win : aWindow object (required)
units [None, ‘height’, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the
Window will be used. See Units for the window and stimuli for explanation of other options.
fieldPos : The centre of the array of elements
fieldSize : The size of the array of elements (this will be overridden by setting explicit xy posi-
tions for the elements)
fieldShape : The shape of the array (‘circle’ or ‘sqr’)
nElements : number of elements in the array
sizes : an array of sizes Nx1, Nx2 or a single value
xys : the xy positions of the elements, relative to the field centre (fieldPos)
colors : specifying the color(s) of the elements. Should be Nx1 (different intensities), Nx3
(different colors) or 1x3 (for a single color).
colorSpace : The type of color specified is the same as those in other stimuli (‘rgb’,’dkl’,’lms’...)
but note that for this stimulus you cannot currently use text-based colors (e.g. names or hex
values)
opacities : the opacity of each element (Nx1 or a single value)
depths : the depths of the elements (Nx1), relative the overall depth of the field (fieldDepth)
fieldDepth : the depth of the field (will be added to the depths of the elements)
oris : the orientations of the elements (Nx1 or a single value)
sfs : the spatial frequencies of the elements (Nx1, Nx2 or a single value)
contrs : the contrasts of the elements, ranging -1 to +1 (Nx1 or a single value)
phases : the spatial phase of the texture on the stimulus (Nx1 or a single value)
elementTex : the texture, to be used by all elements (e.g. ‘sin’, ‘sqr’,.. , ‘myTexture.tif’,
numpy.ones([48,48]))
elementMask : the mask, to be used by all elements (e.g. ‘circle’, ‘gauss’,... , ‘myTexture.tif’,
numpy.ones([48,48]))
texRes : the number of pixels in the textures (overridden if an array or image is provided)
name [string] The name of the objec to be using during logged messages about this stim
17.2. psychopy.visual - many visual stimuli 109
PsychoPy - Psychology software for Python, Release 1.78.00
clearTextures()
Clear the textures associated with the given stimulus. As of v1.61.00 this is called automatically during
garbage collection of your stimulus, so doesn’t need calling explicitly by the user.
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.update() if you
want the stimulus to appear on that frame and then update the screen again.
setColors(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways.
You must provide a triplet of values, which refer to the coordinates in one of the Color spaces. If no
color space is specified then the color space most recently used for this stimulus is used again.
myStim.setColor([1.0,-1.0,-1.0], ‘rgb’)#a red color in rgb space myS-
tim.setColor([0.0,45.0,1.0], ‘dkl’) #DKL space with elev=0, azimuth=45 myS-
tim.setColor([0,0,255], ‘rgb255’) #a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].
myStim.setColor(255, ‘rgb255’) #all guns o max
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1, ‘rgb’, ‘*’) #multiply the color by -1 (which in this space in-
verts the contrast) thisStim.setColor([10,0,0], ‘dkl’, ‘+’)#raise the elevation from the
isoluminant plane by 10 deg
setContrs(value,operation=’‘,log=True)
Set the contrast for each element. Should either be:
•a single value
•an Nx1 array/list
setFieldPos(value,operation=’‘,log=True)
Set the centre of the array (X,Y)
setFieldSize(value,operation=’‘,log=True)
Set the size of the array on the screen (will override current XY positions of the elements)
setMask(value,log=True)
Change the mask (all elements have the same mask). Avoid doing this during time-critical points in your
script. Uploading new textures to the graphics card can be time-consuming.
setOpacities(value,operation=’‘,log=True)
Set the opacity for each element. Should either be a single value or an Nx1 array/list
110 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
setOris(value,operation=’‘,log=True)
Set the orientation for each element. Should either be a single value or an Nx1 array/list
setPhases(value,operation=’‘,log=True)
Set the phase for each element. Should either be:
•a single value
•an Nx1 array/list
•an Nx2 array/list (for separate X and Y phase)
setPos(newPos=None,operation=’‘,units=None,log=True)
Obselete - users should use setFieldPos or instead of setPos
setRgbs(value,operation=’‘,log=True)
DEPRECATED (as of v1.74.00). Please use setColors() instead
setSfs(value,operation=’‘,log=True)
Set the spatial frequency for each element. Should either be:
•a single value
•an Nx1 array/list
•an Nx2 array/list (spatial frequency of the element in X and Y).
If the units for the stimulus are ‘pix’ or ‘norm’ then the units of sf are cycles per stimulus width. For units
of ‘deg’ or ‘cm’ the units are c/cm or c/deg respectively.
setSizes(value,operation=’‘,log=True)
Set the size for each element. Should either be:
•a single value
•an Nx1 array/list
•an Nx2 array/list
setTex(value,log=True)
Change the texture (all elements have the same base texture). Avoid this during time-critical points in your
script. Uploading new textures to the graphics card can be time-consuming.
setXYs(value=None,operation=’‘,log=True)
Set the xy values of the element centres (relative to the centre of the field). Values should be:
•None
•an array/list of Nx2 coordinates.
If value is None then the xy positions will be generated automatically, based on the fieldSize and fieldPos.
In this case opacity will also be overridden by this function (it is used to make elements outside the field
invisible.
updateElementColors()
Create a new array of self._RGBAs based on self.rgbs. Not needed by the user (simple call setColors())
For element arrays the self.rgbs values correspond to one element so this function also converts them to be
one for each vertex of each element
updateElementVertices()
updateTextureCoords()
Create a new array of self._maskCoords
17.2. psychopy.visual - many visual stimuli 111
PsychoPy - Psychology software for Python, Release 1.78.00
17.2.8 GratingStim
class psychopy.visual.GratingStim(win,tex=’sin’,mask=’none’,units=’‘,pos=(0.0,0.0),
size=None,sf=None,ori=0.0,phase=(0.0,0.0),texRes=128,
rgb=None,dkl=None,lms=None,color=(1.0,1.0,1.0),col-
orSpace=’rgb’,contrast=1.0,opacity=1.0,depth=0,rgb-
Pedestal=(0.0,0.0,0.0),interpolate=False,name=’‘,au-
toLog=True,maskParams=None)
Stimulus object for drawing arbitrary bitmaps that can repeat (cycle) in either dimension One of the main stimuli
for PsychoPy.
Formally GratingStim is just a texture behind an optional transparency mask (an ‘alpha mask’). Both the texture
and mask can be arbitrary bitmaps and their combination allows an enormous variety of stimuli to be drawn in
realtime.
Examples:
myGrat =GratingStim(tex=’sin’,mask=’circle’)#gives a circular patch of grating
myGabor =GratingStim(tex=’sin’,mask=’gauss’)#gives a ’Gabor’
A GratingStim can be rotated scaled and shifted in position, its texture can be drifted in X and/or Y and it can
have a spatial frequency in X and/or Y (for an image file that simply draws multiple copies in the patch).
Also since transparency can be controlled two GratingStims can combine e.g. to form a plaid.
Using GratingStim with images from disk (jpg, tif, png...)
Ideally texture images to be rendered should be square with ‘power-of-2’ dimensions e.g. 16x16, 128x128. Any
image that is not will be upscaled (with linear interpolation) to the nearest such texture by PsychoPy. The size
of the stimulus should be specified in the normal way using the appropriate units (deg, pix, cm...). Be sure to
get the aspect ratio the same as the image (if you don’t want it stretched!).
Parameters
win : aWindow object (required)
tex : The texture forming the image
•‘sin’,’sqr’, ‘saw’, ‘tri’, None
• or the name of an image file (most formats supported)
• or a numpy array (1xN or NxN) ranging -1:1
mask : The alpha mask (forming the shape of the image)
•None, ‘circle’, ‘gauss’, ‘raisedCos’
• or the name of an image file (most formats supported)
• or a numpy array (1xN or NxN) ranging -1:1
units [None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the Window will be
used. See Units for the window and stimuli for explanation of other options.
pos : a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. The origin
is the screen centre, the units are determined by units (see above). Stimuli can be position
beyond the window!
size : a tuple (0.5,0.5) or a list [0.5,0.5] for the x and y OR a single value (which will be applied
to x and y). Units are specified by ‘units’ (see above). Sizes can be negative and can extend
beyond the window.
112 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Note: If the mask is Gaussian (‘gauss’), then the ‘size’ parameter refers to the stimulus at
3 standard deviations on each side of the centre (ie. sd=size/6)
sf: a tuple (1.0,1.0) or a list [1.0,1.0] for the x and y OR a single value (which will be applied
to x and y). Where units == ‘deg’ or ‘cm’ units are in cycles per deg/cm. If units == ‘norm’
then sf units are in cycles per stimulus (so scale with stimulus size). If texture is an image
loaded from a file then sf defaults to 1/stim size to give one cycle of the image.
ori: orientation of stimulus in degrees
phase: a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y OR a single value (which will be
applied to x and y). Phase of the stimulus in each direction. NB phase has modulus 1 (rather
than 360 or 2*pi) This is a little unconventional but has the nice effect that setting phase=t*n
drifts a stimulus at n Hz
texRes: resolution of the texture (if not loading from an image file)
color:
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
colorSpace: the color space controlling the interpretation of the color See Color spaces
contrast: float (default= 1.0 )How far the stimulus deviates from the middle grey. Contrast
can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).
opacity: float (default= 1.0 )1.0 is opaque, 0.0 is transparent
depth: The depth argument is deprecated and may be removed in future versions. Depth is
controlled simply by drawing order.
name [string] The name of the object to be using during logged messages about this stim
maskParams: Various types of input. Default to None. This is used to pass additional pa-
rameters to the mask if those are needed. - For the ‘raisedCos’ mask, pass a dict:
{‘fringeWidth’:0.2}, where ‘fringeWidth’ is a parameter (float, 0-1), determining the pro-
portion of the patch that will be blurred by the raised cosine edge.
clearTextures()
Clear the textures associated with the given stimulus. As of v1.61.00 this is called automatically during
garbage collection of your stimulus, so doesn’t need calling explicitly by the user.
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
17.2. psychopy.visual - many visual stimuli 113
PsychoPy - Psychology software for Python, Release 1.78.00
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.:
myStim.setColor([1.0,-1.0,-1.0], ’rgb’)#a red color in rgb space
myStim.setColor([0.0,45.0,1.0], ’dkl’)#DKL space with elev=0, azimuth=45
myStim.setColor([0,0,255], ’rgb255’)#a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].:
myStim.setColor(255,’rgb255’)#all guns o max
114 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color:
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1,’rgb’,’*’)#multiply the color by -1 (which in this space inverts the contrast)
thisStim.setColor([10,0,0], ’dkl’,’+’)#raise the elevation from the isoluminant plane by 10 deg
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setMask(value,log=True)
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPhase(value,operation=’‘,log=True)
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setSF(value,operation=’‘,log=True)
17.2. psychopy.visual - many visual stimuli 115
PsychoPy - Psychology software for Python, Release 1.78.00
setSize(newSize,operation=’‘,units=None,log=True)
Set the stimulus size [X,Y] in the specified (or inherited) units
setTex(value,log=True)
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
17.2.9 ImageStim
class psychopy.visual.ImageStim(win,image=None,mask=None,units=’‘,pos=(0.0,0.0),
size=None,ori=0.0,color=(1.0,1.0,1.0),colorSpace=’rgb’,
contrast=1.0,opacity=1.0,depth=0,interpolate=False,
flipHoriz=False,flipVert=False,texRes=128,name=’‘,au-
toLog=True,maskParams=None)
Parameters
win : aWindow object (required)
image : The image file to be presented (most formats supported)
mask : The alpha mask that can be used to control the outer shape of the stimulus
•None, ‘circle’, ‘gauss’, ‘raisedCos’
• or the name of an image file (most formats supported)
• or a numpy array (1xN or NxN) ranging -1:1
units [None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the Window will be
used. See Units for the window and stimuli for explanation of other options.
pos : a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. The origin
is the screen centre, the units are determined by units (see above). Stimuli can be position
beyond the window!
size : a tuple (0.5,0.5) or a list [0.5,0.5] for the x and y OR a single value (which will be applied
to x and y). Units are specified by ‘units’ (see above). Sizes can be negative and can extend
beyond the window.
Note: If the mask is Gaussian (‘gauss’), then the ‘size’ parameter refers to the stimulus at
3 standard deviations on each side of the centre (ie. sd=size/6)
ori: orientation of stimulus in degrees
color:
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
colorSpace: the color space controlling the interpretation of the color See Color spaces
contrast: float (default= 1.0 )How far the stimulus deviates from the middle grey. Contrast
can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).
116 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
opacity: float (default= 1.0 )1.0 is opaque, 0.0 is transparent
texRes: Sets the resolution of the mask (this is independent of the image resolution)
depth: The depth argument is deprecated and may be removed in future versions. Depth is
controlled simply by drawing order.
name [string] The name of the object to be using during logged messages about this stim
maskParams: Various types of input. Default to None. This is used to pass additional pa-
rameters to the mask if those are needed. - For the ‘raisedCos’ mask, pass a dict:
{‘fringeWidth’:0.2}, where ‘fringeWidth’ is a parameter (float, 0-1), determining the pro-
portion of the patch that will be blurred by the raised cosine edge.
clearTextures()
Clear the textures associated with the given stimulus. As of v1.61.00 this is called automatically during
garbage collection of your stimulus, so doesn’t need calling explicitly by the user.
contains(x,y=None)
Determines if a point x,y is on the image (within its boundary).
See ShapeStim .contains().
draw(win=None)
overlaps(polygon)
Determines if the image overlaps another image or shape (polygon).
See ShapeStim .overlaps().
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
17.2. psychopy.visual - many visual stimuli 117
PsychoPy - Psychology software for Python, Release 1.78.00
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.:
myStim.setColor([1.0,-1.0,-1.0], ’rgb’)#a red color in rgb space
myStim.setColor([0.0,45.0,1.0], ’dkl’)#DKL space with elev=0, azimuth=45
myStim.setColor([0,0,255], ’rgb255’)#a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].:
myStim.setColor(255,’rgb255’)#all guns o max
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color:
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1,’rgb’,’*’)#multiply the color by -1 (which in this space inverts the contrast)
thisStim.setColor([10,0,0], ’dkl’,’+’)#raise the elevation from the isoluminant plane by 10 deg
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setImage(value,log=True)
Set the image to be used for the stimulus to this new value
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
118 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
setMask(value,log=True)
Change the image to be used as an alpha-mask for the image
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setSize(newSize,operation=’‘,units=None,log=True)
Set the stimulus size [X,Y] in the specified (or inherited) units
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
17.2.10 Line
class psychopy.visual.Line(win,start=(-0.5,-0.5),end=(0.5,0.5),**kwargs)
Creates a Line between two points.
(New in version 1.72.00)
Line accepts all input parameters, that ShapeStim accepts, except for vertices, closeShape and fillColor.
The methods contains and overlaps are inherited from ~psychopy.visual.ShapeStim, but always return False
(because a line is not a proper (2D) polygon).
Parameters
win : AWindow object (required)
start [tuple, list or 2x1 array] Specifies the position of the start of the line
end [tuple, list or 2x1 array] Specifies the position of the end of the line
contains()
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps()
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
17.2. psychopy.visual - many visual stimuli 119
PsychoPy - Psychology software for Python, Release 1.78.00
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘)
For ShapeStim use setLineColor() or setFillColor()
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setEnd(end,log=True)
Changes the end point of the line. Argument should be a tuple, list or 2x1 array specifying the coordinates
of the end point
setFillColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape fill. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
Note that shapes where some vertices point inwards will usually not ‘fill’ correctly.
setFillRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setFillColor()
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setLineColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape edge. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
setLineRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setLineColor()
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
120 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setSize(value,operation=’‘,log=True)
Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s
vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.
setStart(start,log=True)
Changes the start point of the line. Argument should be
•tuple, list or 2x1 array specifying the coordinates of the start point
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
setVertices(value=None,operation=’‘,log=True)
Set the xy values of the vertices (relative to the centre of the field). Values should be:
•an array/list of Nx2 coordinates.
17.2.11 MovieStim
class psychopy.visual.MovieStim(win,filename=’‘,units=’pix’,size=None,pos=(0.0,0.0),
ori=0.0,flipVert=False,flipHoriz=False,color=(1.0,1.0,1.0),
colorSpace=’rgb’,opacity=1.0,name=’‘,loop=False,au-
toLog=True,depth=0.0)
A stimulus class for playing movies (mpeg, avi, etc...) in PsychoPy.
Example:
mov =visual.MovieStim(myWin, ’testMovie.mp4’, flipVert=False)
print mov.duration
print mov.format.width, mov.format.height #give the original size of the movie in pixels
mov.draw() #draw the current frame (automagically determined)
See MovieStim.py for demo.
mov.contains() and mov.overlaps() will work only if the containing visual.Window() has units=’pix’.
Parameters
win : aWindow object (required)
filename : a string giving the relative or absolute path to the movie. Can be any movie that
AVbin can read (e.g. mpeg, DivX)
units [None, ‘height’, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the
Window will be used. See Units for the window and stimuli for explanation of other options.
pos : position of the centre of the movie, given in the units specified
flipVert [True or False] If True then the movie will be top-bottom flipped
flipHoriz [True or False] If True then the movie will be right-left flipped
ori : Orientation of the stimulus in degrees
size : Size of the stimulus in units given. If not specified then the movie will take its original
dimensions.
17.2. psychopy.visual - many visual stimuli 121
PsychoPy - Psychology software for Python, Release 1.78.00
color: Modified the weight of the colors in the movie. E,g, color=”red” will only display the
red parts of the movie and make all other things black. white (color=(1,1,1)) is the original
colors.
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
colorSpace: the color space controlling the interpretation of the color See Color spaces
opacity : the movie can be made transparent by reducing this
name [string] The name of the object to be using during logged messages about this stim
loop [bool, optional] Whether to start the movie over from the beginning if draw is called and
the movie is done.
draw(win=None)
Draw the current frame to a particular visual.Window (or to the default win for this object if not specified).
The current position in the movie will be determined automatically.
This method should be called on every frame that the movie is meant to appear
loadMovie(filename,log=True)
Load a movie from file
Parameters
filename: string The name of the file, including path if necessary
Brings up a warning if avbin is not found on the computer. After the file is loaded MovieStim.duration is
updated with the movie duration (in seconds).
pause(log=True)
Pause the current point in the movie (sound will stop, current frame will not advance). If play() is called
again both will restart.
play(log=True)
Continue a paused movie from current position
seek(timestamp,log=True)
Seek to a particular timestamp in the movie. NB this does not seem very robust as at version 1.62 and may
cause crashes!
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setContrast()
“Not yet implemented for MovieStim
setMovie(filename,log=True)
See ~MovieStim.loadMovie (the functions are identical). This form is provided for syntactic consistency
with other visual stimuli.
122 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
stop(log=True)
Stop the current point in the movie (sound will stop, current frame will not advance). Once stopped the
movie cannot be restarted - it must be loaded again. Use pause() if you may need to restart the movie.
17.2.12 PatchStim (deprecated)
class psychopy.visual.PatchStim(*args,**kwargs)
Deprecated (as of version 1.74.00): please use the GratingStim or the ImageStim classes.
The GratingStim has identical abilities to the PatchStim (but possibly different initial values) whereas the Im-
ageStim is designed to be use for non-cyclic images (photographs, not gratings).
clearTextures()
Clear the textures associated with the given stimulus. As of v1.61.00 this is called automatically during
garbage collection of your stimulus, so doesn’t need calling explicitly by the user.
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
17.2. psychopy.visual - many visual stimuli 123
PsychoPy - Psychology software for Python, Release 1.78.00
setColor(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.:
myStim.setColor([1.0,-1.0,-1.0], ’rgb’)#a red color in rgb space
myStim.setColor([0.0,45.0,1.0], ’dkl’)#DKL space with elev=0, azimuth=45
myStim.setColor([0,0,255], ’rgb255’)#a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].:
myStim.setColor(255,’rgb255’)#all guns o max
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color:
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1,’rgb’,’*’)#multiply the color by -1 (which in this space inverts the contrast)
thisStim.setColor([10,0,0], ’dkl’,’+’)#raise the elevation from the isoluminant plane by 10 deg
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
124 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setMask(value,log=True)
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPhase(value,operation=’‘,log=True)
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setSF(value,operation=’‘,log=True)
setSize(newSize,operation=’‘,units=None,log=True)
Set the stimulus size [X,Y] in the specified (or inherited) units
setTex(value,log=True)
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
17.2.13 Polygon
class psychopy.visual.Polygon(win,edges=3,radius=0.5,**kwargs)
Creates a regular polygon (triangles, pentagrams, ...) as a special case of a ShapeStim
(New in version 1.72.00)
Polygon accepts all input parameters that ShapeStim accepts, except for vertices and closeShape.
Parameters
win : AWindow object (required)
edges [int] Number of edges of the polygon
radius [float, int, tuple, list or 2x1 array] Radius of the Polygon (distance from the center to the
corners). May be a -2tuple or list to stretch the polygon asymmetrically
17.2. psychopy.visual - many visual stimuli 125
PsychoPy - Psychology software for Python, Release 1.78.00
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘)
For ShapeStim use setLineColor() or setFillColor()
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
126 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setEdges(edges)
Set the number of edges to a new value
setFillColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape fill. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
Note that shapes where some vertices point inwards will usually not ‘fill’ correctly.
setFillRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setFillColor()
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setLineColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape edge. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
setLineRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setLineColor()
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setRadius(radius,log=True)
Changes the radius of the Polygon. Parameter should be
•float, int, tuple, list or 2x1 array
setSize(value,operation=’‘,log=True)
Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s
vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
setVertices(value=None,operation=’‘,log=True)
Set the xy values of the vertices (relative to the centre of the field). Values should be:
•an array/list of Nx2 coordinates.
17.2. psychopy.visual - many visual stimuli 127
PsychoPy - Psychology software for Python, Release 1.78.00
17.2.14 RadialStim
class psychopy.visual.RadialStim(win,tex=’sqrXsqr’,mask=’none’,units=’‘,pos=(0.0,0.0),
size=(1.0,1.0),radialCycles=3,angularCycles=4,radial-
Phase=0,angularPhase=0,ori=0.0,texRes=64,angular-
Res=100,visibleWedge=(0,360),rgb=None,color=(1.0,1.0,
1.0),colorSpace=’rgb’,dkl=None,lms=None,contrast=1.0,
opacity=1.0,depth=0,rgbPedestal=(0.0,0.0,0.0),interpo-
late=False,name=’‘,autoLog=True)
Stimulus object for drawing radial stimuli, like an annulus, a rotating wedge, a checkerboard etc...
Ideal for fMRI retinotopy stimuli!
Many of the capabilities are built on top of the GratingStim.
This stimulus is still relatively new and I’m finding occasional gliches. it also takes longer to draw than a typical
GratingStim, so not recommended for tasks where high frame rates are needed.
Parameters
win : aWindow object (required)
tex : The texture forming the image
• ‘sqrXsqr’, ‘sinXsin’, ‘sin’,’sqr’,None
• or the name of an image file (most formats supported)
• or a numpy array (1xN, NxNx1, NxNx3) ranging -1:1
mask [none or ‘gauss’] Unlike the mask in the GratingStim, this is a 1-D mask dictating the
behaviour from the centre of the stimulus to the surround.
units [None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the Window will be
used. See Units for the window and stimuli for explanation of other options.
pos : a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. Stimuli can
be position beyond the window!
size : a tuple (0.5,0.5) or a list [0.5,0.5] for the x and y OR a single value (which will be applied
to x and y). Sizes can be negative and stimuli can extend beyond the window.
ori : orientation of stimulus in degrees.
texRes [(default= 128 )] resolution of the texture (if not loading from an image file)
angularRes [(default= 100 )] 100, the number of triangles used to make the sti
radialPhase : the phase of the texture from the centre to the perimeter of the stimulus (in radi-
ans)
angularPhase : the phase of the texture around the stimulus (in radians)
color:
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
colorSpace: the color space controlling the interpretation of the color See Color spaces
128 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
contrast [float (default= 1.0 )] How far the stimulus deviates from the middle grey. Contrast
can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus)
opacity [float (default=*1.0*)] Between 0.0 and 1.0. 1.0 is opaque, 0.0 is transparent
depth: The depth argument is deprecated and may be removed in future versions. Depth is
controlled simply by drawing order.
name [string] The name of the object to be using during logged messages about this stim
clearTextures()
Clear the textures associated with the given stimulus. As of v1.61.00 this is called automatically during
garbage collection of your stimulus, so doesn’t need calling explicitly by the user.
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
If win is specified then override the normal window of this stimulus.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAngularCycles(value,operation=’‘,log=True)
set the number of cycles going around the stimulus
setAngularPhase(value,operation=’‘,log=True)
set the angular phase of the texture (radians)
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
17.2. psychopy.visual - many visual stimuli 129
PsychoPy - Psychology software for Python, Release 1.78.00
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.:
myStim.setColor([1.0,-1.0,-1.0], ’rgb’)#a red color in rgb space
myStim.setColor([0.0,45.0,1.0], ’dkl’)#DKL space with elev=0, azimuth=45
myStim.setColor([0,0,255], ’rgb255’)#a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].:
myStim.setColor(255,’rgb255’)#all guns o max
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color:
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1,’rgb’,’*’)#multiply the color by -1 (which in this space inverts the contrast)
thisStim.setColor([10,0,0], ’dkl’,’+’)#raise the elevation from the isoluminant plane by 10 deg
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
130 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setMask(value,log=True)
Change the alpha-mask for the stimulus
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPhase(value,operation=’‘,log=True)
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setRadialCycles(value,operation=’‘,log=True)
set the number of texture cycles from centre to periphery
setRadialPhase(value,operation=’‘,log=True)
set the radial phase of the texture (radians)
setSF(value,operation=’‘,log=True)
setSize(value,operation=’‘,log=True)
setTex(value,log=True)
Update the texture of the stimulus
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
17.2. psychopy.visual - many visual stimuli 131
PsychoPy - Psychology software for Python, Release 1.78.00
17.2.15 RatingScale
class psychopy.visual.RatingScale(win,scale=’<default>’,choices=None,low=1,high=7,
lowAnchorText=None,highAnchorText=None,tick-
Marks=None,labels=None,precision=1,textSizeFac-
tor=1.0,textColor=’LightGray’,textFont=’Helvetica Bold’,
showValue=True,showScale=True,showAnchors=True,
showAccept=True,acceptKeys=’return’,acceptPreText=’key,
click’,acceptText=’accept?’,acceptSize=1.0,leftKeys=’left’,
rightKeys=’right’,lineColor=’White’,ticksAboveLine=True,
markerStyle=’triangle’,markerColor=None,marker-
Start=False,markerExpansion=1,customMarker=None,
escapeKeys=None,allowSkip=True,skipKeys=’tab’,
mouseOnly=False,singleClick=False,displaySizeFactor=1.0,
stretchHoriz=1.0,pos=None,minTime=1.0,maxTime=0.0,
disappear=False,name=’‘,autoLog=True)
A class for getting numeric or categorical ratings, e.g., a 1-to-7 scale.
Returns a re-usable rating-scale object having a .draw() method, with customizable visual appearance and full
data options, including RT and history.
The .draw() method displays the rating scale, handles the subject’s responses, and updates the display. When the
subject makes a final response, .noResponse goes False (i.e., there is a response). You can then call .getRating()
to obtain the final rating, .getRT() to get the decision time, or .getHistory() to obtain all intermediate values
(rating, RT), up to an including the final one. This feature can be used to obtain continuous ratings using a
single RatingScale object.
The experimenter has to draw the item to be rated, i.e., draw() it in the same window each frame. A RatingScale
instance has no idea what else is on the screen.
The subject can use the arrow keys (left, right) to move the marker in small increments (e.g., 1/100th of a
tick-mark if precision = 100).
Auto-rescaling happens if the low-anchor is 0 and the high-anchor is a multiple of 10, just to reduce visual
clutter.
Example 1:
The default 7-point scale:
myItem = <create your text, image, movie, ...>
myRatingScale = visual.RatingScale(myWin)
while myRatingScale.noResponse:
myItem.draw()
myRatingScale.draw()
myWin.flip()
rating = myRatingScale.getRating()
decisionTime = myRatingScale.getRT()
choiceHistory = myRatingScale.getHistory()
Example 2:
Key-board only. Considerable customization is possible. For fMRI, if your response box sends keys
1-4, you could specify left, right, and accept keys, and no mouse:
myRatingScale =visual.RatingScale(myWin, markerStart=4,
leftKeys=’1’, rightKeys =’2’, acceptKeys=’4’)
Example 3:
132 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Non-numeric choices (categorical, unordered):
myRatingScale =visual.RatingScale(myWin, choices=[’agree’,’disagree’])
A text version of the item will be displayed, but the value returned by getResponse() will be of type
you gave it:
var =3.14
myRatingScale =visual.RatingScale(myWin,
choices=[’cherry’,’apple’,True, var, ’pie’])
So if the subject chooses True, getResponse() will return True (bool) and not u’True’ (unicode).
See Coder Demos -> stimuli -> ratingScale.py for examples. As another example, fMRI_launchScan.py uses a
rating scale for the experimenter to choose between two modes (and not for subjects giving ratings).
The Builder RatingScale component gives a restricted set of options, but also allows full control over a Rat-
ingScale (via ‘customizeEverything’).
Authors 2010 Jeremy Gray, with on-going updates 2012 Henrik Singmann: tickMarks, labels,
ticksAboveLine
Parameters
win : AWindow object (required)
scale : explanation of the numbers to display to the subject, shown above the line; string, default
= ‘<low>=not at all, <high>=extremely’. To suppress all text above the line, set showS-
cale=False. If labels is not False and choices or tickMarks exists, scale defaults to False.
choices : a list of items which the subject can choose among; takes precedence over low,high,
lowAnchorText,highAnchorText,showScale,tickMarks,precision.
low : lowest numeric rating / low anchor (integer, default = 1)
high : highest numeric rating / high anchor (integer, default = 7; at least low + 1)
lowAnchorText : text to dsiplay for the low end of the scale (default = numeric low value)
highAnchorText : text to display for the high end of the scale (default = numeric high value)
tickMarks : list of positions at which tick marks should be placed (low and high need to be
included if tick marks should be at the edges of the scale). If None (the default), tick marks
are automatically equally spaced, one per integer value; auto-rescaling (by a factor of 10)
can happen to reduce visual clutter.
labels : text to be placed at each tick mark as placed by tickMarks and controls where labels
of choices are displayed. Default is None. If None and choices: choices will be plotted at
ticks and showAnchors=False, but scale can be used for plotting above the line. If None and
tickMarks:tickMarks will be used and showAnchors=False. If False, no labels are plotted
at tick marks.
precision : portions of a tick to accept as input [1, 10, 100], default = 1 tick (no fractional parts)
Note: pressing a key in leftKeys or rightKeys will move the marker by one portion of a tick.
Note: precision is incompatible with choices.
textSizeFactor : the size of text elements of the scale. For larger than default text (expand) set
> 1; for smaller, set < 1.
17.2. psychopy.visual - many visual stimuli 133
PsychoPy - Psychology software for Python, Release 1.78.00
textColor : color to use for anchor and scale text (assumed to be RGB), default = ‘LightGray’
textFont : name of the font to use, default = ‘Helvetica Bold’
showValue : show the subject their currently selected number, default = True
showScale : show the scale text (the text above the line), default = True. If False, will not show
any text above the line.
showAnchors : show the two end points of the scale (low,high), default = True
showAccept : show the button to click to accept the current value by using the mouse, default
=True
Note: If showAccept is False and acceptKeys is empty, acceptKeys is reset to [’return’] to
give the subject a way to respond.
acceptKeys : a key or list of keys that are used to mean “accept the current response”, default
=[’return’]
acceptPreText : text to display before any value has been selected
acceptText : text to display in the ‘accept’ button after a value has been selected
acceptSize : width of the accept box relative to the default (e.g., 2 is twice as wide)
leftKeys : a key or list of keys that mean “move leftwards”, default = [’left’]
rightKeys : a key or list of keys that mean “move rightwards”, default = [’right’]
lineColor : color to use for the scale line, default = ‘White’
ticksAboveLine : should the tick marks be displayed above the line (the default) or below
markerStyle : ‘triangle’ (DarkBlue), ‘circle’ (DarkRed), ‘glow’ (White, expanding), or ‘slider’
(translucent Black, looks best with precision=100)
markerColor : None = use defaults; or any legal RGB colorname, e.g., ‘#123456’, ‘DarkRed’
markerStart : False, or the value in [low..‘high‘] to be pre-selected upon initial display
markerExpansion : how much the glow marker expands when moving to the right; 0=none,
negative shrinks; try 10 or -10
customMarker : allows for a user-defined marker; must have a .draw() method, such as a
TextStim() or GratingStim()
escapeKeys : keys that will quit the experiment if pressed by the subject (by calling core.quit()).
default = [ ] (no escape keys).
Note: in the Builder, the default is [’escape’] (to be consistent
with other Builder conventions)
allowSkip : if True, the subject can skip an item by pressing a key in skipKeys, default = True
skipKeys : list of keys the subject can use to skip a response, default = [’tab’]
Note: to require a response to every item, use allowSkip=False
134 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
mouseOnly : require the subject use the mouse only (no keyboard), default = False. can be
used to avoid competing with other objects for keyboard input.
Note: mouseOnly=True and showAccept=False is a bad combination, so showAccept wins
(mouseOnly is reset to False); similarly, mouseOnly and allowSkip can conflict, because
skipping an item is done via key press (mouseOnly wins) mouseOnly=True is helpful if
there will be something else on the screen expecting keyboard input
singleClick : enable a mouse click to both indicate and accept the rating, default = False. Note
that the ‘accept’ box is visible, but clicking it has no effect, its just to display the value. A
legal key press will also count as a singleClick.
pos [tuple (x, y)] where to position the rating scale (x, y) in terms of the window’s units (pix,
norm); default (0.0, -0.4) in norm units
displaySizeFactor : how much to expand or contract the overall rating scale display (not just
the line length)
stretchHoriz: how much to stretch (or compress) the scale horizontally (3 -> use the whole
window); acts like displaySizeFactor, but only in the horizontal direction
minTime : number of seconds that must elapse before a reponse can be accepted, default = 1.0.
maxTime : number of seconds after which a reponse cannot be made accepted. if maxTime <=
minTime, there’s unlimited time. default = 0.0 (wait forever).
disappear : if True, the rating scale will be hidden after a value is accepted; useful when show-
ing multiple scales. The default is to remain on-screen.
name [string] The name of the object to be using during logged messages about this stim
autolog : whether logging should be done automatically
draw()
Update the visual display, check for response (key, mouse, skip).
sets response flags as appropriate (self.noResponse,self.timedOut). draw() only draws the rating scale, not
the item to be rated
getHistory()
Return the subject’s intermediate selection history, up to and including the final accepted choice, as a list
of (rating, time) tuples. The history can be retrieved at any time, allowing for continuous ratings to be
obtained in real-time. Both numerical and categorical choices are stored automatically in the history.
getRT()
Returns the seconds taken to make the rating (or to indicate skip). Returns None if no rating available, or
maxTime if the response timed out. Returns the time elapsed so far if no rating has been accepted yet (e.g.,
for continuous usage).
getRating()
Returns the final, accepted rating, or the current (non-accepted) intermediate selection. The rating is None
if the subject skipped this item, or False if not available. Returns the currently indicated rating even if it
has not been accepted yet (and so might change until accept is pressed).
reset()
Restores the rating-scale to its post-creation state.
The history is cleared, and the status is set to NOT_STARTED. Does not restore the scale text description
(such reset is needed between items when rating multiple items)
17.2. psychopy.visual - many visual stimuli 135
PsychoPy - Psychology software for Python, Release 1.78.00
setDescription(scale=None)
Method to set the text description that appears above the rating line.
Useful when using the same RatingScale object to rate several dimensions. setDescription(None) will
reset the description to its initial state. Set to a space character (‘ ‘) to make the description invisible. The
description will not be visible if showScale is False.
setMarkerPos(tick)
Method to allow the experimenter to set the marker’s position on the scale (in units of tick marks). This
method can also set the index within a list of choices (which start at 0). No range checking is done.
Assuming you have defined rs = RatingScale(...), you can specify a tick position directly:
rs.setMarkerPos(2)
or do range checking, precision management, and auto-rescaling:
rs.setMarkerPos(rs._getMarkerFromTick(2))
To work from a screen coordinate, such as the X position of a mouse click:
rs.setMarkerPos(rs._getMarkerFromPos(mouseX))
17.2.16 Rect
class psychopy.visual.Rect(win,width=0.5,height=0.5,**kwargs)
Creates a rectangle of given width and height as a special case of a ShapeStim
(New in version 1.72.00)
Rect accepts all input parameters, that ~psychopy.visual.ShapeStim accept, except for vertices and closeShape.
Parameters
win : AWindow object (required)
width [int or float] Width of the Rectangle (in its respective units, if specified)
height [int or float] Height of the Rectangle (in its respective units, if specified)
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
136 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘)
For ShapeStim use setLineColor() or setFillColor()
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setFillColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape fill. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
Note that shapes where some vertices point inwards will usually not ‘fill’ correctly.
setFillRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setFillColor()
setHeight(height,log=True)
Changes the height of the Rectangle
17.2. psychopy.visual - many visual stimuli 137
PsychoPy - Psychology software for Python, Release 1.78.00
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setLineColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape edge. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
setLineRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setLineColor()
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setSize(value,operation=’‘,log=True)
Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s
vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
setVertices(value=None,operation=’‘,log=True)
Set the xy values of the vertices (relative to the centre of the field). Values should be:
•an array/list of Nx2 coordinates.
setWidth(width,log=True)
Changes the width of the Rectangle
17.2.17 ShapeStim
class psychopy.visual.ShapeStim(win,units=’‘,lineWidth=1.0,lineColor=(1.0,1.0,1.0),line-
ColorSpace=’rgb’,fillColor=None,fillColorSpace=’rgb’,
vertices=((-0.5,0),(0,0.5),(0.5,0)),closeShape=True,pos=(0,
0),size=1,ori=0.0,opacity=1.0,contrast=1.0,depth=0,in-
terpolate=True,lineRGB=None,fillRGB=None,name=’‘,
autoLog=True)
Create geometric (vector) shapes by defining vertex locations.
Shapes can be outlines or filled, by setting lineRGB and fillRGB to rgb triplets, or None. They can also be
rotated (stim.setOri(__)) and translated (stim.setPos(__)) like any other stimulus.
NB for now the fill of objects is performed using glBegin(GL_POLYGON) and that is limited to convex shapes.
With concavities you get unpredictable results (e.g. add a fill color to the arrow stim below). To create concav-
ities, you can combine multiple shapes, or stick to just outlines. (If anyone wants to rewrite ShapeStim to use
glu tesselators that would be great!)
Parameters
win : AWindow object (required)
138 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
units [None, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the Window will be
used. See Units for the window and stimuli for explanation of other options.
lineColor :
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
lineColorSpace: The color space controlling the interpretation of the lineColor. See Color
spaces
fillColor :
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
lineWidth [int (or float?)] specifying the line width in pixels
vertices [a list of lists or a numpy array (Nx2)] specifying xy positions of each vertex
closeShape [True or False] Do you want the last vertex to be automatically connected to the
first?
pos [tuple, list or 2x1 array] the position of the anchor for the stimulus (relative to which the
vertices are drawn)
size [float, int, tuple, list or 2x1 array] Scales the ShapeStim up or down. Size is independent of
the units, i.e. setting the size to 1.5 will make the stimulus to be 1.5 times it’s original size
as defined by the vertices. Use a 2-tuple to scale asymmetrically.
ori [float or int] the shape can be rotated around the anchor
opacity [float (default= 1.0 )] 1.0 is opaque, 0.0 is transparent
contrast: float (default= 1.0 )How far the stimulus deviates from the middle grey. Contrast
can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).
depth: The depth argument is deprecated and may be removed in future versions. Depth is
controlled simply by drawing order.
interpolate [True or False] If True the edge of the line will be antialiased.
name [string] The name of the object to be using during logged messages about this stim
contains(x,y=None)
Determines if a point x,y is inside the extent of the stimulus.
Can accept: a) two args, x and y; b) one arg, as a point (x,y) that is list-like; or c) an object with a getPos()
method that returns x,y, such as a mouse. Returns True if the point is within the area defined by vertices.
This handles complex shapes, including concavities and self-crossings.
17.2. psychopy.visual - many visual stimuli 139
PsychoPy - Psychology software for Python, Release 1.78.00
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
contains method; the extent of the stmulus is determined purely by the size, pos and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
overlaps(polygon)
Determines if this stimulus intersects another one. If polygon is another stimulus instance, then the vertices
and location of that stimulus will be used as the polygon. Overlap detection is only approximate; it can
fail with pointy shapes. Returns True if the two shapes overlap.
Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the
overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings
(and by the vertices for shape stimuli).
See coder demo, shapeContains.py
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘)
For ShapeStim use setLineColor() or setFillColor()
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
140 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setFillColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape fill. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
Note that shapes where some vertices point inwards will usually not ‘fill’ correctly.
setFillRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setFillColor()
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setLineColor(color,colorSpace=None,operation=’‘,log=True)
Sets the color of the shape edge. See psychopy.visual.GratingStim.setColor() for further
details of how to use this function.
setLineRGB(value,operation=’‘)
DEPRECATED since v1.60.05: Please use setLineColor()
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(newRGB,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setSize(value,operation=’‘,log=True)
Sets the size of the shape. Size is independent of the units of shape and will simply scale the shape’s
vertices by the factor given. Use a tuple or list of two values to scale asymmetrically.
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
setVertices(value=None,operation=’‘,log=True)
Set the xy values of the vertices (relative to the centre of the field). Values should be:
•an array/list of Nx2 coordinates.
17.2.18 SimpleImageStim
class psychopy.visual.SimpleImageStim(win,image=’‘,units=’‘,pos=(0.0,0.0),flipHoriz=False,
flipVert=False,name=’‘,autoLog=True)
A simple stimulus for loading images from a file and presenting at exactly the resolution and color in the file
(subject to gamma correction if set).
Unlike the ImageStim, this type of stimulus cannot be rescaled, rotated or masked (although flipping horizontally
or vertically is possible). Drawing will also tend to be marginally slower, because the image isn’t preloaded to
the graphics card. The slight advantage, however is that the stimulus will always be in its original aspect ratio,
with no interplotation or other transformation.
17.2. psychopy.visual - many visual stimuli 141
PsychoPy - Psychology software for Python, Release 1.78.00
SimpleImageStim does not support a depth parameter (the OpenGL method that draws the pixels does not
support it). Simple images will obscure any other stimulus type.
Parameters
win : aWindow object (required)
image : The filename, including relative or absolute path. The image can be any format that the
Python Imagin Library can import (which is almost all).
units [None, ‘height’, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the
Window will be used. See Units for the window and stimuli for explanation of other options.
pos : a tuple (0.0,0.0) or a list [0.0,0.0] for the x and y of the centre of the stimulus. The origin
is the screen centre, the units are determined by units (see above). Stimuli can be position
beyond the window!
name [string] The name of the object to be using during logged messages about this stim
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
setDepth(newDepth,operation=’‘,log=True)
setFlipHoriz(newVal=True,log=True)
If set to True then the image will be flipped horiztonally (left-to-right). Note that this is relative to the
original image, not relative to the current state.
setFlipVert(newVal=True,log=True)
If set to True then the image will be flipped vertically (top-to-bottom). Note that this is relative to the
original image, not relative to the current state.
setImage(filename=None,log=True)
Set the image to be drawn.
Parameters
•filename: The filename, including relative or absolute path if necessary. Can actually also
be an image loaded by PIL.
setPos(newPos,operation=’‘,units=None,log=True)
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
17.2.19 TextStim
class psychopy.visual.TextStim(win,text=’Hello World’,font=’‘,pos=(0.0,0.0),depth=0,
rgb=None,color=(1.0,1.0,1.0),colorSpace=’rgb’,opacity=1.0,
contrast=1.0,units=’‘,ori=0.0,height=None,antialias=True,
bold=False,italic=False,alignHoriz=’center’,alignVert=’center’,
fontFiles=[],wrapWidth=None,flipHoriz=False,flipVert=False,
name=’‘,autoLog=True)
Class of text stimuli to be displayed in a Window
Parameters
win: A Window object. Required - the stimulus must know where to draw itself
text: The text to be rendered
pos: Position on the screen
142 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
color:
Could be a:
• web name for a color (e.g. ‘FireBrick’);
• hex value (e.g. ‘#FF0047’);
• tuple (1.0,1.0,1.0); list [1.0,1.0, 1.0]; or numpy array.
If the last three are used then the color space should also be given See Color spaces
colorSpace: the color space controlling the interpretation of the color See Color spaces
contrast: float (default= 1.0 )How far the stimulus deviates from the middle grey. Contrast
can vary -1:1 (this is a multiplier for the values given in the color description of the stimulus).
opacity: float (default= 1.0 )How transparent the object will be (0 for transparent, 1 for
opaque)
units [None, ‘height’, ‘norm’, ‘cm’, ‘deg’ or ‘pix’] If None then the current units of the
Window will be used. See Units for the window and stimuli for explanation of other options.
ori: Orientation of the text
height: Height of the characters (including the ascent of the letter and the descent)
antialias: boolean to allow (or not) antialiasing the text
bold: Make the text bold (better to use a bold font name)
italic: Make the text italic (better to use an actual italic font)
alignHoriz: The horizontal alignment (‘left’, ‘right’ or ‘center’)
alignVert: The vertical alignment (‘top’, ‘bottom’ or ‘center’)
fontFiles: A list of additional files if the font is not in the standard system location (include the
full path)
wrapWidth: The width the text should run before wrapping
flipHoriz [boolean] Mirror-reverse the text in the left-right direction
flipVert [boolean] Mirror-reverse the text in the up-down direction
name [string] The name of the object to be using during logged messages about this stim
depth: The depth argument is deprecated and may be removed in future versions. Depth is
controlled simply by drawing order.
contains(polygon)
Not implemented for TextStim
draw(win=None)
Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want
the stimulus to appear on that frame and then update the screen again.
If win is specified then override the normal window of this stimulus.
overlaps(polygon)
Not implemented for TextStim
setAutoDraw(val,log=True)
Add or remove a stimulus from the list of stimuli that will be automatically drawn on each flip. You do
NOT need to call this on every frame flip!
17.2. psychopy.visual - many visual stimuli 143
PsychoPy - Psychology software for Python, Release 1.78.00
Parameters
•val: True/False True to add the stimulus to the draw list, False to remove it
setAutoLog(val=True)
Turn on (or off) autoLogging for this stimulus. When autologging is enabled it can be overridden for an
individual set() operation using the log=False argument.
Parameters
• val: True (default) or False
setColor(color,colorSpace=None,operation=’‘,log=True)
Set the color of the stimulus. See Color spaces for further information about the various ways to specify
colors and their various implications.
Parameters
color : Can be specified in one of many ways. If a string is given then it is in-
terpreted as the name of the color. Any of the standard html/X11 color names
<http://www.w3schools.com/html/html_colornames.asp> can be used. e.g.:
myStim.setColor(’white’)
myStim.setColor(’RoyalBlue’)#(the case is actually ignored)
A hex value can be provided, also formatted as with web colors. This can be provided as a string that
begins with # (not using python’s usual 0x000000 format):
myStim.setColor(’#DDA0DD’)#DDA0DD is hexadecimal for plum
You can also provide a triplet of values, which refer to the coordinates in one of the Color spaces. If
no color space is specified then the color space most recently used for this stimulus is used again.
myStim.setColor([1.0,-1.0,-1.0], ‘rgb’)#a red color in rgb space myS-
tim.setColor([0.0,45.0,1.0], ‘dkl’) #DKL space with elev=0, azimuth=45 myS-
tim.setColor([0,0,255], ‘rgb255’) #a blue stimulus using rgb255 space
Lastly, a single number can be provided, x, which is equivalent to providing [x,x,x].
myStim.setColor(255, ‘rgb255’) #all guns o max
colorSpace : string or None
defining which of the Color spaces to use. For strings and hex values this is not needed. If None
the default colorSpace for the stimulus is used (defined during initialisation).
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
for colors specified as a triplet of values (or single intensity value) the new value will perform
this operation on the previous color
thisStim.setColor([1,1,1],’rgb255’,’+’)#increment all guns by 1 value
thisStim.setColor(-1, ‘rgb’, ‘*’) #multiply the color by -1 (which in this space in-
verts the contrast) thisStim.setColor([10,0,0], ‘dkl’, ‘+’)#raise the elevation from the
isoluminant plane by 10 deg
setContrast(newContrast,operation=’‘,log=True)
” Set the contrast of the stimulus.
Parameters
144 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
newContrast [float] The contrast of the stimulus:
# 0.0 to 1.0 decreases contrast #Here
# 1.0 means unchanged
# 0.0 to -1.0 inverts with decreased contrast
# -1.0 means exactly inverted.
# >1.0 increases contrast. (See warning below)
# <-1.0 inverts with increased contrast (See warning below)
WARNING. Setting contrast below -1 or above 1 will produce strange results if this forces the stimulus
to blacker-than-black or whiter-than-white.
operation : one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setDKL(newDKL,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setDepth(newDepth,operation=’‘,log=True)
setFlip(direction,log=True)
(used by Builder to simplify the dialog)
setFlipHoriz(newVal=True,log=True)
If set to True then the text will be flipped horiztonally (left-to-right). Note that this is relative to the original,
not relative to the current state.
setFlipVert(newVal=True,log=True)
If set to True then the text will be flipped vertically (top-to-bottom). Note that this is relative to the original,
not relative to the current state.
setFont(font,log=True)
Set the font to be used for text rendering. font should be a string specifying the name of the font (in system
resources)
setHeight(height,log=True)
Set the height of the letters (including the entire box that surrounds the letters in the font). The width of
the letters is then defined by the font.
setLMS(newLMS,operation=’‘)
DEPRECATED since v1.60.05: Please use setColor
setOpacity(newOpacity,operation=’‘,log=True)
Set the opacity of the stimulus. :parameters: newOpacity: float between 0 (transparent) and 1 (opaque).
operation: one of ‘+’,’-‘,’*’,’/’, or ‘’ for no operation (simply replace value)
setOri(newOri,operation=’‘,log=True)
Set the stimulus orientation in degrees
setPos(newPos,operation=’‘,units=None,log=True)
Set the stimulus position in the specified (or inherited) units
setRGB(text,operation=’‘,log=True)
setSize(newSize,operation=’‘,units=None,log=True)
Set the stimulus size [X,Y] in the specified (or inherited) units
setText(text=None,log=True)
Set the text to be rendered using the current font
17.2. psychopy.visual - many visual stimuli 145
PsychoPy - Psychology software for Python, Release 1.78.00
setUseShaders(val=True)
Set this stimulus to use shaders if possible.
17.3 psychopy.data - functions for storing/saving/analysing data
Routines for handling data structures and analysis
17.3.1 ExperimentHandler
class psychopy.data.ExperimentHandler(name=’‘,version=’‘,extraInfo=None,runtime-
Info=None,originPath=None,savePickle=True,
saveWideText=True,dataFileName=’‘)
A container class for keeping track of multiple loops/handlers
Useful for generating a single data file from an experiment with many different loops (e.g. interleaved staircases
or loops within loops
Usage exp = data.ExperimentHandler(name=”Face Preference”,version=‘0.1.0’)
Parameters
name [a string or unicode] As a useful identifier later
version [usually a string (e.g. ‘1.1.0’)] To keep track of which version of the experiment was
run
extraInfo [a dictionary] Containing useful information about this run (e.g. {‘partici-
pant’:’jwp’,’gender’:’m’,’orientation’:90} )
runtimeInfo [psychopy.info.RunTimeInfo] Containining information about the sys-
tem as detected at runtime
originPath [string or unicode] The path and filename of the originating script/experiment If not
provided this will be determined as the path of the calling script.
dataFilename [string] This is defined in advance and the file will be saved at any point that the
handler is removed or discarded (unless .abort() had been called in advance). The handler
will attempt to populate the file even in the event of a (not too serious) crash!
abort()
Inform the ExperimentHandler that the run was aborted.
Experiment handler will attempt automatically to save data (even in the event of a crash if possible). So if
you quit your script early you may want to tell the Handler not to save out the data files for this run. This
is the method that allows you to do that.
addData(name,value)
Add the data with a given name to the current experiment.
Typically the user does not need to use this function; if you added your data to the loop and had already
added the loop to the experiment then the loop will automatically inform the experiment that it has received
data.
Multiple data name/value pairs can be added to any given entry of the data file and is considered part of
the same entry until the nextEntry() call is made.
e.g.:
146 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
#add some data for this trial
exp.addData(’resp.rt’,0.8)
exp.addData(’resp.key’,’k’)
#end of trial - move to next line in data output
exp.nextEntry()
addLoop(loopHandler)
Add a loop such as a TrialHandler or StairHandler Data from this loop will be included in the
resulting data files.
loopEnded(loopHandler)
Informs the experiment handler that the loop is finished and not to include its values in further entries of
the experiment.
This method is called by the loop itself if it ends its iterations, so is not typically needed by the user.
nextEntry()
Calling nextEntry indicates to the ExperimentHandler that the current trial has ended and so further ad-
dData() calls correspond to the next trial.
saveAsPickle(fileName,fileCollisionMethod=’rename’)
Basically just saves a copy of self (with data) to a pickle file.
This can be reloaded if necessary and further analyses carried out.
Parameters fileCollisionMethod: Collision method passed to _handleFileCollision()
saveAsWideText(fileName,delim=None,matrixOnly=False,appendFile=False)
Saves a long, wide-format text file, with one line representing the attributes and data for a single trial.
Suitable for analysis in R and SPSS.
If appendFile=True then the data will be added to the bottom of an existing file. Otherwise, if the file
exists already it will be overwritten
If matrixOnly=True then the file will not contain a header row, which can be handy if you want to append
data to an existing file of the same format.
17.3.2 TrialHandler
class psychopy.data.TrialHandler(trialList,nReps,method=’random’,dataTypes=None,ex-
traInfo=None,seed=None,originPath=None,name=’‘)
Class to handle trial sequencing and data storage.
Calls to .next() will fetch the next trial object given to this handler, according to the method specified (random,
sequential, fullRandom). Calls will raise a StopIteration error if trials have finished.
See demo_trialHandler.py
The psydat file format is literally just a pickled copy of the TrialHandler object that saved it. You can open it
with:
from psychopy import misc
dat =misc.fromFile(path)
Then you’ll find that dat has the following attributes that
Parameters
trialList: a simple list (or flat array) of dictionaries specifying conditions This can be im-
ported from an excel/csv file using importConditions()
nReps: number of repeats for all conditions
17.3. psychopy.data - functions for storing/saving/analysing data 147
PsychoPy - Psychology software for Python, Release 1.78.00
method: ‘random’, ‘sequential’, or ‘fullRandom’ ‘sequential’ obviously presents the condi-
tions in the order they appear in the list. ‘random’ will result in a shuffle of the conditions
on each repeat, but all conditions occur once before the second repeat etc. ‘fullRandom’
fully randomises the trials across repeats as well, which means you could potentially run all
trials of one condition before any trial of another.
dataTypes: (optional) list of names for data storage. e.g. [’corr’,’rt’,’resp’] If not provided
then these will be created as needed during calls to addData()
extraInfo: A dictionary This will be stored alongside the data and usually describes the exper-
iment and subject ID, date etc.
seed: an integer If provided then this fixes the random number generator to use the same pat-
tern of trials, by seeding its startpoint
originPath: a string describing the location of the script/experiment file path The psydat
file format will store a copy of the experiment if possible. If no file path is provided here
then the TrialHandler will still store a copy of the script where it was created
Attributes (after creation) .data - a dictionary of numpy arrays, one for each data type stored
.trialList - the original list of dicts, specifying the conditions
.thisIndex - the index of the current trial in the original conditions list
.nTotal - the total number of trials that will be run
.nRemaining - the total number of trials remaining
.thisN - total trials completed so far
.thisRepN - which repeat you are currently on
.thisTrialN - which trial number within that repeat
.thisTrial - a dictionary giving the parameters of the current trial
.finished - True/False for have we finished yet
.extraInfo - the dictionary of extra info as given at beginning
.origin - the contents of the script or builder experiment that created the handler
addData(thisType,value,position=None)
Add data for the current trial
getEarlierTrial(n=-1)
Returns the condition information from n trials previously. Useful for comparisons in n-back tasks. Returns
‘None’ if trying to access a trial prior to the first.
getExp()
Return the ExperimentHandler that this handler is attached to, if any. Returns None if not attached
getFutureTrial(n=1)
Returns the condition for n trials into the future, without advancing the trials. Returns ‘None’ if attempting
to go beyond the last trial.
getOriginPathAndFile(originPath=None)
Attempts to determine the path of the script that created this data file and returns both the path to that script
and it’s contents. Useful to store the entire experiment with the data.
If originPath is provided (e.g. from Builder) then this is used otherwise the calling script is the originPath
(fine from a standard python script).
148 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
next()
Advances to next trial and returns it. Updates attributes; thisTrial, thisTrialN and thisIndex If the trials
have ended this method will raise a StopIteration error. This can be handled with code such as:
trials = data.TrialHandler(.......)
for eachTrial in trials:#automatically stops when done
#do stuff
or:
trials = data.TrialHandler(.......)
while True: #ie forever
try:
thisTrial = trials.next()
except StopIteration:#we got a StopIteration error
break #break out of the forever loop
#do stuff here for the trial
nextTrial()
DEPRECATION WARNING: nextTrial() will be deprecated please use next() instead. jwp: 19/6/06
printAsText(stimOut=[],dataOut=(‘all_mean’,‘all_std’,‘all_raw’),delim=’t’,ma-
trixOnly=False)
Exactly like saveAsText() except that the output goes to the screen instead of a file
saveAsExcel(fileName,sheetName=’rawData’,stimOut=[],dataOut=(‘n’,‘all_mean’,‘all_std’,
‘all_raw’),matrixOnly=False,appendFile=True)
Save a summary data file in Excel OpenXML format workbook (xlsx) for processing in most spreadsheet
packages. This format is compatible with versions of Excel (2007 or greater) and and with OpenOffice
(>=3.0).
It has the advantage over the simpler text files (see TrialHandler.saveAsText() ) that data can be
stored in multiple named sheets within the file. So you could have a single file named after your experiment
and then have one worksheet for each participant. Or you could have one file for each participant and then
multiple sheets for repeated sessions etc.
The file extension .xlsx will be added if not given already.
Parameters
fileName: string the name of the file to create or append. Can include relative or absolute
path
sheetName: string the name of the worksheet within the file
stimOut: list of strings the attributes of the trial characteristics to be output. To use this
you need to have provided a list of dictionaries specifying to trialList parameter of the
TrialHandler and give here the names of strings specifying entries in that dictionary
dataOut: list of strings specifying the dataType and the analysis to be performed, in the
form dataType_analysis. The data can be any of the types that you added using trialHan-
dler.data.add() and the analysis can be either ‘raw’ or most things in the numpy library,
including ‘mean’,’std’,’median’,’max’,’min’. e.g. rt_max will give a column of max reac-
tion times across the trials assuming that rt values have been stored. The default values
will output the raw, mean and std of all datatypes found
appendFile: True or False If False any existing file with this name will be overwritten. If
True then a new worksheet will be appended. If a worksheet already exists with that name
a number will be added to make it unique.
saveAsPickle(fileName,fileCollisionMethod=’rename’)
Basically just saves a copy of the handler (with data) to a pickle file.
17.3. psychopy.data - functions for storing/saving/analysing data 149
PsychoPy - Psychology software for Python, Release 1.78.00
This can be reloaded if necessesary and further analyses carried out.
Parameters fileCollisionMethod: Collision method passed to _handleFileCollision()
saveAsText(fileName,stimOut=[],dataOut=(‘n’,‘all_mean’,‘all_std’,‘all_raw’),delim=None,ma-
trixOnly=False,appendFile=True,summarised=True)
Write a text file with the data and various chosen stimulus attributes
Parameters
fileName: will have .dlm appended (so you can double-click it to open in excel) and can
include path info.
stimOut: the stimulus attributes to be output. To use this you need to use a list of dictionaries
and give here the names of dictionary keys that you want as strings
dataOut: a list of strings specifying the dataType and the analysis to be performed,in the
form dataType_analysis. The data can be any of the types that you added using trialHan-
dler.data.add() and the analysis can be either ‘raw’ or most things in the numpy library,
including; ‘mean’,’std’,’median’,’max’,’min’... The default values will output the raw,
mean and std of all datatypes found
delim: allows the user to use a delimiter other than tab (”,” is popular with file extension
”.csv”)
matrixOnly: outputs the data with no header row or extraInfo attached
appendFile: will add this output to the end of the specified file if it already exists
saveAsWideText(fileName,delim=’t’,matrixOnly=False,appendFile=True)
Write a text file with the session, stimulus, and data values from each trial in chronological order.
That is, unlike ‘saveAsText’ and ‘saveAsExcel’:
• each row comprises information from only a single trial.
• no summarising is done (such as collapsing to produce mean and standard deviation values across
trials).
This ‘wide’ format, as expected by R for creating dataframes, and various other analysis programs, means
that some information must be repeated on every row.
In particular, if the trialHandler’s ‘extraInfo’ exists, then each entry in there occurs in every row. In builder,
this will include any entries in the ‘Experiment info’ field of the ‘Experiment settings’ dialog. In Coder,
this information can be set using something like:
myTrialHandler.extraInfo = {’SubjID’:’Joan Smith’, ’DOB’:1970 Nov 16, ’Group’:’Control’}
Parameters
fileName: if extension is not specified, ‘.csv’ will be appended if the delimiter is ‘,’, else
‘.txt’ will be appended. Can include path info.
delim: allows the user to use a delimiter other than the default tab (”,” is popular with file
extension ”.csv”)
matrixOnly: outputs the data with no header row.
appendFile: will add this output to the end of the specified file if it already exists.
setExp(exp)
Sets the ExperimentHandler that this handler is attached to
Do NOT attempt to set the experiment using:
150 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
trials._exp =myExperiment
because it needs to be performed using the weakref module.
17.3.3 StairHandler
class psychopy.data.StairHandler(startVal,nReversals=None,stepSizes=4,nTrials=0,nUp=1,
nDown=3,extraInfo=None,method=‘2AFC’,stepType=’db’,
minVal=None,maxVal=None,originPath=None,name=’‘)
Class to handle smoothly the selection of the next trial and report current values etc. Calls to nextTrial() will
fetch the next object given to this handler, according to the method specified.
See demo_trialHandler.py
The staircase will terminate when nTrials AND nReversals have been exceeded. If stepSizes was an array and
has been exceeded before nTrials is exceeded then the staircase will continue to reverse
Parameters
startVal: The initial value for the staircase.
nReversals: The minimum number of reversals permitted. If stepSizes is a list then there must
also be enough reversals to satisfy this list.
stepSizes: The size of steps as a single value or a list (or array). For a single value the step size
is fixed. For an array or list the step size will progress to the next entry at each reversal.
nTrials: The minimum number of trials to be conducted. If the staircase has not reached the
required number of reversals then it will continue.
nUp: The number of ‘incorrect’ (or 0) responses before the staircase level increases.
nDown: The number of ‘correct’ (or 1) responses before the staircase level decreases.
extraInfo: A dictionary (typically) that will be stored along with collected data using
saveAsPickle() or saveAsText() methods.
stepType: specifies whether each step will be a jump of the given size in ‘db’, ‘log’ or ‘lin’
units (‘lin’ means this intensity will be added/subtracted)
method: Not used and may be deprecated in future releases.
stepType: ‘db’, ‘lin’, ‘log’ The type of steps that should be taken each time. ‘lin’ will simply
add or subtract that amount each step, ‘db’ and ‘log’ will step by a certain number of decibels
or log units (note that this will prevent your value ever reaching zero or less)
minVal: None, or a number The smallest legal value for the staircase, which can be used to
prevent it reaching impossible contrast values, for instance.
maxVal: None, or a number The largest legal value for the staircase, which can be used to
prevent it reaching impossible contrast values, for instance.
addData(result,intensity=None)
Add a 1 or 0 to signify a correct/detected or incorrect/missed trial
This is essential to advance the staircase to a new intensity level!
Supplying an intensity value here indicates that you did not use the recommended intensity in your last
trial and the staircase will replace its recorded value with the one you supplied here.
calculateNextIntensity()
based on current intensity, counter of correct responses and current direction
17.3. psychopy.data - functions for storing/saving/analysing data 151
PsychoPy - Psychology software for Python, Release 1.78.00
getExp()
Return the ExperimentHandler that this handler is attached to, if any. Returns None if not attached
getOriginPathAndFile(originPath=None)
Attempts to determine the path of the script that created this data file and returns both the path to that script
and it’s contents. Useful to store the entire experiment with the data.
If originPath is provided (e.g. from Builder) then this is used otherwise the calling script is the originPath
(fine from a standard python script).
next()
Advances to next trial and returns it. Updates attributes; thisTrial,thisTrialN and thisIndex.
If the trials have ended, calling this method will raise a StopIteration error. This can be handled with code
such as:
staircase = data.StairHandler(.......)
for eachTrial in staircase:#automatically stops when done
#do stuff
or:
staircase = data.StairHandler(.......)
while True: #ie forever
try:
thisTrial = staircase.next()
except StopIteration:#we got a StopIteration error
break #break out of the forever loop
#do stuff here for the trial
nextTrial()
DEPRECATION WARNING: nextTrial() will be deprecated please use next() instead. jwp: 19/6/06
printAsText(stimOut=[],dataOut=(‘all_mean’,‘all_std’,‘all_raw’),delim=’t’,ma-
trixOnly=False)
Exactly like saveAsText() except that the output goes to the screen instead of a file
saveAsExcel(fileName,sheetName=’data’,matrixOnly=False,appendFile=True)
Save a summary data file in Excel OpenXML format workbook (xlsx) for processing in most spreadsheet
packages. This format is compatible with versions of Excel (2007 or greater) and and with OpenOffice
(>=3.0).
It has the advantage over the simpler text files (see TrialHandler.saveAsText() ) that data can be
stored in multiple named sheets within the file. So you could have a single file named after your experiment
and then have one worksheet for each participant. Or you could have one file for each participant and then
multiple sheets for repeated sessions etc.
The file extension .xlsx will be added if not given already.
The file will contain a set of values specifying the staircase level (‘intensity’) at each reversal, a list of
reversal indices (trial numbers), the raw staircase/intensity level on every trial and the corresponding re-
sponses of the participant on every trial.
Parameters
fileName: string the name of the file to create or append. Can include relative or absolute
path
sheetName: string the name of the worksheet within the file
matrixOnly: True or False If set to True then only the data itself will be output (no addi-
tional info)
152 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
appendFile: True or False If False any existing file with this name will be overwritten. If
True then a new worksheet will be appended. If a worksheet already exists with that name
a number will be added to make it unique.
saveAsPickle(fileName)
Basically just saves a copy of self (with data) to a pickle file.
This can be reloaded if necess and further analyses carried out.
saveAsText(fileName,delim=’t’,matrixOnly=False)
Write a text file with the data
Parameters
fileName: a string The name of the file, including path if needed. The extension .dlm will
be added if not included.
delim: a string the delimitter to be used (e.g. ‘ ‘ for tab-delimitted, ‘,’ for csv files)
matrixOnly: True/False If True, prevents the output of the extraInfo provided at initialisa-
tion.
setExp(exp)
Sets the ExperimentHandler that this handler is attached to
Do NOT attempt to set the experiment using:
trials._exp =myExperiment
because it needs to be performed using the weakref module.
17.3.4 MultiStairHandler
class psychopy.data.MultiStairHandler(stairType=’simple’,method=’random’,condi-
tions=None,nTrials=50,originPath=None,name=’‘)
A Handler to allow easy interleaved staircase procedures (simple or QUEST).
Parameters for the staircases, as used by the relevant StairHandler or QuestHandler (e.g. the startVal,
minVal,maxVal...) should be specified in the conditions list and may vary between each staircase. In particular,
the conditions /must/ include the a startVal (because this is a required argument to the above handlers) a label to
tag the staircase and a startValSd (only for QUEST staircases). Any parameters not specified in the conditions
file will revert to the default for that individual handler.
If you need to custom the behaviour further you may want to look at the recipe on interleavedStairs.
Params
stairType: ‘simple’ or ‘quest’ Use a StairHandler or QuestHandler
method: ‘random’ or ‘sequential’ The stairs are shuffled in each repeat but not randomised
more than that (so you can’t have 3 repeats of the same staircase in a row unless it’s the only
one still running)
conditions: a list of dictionaries specifying conditions Can be used to control parameters
for the different staicases. Can be imported from an Excel file using psy-
chopy.data.importTrialTypes MUST include keys providing, ‘startVal’, ‘label’ and ‘start-
ValSd’ (QUEST only). The ‘label’ will be used in data file saving so should be unique. See
Example Usage below.
nTrials=50 Minimum trials to run (but may take more if the staircase hasn’t also met its minimal
reversals. See StairHandler
17.3. psychopy.data - functions for storing/saving/analysing data 153
PsychoPy - Psychology software for Python, Release 1.78.00
Example usage:
conditions=[
{’label’:’low’,’startVal’:0.1,’ori’:45},
{’label’:’high’,’startVal’:0.8,’ori’:45},
{’label’:’low’,’startVal’:0.1,’ori’:90},
{’label’:’high’,’startVal’:0.8,’ori’:90},
]
stairs =data.MultiStairHandler(conditions=conditions, nTrials=50)
for thisIntensity, thisCondition in stairs:
thisOri =thisCondition[’ori’]
#do something with thisIntensity and thisOri
stairs.addData(correctIncorrect)#this is ESSENTIAL
#save data as multiple formats
stairs.saveDataAsExcel(fileName)#easy to browse
stairs.saveAsPickle(fileName)#contains more info
addData(result,intensity=None)
Add a 1 or 0 to signify a correct/detected or incorrect/missed trial
This is essential to advance the staircase to a new intensity level!
getExp()
Return the ExperimentHandler that this handler is attached to, if any. Returns None if not attached
getOriginPathAndFile(originPath=None)
Attempts to determine the path of the script that created this data file and returns both the path to that script
and it’s contents. Useful to store the entire experiment with the data.
If originPath is provided (e.g. from Builder) then this is used otherwise the calling script is the originPath
(fine from a standard python script).
next()
Advances to next trial and returns it.
This can be handled with code such as:
staircase = data.MultiStairHandler(.......)
for eachTrial in staircase:#automatically stops when done
#do stuff here for the trial
or:
staircase = data.MultiStairHandler(.......)
while True: #ie forever
try:
thisTrial = staircase.next()
except StopIteration:#we got a StopIteration error
break #break out of the forever loop
#do stuff here for the trial
nextTrial()
DEPRECATION WARNING: nextTrial() will be deprecated please use next() instead. jwp: 19/6/06
printAsText(delim=’t’,matrixOnly=False)
Write the data to the standard output stream
Parameters
154 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
delim: a string the delimitter to be used (e.g. ‘ ‘ for tab-delimitted, ‘,’ for csv files)
matrixOnly: True/False If True, prevents the output of the extraInfo provided at initialisa-
tion.
saveAsExcel(fileName,matrixOnly=False,appendFile=False)
Save a summary data file in Excel OpenXML format workbook (xlsx) for processing in most spreadsheet
packages. This format is compatible with versions of Excel (2007 or greater) and and with OpenOffice
(>=3.0).
It has the advantage over the simpler text files (see TrialHandler.saveAsText() ) that the data
from each staircase will be save in the same file, with the sheet name coming from the ‘label’ given in the
dictionary of conditions during initialisation of the Handler.
The file extension .xlsx will be added if not given already.
The file will contain a set of values specifying the staircase level (‘intensity’) at each reversal, a list of
reversal indices (trial numbers), the raw staircase/intensity level on every trial and the corresponding re-
sponses of the participant on every trial.
Parameters
fileName: string the name of the file to create or append. Can include relative or absolute
path
matrixOnly: True or False If set to True then only the data itself will be output (no addi-
tional info)
appendFile: True or False If False any existing file with this name will be overwritten. If
True then a new worksheet will be appended. If a worksheet already exists with that name
a number will be added to make it unique.
saveAsPickle(fileName)
Saves a copy of self (with data) to a pickle file.
This can be reloaded later and further analyses carried out.
saveAsText(fileName,delim=’t’,matrixOnly=False)
Write out text files with the data.
For MultiStairHandler this will output one file for each staircase that was run, with _label added to the
fileName that you specify above (label comes from the condition dictionary you specified when you created
the Handler).
Parameters
fileName: a string The name of the file, including path if needed. The extension .dlm will
be added if not included.
delim: a string the delimitter to be used (e.g. ‘ ‘ for tab-delimitted, ‘,’ for csv files)
matrixOnly: True/False If True, prevents the output of the extraInfo provided at initialisa-
tion.
setExp(exp)
Sets the ExperimentHandler that this handler is attached to
Do NOT attempt to set the experiment using:
trials._exp =myExperiment
because it needs to be performed using the weakref module.
17.3. psychopy.data - functions for storing/saving/analysing data 155
PsychoPy - Psychology software for Python, Release 1.78.00
17.3.5 QuestHandler
class psychopy.data.QuestHandler(startVal,startValSd,pThreshold=0.82,nTrials=None,stopIn-
terval=None,method=’quantile’,stepType=’log’,beta=3.5,
delta=0.01,gamma=0.5,grain=0.01,range=None,ex-
traInfo=None,minVal=None,maxVal=None,staircase=None,
originPath=None,name=’‘)
Class that implements the Quest algorithm for quick measurement of psychophysical thresholds.
Uses Andrew Straw’s QUEST, which is a Python port of Denis Pelli’s Matlab code.
Measures threshold using a Weibull psychometric function. Currently, it is not possible to use a different psy-
chometric function.
Threshold ‘t’ is measured on an abstract ‘intensity’ scale, which usually corresponds to log10 contrast.
The Weibull psychometric function:
p2=delta*gamma+(1-delta)*(1-(1-gamma)*exp(-10**(beta*(x2+xThreshold))))
Example:
# setup display/window
...
# create stimulus
stimulus =visual.RadialStim(win=win, tex=’sinXsin’, size=1, pos=[0,0], units=’deg’)
...
# create staircase object
# trying to find out the point where subject’s response is 50/50
# if wanted to do a 2AFC then the defaults for pThreshold and gamma are good
staircase =data.QuestHandler(staircase._nextIntensity, 0.2, pThreshold=0.63, gamma=0.01,
nTrials=20, minVal=0, maxVal=1)
...
while thisContrast in staircase:
# setup stimulus
stimulus.setContrast(thisContrast)
stimulus.draw()
win.flip()
core.wait(0.5)
# get response
...
# inform QUEST of the response, needed to calculate next level
staircase.addData(thisResp)
...
# can now access 1 of 3 suggested threshold levels
staircase.mean()
staircase.mode()
staircase.quantile() #gets the median
Typical values for pThreshold are:
• 0.82 which is equivalent to a 3 up 1 down standard staircase
• 0.63 which is equivalent to a 1 up 1 down standard staircase (and might want gamma=0.01)
The variable(s) nTrials and/or stopSd must be specified.
beta,delta, and gamma are the parameters of the Weibull psychometric function.
Parameters
startVal: Prior threshold estimate or your initial guess threshold.
156 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
startValSd: Standard deviation of your starting guess threshold. Be generous with the sd as
QUEST will have trouble finding the true threshold if it’s more than one sd from your initial
guess.
pThreshold Your threshold criterion expressed as probability of response==1. An intensity
offset is introduced into the psychometric function so that the threshold (i.e., the midpoint
of the table) yields pThreshold..
nTrials: None or a number The maximum number of trials to be conducted.
stopInterval: None or a number The minimum 5-95% confidence interval required in the
threshold estimate before stopping. If both this and nTrials is specified, whichever happens
first will determine when Quest will stop.
method: ‘quantile’, ‘mean’, ‘mode’ The method used to determine the next threshold to test.
If you want to get a specific threshold level at the end of your staircasing, please use the
quantile, mean, and mode methods directly.
stepType: ‘log’, ‘db’, ‘lin’ The type of steps that should be taken each time. ‘db’ and ‘log’ will
transform your intensity levels into decibels or log units and will move along the psycho-
metric function with these values.
beta: 3.5 or a number Controls the steepness of the psychometric function.
delta: 0.01 or a number The fraction of trials on which the observer presses blindly.
gamma: 0.5 or a number The fraction of trials that will generate response 1 when intensity=-
Inf.
grain: 0.01 or a number The quantization of the internal table.
range: None, or a number The intensity difference between the largest and smallest intensity
that the internal table can store. This interval will be centered on the initial guess tGuess.
QUEST assumes that intensities outside of this range have zero prior probability (i.e., they
are impossible).
extraInfo: A dictionary (typically) that will be stored along with collected data using
saveAsPickle() or saveAsText() methods.
minVal: None, or a number The smallest legal value for the staircase, which can be used to
prevent it reaching impossible contrast values, for instance.
maxVal: None, or a number The largest legal value for the staircase, which can be used to
prevent it reaching impossible contrast values, for instance.
staircase: None or StairHandler Can supply a staircase object with intensities and results.
Might be useful to give the quest algorithm more information if you have it. You can also
call the importData function directly.
addData(result,intensity=None)
Add a 1 or 0 to signify a correct/detected or incorrect/missed trial
Supplying an intensity value here indicates that you did not use the recommended intensity in your last
trial and the staircase will replace its recorded value with the one you supplied here.
calculateNextIntensity()
based on current intensity and counter of correct responses
confInterval(getDifference=False)
give the range of the 5-95% confidence interval
getExp()
Return the ExperimentHandler that this handler is attached to, if any. Returns None if not attached
17.3. psychopy.data - functions for storing/saving/analysing data 157
PsychoPy - Psychology software for Python, Release 1.78.00
getOriginPathAndFile(originPath=None)
Attempts to determine the path of the script that created this data file and returns both the path to that script
and it’s contents. Useful to store the entire experiment with the data.
If originPath is provided (e.g. from Builder) then this is used otherwise the calling script is the originPath
(fine from a standard python script).
importData(intensities,results)
import some data which wasn’t previously given to the quest algorithm
incTrials(nNewTrials)
increase maximum number of trials Updates attribute: nTrials
mean()
mean of Quest posterior pdf
mode()
mode of Quest posterior pdf
next()
Advances to next trial and returns it. Updates attributes; thisTrial,thisTrialN,thisIndex,finished,intensities
If the trials have ended, calling this method will raise a StopIteration error. This can be handled with code
such as:
staircase = data.QuestHandler(.......)
for eachTrial in staircase:#automatically stops when done
#do stuff
or:
staircase = data.QuestHandler(.......)
while True: #ie forever
try:
thisTrial = staircase.next()
except StopIteration:#we got a StopIteration error
break #break out of the forever loop
#do stuff here for the trial
nextTrial()
DEPRECATION WARNING: nextTrial() will be deprecated please use next() instead. jwp: 19/6/06
printAsText(stimOut=[],dataOut=(‘all_mean’,‘all_std’,‘all_raw’),delim=’t’,ma-
trixOnly=False)
Exactly like saveAsText() except that the output goes to the screen instead of a file
quantile(p=None)
quantile of Quest posterior pdf
saveAsExcel(fileName,sheetName=’data’,matrixOnly=False,appendFile=True)
Save a summary data file in Excel OpenXML format workbook (xlsx) for processing in most spreadsheet
packages. This format is compatible with versions of Excel (2007 or greater) and and with OpenOffice
(>=3.0).
It has the advantage over the simpler text files (see TrialHandler.saveAsText() ) that data can be
stored in multiple named sheets within the file. So you could have a single file named after your experiment
and then have one worksheet for each participant. Or you could have one file for each participant and then
multiple sheets for repeated sessions etc.
The file extension .xlsx will be added if not given already.
158 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
The file will contain a set of values specifying the staircase level (‘intensity’) at each reversal, a list of
reversal indices (trial numbers), the raw staircase/intensity level on every trial and the corresponding re-
sponses of the participant on every trial.
Parameters
fileName: string the name of the file to create or append. Can include relative or absolute
path
sheetName: string the name of the worksheet within the file
matrixOnly: True or False If set to True then only the data itself will be output (no addi-
tional info)
appendFile: True or False If False any existing file with this name will be overwritten. If
True then a new worksheet will be appended. If a worksheet already exists with that name
a number will be added to make it unique.
saveAsPickle(fileName)
Basically just saves a copy of self (with data) to a pickle file.
This can be reloaded if necess and further analyses carried out.
saveAsText(fileName,delim=’t’,matrixOnly=False)
Write a text file with the data
Parameters
fileName: a string The name of the file, including path if needed. The extension .dlm will
be added if not included.
delim: a string the delimitter to be used (e.g. ‘ ‘ for tab-delimitted, ‘,’ for csv files)
matrixOnly: True/False If True, prevents the output of the extraInfo provided at initialisa-
tion.
sd()
standard deviation of Quest posterior pdf
setExp(exp)
Sets the ExperimentHandler that this handler is attached to
Do NOT attempt to set the experiment using:
trials._exp =myExperiment
because it needs to be performed using the weakref module.
simulate(tActual)
returns a simulated user response to the next intensity level presented by Quest, need to supply the actual
threshold level
17.3.6 FitWeibull
class psychopy.data.FitWeibull(xx,yy,sems=1.0,guess=None,display=1,expectedMin=0.5)
Fit a Weibull function (either 2AFC or YN) of the form:
y=chance +(1.0-chance)*(1-exp( -(xx/alpha)**(beta) ))
and with inverse:
17.3. psychopy.data - functions for storing/saving/analysing data 159
PsychoPy - Psychology software for Python, Release 1.78.00
x=alpha *(-log((1.0-y)/(1-chance)))**(1.0/beta)
After fitting the function you can evaluate an array of x-values with fit.eval(x), retrieve the inverse of
the function with fit.inverse(y) or retrieve the parameters from fit.params (a list with [alpha,
beta])
eval(xx=None,params=None)
inverse(yy,params=None)
17.3.7 FitLogistic
class psychopy.data.FitLogistic(xx,yy,sems=1.0,guess=None,display=1,expectedMin=0.5)
Fit a Logistic function (either 2AFC or YN) of the form:
y=chance +(1-chance)/(1+exp((PSE-xx)*JND))
and with inverse:
x=PSE -log((1-chance)/(yy-chance) -1)/JND
After fitting the function you can evaluate an array of x-values with fit.eval(x), retrieve the inverse of the
function with fit.inverse(y) or retrieve the parameters from fit.params (a list with [PSE, JND])
eval(xx=None,params=None)
inverse(yy,params=None)
17.3.8 FitNakaRushton
class psychopy.data.FitNakaRushton(xx,yy,sems=1.0,guess=None,display=1)
Fit a Naka-Rushton function of the form:
yy =rMin +(rMax-rMin) *xx**n/(xx**n+c50**n)
After fitting the function you can evaluate an array of x-values with fit.eval(x), retrieve the inverse of the
function with fit.inverse(y) or retrieve the parameters from fit.params (a list with [rMin, rMax,
c50, n])
Note that this differs from most of the other functions in not using a value for the expected minimum. Rather, it
fits this as one of the parameters of the model.
eval(xx=None,params=None)
inverse(yy,params=None)
17.3.9 FitCumNormal
class psychopy.data.FitCumNormal(xx,yy,sems=1.0,guess=None,display=1,expectedMin=0.5)
Fit a Cumulative Normal function (aka error function or erf) of the form:
y=chance +(1-chance)*(special.erf(xx*xScale -xShift)/2.0+0.5)
and with inverse:
x=(erfinv((yy-chance)/(1-chance)*2.0-1)+xShift)/xScale
160 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
After fitting the function you can evaluate an array of x-values with fit.eval(x), retrieve the inverse of the function
with fit.inverse(y) or retrieve the parameters from fit.params (a list with [centre, sd] for the Gaussian distribution
forming the cumulative)
NB: Prior to version 1.74 the parameters had different meaning, relating to xShift and slope of the function
(similar to 1/sd). Although that is more in with the parameters for the Weibull fit, for instance, it is less in
keeping with standard expectations of normal (Gaussian distributions) so in version 1.74.00 the parameters
became the [centre,sd] of the normal distribution.
eval(xx=None,params=None)
inverse(yy,params=None)
17.3.10 importConditions()
psychopy.data.importConditions(fileName,returnFieldNames=False)
Imports a list of conditions from an .xlsx, .csv, or .pkl file
The output is suitable as an input to TrialHandler trialTypes or to MultiStairHandler as a conditions
list.
If fileName ends with:
• .csv: import as a comma-separated-value file (header + row x col)
• .xlsx: import as Excel 2007 (xlsx) files. Sorry no support for older (.xls) is planned.
• .pkl: import from a pickle file as list of lists (header + row x col)
The file should contain one row per type of trial needed and one column for each parameter that defines the trial
type. The first row should give parameter names, which should:
•be unique
•begin with a letter (upper or lower case)
•contain no spaces or other punctuation (underscores are permitted)
17.3.11 functionFromStaircase()
psychopy.data.functionFromStaircase(intensities,responses,bins=10)
Create a psychometric function by binning data from a staircase procedure
usage:
[intensity, meanCorrect, n] =functionFromStaircase(intensities, responses, bins)
where:
intensities are a list of intensities to be binned
responses are a list of 0,1 each corresponding to the equivalent intensity value
bins can be an integer (giving that number of bins) or ‘unique’ (where each bin is made from ALL data
for exactly one intensity value)
intensity is the center of an intensity bin
meanCorrect is mean % correct in that bin
nis number of responses contributing to that mean
17.3. psychopy.data - functions for storing/saving/analysing data 161
PsychoPy - Psychology software for Python, Release 1.78.00
17.3.12 bootStraps()
psychopy.data.bootStraps(dat,n=1)
Create a list of n bootstrapped resamples of the data
SLOW IMPLEMENTATION (Python for-loop)
Usage: out = bootStraps(dat, n=1)
Where:
dat an NxM or 1xN array (each row is a different condition, each column is a different trial)
nnumber of bootstrapped resamples to create
out
• dim[0]=conditions
• dim[1]=trials
• dim[2]=resamples
17.4 psychopy.contrib.opensslwrap Encryption (beta)
17.4.1 Overview
Aim: Better protect psychology and neuroscience lab information from casual inspection or accidental disclosure,
using public-key encryption for security and flexibility.
Example use-case: Encrypt a data file on a testing-room computer for better privacy and data integrity, before moving
or archiving it. Do so from wihtin PsychoPy, without ever needing to be able to decrypt on the same computer or store
a decryption password in an archive.
Encryption involves some special considerations that are not relevant to other aspects of PsychoPy. Perhaps the most
important thing to note is that, depending on your circumstances, the use of encryption can conflict with policies of
your boss or institution (or even government). You are responsible for knowing your situation, and for the conse-
quences of your decisions about whether and how to use encryption.
NOTICE A much improved version of opensslwrap is available as a separate python package called pyFileSec, which
is directly based on opensslwrap but goes far beyond it. pyFileSec is under active developement and will soon be
integrated with PsychoPy. For this reason, opensslwrap should not be used for new projects, and will be retained in
PsychoPy only for backwards compatibility and only for a short while.
Status & Caveats: As of April 2012, this is beta software, made available for evaluation and testing purposes. All
feedback can be posted to the psychopy-dev list.
The built-in tests can be run from the command line:
$ python opensslwrap.py
or save the output to a log file (not sure about Windows syntax for this):
$ python opensslwrap.py >& test.log
They can also be run from the PsychoPy test-suite (under testContrib).
Reports of failed tests are especially welcome, as are ideas for other tests, or questions or comments about the doc-
umentation (below). Reports of successful tests with information about the operating system are also useful. The
command line tests are designed to work without requiring that psychopy be installed.
162 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
If the test output ends with “test SUCCESS, reporting complete”, that’s a success. (If the testContrib test-battery
passes from the PsychoPy test-suite, that is also success.) Note that some of the tests are designed to check error
situations; i.e., what is being tested is that situations that should fail, do fail, and are recognized as failure situations.
This means that you should see some things that look exactly like error messages along the way (e.g., “RSA operation
error”); the key thing is seeing SUCCESS at the end.
If you venture beyond running the test-suite, which is certainly encouraged, please do so for testing purposes, not for
mission-critical applications. To try it out, you will need at least one RSA key pair. (For the test-suite, key pairs are
auto-generated and then deleted). A hint for the curious: “openssl genrsa –help”, or look through the test code, and
then do your homework. For high-quality keys, PGP or GnuPG are better.
You should not assume that it will meet HIPAA, FIPS 140-2, or some other requirement. There’s been no proper
security audit at this point; the effective level of security is currently best described as “unknown”. The aim is that the
encryption will be effective for the purpose of data transfer and storage within a lab, and assumes that a) the data have
low economic value data, and b) the lab has reasonable physical and network security, and has only trusted people
working there.
The encryption is definitely strong enough to cause trouble if used incorrectly. Consider an example: Although you
can lock yourself out of your own car, you can hire someone with training and special tools to break in on your behalf.
With encryption, however, it would likely be prohibitively expensive to hire someone to break in on your behalf, and
might not be possible. So you could actually lose your data by trying to secure it. Please also note that, for better
security, the default behavior is to delete the unencrypted original file (it can be retained, as an option; see Example 2
below).
Security strategy: The methods provided rely only on the widely used software package, OpenSSL, us-
ing its implementation of RSA and AES (which are industry standards). Many people are invested
in making OpenSSL robust, and one specific version of OpenSSL has received FIPS 140-2 certification
(http://www.openssl.org/docs/fips/fipsnotes.html). The effective weak link is almost certainly not cryptographic but
rather in how the encryption key(s) are handled, which partly depends on you, including generation, signing, storage,
backup. (For what its worth: the cryptographic weak link is the RSA public key, especially because: 1) key verification
is not attempted, and 2) you, as the user, can provide keys of varying strengths, including key length, entropy quality,
provenance, handling.) If the keys are bad or compromised, the encryption strength is basically irrelevant.
Using a public-key as part of encryption allows a non-secret “password” (the public key) to be distributed for en-
cryption. This separates encryption from decryption, allowing logical and physical separation, giving considerable
flexibility. The idea is that anyone anywhere can encrypt information that only a trusted process (with access to the
private keys) can decrypt. Anyone anywhere can know the process used to achieve the encryption without compro-
mising the achievable degree of security. Its the private key that is essential to keep private.
Some considerations:
• Tests are provided as part of the library. To run all tests, run “python opensslwrap.py” from the command line.
This should work on machines with python 2.5+ and openssl 0.9.8+.
• OpenSSL is not distributed as part of the library. You need to obtain it separately (and may already have it; see
Installation, below).
• Encrypt and decrypt only on trusted machines, with access limited to trusted people.
• By design, the computer used for encryption can be different from the computer used for decryption; it can be a
different device, operating system, and openssl version.
• “Best practice” is not to move your private key from the machine on which it was generated; certainly never
ever email it. Its fine to share the public key.
• Some good advice from GnuPG: “If your system allows for encrypted swap partitions, please make use of that
feature.”
Usage Examples:
In general items are given as the name of a file, not as the item itself.
17.4. psychopy.contrib.opensslwrap Encryption (beta) 163
PsychoPy - Psychology software for Python, Release 1.78.00
1. Encrypt a plaintext file named data, using a .pem format RSA pubkey:
>>> from opensslwrap import *
>>> data =’/path/to/data.txt’
>>> pubkey =’/path/to/my/pubkey.pem’
>>> ciphertext =encrypt(data, pubkey)
ciphertext is a path to (i.e., the file name of) the newly encrypted data, data is the path to the unencrypted
(original, plaintext) data, and pubkey is the path to the PEM format public-key.
Note: The default behavior is to delete the unencrypted file, data. This seems safer from a security standpoint.
Note: The private key is not involved at all in encryption, meaning that it can be stored on another machine
entirely.
2. Same as example 1, but don’t delete the original (unencrypted) datafile:
>>> ciphertext =encrypt(data, pubkey, keep=’orig’)
3. Decrypt the ciphertext, using the private key that’s paired with pubkey, with an optional passphrase stored in a
file (will try to prompt for passphrase if privkey has a passphrase and its path is not given):
>>> plaintext =decrypt(ciphertext, privkey [, passphrase])
4. Change (rotate) the RSA encryption keys, swapping out an old one, replacing with a new one (again, using
filenames):
>>> rotate(ciphertext, privkey_old, pubkey_new, priv_passphrase)
Questions:
Q: Will encryption make my data safe?
A: Think of it as adding another layer of security, of itself not being a complete solution. There are many issues
involved in securing your data, and encryption alone does not magically solve all of them. Security needs to be
considered at all stages in the process. The encryption provided (RSA + AES) is genuinely strong encryption (and as
such could cause problems). Key management is the hard part (which is why PsychoPy does not attempt to do it for
you.)
Q: What if I think my private RSA private key is no longer private?
A: Obviously, try to avoid this situation. If it happens: 1) Generate a new RSA key-pair, and then 2) rotate() the
encryption on all files that were encrypted using the public key associated with the compromised private key (see
below on how to rotate).
The meta-data includes information about what public key was used for encryption, to make it easier to identify the
relevant files. But even without that information, you could just try rotate()’ing the encryption on all files, and it
would only succeed for those with the right key pair. The meta-data are not required for key rotation. PsychoPy is not
needed for rotation (or decryption). Even opensslwrap is not needed: It is just a wrapper to make it easier to work with
standard, strong encryption tools (i.e., openssl).
Q: What if the internal (AES) password was disclosed (i.e., not the private key but the one-time password that is used
for the AES encryption)?
A: This is not very likely, and it would affect at most one file. Fix: Just rotate() the encryption for that file–using the
same keys is fine. That is, if you decrypt and re-encrypt (i.e., rotate) with the same key pair, a new internal one-time
password will be generated during the re-encryption step. (The old AES password is not re-used, ever, which is a
crucial difference between the AES password and the RSA key pair.)
164 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Q: What if I lose my private key?
A: The whole idea is that, if you don’t have the private key, the encryption should be strong enough that data recovery
is a very expensive proposition, if its even possible (and hopefully its not possible). You should design your procedures
under the assumption that data recovery will not be possible if you lose the private key. If you do lose the key, resign
yourself to the idea that your encrypted data are going to stay encrypted forever. This is not at all to say that it is
impossible for the encryption to be compromised by someone, just that you should not plan on being able to do it, or
even hire someone to do it.
Known limitations:
• Depends on calls to openssl using files, and files can sometimes be slow. In turn, this could cause something to
fail. This is unlikely based on tests so far, but if it happens, just try again.
• File sizes are assumed to fit entirely in RAM, with no checking (generally fine).
• Testing so far has been in limited testing environments. All tests pass on:
–Mac 10.6.8 OpenSSL 0.9.8r python 2.7.1
–Win XP sp2 OpenSSL 1.0.1 python 2.6.6
–CentOS 6.2 OpenSSL 1.0.0 python 2.7.2 (without psychopy installed)
Plus: a file encrypted on mac decrypted on both Win XP and CentOS.
Principles and Approach:
• Rely exclusively on standard widely available & supported tools and algorithms. OpenSSL and the basic ap-
proach (RSA + AES 256) are well-understood and recommended, e.g., http://crypto.stackexchange.com/a/15/
.
• Eventually opensslwrap.py will be signed and verifyable (once its more stable).
• Avoid obfuscation and “security through obscurity”. Obfuscation does not enchance security, yet can make data
recovery more difficult or expensive. So transparency is more important. For this reason, meta-data are gener-
ated by default (which can be disabled). In particular, using explicit labels in file names does not compromise
security; it just makes things less obscure..
• Encryption will refuse to proceed if the OpenSSL version < ‘0.9.8’; this will eventually go higher.
• Encryption will not proceed if the public key < 1024 bits (but go with 2048).
• AES256 is very strong cryptographically but requires a password (for symmetric encryption). A one-time
password is generated, and never re-used for other data.
• One key step is to use the password (and salt) to AES-encrypt the data:
$ openssl enc -e -aes-256-cbc -a -salt -in file.txt -out file.enc -pass file:<pwd_file>
• A second key step is to RSA public-key encrypt the password (using OAEP padding):
$ openssl rsautl -in pwd_file.txt -out pwd_file.rsa -inkey public.pem -pubin -oaep -encrypt
• Include a hash (sha256) of the encrypted file in the meta-data.
• Bundle the bits together for ease of archiving and handling (one .tgz file, using ”.enc” as the extension).
• Decrypt by using the private key to recover the password (which is one of the files in the .tgz bundle), and then
use the password to recover the data (from the AES- encrypted file in the bundle).
• The program does not try to manage the RSA keys. Its completely up to you (the user).
• Use and return full paths to files, to reduce ambiguity.
17.4. psychopy.contrib.opensslwrap Encryption (beta) 165
PsychoPy - Psychology software for Python, Release 1.78.00
17.4.2 Installing OpenSSL
• Mac & linux: openssl should be installed already, typically in /usr/bin/openssl If fact, if openssl is in a different
location, a warning will be generated.
• Windows: download from http://www.slproweb.com/products/Win32OpenSSL.html On win XP, install into
C:\OpenSSL-Win32\bin\openssl.exe; Windows Vista and later will try to discover the installation path (not
tested)
17.4.3 Encryption (beta)
psychopy.contrib.opensslwrap.encrypt(datafile,pubkeyPem,meta=True,keep=None)
Encrypt a file using openssl, AES-256, and an RSA public-key.
Returns: full path to the encrypted file (= .tgz bundle of 3 files). By default the original plaintext is deleted after
encryption (see parameter keep).
The idea is that you can have and share a public key, which anyone can use to encrypt things that only you can
decrypt. Generating good keys and managing them is non-trivial, and is entirely up to you. (GPG can help a
lot.) For better security, it is good to use signed public keys. No attempt is made here to verify key signatures
automatically; you could do so manually using verify().
Parameters
datafile:The path (name) of the original plaintext file to be encrypted.
pubkeyPem:The public key to use, specified as the path to a .pem file. Example file contents
(1024 bit pub.pem):
-----BEGIN PUBLIC KEY-----
MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBALcw2C2Tyiq514Nc+Oe1TvweyzK92PSm
s7KYMziTNcMy50E9KjSb7k8U/6Jaz/foeWFJqID1cmiyj1whZfZ4KycCAwEAAQ==
-----END PUBLIC KEY-----
meta:If True, include meta-data as plaintext in the archive:
original file name & sha256 of encrypted
platform & date
openssl version, padding
pubkey info (to aid in key rotation)
keep:None (default) = remove original (unencrypted) & all intermediate files (more secure)
‘orig’ = leave original file, delete intermediate (encrypted) files ‘all’ = leave all intermed
files & orig (for testing purposes)
17.4.4 Decryption (beta)
psychopy.contrib.opensslwrap.decrypt(dataEnc,privkeyPem,passphraseFile=’‘,outFile=’‘)
Decrypt a file that was encoded using encrypt().
To get the data back, need two files: data.enc and privkey.pem. If the private key has a passphrase, you’ll need
that too.
166 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
17.4.5 Key rotation (beta)
psychopy.contrib.opensslwrap.rotate(fileEnc,oldPriv,newPub,passphraseFile=None,
keep=None)
Swap old encryption for new (decrypt-then-re-encrypt).
Returns path to new encrypted file, adding to the meta-data.
17.4.6 Sign & verify (beta)
psychopy.contrib.opensslwrap.sign(file,priv,passphraseFile=None)
Use a private key to sign a given file.
Returns the signature as string, which can be passed to verify()
psychopy.contrib.opensslwrap.verify(file,pub,sig)
Use a public key to verify file integrity (signature), as matching hash (sha256)
17.5 psychopy.event - for keypresses and mouse clicks
class psychopy.event.Mouse(visible=True,newPos=None,win=None)
Easy way to track what your mouse is doing. It needn’t be a class, but since Joystick works better as a class this
may as well be one too for consistency
Create your visual.Window before creating a Mouse.
Parameters
visible [True or False] makes the mouse invisbile if necessary
newPos [None or [x,y]] gives the mouse a particular starting position (pygame Window only)
win [None or Window] the window to which this mouse is attached (the first found if None
provided)
clickReset(buttons=[0, 1, 2])
Reset a 3-item list of core.Clocks use in timing button clicks. The pyglet mouse-button-pressed handler
uses their clock.getLastResetTime() when a button is pressed so the user can reset them at stimulus onset
or offset to measure RT. The default is to reset all, but they can be reset individually as specified in buttons
list
getPos()
Returns the current postion of the mouse, in the same units as the Window (0,0) is at centre
getPressed(getTime=False)
Returns a 3-item list indicating whether or not buttons 0,1,2 are currently pressed
If getTime=True (False by default) then getPressed will return all buttons that have been pressed since the
last call to mouse.clickReset as well as their time stamps:
buttons =mouse.getPressed()
buttons, times =mouse.getPressed(getTime=True)
Typically you want to call mouse.clickReset() at stimulus onset, then after the button is pressed in reaction
to it, the total time elapsed from the last reset to click is in mouseTimes. This is the actual RT, regardless
of when the call to getPressed() was made.
17.5. psychopy.event - for keypresses and mouse clicks 167
PsychoPy - Psychology software for Python, Release 1.78.00
getRel()
Returns the new position of the mouse relative to the last call to getRel or getPos, in the same units as the
Window.
getVisible()
Gets the visibility of the mouse (1 or 0)
getWheelRel()
Returns the travel of the mouse scroll wheel since last call. Returns a numpy.array(x,y) but for most wheels
y is the only value that will change (except mac mighty mice?)
isPressedIn(shape, buttons=[0, 1, 2])
Returns True if the mouse is currently inside the shape and one of the mouse buttons is pressed. The default
is that any of the 3 buttons can indicate a click; for only a left-click, specifiy buttons=[0]:
if mouse.isPressedIn(shape):
if mouse.isPressedIn(shape, buttons=[0]): # left-clicks only
Ideally, shape can be anything that has a .contains() method, like ShapeStim or Polygon. Not tested with
ImageStim.
mouseMoveTime()
mouseMoved(distance=None,reset=False)
Determine whether/how far the mouse has moved
With no args returns true if mouse has moved at all since last getPos() call, or distance (x,y) can be set to
pos or neg distances from x and y to see if moved either x or y that far from lastPos , or distance can be an
int/float to test if new coordinates are more than that far in a straight line from old coords.
Retrieve time of last movement from self.mouseClock.getTime().
Reset can be to ‘here’ or to screen coords (x,y) which allows measuring distance from there to mouse
when moved. if reset is (x,y) and distance is set, then prevPos is set to (x,y) and distance from (x,y) to here
is checked, mouse.lastPos is set as current (x,y) by getPos(), mouse.prevPos holds lastPos from last time
mouseMoved was called
setPos(newPos=(0,0))
Sets the current postiion of the mouse (pygame only), in the same units as the Window (0,0) is at centre
Parameters
newPos [(x,y) or [x,y]] the new position on the screen
setVisible(visible)
Sets the visibility of the mouse to 1 or 0
NB when the mouse is not visible its absolute position is held at (0,0) to prevent it from going off the
screen and getting lost! You can still use getRel() in that case.
psychopy.event.clearEvents(eventType=None)
Clears all events currently in the event buffer. Optional argument, eventType, specifies only certain types to be
cleared
Parameters
eventType [None, ‘mouse’, ‘joystick’, ‘keyboard’] If this is not None then only events of the
given type are cleared
psychopy.event.waitKeys(maxWait=inf,keyList=None,timeStamped=False)
Same as ~psychopy.event.getKeys, but halts everything (including drawing) while awaiting input from keyboard.
Implicitly clears keyboard, so any preceding keypresses will be lost.
Parameters
168 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
maxWait [any numeric value.] Maximum number of seconds period and which keys to wait
for. Default is float(‘inf’) which simply waits forever.
Returns None if times out.
psychopy.event.getKeys(keyList=None,timeStamped=False)
Returns a list of keys that were pressed.
Parameters
keyList [None or []] Allows the user to specify a set of keys to check for. Only keypresses from
this set of keys will be removed from the keyboard buffer. If the keyList is None all keys
will be checked and the key buffer will be cleared completely. NB, pygame doesn’t return
timestamps (they are always 0)
timeStamped [False or True or Clock] If True will return a list of tuples instead of a list of
keynames. Each tuple has (keyname, time). If a core.Clock is given then the time will be
relative to the Clock‘s last reset
Author
• 2003 written by Jon Peirce
• 2009 keyList functionality added by Gary Strangman
• 2009 timeStamped code provided by Dave Britton
psychopy.event.xydist(p1=[0.0, 0.0], p2=[0.0, 0.0])
Helper function returning the cartesian distance between p1 and p2
17.6 psychopy.filters - helper functions for creating filters
Various useful functions for creating filters and textures (e.g. for PatchStim)
psychopy.filters.butter2d_bp(size,cutin,cutoff,n)
Bandpass Butterworth filter in two dimensions
Parameters
size [tuple] size of the filter
cutin [float] relative cutin frequency of the filter (0 - 1.0)
cutoff [float] relative cutoff frequency of the filter (0 - 1.0)
n[int, optional] order of the filter, the higher n is the sharper the transition is.
Returns
numpy.ndarray filter kernel in 2D centered
psychopy.filters.butter2d_hp(size,cutoff,n=3)
Highpass Butterworth filter in two dimensions
Parameters
size [tuple] size of the filter
cutoff [float] relative cutoff frequency of the filter (0 - 1.0)
n[int, optional] order of the filter, the higher n is the sharper the transition is.
Returns
numpy.ndarray: filter kernel in 2D centered
17.6. psychopy.filters - helper functions for creating filters 169
PsychoPy - Psychology software for Python, Release 1.78.00
psychopy.filters.butter2d_lp(size,cutoff,n=3)
Create lowpass 2D Butterworth filter
Parameters
size [tuple] size of the filter
cutoff [float] relative cutoff frequency of the filter (0 - 1.0)
n[int, optional] order of the filter, the higher n is the sharper the transition is.
Returns
numpy.ndarray filter kernel in 2D centered
psychopy.filters.butter2d_lp_elliptic(size,cutoff_x,cutoff_y,n=3,alpha=0,offset_x=0,off-
set_y=0)
Butterworth lowpass filter of any elliptical shape.
Parameters
size [tuple] size of the filter
cutoff_x, cutoff_y [float, float] relative cutoff frequency of the filter (0 - 1.0) for x and y axes
alpha [float, optional] rotation angle (in radians)
offset_x, offset_y [float] offsets for the ellipsoid
n[int, optional] order of the filter, the higher n is the sharper the transition is.
Returns
numpy.ndarray: filter kernel in 2D centered
psychopy.filters.conv2d(smaller,larger)
convolve a pair of 2d numpy matrices Uses fourier transform method, so faster if larger matrix has dimensions
of size 2**n
Actually right now the matrices must be the same size (will sort out padding issues another day!)
psychopy.filters.getRMScontrast(matrix)
Returns the RMS contrast (the sample standard deviation) of a array
psychopy.filters.imfft(X)
Perform 2D FFT on an image and center low frequencies
psychopy.filters.imifft(X)
Inverse 2D FFT with decentering
psychopy.filters.makeGauss(x,mean=0.0,sd=1.0,gain=1.0,base=0.0)
Return the gaussian distribution for a given set of x-vals
Parameters
mean: float the centre of the distribution
sd: float the width of the distribution
gain: float the height of the distribution
base: float an offset added to the result
psychopy.filters.makeGrating(res,ori=0.0,cycles=1.0,phase=0.0,gratType=’sin’,contr=1.0)
Make an array containing a luminance grating of the specified params
Parameters
res: integer the size of the resulting matrix on both dimensions (e.g 256)
170 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
ori: float or int (default=0.0) the orientation of the grating in degrees
cycles:float or int (default=1.0) the number of grating cycles within the array
phase: float or int (default=0.0) the phase of the grating in degrees (NB this differs to most
PsychoPy phase arguments which use units of fraction of a cycle)
gratType: ‘sin’, ‘sqr’, ‘ramp’ or ‘sinXsin’ (default=”sin”) the type of grating to be ‘drawn’
contr: float (default=1.0) contrast of the grating
Returns a square numpy array of size resXres
psychopy.filters.makeMask(matrixSize, shape=’circle’, radius=1.0, center=(0.0, 0.0), range=[-1,
1], fringeWidth=0.2)
Returns a matrix to be used as an alpha mask (circle,gauss,ramp)
Parameters
matrixSize: integer the size of the resulting matrix on both dimensions (e.g 256)
shape: ‘circle’,’gauss’,’ramp’ (linear gradient from center),
‘raisedCosine’ (the edges are blurred by a raised cosine)
shape of the mask
radius: float scale factor to be applied to the mask (circle with radius of [1,1] will extend just
to the edge of the matrix). Radius can asymmetric, e.g. [1.0,2.0] will be wider than it is tall.
center: 2x1 tuple or list (default=[0.0,0.0]) the centre of the mask in the matrix ([1,1] is top-
right corner, [-1,-1] is bottom-left)
fringeWidth: float (0-1) The proportion of the raisedCosine that is being blurred.
range: 2x1 tuple or list (default=[-1,1]) The minimum and maximum value in the mask ma-
trix
psychopy.filters.makeRadialMatrix(matrixSize,center=(0.0,0.0),radius=1.0)
Generate a square matrix where each element val is its distance from the centre of the matrix
Parameters
matrixSize: integer the size of the resulting matrix on both dimensions (e.g 256)
radius: float scale factor to be applied to the mask (circle with radius of [1,1] will extend just
to the edge of the matrix). Radius can be asymmetric, e.g. [1.0,2.0] will be wider than it is
tall.
center: 2x1 tuple or list (default=[0.0,0.0]) the centre of the mask in the matrix ([1,1] is top-
right corner, [-1,-1] is bottom-left)
psychopy.filters.maskMatrix(matrix,shape=’circle’,radius=1.0,center=(0.0,0.0))
Make and apply a mask to an input matrix (e.g. a grating)
Parameters
matrix: a square numpy array array to which the mask should be applied
shape: ‘circle’,’gauss’,’ramp’ (linear gradient from center) shape of the mask
radius: float scale factor to be applied to the mask (circle with radius of [1,1] will extend just
to the edge of the matrix). Radius can be asymmetric, e.g. [1.0,2.0] will be wider than it is
tall.
center: 2x1 tuple or list (default=[0.0,0.0]) the centre of the mask in the matrix ([1,1] is top-
right corner, [-1,-1] is bottom-left)
17.6. psychopy.filters - helper functions for creating filters 171
PsychoPy - Psychology software for Python, Release 1.78.00
17.7 psychopy.gui - create dialogue boxes
17.7.1 DlgFromDict
class psychopy.gui.DlgFromDict(dictionary,title=’‘,fixed=[],order=[],tip={})
Creates a dialogue box that represents a dictionary of values. Any values changed by the user are change
(in-place) by this dialogue box. e.g.:
info ={’Observer’:’jwp’,’GratingOri’:45,’ExpVersion’:1.1,’Group’: [’Test’,’Control’]}
infoDlg =gui.DlgFromDict(dictionary=info, title=’TestExperiment’, fixed=[’ExpVersion’])
if infoDlg.OK:
print info
else:print ’User Cancelled’
In the code above, the contents of info will be updated to the values returned by the dialogue box.
If the user cancels (rather than pressing OK), then the dictionary remains unchanged. If you want to check
whether the user hit OK, then check whether DlgFromDict.OK equals True or False
See GUI.py for a usage demo, including order and tip (tooltip).
17.7.2 Dlg
class psychopy.gui.Dlg(title=’PsychoPy dialogue’,pos=None,size=wx.Size(-1,-1),style=536877057)
A simple dialogue box. You can add text or input boxes (sequentially) and then retrieve the values.
see also the function dlgFromDict for an even simpler version
Example:
from psychopy import gui
myDlg =gui.Dlg(title="JWP’s experiment")
myDlg.addText(’Subject info’)
myDlg.addField(’Name:’)
myDlg.addField(’Age:’,21)
myDlg.addText(’Experiment Info’)
myDlg.addField(’Grating Ori:’,45)
myDlg.addField(’Group:’, choices=["Test","Control"])
myDlg.show()#show dialog and wait for OK or Cancel
if gui.OK:#then the user pressed OK
thisInfo =myDlg.data
print thisInfo
else:print ’user cancelled’
addField(label=’‘,initial=’‘,color=’‘,choices=None,tip=’‘)
Adds a (labelled) input field to the dialogue box, optional text color and tooltip. Returns a handle to the
field (but not to the label). If choices is a list or tuple, it will create a dropdown selector.
addFixedField(label=’‘,value=’‘,tip=’‘)
Adds a field to the dialogue box (like addField) but the field cannot be edited. e.g. Display experiment
version. tool-tips are disabled (by wx).
addText(text,color=’‘)
show()
Presents the dialog and waits for the user to press either OK or CANCEL.
This function returns nothing.
172 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
When they do, dlg.OK will be set to True or False (according to which button they pressed. If OK==True
then dlg.data will be populated with a list of values coming from each of the input fields created.
17.7.3 fileOpenDlg
class psychopy.gui.fileOpenDlg
A simple dialogue allowing access to the file system. (Useful in case you collect an hour of data and then try to
save to a non-existent directory!!)
Parameters
tryFilePath: string default file path on which to open the dialog
tryFilePath: string default file name, as suggested file
prompt: string (default “Select file to open”) can be set to custom prompts
allowed: string (available since v1.62.01) a string to specify file filters. e.g. “BMP files
(.bmp)|.bmp|GIF files (.gif)|.gif” See http://www.wxpython.org/docs/api/wx.FileDialog-
class.html for further details
If tryFilePath or tryFileName are empty or invalid then current path and empty names are used to start search.
If user cancels, then None is returned.
17.7.4 fileSaveDlg
class psychopy.gui.fileSaveDlg
A simple dialogue allowing access to the file system. (Useful in case you collect an hour of data and then try to
save to a non-existent directory!!)
Parameters
initFilePath: string default file path on which to open the dialog
initFilePath: string default file name, as suggested file
prompt: string (default “Select file to open”) can be set to custom prompts
allowed: string a string to specify file filters. e.g. “BMP files (.bmp)|.bmp|GIF files (.gif)|.gif”
See http://www.wxpython.org/docs/api/wx.FileDialog-class.html for further details
If initFilePath or initFileName are empty or invalid then current path and empty names are used to start search.
If user cancels the None is returned.
17.8 psychopy.hardware - hardware interfaces
PsychoPy can access a wide range of external hardware. For some devices the interface has already been created in the
following sub-packages of PsychoPy. For others you may need to write the code to access the serial port etc. manually.
Contents:
17.8. psychopy.hardware - hardware interfaces 173
PsychoPy - Psychology software for Python, Release 1.78.00
17.8.1 Cedrus (response boxes)
The pyxid package, written by Cedrus, is included in the Standalone PsychoPy distributions. See
https://github.com/cedrus-opensource/pyxid for further info.
Example usage:
import pyxid
# get a list of all attached XID devices
devices = pyxid.get_xid_devices()
dev = devices[0] # get the first device to use
if dev.is_response_device():
dev.reset_base_timer()
dev.reset_rt_timer()
while True:
dev.poll_for_response()
if dev.response_queue_size() > 0:
response = dev.get_next_response()
# do something with the response
Useful functions
pyxid.get_xid_device(device_number)
returns device at a given index.
Raises ValueError if the device at the passed in index doesn’t exist.
pyxid.get_xid_devices()
Returns a list of all Xid devices connected to your computer.
Device classes
class pyxid.ResponseDevice(connection,name=’Unknown XID Device’,keymap=None,trig-
ger_prefix=’Button’)
clear_response_queue()
Clears the response queue
get_next_response()
Pops the response at the beginning of the response queue and returns it.
This function returns a dict object with the following keys:
pressed: A boolean value of whether the event was a keypress or key release.
key: The key on the device that was pressed. This is a 0 based index.
port: Device port the response came from. Typically this is 0 on RB-series devices, and 2 on
SV-1 voice key devices.
time: For the time being, this just returns 0. There is currently an issue with clock drift in the
Cedrus XID devices. Once we have this issue resolved, time will report the value of the RT
timer in miliseconds.
poll_for_response()
Polls the device for user input
174 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
If there is a keymapping for the device, the key map is applied to the key reported from the device.
If a response is waiting to be processed, the response is appended to the internal response_queue
response_queue_size()
Number of responses in the response queue
class pyxid.XidDevice(xid_connection)
Class for interfacing with a Cedrus XID device.
At the beginning of an experiment, the developer should call:
XidDevice.reset_base_timer()
Whenever a stimulus is presented, the developer should call:
XidDevice.reset_rt_timer()
Developers Note: Currently there is a known issue of clock drift in the XID devices. Due to this, the dict
returned by XidDevice.get_next_response() returns 0 for the reaction time value.
This issue will be resolved in a future release of this library.
init_device()
Initializes the device with the proper keymaps and name
17.8.2 Cambridge Research Systems Ltd.
class psychopy.hardware.crs.BitsBox(win, contrast=1.0, gamma=[1.0, 1.0, 1.0], nEntries=256,
bitsType=’bits++’)
The main class to control a bits++ box.
This is usually a class added within the window object and is typically accessed from there. e.g.:
from psychopy import visual
win =visual.Window([800,600], bitsMode=’fast’)
win.bits.setContrast(0.5)#use bits++ to reduce the whole screen contrast by 50%
setContrast(contrast,LUTrange=1.0)
Optional parameter LUTrange determines which entries of the LUT will be set to this contrast
Parameters
contrast [float in the range 0:1] The contrast for the range being set
LUTrange [float or array] If a float is given then this is the fraction of the LUT to be used.
If an array of floats is given, these will specify the start/stop points as fractions of the LUT.
If an array of ints (0-255) is given these determine the start stop indices of the LUT
Examples:
setContrast(1.0,0.5) will set the central 50% of the LUT so that a stimulus with contr=0.5
will actually be drawn with contrast 1.0
setContrast(1.0,[0.25,0.5])
setContrast(1.0,[63,127]) will set the lower-middle quarter of the LUT (which might be
useful in LUT animation paradigms)
setGamma(newGamma)
Set the LUT to have the requested gamma. Currently also resets the LUT to be a linear contrast ramp
spanning its full range. May change this to read the current LUT, undo previous gamm and then apply new
one?
17.8. psychopy.hardware - hardware interfaces 175
PsychoPy - Psychology software for Python, Release 1.78.00
setLUT(newLUT=None,gammaCorrect=True,LUTrange=1.0)
Sets the LUT to a specific range of values.
Note that, if you leave gammaCorrect=True then any LUT values you supply will automatically be gamma
corrected.
If BitsBox setMethod is ‘fast’ then the LUT will take effect on the next Window.update() If the
setMethod is ‘slow’ then the update will take place over the next 1-4secs down the USB port.
Examples:
bitsBox.setLUT() builds a LUT using bitsBox.contrast and bitsBox.gamma
bitsBox.setLUT(newLUT=some256x1array) (NB array should be float 0.0:1.0) Builds a
luminance LUT using newLUT for each gun (actually array can be 256x1 or 1x256)
bitsBox.setLUT(newLUT=some256x3array) (NB array should be float 0.0:1.0) Allows
you to use a different LUT on each gun
(NB by using BitsBox.setContr() and BitsBox.setGamma() users may not need this function!?)
17.8.3 egi (pynetstation)
Interface to EGI Netstation
This is currently a simple import of pynetstation That needs to be installed (but is included in the Standalone distribu-
tions of PsychoPy as of version 1.62.01).
installation:
Download the package from the link above and copy egi.py into your site-packages directory.
usage:
from psychopy.hardware import egi
For an example see the demos menu of the PsychoPy Coder For further documentation see the pynetstation website
17.8.4 Launch an fMRI experiment: Test or Scan
Idea: Run or debug an experiment script using exactly the same code, i.e., for both testing and online data acquisition.
To debug timing, you can emulate sync pulses and user responses. Limitations: pyglet only; keyboard events only.
psychopy.hardware.emulator.launchScan(win,settings,globalClock=None,simRe-
sponses=None,mode=’None’,esc_key=’escape’,
instr=’select Scan or Test,press en-
ter’,wait_msg=’waiting for scanner...’,
wait_timeout=300)
Accepts up to four fMRI scan parameters (TR, volumes, sync-key, skip), and launches an experiment in one of
two modes: Scan, or Test.
Usage See Coder Demo -> experiment control -> fMRI_launchScan.py.
In brief: 1) from psychopy.hardware.emulator import launchScan; 2) Define your args; and 3)
add ‘vol = launchScan(args)’ at the top of your experiment script.
launchScan() waits for the first sync pulse and then returns, allowing your experiment script to proceed. The
key feature is that, in test mode, it first starts an autonomous thread that emulates sync pulses (i.e., emulated by
your CPU rather than generated by an MRI machine). The thread places a character in the key buffer, exactly
like a keyboard event does. launchScan will wait for the first such sync pulse (i.e., character in the key buffer).
176 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
launchScan returns the number of sync pulses detected so far (i.e., 1), so that a script can account for them
explicitly.
If a globalClock is given (highly recommended), it is reset to 0.0 when the first sync pulse is detected. If a mode
was not specified when calling launchScan, the operator is prompted to select Scan or Test.
If scan mode is selected, the script will wait until the first scan pulse is detected. Typically this would be coming
from the scanner, but note that it could also be a person manually pressing that key.
If test mode is selected, launchScan() starts a separate thread to emit sync pulses / key presses. Note that this
thread is effectively nothing more than a key-pressing metronome, emitting a key at the start of every TR, doing
so with high temporal precision.
If your MR hardware interface does not deliver a key character as a sync flag, you can still use launchScan() to
test script timing. You have to code your experiment to trigger on either a sync character (to test timing) or your
usual sync flag (for actual scanning).
Parameters win: a Window object (required)
settings : a dict containing up to 5 parameters (2 required: TR, volumes)
TR : seconds per whole-brain volume (minimum value = 0.1s)
volumes : number of whole-brain (3D) volumes to obtain in a given scanning run.
sync : (optional) key for sync timing, default = ‘5’.
skip : (optional) how many volumes to silently omit initially (during T1 stabilization,
no sync pulse). default = 0.
sound : (optional) whether to play a sound when simulating scanner sync pulses
globalClock : optional but highly recommended Clock to be used during the scan; if one is
given, it is reset to 0.000 when the first sync pulse is received.
simResponses : optional list of tuples [(time, key), (time, key), ...]. time values are seconds
after the first scan pulse is received.
esc_key : key to be used for user-interrupt during launch. default = ‘escape’
mode : if mode is ‘Test’ or ‘Scan’, launchScan() will start in that mode.
instr : instructions to be displayed to the scan operator during mode selection.
wait_msg : message to be displayed to the subject while waiting for the scan to start (i.e., after
operator indicates start but before the first scan pulse is received).
wait_timeout : time in seconds that launchScan will wait before assuming something went
wrong and exiting. Defaults to 300sec (5 minutes). Raises a TimeoutError if no sync pulse
is received in the allowable time.
class psychopy.hardware.emulator.ResponseEmulator(simResponses=None)
Class to allow simulation of a user’s keyboard responses during a scan.
Given a list of response tuples (time, key), the thread will simulate a user pressing a key at a specific time
(relative to the start of the run).
Author: Jeremy Gray; Idea: Mike MacAskill
class psychopy.hardware.emulator.SyncGenerator(TR=1.0,volumes=10,sync=‘5’,skip=0,
sound=False)
Class for a character-emitting metronome thread (emulate MR sync pulse).
17.8. psychopy.hardware - hardware interfaces 177
PsychoPy - Psychology software for Python, Release 1.78.00
Aim: Allow testing of temporal robustness of fMRI scripts by emulating a hardware sync pulse. Adds an
arbitrary ‘sync’ character to the key buffer, with sub-millisecond precision (less precise if CPU is maxed).
Recommend: TR=1.000 or higher and less than 100% CPU. Shorter TR –> higher CPU load.
Parameters: TR: seconds per whole-brain volume volumes: number of 3D volumes to obtain in a given scan-
ning run sync: character used as flag for sync timing, default=‘5’ skip: how many frames to silently omit
initially during T1
stabilization, no sync pulse. Not needed to test script timing, but will give more accurate feel to
start of run. aka “discdacqs”.
sound: simulate scanner noise
17.8.5 fORP response box
fORP fibre optic (MR-compatible) response devices by CurrentDesigns: http://www.curdes.com/ This class is only
useful when the fORP is connected via the serial port. If you’re connecting via USB, just treat it like a standard
keyboard.
class psychopy.hardware.forp.ButtonBox(serialPort=1,baudrate=19200)
Serial line interface to the fORP MRI response box.
To use this object class, select the box use setting serialPort, and connect the serial line. To emulate key
presses with a serial connection, use getEvents(asKeys=True) (e.g., to be able to use a RatingScale object during
scanning). Alternatively connect the USB cable and use fORP to emulate a keyboard.
fORP sends characters at 800Hz, so you should check the buffer frequently. Also note that the trigger event
numpy the fORP is typically extremely short (occurs for a single 800Hz epoch).
Parameters
serialPort :should be a number (where 1=COM1, ...)
baud :the communication rate (baud), eg, 57600
clearBuffer()
Empty the input buffer of all characters
clearStatus()
Resets the pressed statuses, so getEvents will return pressed buttons, even if they were already pressed in
the last call.
getEvents(returnRaw=False,asKeys=False,allowRepeats=False)
Returns a list of unique events (one event per button pressed) and also stores a copy of the full list of events
since last getEvents() (stored as ForpBox.rawEvts)
returnRaw :return (not just store) the full event list
asKeys :If True, will also emulate pyglet keyboard events, so that button 1 will register as a keyboard
event with value “1”, and as such will be detectable using event.getKeys()
allowRepeats :If True, this will return pressed buttons even if they were held down between calls to
getEvents(). If the fORP is on the “Eprime” setting, you will get a stream of button presses while a
button is held down. On the “Bitwise” setting, you will get a set of all currently pressed buttons every
time a button is pressed or released. This option might be useful if you think your participant may be
holding the button down before you start checking for presses.
getUniqueEvents(fullEvts=False)
Returns a Python set of the unique (unordered) events of either a list given or the current rawEvts buffer
178 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
17.8.6 ioLab
Interface to ioLab button box
This is currently a simple import of the ioLab python library. That needs to be installed (but is included in the
Standalone distributions of PsychoPy as of version 1.62.01).
installation:
easy_install iolabs
usage:
from psychopy.hardware import ioLabs
for examples see the demos menu of the PsychoPy Coder or go to the URL above.
17.8.7 joystick (pyglet and pygame)
Control joysticks and gamepads from within PsychoPy
You do need a window (and you need to be flipping it) for the joystick to be updated.
Known issues:
• currently under pyglet the joystick axes initialise to a value of zero and stay like this until the first time that
axis moves
• currently pygame (1.9.1) spits out lots of debug messages about the joystick and these can’t be turned off
:-/
Typical usage:
from psychopy.hardware import joystick
from psychopy import visual
joystick.backend=’pyglet’#must match the Window
win =visual.Window([400,400], winType=’pyglet’)
nJoys =joystick.getNumJoysticks()#to check if we have any
id=0
joy =joystick.Joystick(id)#id must be <= nJoys-1
nAxes =joy.getNumAxes()#for interest
while True:#while presenting stimuli
currentjoy.getX()
#...
win.flip()#flipping implicitly updates the joystick info
psychopy.hardware.joystick.getNumJoysticks()
Return a count of the number of joysticks available.
class psychopy.hardware.joystick.Joystick(id)
An object to control a multi-axis joystick or gamepad
Known issues Currently under pyglet backends the axis values initialise to zero rather than reading
the current true value. This gets fixed on the first change to each axis.
getAllAxes()
Get a list of all current axis values
17.8. psychopy.hardware - hardware interfaces 179
PsychoPy - Psychology software for Python, Release 1.78.00
getAllButtons()
Get the state of all buttons as a list
getAllHats()
Get the current values of all available hats as a list of tuples. Each value is a tuple (x,y) where x and y can
be -1,0,+1
getAxis(axisId)
Get the value of an axis by an integer id (from 0 to number of axes-1)
getButton(buttonId)
Get the state of a given button.
buttonId should be a value from 0 to the number of buttons-1
getHat(hatId=0)
Get the position of a particular hat. The position returned is an (x,y) tuple where x and y can be -1,0 or +1
getName()
Returns the manufacturer-defined name describing the device
getNumAxes()
Returns the number of joystick axes found
getNumButtons()
Returns the number of digital buttons on the device
getNumHats()
Get the number of hats on this joystick
getX()
Returns the value on the X axis (equivalent to joystick.getAxis(0))
getY()
Returns the value on the Y axis (equivalent to joystick.getAxis(1))
getZ()
Returns the value on the Z axis (equivalent to joystick.getAxis(2))
17.8.8 labjack (USB I/O devices)
The labjack package is included in the Standalone PsychoPy distributions. It differs slightly form the standard version
distributed by labjack (www.labjack.com) in the import. From the cutoms distribution use:
from labjack import u3
NOT:
import u3
In all other respects the library is the same and instructions on how to use it can be found here:
http://labjack.com/support/labjackpython
Note: To use labjack devices you do need also to install the driver software described on the page above
labjack.u3
alias of labjack.u3
180 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
17.8.9 Minolta
Minolta light-measuring devices See http://www.konicaminolta.com/instruments
class psychopy.hardware.minolta.LS100(port,maxAttempts=1)
A class to define a Minolta LS100 (or LS110?) photometer
You need to connect a LS100 to the serial (RS232) port and when you turn it on press the F key on the device.
This will put it into the correct mode to communicate with the serial port.
usage:
from psychopy.hardware import minolta
phot =minolta.LS100(port)
if phot.OK:#then we successfully made a connection and can send/receive
print phot.getLum()
Parameters port: string
the serial port that should be checked
maxAttempts: int If the device doesn’t respond first time how many attempts should be made?
If you’re certain that this is the correct port and the device is on and correctly configured
then this could be set high. If not then set this low.
Troubleshooting Various messages are printed to the log regarding the function of this device, but
to see them you need to set the printing of the log to the correct level:
from psychopy import log
logging.console.setLevel(logging.ERROR)#error messages only
logging.console.setLevel(logging.INFO)#will give a little more info
logging.console.setLevel(logging.DEBUG)#will export a log of all communications
If you’re using a keyspan adapter (at least on OS X) be aware that it needs a driver installed.
Otherwise no ports wil be found.
Error messages:
ERROR: Couldn’t connect to Minolta LS100/110 on ____:This likely
means that the device is not connected to that port (although the port has been found and
opened). Check that the device has the [in the bottom right of the display; if not turn off
and on again holding the Fkey.
ERROR: No reply from LS100:The port was found, the connection was made and an
initial command worked, but then the device stopped communating. If the first measurement
taken with the device after connecting does not yield a reasonble intensity the device can
sulk (not a technical term!). The “[” on the display will disappear and you can no longer
communicate with the device. Turn it off and on again (with F depressed) and use a reason-
ably bright screen for your first measurement. Subsequent measurements can be dark (or
we really would be in trouble!!).
checkOK(msg)
Check that the message from the photometer is OK. If there’s an error print it.
Then return True (OK) or False.
clearMemory()
Clear the memory of the device from previous measurements
17.8. psychopy.hardware - hardware interfaces 181
PsychoPy - Psychology software for Python, Release 1.78.00
getLum()
Makes a measurement and returns the luminance value
measure()
Measure the current luminance and set .lastLum to this value
sendMessage(message,timeout=5.0)
Send a command to the photometer and wait an alloted timeout for a response.
setMaxAttempts(maxAttempts)
Changes the number of attempts to send a message and read the output Typically this should be low
initially, if you aren’t sure that the device is setup correctly but then, after the first successful reading, set
it higher.
setMode(mode=‘04’)
Set the mode for measurements. Returns True (success) or False
‘04’ means absolute measurements. ‘08’ = peak ‘09’ = cont
See user manual for other modes
17.8.10 PhotoResearch
Supported devices:
•PR650
•PR655/PR670
PhotoResearch spectrophotometers See http://www.photoresearch.com/
class psychopy.hardware.pr.PR650(port,verbose=None)
An interface to the PR650 via the serial port.
(Added in version 1.63.02)
example usage:
from psychopy.hardware.pr import PR650
myPR650 =PR650(port)
myPR650.getLum()#make a measurement
nm, power =myPR650.getLastSpectrum()#get a power spectrum for the last measurement
NB psychopy.hardware.findPhotometer() will locate and return any supported device for you so
you can also do:
from psychopy import hardware
phot =hardware.findPhotometer()
print phot.getLum()
Troubleshooting Various messages are printed to the log regarding the function of this device, but
to see them you need to set the printing of the log to the correct level:
from psychopy import log
logging.console.setLevel(logging.ERROR)#error messages only
logging.console.setLevel(logging.INFO)#will give a little more info
logging.console.setLevel(logging.DEBUG)#will export a log of all communications
182 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
If you’re using a keyspan adapter (at least on OS X) be aware that it needs a driver installed.
Otherwise no ports wil be found.
Also note that the attempt to connect to the PR650 must occur within the first few seconds after
turning it on.
getLastLum()
This retrieves the luminance (in cd/m**2) from the last call to .measure()
getLastSpectrum(parse=True)
This retrieves the spectrum from the last call to .measure()
If parse=True (default): The format is a num array with 100 rows [nm, power]
otherwise: The output will be the raw string from the PR650 and should then be passed to
.parseSpectrumOutput(). It’s more efficient to parse R,G,B strings at once than each individu-
ally.
getLum()
Makes a measurement and returns the luminance value
getSpectrum(parse=True)
Makes a measurement and returns the current power spectrum
If parse=True (default): The format is a num array with 100 rows [nm, power]
If parse=False (default): The output will be the raw string from the PR650 and should then be passed
to .parseSpectrumOutput(). It’s slightly more efficient to parse R,G,B strings at once than
each individually.
measure(timeOut=30.0)
Make a measurement with the device. For a PR650 the device is instructed to make a measurement and
then subsequent commands are issued to retrieve info about that measurement
parseSpectrumOutput(rawStr)
Parses the strings from the PR650 as received after sending the command ‘d5’. The input argument “raw-
Str” can be the output from a single phosphor spectrum measurement or a list of 3 such measurements
[rawR, rawG, rawB].
sendMessage(message,timeout=0.5,DEBUG=False)
Send a command to the photometer and wait an alloted timeout for a response (Timeout should be long for
low light measurements)
class psychopy.hardware.pr.PR655(port)
An interface to the PR655/PR670 via the serial port.
example usage:
from psychopy.hardware.pr import PR655
myPR655 =PR655(port)
myPR655.getLum()#make a measurement
nm, power =myPR655.getLastSpectrum()#get a power spectrum for the last measurement
NB psychopy.hardware.findPhotometer() will locate and return any supported device for you so
you can also do:
from psychopy import hardware
phot =hardware.findPhotometer()
print phot.getLum()
17.8. psychopy.hardware - hardware interfaces 183
PsychoPy - Psychology software for Python, Release 1.78.00
Troubleshooting If the device isn’t responding try turning it off and turning it on again, and/or
disconnecting/reconnecting the USB cable. It may be that the port has become controlled by
some other program.
endRemoteMode()
Puts the colorimeter back into normal mode
getDeviceSN()
Return the device serial number
getDeviceType()
Return the device type (e.g. ‘PR-655’ or ‘PR-670’)
getLastColorTemp()
Fetches (from the device) the color temperature (K) of the last measurement
Returns list: status, units, exponent, correlated color temp (Kelvins), CIE 1960 deviation
See also measure() automatically populates pr655.lastColorTemp with the color temp in
Kelvins
getLastSpectrum(parse=True)
This retrieves the spectrum from the last call to measure()
If parse=True (default):
The format is a num array with 100 rows [nm, power]
otherwise:
The output will be the raw string from the PR650 and should then be passed to
parseSpectrumOutput(). It’s more efficient to parse R,G,B strings at once than each indi-
vidually.
getLastTristim()
Fetches (from the device) the last CIE 1931 Tristimulus values
Returns list: status, units, Tristimulus Values
See also measure() automatically populates pr655.lastTristim with just the tristimulus coor-
dinates
getLastUV()
Fetches (from the device) the last CIE 1976 u,v coords
Returns list: status, units, Photometric brightness, u, v
See also measure() automatically populates pr655.lastUV with [u,v]
getLastXY()
Fetches (from the device) the last CIE 1931 x,y coords
Returns list: status, units, Photometric brightness, x,y
See also measure() automatically populates pr655.lastXY with [x,y]
measure(timeOut=30.0)
Make a measurement with the device.
This automatically populates:
•.lastLum
•‘‘.lastSpectrum‘
•.lastCIExy
184 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
•.lastCIEuv
parseSpectrumOutput(rawStr)
Parses the strings from the PR650 as received after sending the command ‘D5’. The input argument
“rawStr” can be the output from a single phosphor spectrum measurement or a list of 3 such measurements
[rawR, rawG, rawB].
sendMessage(message,timeout=0.5,DEBUG=False)
Send a command to the photometer and wait an alloted timeout for a response (Timeout should be long for
low light measurements)
startRemoteMode()
Sets the Colorimeter into remote mode
17.8.11 pylink (SR research)
For now the SR Research pylink module is packaged with the Standalone flavours of PsychoPy and can be imported
with:
import pylink
You do need to install the Display Software (which they also call Eyelink Developers Kit) for your particular platform.
This can be found by following the threads from:
https://www.sr-support.com/forums/forumdisplay.php?f=17
for pylink documentation see:
https://www.sr-support.com/forums/showthread.php?t=14 Performing research with eye-tracking equipment typically
requires a long-term investment in software tools to collect, process, and analyze data. Much of this involves real-time
data collection, saccadic analysis, calibration routines, and so on. The EyeLink® eye-tracking system is designed to
implement most of the required software base for data collection and conversion. It is most powerful when used with
the Ethernet link interface, which allows remote control of data collection and real-time data transfer. The PyLink
toolkit includes Pylink module, which implements all core EyeLink functions and classes for EyeLink connection
and the eyelink graphics, such as the display of camera image, calibration, validation, and drift correct. The EyeLink
graphics is currently implemented using Simple Direct Media Layer (SDL: www.libsdl.org).
The Pylink library contains a set of classes and functions, which are used to program experiments on many different
platforms, such as MS-DOS, Windows, Linux, and the Macintosh. Some programming standards, such as placement
of messages in the EDF file by your experiment, and the use of special data types, have been implemented to allow
portability of the development kit across platforms. The standard messages allow general analysis tools such as
EDF2ASC converter or EyeLink Data Viewer to process your EDF files.
psychopy.hardware.findPhotometer(ports=None,device=None)
Try to find a connected photometer/photospectrometer! PsychoPy will sweep a series of serial ports trying to
open them. If a port successfully opens then it will try to issue a command to the device. If it responds with one
of the expected values then it is assumed to be the appropriate device.
Parameters
ports [a list of ports to search] Each port can be a string (e.g. ‘COM1’, ‘’/dev/tty.Keyspan1.1’)
or a number (for win32 comports only). If none are provided then PsychoPy will sweep
COM0-10 on win32 and search known likely port names on OS X and linux.
device [string giving expected device (e.g. ‘PR650’, ‘PR655’, ‘LS110’).] If this is not given
then an attempt will be made to find a device of any type, but this often fails
Returns
• An object representing the first photometer found
17.8. psychopy.hardware - hardware interfaces 185
PsychoPy - Psychology software for Python, Release 1.78.00
• None if the ports didn’t yield a valid response
• None if there were not even any valid ports (suggesting a driver not being installed)
e.g.:
photom =findPhotometer(device=’PR655’)#sweeps ports 0 to 10 searching for a PR655
print photom.getLum()
if hasattr(photom, ’getSpectrum’):#can retrieve spectrum (e.g. a PR650)
print photom.getSpectrum()
17.9 psychopy.info - functions for getting information about the
system
Fetching data about the system
class psychopy.info.RunTimeInfo(author=None,version=None,win=None,refreshTest=’grating’,
userProcsDetailed=False,verbose=False,randomSeed=None)
Returns a snapshot of your configuration at run-time, for immediate or archival use.
Returns a dict-like object with info about PsychoPy, your experiment script, the system & OS, your window and
monitor settings (if any), python & packages, and openGL.
If you want to skip testing the refresh rate, use ‘refreshTest=None’
Example usage: see runtimeInfo.py in coder demos.
Author
• 2010 written by Jeremy Gray, with input from Jon Peirce and Alex Holcombe
Parameters
win [None, False, Window instance] what window to use for refresh rate testing (if any) and
settings. None -> temporary window using defaults; False -> no window created, used, nor
profiled; a Window() instance you have already created
author [None, string] None = try to autodetect first __author__ in sys.argv[0]; string = user-
supplied author info (of an experiment)
version [None, string] None = try to autodetect first __version__ in sys.argv[0]; string = user-
supplied version info (of an experiment)
verbose : False, True; how much detail to assess
refreshTest [None, False, True, ‘grating’] True or ‘grating’ = assess refresh average, median,
and SD of 60 win.flip()s, using visual.getMsPerFrame() ‘grating’ = show a visual during the
assessment; True = assess without a visual
userProcsDetailed: False, True get details about concurrent user’s processses (command,
process-ID)
randomSeed: None a way for the user to record, and optionally set, a random seed for making
reproducible random sequences ‘set:XYZ’ will both record the seed, ‘XYZ’, and set it: ran-
dom.seed(‘XYZ’); numpy.random.seed() is NOT set None defaults to python default; ‘time’
= use time.time() as the seed, as obtained during RunTimeInfo() randomSeed=’set:time’ will
give a new random seq every time the script is run, with the seed recorded.
Returns a flat dict (but with several groups based on key names):
186 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
psychopy [version, rush() availability] psychopyVersion, psychopyHaveExtRush, git branch
and current commit hash if available
experiment [author, version, directory, name, current time-stamp, ] SHA1 digest, VCS info (if
any, svn or hg only), experimentAuthor, experimentVersion, ...
system [hostname, platform, user login, count of users, user process info (count, cmd + pid),
flagged processes] systemHostname, systemPlatform, ...
window [(see output; many details about the refresh rate, window, and monitor; units are
noted)] windowWinType, windowWaitBlanking, ...windowRefreshTimeSD_ms, ... win-
dowMonitor.<details>, ...
python [version of python, versions of key packages (wx, numpy, scipy, matplotlib, pyglet,
pygame)] pythonVersion, pythonScipyVersion, ...
openGL [version, vendor, rendering engine, plus info on whether several extensions are
present] openGLVersion, ..., openGLextGL_EXT_framebuffer_object, ...
psychopy.info.getRAM()
Return system’s physical RAM & available RAM, in M.
Slow on Mac and Linux; fast on Windows. psutils is good but another dep.
17.10 psychopy.logging - control what gets logged
Provides functions for logging error and other messages to one or more files and/or the console, using python’s own
logging module. Some warning messages and error messages are generated by PsychoPy itself. The user can generate
more using the functions in this module.
There are various levels for logged messages with the following order of importance: ERROR, WARNING, DATA,
EXP, INFO and DEBUG.
When setting the level for a particular log target (e.g. LogFile) the user can set the minimum level that is required
for messages to enter the log. For example, setting a level of INFO will result in INFO, EXP, DATA, WARNING and
ERROR messages to be recorded but not DEBUG messages.
By default, PsychoPy will record messages of WARNING level and above to the console. The user can silence that by
setting it to receive only CRITICAL messages, (which PsychoPy doesn’t use) using the commands:
from psychopy import logging
logging.console.setLevel(logging.CRITICAL)
class psychopy.logging.LogFile(f=None,level=30,filemode=’a’,logger=None,encoding=’utf8’)
A text stream to receive inputs from the logging system
Create a log file as a target for logged entries of a given level
Parameters
•f: this could be a string to a path, that will be created if it doesn’t exist. Alternatively this
could be a file object, sys.stdout or any object that supports .write() and .flush() methods
•level: The minimum level of importance that a message must have to be logged by this
target.
•mode: ‘a’, ‘w’ Append or overwrite existing log file
setLevel(level)
Set a new minimal level for the log file/stream
17.10. psychopy.logging - control what gets logged 187
PsychoPy - Psychology software for Python, Release 1.78.00
write(txt)
Write directy to the log file (without using logging functions). Useful to send messages that only this file
receives
psychopy.logging.addLevel(level,levelName)
Associate ‘levelName’ with ‘level’.
This is used when converting levels to text during message formatting.
psychopy.logging.critical(message)
Send the message to any receiver of logging info (e.g. a LogFile) of level log.CRITICAL or higher
psychopy.logging.data(msg,t=None,obj=None)
Log a message about data collection (e.g. a key press)
usage:: log.data(message)
Sends the message to any receiver of logging info (e.g. a LogFile) of level log.DATA or higher
psychopy.logging.debug(msg,t=None,obj=None)
Log a debugging message (not likely to be wanted once experiment is finalised)
usage:: log.debug(message)
Sends the message to any receiver of logging info (e.g. a LogFile) of level log.DEBUG or higher
psychopy.logging.error(message)
Send the message to any receiver of logging info (e.g. a LogFile) of level log.ERROR or higher
psychopy.logging.exp(msg,t=None,obj=None)
Log a message about the experiment (e.g. a new trial, or end of a stimulus)
usage:: log.exp(message)
Sends the message to any receiver of logging info (e.g. a LogFile) of level log.EXP or higher
psychopy.logging.fatal(msg,t=None,obj=None)
log.critical(message) Send the message to any receiver of logging info (e.g. a LogFile) of level log.CRITICAL
or higher
psychopy.logging.flush(logger=<psychopy.logging._Logger instance at 0x1f8f788>)
Send current messages in the log to all targets
psychopy.logging.getLevel(level)
Return the textual representation of logging level ‘level’.
If the level is one of the predefined levels (CRITICAL, ERROR, WARNING, INFO, DEBUG) then you get the
corresponding string. If you have associated levels with names using addLevelName then the name you have
associated with ‘level’ is returned.
If a numeric value corresponding to one of the defined levels is passed in, the corresponding string representation
is returned.
Otherwise, the string “Level %s” % level is returned.
psychopy.logging.info(msg,t=None,obj=None)
Log some information - maybe useful, maybe not
usage:: log.info(message)
Sends the message to any receiver of logging info (e.g. a LogFile) of level log.INFO or higher
psychopy.logging.log(msg,level,t=None,obj=None)
Log a message
usage:: log(level, msg, t=t, obj=obj)
188 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Log the msg, at a given level on the root logger
psychopy.logging.setDefaultClock(clock)
Set the default clock to be used to reference all logging times. Must be a psychopy.core.Clock object.
Beware that if you reset the clock during the experiment then the resets will be reflected here. That might be
useful if you want your logs to be reset on each trial, but probably not.
psychopy.logging.warn(msg,t=None,obj=None)
log.warning(message)
Sends the message to any receiver of logging info (e.g. a LogFile) of level log.WARNING or higher
psychopy.logging.warning(message)
Sends the message to any receiver of logging info (e.g. a LogFile) of level log.WARNING or higher
17.10.1 flush()
psychopy.logging.flush(logger=<psychopy.logging._Logger instance at 0x1f8f788>)
Send current messages in the log to all targets
17.10.2 setDefaultClock()
psychopy.logging.setDefaultClock(clock)
Set the default clock to be used to reference all logging times. Must be a psychopy.core.Clock object.
Beware that if you reset the clock during the experiment then the resets will be reflected here. That might be
useful if you want your logs to be reset on each trial, but probably not.
17.11 psychopy.microphone - Capture and analyze sound
(Available as of version 1.74.00; Advanced features available as of 1.77.00)
17.11.1 Overview
AudioCapture() allows easy audio recording and saving of arbitrary sounds to a file (wav format). AudioCapture will
likely be replaced entirely by AdvAudioCapture in the near future.
AdvAudioCapture() can do everything AudioCapture does, and also allows onset-marker sound insertion and de-
tection, loudness computation (RMS audio “power”), and lossless file compression (flac). The Builder microphone
component now uses AdvAudioCapture by default.
Speech2Text() provides speech recognition (courtesy of google), with about 1-2 seconds latency for a 2 sec voice
recording. Note that the sound files are sent to google over the internet. Intended for within-experiment processing
(near real-time, 1-2s delayed), in which priority is given to keeping an experiment session moving along, even if that
means skipping a slow response once in a while. See coder demo > input > speech_recognition.py.
Eventually, other features are planned, including: speech onset detection (to automatically estimate vocal RT for
a given speech sample), and interactive visual inspection of sound waveform, with playback and manual onset
determination (= the “gold standard” for RT).
17.11. psychopy.microphone - Capture and analyze sound 189
PsychoPy - Psychology software for Python, Release 1.78.00
17.11.2 Audio Capture
psychopy.microphone.switchOn(sampleRate=48000,outputDevice=None,bufferSize=None)
You need to switch on the microphone before use, which can take several seconds. The only time you can
specify the sample rate (in Hz) is during switchOn().
Considerations on the default sample rate 48kHz:
DVD or video = 48,000
CD-quality = 44,100 / 24 bit
human hearing: ~15,000 (adult); children & young adult higher
human speech: 100-8,000 (useful for telephone: 100-3,300)
google speech API: 16,000 or 8,000 only
Nyquist frequency: twice the highest rate, good to oversample a bit
pyo’s downsamp() function can reduce 48,000 to 16,000 in about 0.02s (uses integer steps sizes) So recording
at 48kHz will generate high-quality archival data, and permit easy downsampling.
outputDevice, bufferSize: set these parameters on the pyoSndServer before booting; None means use
pyo’s default values
class psychopy.microphone.AdvAudioCapture(name=’advMic’,filename=’‘,saveDir=’‘,sample-
type=0,buffering=16,chnl=0,stereo=True)
Class extends AudioCapture, plays a marker sound as a “start” indicator.
Has method for retrieving the marker onset time from the file, to allow calculation of vocal RT (or other sound-
based RT).
See Coder demo > input > latencyFromTone.py
compress(keep=False)
Compress using FLAC (lossless compression).
getLoudness()
Return the RMS loudness of the saved recording.
getMarkerInfo()
Returns (hz, duration, volume) of the marker sound. Custom markers always return 0 hz (regardless of the
sound).
getMarkerOnset(chunk=128,secs=0.5,filename=’‘)
Return (onset, offset) time of the first marker within the first secs of the saved recording.
Has approx ~1.33ms resolution at 48000Hz, chunk=64. Larger chunks can speed up processing times, at
a sacrifice of some resolution, e.g., to pre-process long recordings with multiple markers.
If given a filename, it will first set that file as the one to work with, and then try to detect the onset marker.
playMarker()
Plays the current marker sound. This is automatically called at the start of recording, but can be called
anytime to insert a marker.
playback(block=True)
Plays the saved .wav file, as just recorded or resampled. Execution blocks by default, but can return
immediately with block=False.
record(sec,filename=’‘,block=False)
Starts recording and plays an onset marker tone just prior to returning. The idea is that the start of the tone
in the recording indicates when this method returned, to enable you to sync a known recording onset with
other events.
resample(newRate=16000,keep=True)
Re-sample the saved file to a new rate, return the full path.
190 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Can take several visual frames to resample a 2s recording.
The default values for resample() are for google-speech, keeping the original (presumably recorded at
48kHz) to archive. A warning is generated if the new rate not an integer factor / multiple of the old rate.
To control anti-aliasing, use pyo.downsamp() or upsamp() directly.
reset()
Restores to fresh state, ready to record again
setFile(filename)
Sets the name of the file to work with, e.g., for getting onset time.
setMarker(tone=19000,secs=0.015,volume=0.03)
Sets the onset marker, where tone is either in hz or a custom sound.
The default tone (19000 Hz) is recommended for auto-detection, as being easier to isolate from speech
sounds (and so reliable to detect). The default duration and volume are appropriate for a quiet setting
such as a lab testing room. A louder volume, longer duration, or both may give better results when
recording loud sounds or in noisy environments, and will be auto-detected just fine (even more easily). If
the hardware microphone in use is not physically near the speaker hardware, a louder volume is likely to
be required.
Custom sounds cannot be auto-detected, but are supported anyway for presentation purposes. E.g., a
recording of someone saying “go” or “stop” could be passed as the onset marker.
stop()
Interrupt a recording that is in progress; close & keep the file.
Ends the recording before the duration that was initially specified. The same file name is retained, with the
same onset time but a shorter duration.
The same recording cannot be resumed after a stop (it is not a pause), but you can start a new one.
uncompress(keep=False)
Uncompress from FLAC to .wav format.
17.11.3 Speech recognition
class psychopy.microphone.Speech2Text(filename,lang=’en-US’,timeout=10,samplin-
grate=16000,pro_filter=2,quiet=True)
Class for speech-recognition (voice to text), using Google’s public API.
Google’s speech API is currently free to use, and seems to work well. Intended for within-experiment processing
(near real-time, 1-2s delayed), in which its often important to skip a slow or failed response, and not wait a long
time; BatchSpeech2Text() reverses these priorities.
It is possible (and perhaps even likely) that Google will start charging for usage. In addition, they can change
the interface at any time, including in the middle of an experiment. (If so, please post to the user list and we’ll
try to develop a fix, but there could still be some downtime.) Presumably, confidential or otherwise sensitive
voice data should not be sent to google.
Note Requires that flac is installed (free download from https://xiph.org/flac/download.html). If you
download and install flac, but get an error that flac is missing, try setting the full path to flac in
preferences -> general -> flac.
Usage
1.Always import and make an object; no data are available yet:
17.11. psychopy.microphone - Capture and analyze sound 191
PsychoPy - Psychology software for Python, Release 1.78.00
from microphone import Speech2Text
gs =Speech2Text(’speech_clip.wav’)# set-up only
2.Then, either: Initiate a query and wait for response from google (or until the time-out limit is reached).
This is “blocking” mode, and is the easiest to do:
resp =gs.getResponse() # execution blocks here
print resp.word, resp.confidence
3.Or instead (advanced usage): Initiate a query, but do not wait for a response (“thread” mode: no blocking,
no timeout, more control). running will change to False when a response is received (or hang indefinitely
if something goes wrong–so you might want to implement a time-out as well):
resp =gs.getThread() # returns immediately
while resp.running:
print ’.’,# displays dots while waiting
sys.stdout.flush()
core.wait(0.1)
print resp.words
4.Options: Set-up with a different language for the same speech clip; you’ll get a different response (possibly
having UTF-8 characters):
gs =Speech2Text(’speech_clip.wav’, lang=’ja-JP’)
resp =gs.getResponse()
Example See Coder demos / input / speech_recognition.py
Known limitations Availability is subject to the whims of google. Any changes google makes along
the way could either cause complete failure (disruptive), or could cause slightly different results
to be obtained (without it being readily obvious that something had changed). For this reason,
its probably a good idea to re-run speech samples through Speech2Text at the end of a study; see
BatchSpeech2Text().
Author Jeremy R. Gray, with thanks to Lefteris Zafiris for his help and excellent command-line
perl script at https://github.com/zaf/asterisk-speech-recog (GPLv2)
Parameters
filename [<required>] name of the speech file (.flac, .wav, or .spx) to process. wav files will be
converted to flac, and for this to work you need to have flac (as an executable). spx format
is speex-with-headerbyte (for google).
lang :the presumed language of the speaker, as a locale code; default ‘en-US’
timeout :seconds to wait before giving up, default 10
samplingrate :the sampling rate of the speech clip in Hz, either 16000 or 8000. You can record
at a higher rate, and then down-sample to 16000 for speech recognition. file is the down-
sampled file, not the original. the sampling rate is auto-detected for .wav files.
pro_filter :profanity filter level; default 2 (e.g., f***)
quiet :no reporting intermediate details; default True (non-verbose)
getResponse()
Calls getThread(), and then polls the thread until there’s a response.
Will time-out if no response comes within timeout seconds. Returns an object having the speech data in
its namespace. If there’s no match, generally the values will be equivalent to None (e.g., an empty string).
192 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
If you do resp = getResponse(), you’ll be able to access the data in several ways:
resp.word :the best match, i.e., the most probably word, or None
resp.confidence :google’s confidence about .word, ranging 0 to 1
resp.words :tuple of up to 5 guesses; so .word == .words[0]
resp.raw :the raw response from google (just a string)
resp.json :a parsed version of raw, from json.load(raw)
getThread()
Send a query to google using a new thread, no blocking or timeout.
Returns a thread which will eventually (not immediately) have the speech data in its namespace; see
getResponse. In theory, you could have several threads going simultaneously (almost all the time is spent
waiting for a response), rather than doing them sequentially (not tested).
class psychopy.microphone.BatchSpeech2Text(files,threads=3,verbose=False)
Like Speech2Text(), but takes a list of sound files or a directory name to search for matching sound files, and
returns a list of (filename, response) tuples. response‘s are described in Speech2Text.getResponse().
Can use up to 5 concurrent threads. Intended for post-experiment processing of multiple files, in which waiting
for a slow response is not a problem (better to get the data).
If files is a string, it will be used as a directory name for glob (matching all *.wav,*.flac, and *.spx files). There’s
currently no re-try on http error.
17.11.4 Misc
PsychoPy provides lossless compression using FLAC codec. (This requires that flac is installed on your computer. It
is not included with PsychoPy by default, but you can download for free from http://xiph.org/flac/ ). Functions for
file-oriented Discrete Fourier Transform and RMS computation are also provided.
psychopy.microphone.wav2flac(path,keep=True)
Lossless compression: convert .wav file (on disk) to .flac format.
If path is a directory name, convert all .wav files in the directory.
keep to retain the original .wav file(s), default True.
psychopy.microphone.flac2wav(path,keep=True)
Uncompress: convert .flac file (on disk) to .wav format (new file).
If path is a directory name, convert all .flac files in the directory.
keep to retain the original .flac file(s), default True.
psychopy.microphone.getDft(data,sampleRate=None,wantPhase=False)
Compute and return magnitudes of numpy.fft.fft() of the data.
If given a sample rate (samples/sec), will return (magn, freq). If wantPhase is True, phase in radians is also
returned (magn, freq, phase). data should have power-of-2 samples, or will be truncated.
psychopy.microphone.getRMS(data)
Compute and return the audio power (“loudness”).
Identical to std() if the mean is 0; .wav data should have a mean of 0. Returns an array if given stereo data (RMS
computed within-channel).
data can be an array (1D, 2D) or filename; .wav format only. data from .wav files will be normalized to -1..+1
before RMS is computed.
17.11. psychopy.microphone - Capture and analyze sound 193
PsychoPy - Psychology software for Python, Release 1.78.00
17.12 psychopy.misc - miscellaneous routines for converting units
etc
Tools, nothing to do with psychophysics or experiments - just handy things like conversion functions etc...
psychopy.misc.array2image(a)
Takes an array and returns an image object (PIL)
psychopy.misc.cart2pol(x,y,units=’deg’)
Convert from cartesian to polar coordinates
Usage theta, radius = pol2cart(x, y, units=’deg’)
units refers to the units (rad or deg) for theta that should be returned
psychopy.misc.cart2sph(z,y,x)
Convert from cartesian coordinates (x,y,z) to spherical (elevation, azimuth, radius). Output is in degrees.
usage: array3xN[el,az,rad] = cart2sph(array3xN[x,y,z]) OR elevation, azimuth, radius = cart2sph(x,y,z)
If working in DKL space, z = Luminance, y = S and x = LM
psychopy.misc.cm2deg(cm,monitor)
Convert size in cm to size in degrees for a given Monitor object
psychopy.misc.cm2pix(cm,monitor)
Convert size in degrees to size in pixels for a given Monitor object
psychopy.misc.createXYs(x,y=None)
Create an Nx2 array of XY values including all combinations of the x and y values provided.
>>> createXYs(x=[1,2,3],y=[4,5,6])
array([[1, 4],
[2, 4],
[3, 4],
[1, 5],
[2, 5],
[3, 5],
[1, 6],
[2, 6],
[3, 6]])
>>> createXYs(x=[1,2,3]) #assumes y=x
array([[1, 1],
[2, 1],
[3, 1],
[1, 2],
[2, 2],
[3, 2],
[1, 3],
[2, 3],
[3, 3]])
psychopy.misc.deg2cm(degrees,monitor)
Convert size in degrees to size in pixels for a given Monitor object
psychopy.misc.deg2pix(degrees,monitor)
Convert size in degrees to size in pixels for a given Monitor object
psychopy.misc.dkl2rgb(dkl,conversionMatrix=None)
Convert from DKL color space (cone-opponent space from Derrington, Krauskopf & Lennie) to RGB.
194 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied
(note that this will not be an accurate representation of the color space unless you supply a conversion matrix).
usage:
rgb(Nx3) =dkl2rgb(dkl_Nx3(el,az,radius), conversionMatrix)
rgb(NxNx3) =dkl2rgb(dkl_NxNx3(el,az,radius), conversionMatrix)
psychopy.misc.dklCart2rgb(LUM,LM,S,conversionMatrix=None)
Like dkl2rgb except that it uses cartesian coords (LM,S,LUM) rather than spherical coords for DKL (elev, azim,
contr)
NB: this may return rgb values >1 or <-1
psychopy.misc.extendArr(inArray,newSize)
Takes a numpy array and returns it padded with zeros to the necessary size
>>> misc.extendArr([1,2,3],5)
array([1, 2, 3, 0, 0])
psychopy.misc.float_uint16(inarray)
Converts arrays, lists, tuples and floats ranging -1:1 into an array of Uint16s ranging 0:2^16
psychopy.misc.float_uint8(inarray)
Converts arrays, lists, tuples and floats ranging -1:1 into an array of Uint8s ranging 0:255
>>> float_uint8(-1)
0
>>> float_uint8(0)
128
psychopy.misc.fromFile(filename)
load data (of any sort) from a pickle file
simple wrapper of the cPickle module in core python
psychopy.misc.hsv2rgb(hsv_Nx3)
Convert from HSV color space to RGB gun values
usage:
rgb_Nx3 =hsv2rgb(hsv_Nx3)
Note that in some uses of HSV space the Hue component is given in radians or cycles (range 0:1]). In this
version H is given in degrees (0:360).
Also note that the RGB output ranges -1:1, in keeping with other PsychoPy functions
psychopy.misc.image2array(im)
Takes an image object (PIL) and returns a numpy array
psychopy.misc.lms2rgb(lms_Nx3,conversionMatrix=None)
Convert from cone space (Long, Medium, Short) to RGB.
Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied
(note that you will not get an accurate representation of the color space unless you supply a conversion matrix)
usage:
rgb_Nx3 =lms2rgb(dkl_Nx3(el,az,radius), conversionMatrix)
psychopy.misc.makeImageAuto(inarray)
Combines float_uint8 and image2array operations ie. scales a numeric array from -1:1 to 0:255 and converts to
PIL image format
17.12. psychopy.misc - miscellaneous routines for converting units etc 195
PsychoPy - Psychology software for Python, Release 1.78.00
psychopy.misc.mergeFolder(src,dst,pattern=None)
Merge a folder into another.
Existing files in dst with the same name will be overwritten. Non-existent files/folders will be created.
psychopy.misc.pix2cm(pixels,monitor)
Convert size in pixels to size in cm for a given Monitor object
psychopy.misc.pix2deg(pixels,monitor)
Convert size in pixels to size in degrees for a given Monitor object
psychopy.misc.plotFrameIntervals(intervals)
Plot a histogram of the frame intervals.
Where intervals is either a filename to a file, saved by Window.saveFrameIntervals or simply a list (or array) of
frame intervals
psychopy.misc.pol2cart(theta,radius,units=’deg’)
Convert from polar to cartesian coordinates
usage:
x,y =pol2cart(theta, radius, units=’deg’)
psychopy.misc.radians(degrees)
Convert degrees to radians
>>> radians(180)
3.1415926535897931
>>> degrees(45)
0.78539816339744828
psychopy.misc.ratioRange(start,nSteps=None,stop=None,stepRatio=None,stepdB=None,stepLo-
gUnits=None)
Creates a array where each step is a constant ratio rather than a constant addition.
Specify start and any 2 of, nSteps,stop,stepRatio,stepdB,stepLogUnits
>>> ratioRange(1,nSteps=4,stop=8)
array([ 1., 2., 4., 8.])
>>> ratioRange(1,nSteps=4,stepRatio=2)
array([ 1., 2., 4., 8.])
>>> ratioRange(1,stop=8,stepRatio=2)
array([ 1., 2., 4., 8.])
psychopy.misc.rgb2dklCart(picture,conversionMatrix=None)
Convert an RGB image into Cartesian DKL space
psychopy.misc.rgb2lms(rgb_Nx3,conversionMatrix=None)
Convert from RGB to cone space (LMS)
Requires a conversion matrix, which will be generated from generic Sony Trinitron phosphors if not supplied
(note that you will not get an accurate representation of the color space unless you supply a conversion matrix)
usage:
lms_Nx3 =rgb2lms(rgb_Nx3(el,az,radius), conversionMatrix)
psychopy.misc.shuffleArray(inArray,shuffleAxis=-1,seed=None)
Takes a (flat) num array, list or string and returns a shuffled version as a num array with the same shape. Optional
argument ShuffleAxis determines the axis to shuffle along (default=-1 meaning shuffle across entire matrix?)
THIS DOESN’T WORK WITH MATRICES YET - ONLY FLAT ARRAYS - APPEARS TO BE BUG IN
EITHER NUMPY.ARGSORT() OR NUMPY.TAKE()
196 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
psychopy.misc.sph2cart(*args)
Convert from spherical coordinates (elevation, azimuth, radius) to cartesian (x,y,z)
usage: array3xN[x,y,z] = sph2cart(array3xN[el,az,rad]) OR x,y,z = sph2cart(elev, azim, radius)
psychopy.misc.toFile(filename,data)
save data (of any sort) as a pickle file
simple wrapper of the cPickle module in core python
psychopy.misc.uint8_float(inarray)
Converts arrays, lists, tuples and UINTs ranging 0:255 into an array of floats ranging -1:1
17.13 psychopy.monitors - for those that don’t like Monitor Center
Most users won’t need to use the code here. In general the Monitor Centre interface is sufficient and monitors setup
that way can be passed as strings to Window s. If there is some aspect of the normal calibration that you wish to
override. eg:
from psychopy import visual, monitors
mon =monitors.Monitor(’SonyG55’)#fetch the most recent calib for this monitor
mon.setDistance(114)#further away than normal?
win =visual.Window(size=[1024,768], monitor=mon)
You might also want to fetch the Photometer class for conducting your own calibrations
17.13.1 Monitor
class psychopy.monitors.Monitor(name,width=None,distance=None,gamma=None,notes=None,
useBits=None,verbose=True,currentCalib={})
Creates a monitor object for storing calibration details. This will be loaded automatically from disk if the
monitor name is already defined (see methods).
Many settings from the stored monitor can easilly be overridden either by adding them as arguments during the
initial call.
arguments:
•width, distance, gamma are details about the calibration
•notes is a text field to store any useful info
•useBits True, False, None
•verbose True, False, None
•currentCalib is a dict object containing various fields for a calibration. Use with caution since
the dict may not contain all the necessary fields that a monitor object expects to find.
eg:
myMon = Monitor(’sony500’, distance=114) Fetches the info on the sony500 and overrides its
usual distance to be 114cm for this experiment.
myMon = Monitor(’sony500’) followed by...
myMon[’distance’]=114 ...does the same!
For both methods, if you then save any modifications will be saved as well.
17.13. psychopy.monitors - for those that don’t like Monitor Center 197
PsychoPy - Psychology software for Python, Release 1.78.00
copyCalib(calibName=None)
Stores the settings for the current calibration settings as new monitor.
delCalib(calibName)
Remove a specific calibration from the current monitor. Won’t be finalised unless monitor is saved
gammaIsDefault()
Determine whether we’re using the default gamma values
getCalibDate()
As a python date object (convert to string using calibTools.strFromDate
getDKL_RGB(RECOMPUTE=False)
Returns the DKL->RGB conversion matrix. If one has been saved this will be returned. Otherwise, if
power spectra are available for the monitor a matrix will be calculated.
getDistance()
Returns distance from viewer to the screen in cm, or None if not known
getGamma()
getGammaGrid()
Gets the min,max,gamma values for the each gun
getLMS_RGB(RECOMPUTE=False)
Returns the LMS->RGB conversion matrix. If one has been saved this will be returned. Otherwise (if
power spectra are available for the monitor) a matrix will be calculated.
getLevelsPost()
Gets the measured luminance values from last calibration TEST
getLevelsPre()
Gets the measured luminance values from last calibration
getLineariseMethod()
Gets the min,max,gamma values for the each gun
getLumsPost()
Gets the measured luminance values from last calibration TEST
getLumsPre()
Gets the measured luminance values from last calibration
getMeanLum()
getNotes()
Notes about the calibration
getPsychopyVersion()
getSizePix()
Returns the size of the current calibration in pixels, or None if not defined
getSpectra()
Gets the wavelength values from the last spectrometer measurement (if available)
usage:
• nm, power = monitor.getSpectra()
getUseBits()
Was this calibration carried out witha a bits++ box
getWidth()
Of the viewable screen in cm, or None if not known
198 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
lineariseLums(desiredLums,newInterpolators=False,overrideGamma=None)
lums should be uncalibrated luminance values (e.g. a linear ramp) ranging 0:1
newCalib(calibName=None,width=None,distance=None,gamma=None,notes=None,
useBits=False,verbose=True)
create a new (empty) calibration for this monitor and makes this the current calibration
saveMon()
saves the current dict of calibs to disk
setCalibDate(date=None)
Sets the calibration to a given date/time or to the current date/time if none given. (Also returns the date as
set)
setCurrent(calibration=-1)
Sets the current calibration for this monitor. Note that a single file can hold multiple calibrations each
stored under a different key (the date it was taken)
The argument is either a string (naming the calib) or an integer eg:
myMon.setCurrent’mainCalib’) fetches the calibration named mainCalib calibName
= myMon.setCurrent(0) fetches the first calibration (alphabetically) for this monitor
calibName = myMon.setCurrent(-1) fetches the last alphabetical calib for this moni-
tor (this is default) If default names are used for calibs (ie date/time stamp) then this will import
the most recent.
setDKL_RGB(dkl_rgb)
sets the DKL->RGB conversion matrix for a chromatically calibrated monitor (matrix is a 3x3 num array).
setDistance(distance)
To the screen (cm)
setGamma(gamma)
Sets the gamma value(s) for the monitor. This only uses a single gamma value for the three guns, which is
fairly approximate. Better to use setGammaGrid (which uses one gamma value for each gun)
setGammaGrid(gammaGrid)
Sets the min,max,gamma values for the each gun
setLMS_RGB(lms_rgb)
sets the LMS->RGB conversion matrix for a chromatically calibrated monitor (matrix is a 3x3 num array).
setLevelsPost(levels)
Sets the last set of luminance values measured AFTER calibration
setLevelsPre(levels)
Sets the last set of luminance values measured during calibration
setLineariseMethod(method)
Sets the method for linearising 0 uses y=a+(bx)^gamma 1 uses y=(a+bx)^gamma 2 uses linear interpola-
tion over the curve
setLumsPost(lums)
Sets the last set of luminance values measured AFTER calibration
setLumsPre(lums)
Sets the last set of luminance values measured during calibration
setMeanLum(meanLum)
Records the mean luminance (for reference only)
setNotes(notes)
For you to store notes about the calibration
17.13. psychopy.monitors - for those that don’t like Monitor Center 199
PsychoPy - Psychology software for Python, Release 1.78.00
setPsychopyVersion(version)
setSizePix(pixels)
setSpectra(nm,rgb)
sets the phosphor spectra measured by the spectrometer
setUseBits(usebits)
setWidth(width)
Of the viewable screen (cm)
17.13.2 GammaCalculator
class psychopy.monitors.GammaCalculator(inputs=[],lums=[],gamma=None,bitsIN=8,bit-
sOUT=8,eq=1)
Class for managing gamma tables
Parameters:
•inputs (required)= values at which you measured screen luminance either in range 0.0:1.0, or range
0:255. Should include the min and max of the monitor
Then give EITHER “lums” or “gamma”:
•lums = measured luminance at given input levels
•gamma = your own gamma value (single float)
•bitsIN = number of values in your lookup table
•bitsOUT = number of bits in the DACs
myTable.gammaModel myTable.gamma
fitGammaErrFun(params,x,y,minLum,maxLum)
Provides an error function for fitting gamma function
(used by fitGammaFun)
fitGammaFun(x,y)
Fits a gamma function to the monitor calibration data.
Parameters: -xVals are the monitor look-up-table vals (either 0-255 or 0.0-1.0) -yVals are the measured
luminances from a photometer/spectrometer
17.13.3 getAllMonitors()
psychopy.monitors.getAllMonitors()
Find the names of all monitors for which calibration files exist
17.13.4 findPR650()
psychopy.monitors.findPR650(ports=None)
DEPRECATED (as of v.1.60.01). Use psychopy.hardware.findPhotometer() instead, which finds
a wider range of devices
200 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
17.13.5 getLumSeriesPR650()
psychopy.monitors.getLumSeriesPR650(lumLevels=8,winSize=(800,600),monitor=None,
gamma=1.0,allGuns=True,useBits=False,auto-
Mode=’auto’,stimSize=0.3,photometer=’COM1’)
DEPRECATED (since v1.60.01): Use pscyhopy.monitors.getLumSeries() instead
17.13.6 getRGBspectra()
psychopy.monitors.getRGBspectra(stimSize=0.3,winSize=(800,600),photometer=’COM1’)
usage: getRGBspectra(stimSize=0.3, winSize=(800,600), photometer=’COM1’)
Params
• ‘photometer’ could be a photometer object or a serial port name on which
a photometer might be found (not recommended)
17.13.7 gammaFun()
psychopy.monitors.gammaFun(xx,minLum,maxLum,gamma,eq=1,a=None,b=None,k=None)
Returns gamma-transformed luminance values. y = gammaFun(x, minLum, maxLum, gamma)
a and b are calculated directly from minLum, maxLum, gamma
Parameters:
•xx are the input values (range 0-255 or 0.0-1.0)
•minLum = the minimum luminance of your monitor
•maxLum = the maximum luminance of your monitor (for this gun)
•gamma = the value of gamma (for this gun)
17.13.8 gammaInvFun()
psychopy.monitors.gammaInvFun(yy,minLum,maxLum,gamma,b=None,eq=1)
Returns inverse gamma function for desired luminance values. x = gammaInvFun(y, minLum, maxLum,
gamma)
a and b are calculated directly from minLum, maxLum, gamma Parameters:
•xx are the input values (range 0-255 or 0.0-1.0)
•minLum = the minimum luminance of your monitor
•maxLum = the maximum luminance of your monitor (for this gun)
•gamma = the value of gamma (for this gun)
•eq determines the gamma equation used; eq==1[default]: yy = a + (b*xx)**gamma eq==2: yy = (a +
b*xx)**gamma
17.13. psychopy.monitors - for those that don’t like Monitor Center 201
PsychoPy - Psychology software for Python, Release 1.78.00
17.13.9 makeDKL2RGB()
psychopy.monitors.makeDKL2RGB(nm,powerRGB)
creates a 3x3 DKL->RGB conversion matrix from the spectral input powers
17.13.10 makeLMS2RGB()
psychopy.monitors.makeLMS2RGB(nm,powerRGB)
Creates a 3x3 LMS->RGB conversion matrix from the spectral input powers
17.14 psychopy.parallel - functions for interacting with the paral-
lel port
This module provides read/write access to the parallel port for Linux or Windows.
There is a legacy API which consists of the routines which are directly in this module. This API assumes you only
ever want to use a single parallel port at once. These routines will attempt to autodetect the method which should be
used to access your parallel port from those available.
There is also a newer, class-based API exposed in the classes PParallelLinux,PParallelInpOut32 and
PParallelDLPortIO. Each instance of these classes can be used to access a different parallel port.
psychopy.parallel.readPin(pinNumber)
Determine whether a desired (input) pin is high(1) or low(0).
Pins 2-13 and 15 are currently read here
psychopy.parallel.setData(data)
Set the data to be presented on the parallel port (one ubyte). Alternatively you can set the value of each pin (data
pins are pins 2-9 inclusive) using setPin()
examples:
parallel.setData(0)#sets all pins low
parallel.setData(255)#sets all pins high
parallel.setData(2)#sets just pin 3 high (remember that pin2=bit0)
parallel.setData(3)#sets just pins 2 and 3 high
you can also convert base 2 to int v easily in python:
parallel.setData( int("00000011",2) )#pins 2 and 3 high
parallel.setData( int("00000101",2) )#pins 2 and 4 high
psychopy.parallel.setPin(pinNumber,state)
Set a desired pin to be high(1) or low(0).
Only pins 2-9 (incl) are normally used for data output:
parallel.setPin(3,1)#sets pin 3 high
parallel.setPin(3,0)#sets pin 3 low
psychopy.parallel.setPortAddress(address=888)
Set the memory address or device node for your parallel port of your parallel port, to be used in subsequent
commands
common port addresses:
202 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
LPT1 =0x0378 or 0x03BC
LPT2 =0x0278 or 0x0378
LPT3 =0x0278
or for Linux:: /dev/parport0
This routine will attempt to find a usable driver depending on your platform
17.14.1 PParallelLinux
class psychopy.parallel.PParallelLinux(address=’/dev/parport0’)
This class provides read/write access to the parallel port for linux using pyparallel.
Note that you must have the lp module removed and the ppdev module loaded to use this code:
sudo rmmod lp
sudo modprobe ppdev
Set the device node of your parallel port
common port addresses:
LPT1 = /dev/parport0
LPT2 = /dev/parport1
LPT3 = /dev/parport2
17.14.2 PParallelInpOut32
class psychopy.parallel.PParallelInpOut32(address=888)
This class provides read/write access to the parallel port on a PC using inpout32 (for instance for Windows 7
64-bit)
Set the memory address of your parallel port, to be used in subsequent calls to this object
common port addresses:
LPT1 =0x0378 or 0x03BC
LPT2 =0x0278 or 0x0378
LPT3 =0x0278
17.14.3 PParallelDLPortIO
class psychopy.parallel.PParallelDLPortIO(address=888)
This class provides read/write access to the parallel port on a PC.
This is a wrapper around Dincer Aydin’s ‘winioport‘_ for reading and writing to the parallel port, but adds the
following additional functions for convenience.
On windows ‘winioport‘_ requires the ‘PortIO driver‘_ to be installed.
An alternative on Linux might be to use PyParallel An alternative on other versions of Windows might be to use
inpout32.
. _winioport: http://www.dinceraydin.com/python/indexeng.html .. _PortIO driver:
http://www.winfordeng.com/support/download.php
Set the memory address of your parallel port, to be used in subsequent method calls on this class.
17.14. psychopy.parallel - functions for interacting with the parallel port 203
PsychoPy - Psychology software for Python, Release 1.78.00
common port addresses:
LPT1 =0x0378 or 0x03BC
LPT2 =0x0278 or 0x0378
LPT3 =0x0278
17.15 psychopy.serial - functions for interacting with the serial
port
PsychoPy is compatible with Chris Liechti’s pyserial package. You can use it like this:
import serial
ser =serial.Serial(0,19200, timeout=1)# open first serial port
#ser = serial.Serial(’/dev/ttyS1’, 19200, timeout=1)#or something like this for mac/linux machines
ser.write(’someCommand’)
line =ser.readline() # read a ’\n’ terminated line
ser.close()
Ports are fully configurable with all the options you would expect of RS232 communications. See
http://pyserial.sourceforge.net for further details and documentation.
pyserial is packaged in the Standalone (win and mac distributions), for manual installations you should install this
yourself.
17.16 psychopy.sound - play various forms of sound
17.16.1 Sound
class psychopy.sound.SoundPygame(value=’C’,secs=0.5,octave=4,sampleRate=44100,bits=16,
name=’‘,autoLog=True)
Create a sound object, from one of many ways.
Parameters
value: can be a number, string or an array:
• If it’s a number between 37 and 32767 then a tone will be generated at that frequency in
Hz.
• It could be a string for a note (‘A’,’Bfl’,’B’,’C’,’Csh’...). Then you may want to specify
which octave as well
• Or a string could represent a filename in the current location, or mediaLocation, or a full
path combo
• Or by giving an Nx2 numpy array of floats (-1:1) you can specify the sound yourself as a
waveform
secs: duration (only relevant if the value is a note name or a frequency value)
octave: is only relevant if the value is a note name. Middle octave of a piano is 4. Most com-
puters won’t output sounds in the bottom octave (1) and the top octave (8) is generally
painful
sampleRate(=44100): If a sound has already been created or if the
bits(=16): Pygame uses the same bit depth for all sounds once initialised
204 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
fadeOut(mSecs)
fades out the sound (when playing) over mSecs. Don’t know why you would do this in psychophysics but
it’s easy and fun to include as a possibility :)
getDuration()
Get’s the duration of the current sound in secs
getVolume()
Returns the current volume of the sound (0.0:1.0)
play(fromStart=True,log=True)
Starts playing the sound on an available channel. If no sound channels are available, it will not play and
return None.
This runs off a separate thread i.e. your code won’t wait for the sound to finish before continuing. You need
to use a psychopy.core.wait() command if you want things to pause. If you call play() whiles something is
already playing the sounds will be played over each other.
setVolume(newVol,log=True)
Sets the current volume of the sound (0.0:1.0)
stop(log=True)
Stops the sound immediately
17.17 psychopy.web - Web methods
17.17.1 Test for access
psychopy.web.haveInternetAccess(forceCheck=False)
Detect active internet connection or fail quickly.
If forceCheck is False, will rely on a cached value if possible.
psychopy.web.requireInternetAccess(forceCheck=False)
Checks for access to the internet, raise error if no access.
17.17.2 Upload a file over http
psychopy.web.upload(selector,filename,basicAuth=None,host=None,https=False)
Upload a local file over the internet to a configured http server.
This method handshakes with a php script on a remote server to transfer a local file to another machine via http
(using POST).
Returns “success” plus a sha256 digest of the file on the server and a byte count. If the upload was not successful,
an error code is returned (eg, “too_large” if the file size exceeds the limit specified server-side in up.php, or
“no_file” if there was no POST attachment).
Note: The server that receives the files needs to be configured before uploading will work. php files and notes
for a sys-admin are included in psychopy/contrib/http/. In particular, the php script up.php needs to be copied to
the server’s web-space, with appropriate permissions and directories, including apache basic auth and https (if
desired). The maximum size for an upload can be configured within up.php
A configured test-server is available; see the Coder demo for details (upload size is limited to ~1500 characters
for the demo).
17.17. psychopy.web - Web methods 205
PsychoPy - Psychology software for Python, Release 1.78.00
Parameters:
selector [(required, string)] a standard URL of the form http://host/path/to/up.php, e.g.,
http://upload.psychopy.org/test/up.php
Note: Limited https support is provided (see below).
filename [(required, string)] the path to the local file to be transferred. The file can be any format:
text, utf-8, binary. All files are hex encoded while in transit (increasing the effective file size).
Note: Encryption (beta) is available as a separate step. That is, first encrypt() the file, then
upload() the encrypted file in the same way that you would any other file.
basicAuth [(optional)] apache ‘user:password’ string for basic authentication. If a basicAuth value
is supplied, it will be sent as the auth credentials (in cleartext); using https will encrypt the
credentials.
host [(optional)] The default process is to extract host information from the selector. The host option
allows you to specify a host explicitly (i.e., if it differs from the selector).
https [(optional)] If the remote server is configured to use https, passing the parameter https=True
will encrypt the transmission including all data and basicAuth credentials. It is approximately as
secure as using a self-signed X.509 certificate.
An important caveat is that the authenticity of the certificate returned from the server is not
checked, and so the certificate could potentially be spoofed (see the warning under HTTPSCon-
nection http://docs.python.org/library/httplib.html). Overall, using https can still be much more
secure than not using it. The encryption is good, but that of itself does not eliminate all risk.
Importantly, it is not as secure as one might expect, given that all major web browsers do check
certificate authenticity. The idea behind this parameter is to require people to explicitly indicate
that they want to proceed anyway, in effect saying “I know what I am doing and accept the risks
(of using un-verified certificates)”.
Example:
See Coder demo / misc / http_upload.py
Author: Jeremy R. Gray, 2012
17.17.3 Proxy set-up and testing
psychopy.web.setupProxy()
Set up the urllib proxy if possible.
The function will use the following methods in order to try and determine proxies:
1. standard urllib2.urlopen (which will use any statically-defined http-proxy settings)
2. previous stored proxy address (in prefs)
3. proxy.pac files if these have been added to system settings
4. auto-detect proxy settings (WPAD technology)
Returns True (success) or False (failure)
206 Chapter 17. Reference Manual (API)
PsychoPy - Psychology software for Python, Release 1.78.00
psychopy.web.testProxy(handler,URL=None)
Test whether we can connect to a URL with the current proxy settings.
handler can be typically web.proxies, if web.setupProxy() has been run.
Returns
• True (success)
• a urllib2.URLError (which can be interrogated with .reason)
• a urllib2.HTTPError (which can be interrogated with .code)
For those that prefer Epydoc formatted API, that is also available here
17.18 Indices and tables
•genindex
•modindex
•search
17.18. Indices and tables 207
PsychoPy - Psychology software for Python, Release 1.78.00
208 Chapter 17. Reference Manual (API)
CHAPTER
EIGHTEEN
FOR DEVELOPERS
There is a separate mailing list to discuss development ideas and issues.
For developers the best way to use PsychoPy is to install a version to your own copy of python (preferably 2.6 but 2.5
is OK). Make sure you have all the Dependencies, including the extra recommendedPackages for developers.
Don’t install PsychoPy. Instead fetch a copy of the git repository and add this to the python path using a .pth file. Other
users of the computer might have their own standalone versions installed without your repository version touching
them.
18.1 Using the repository
Note: Much of the following is explained with more detail in the nitime documentation, and then in further detail in
numerous online tutorials.
18.1.1 Workflow
The use of git and the following workflow allows people to contribute changes that can easily be incorporated back
into the project, while (hopefully) maintaining order and consistency in the code. All changes should be tracked and
reversible.
• Create a fork of the central psychopy/psychopy repository
• Create a local clone of that fork
•For small changes
–make the changes directly in the master branch
–push back to your fork
–submit a pull request to the central repository
•For substantial changes (new features)
–create a branch
–when finished run unit tests
–when the unit tests pass merge changes back into the master branch
–submit a pull request to the central repository
209
PsychoPy - Psychology software for Python, Release 1.78.00
18.1.2 Create your own fork of the central repository
Go to github, create an account and make a fork of the psychopy repository You can change your fork in any way you
choose without it affecting the central project. You can also share your fork with others, including the central project.
18.1.3 Fetch a local copy
Install git on your computer. Create and upload an ssh key to your github account - this is necessary for you to push
changes back to your fork of the project at github.
Then, in a folder of your choosing fetch your fork:
$ git clone git@github.com:USER/psychopy.git
$ cd psychopy
$ git remote add upstream git://github.com/psychopy/psychopy.git
The last line connects your copy (with read access) to the central server so you can easily fetch any updates to the
central repository.
18.1.4 Fetching the latest version
Periodically it’s worth fetching any changes to the central psychopy repository (into your master branch, more on that
below):
$ git checkout master
$ git pull upstream master # here ’master’ is the desired branch of psychopy to fetch
18.1.5 Run PsychoPy using your local copy
Now that you’ve fetched the latest version of psychopy using git, you should run this version in order to try out
yours/others latest improvements. See this guide on how to permanently run your git version of psychopy instead of
the version you previously installed.
Run git version for just one session (linux and mac only): If you want to switch between the latest-and-greatest
development version from git and the stable version installed on your system, you can choose to only temporarily run
the git version. Open a terminal and set a temporary python path to your psychopy git folder, then start your editor of
choice:
$ export PYTHONPATH=/path/to/local/git/folder/
$ psychopy
18.1.6 Fixing bugs and making minor improvements
You can make minor changes directly in the master branch of your fork. After making a change you need to commit a
set of changes to your files with a message. This enables you to group together changes and you will subsequently be
able to go back to any previous commit, so your changes are reversible.
I (Jon) usually do this by opening the graphical user interface that comes with git:
$ git gui
From the GUI you can select (or stage in git terminology) the files that you want to include in this particular commit
and give it a message. Give a clear summary of the changes for the first line. You can add more details about the
changes on lower lines if needed.
210 Chapter 18. For Developers
PsychoPy - Psychology software for Python, Release 1.78.00
If you have internet access then you could also push your changes back up to your fork (which is called your origin
by default), either by pressing the push button in the GUI or by closing that and typing:
$ git push
18.1.7 Commit messages
Informative commit messages are really useful when we have to go back through the repository finding the time that a
particular change to the code occurred. Precede your message with one or more of the following to help us spot easily
if this is a bug fix (which might need pulling into other development branches) or new feature (which we might want
to avoid pulling in if it might disrupt existing code).
•BF : bug fix
•RF : refactoring
•NF : new feature
•ENH : enhancement (improvement to existing code)
•DOC: for all kinds of documentation related commits
•TEST: for adding or changing tests
18.1.8 Share your improvement with others
Only a couple of people have direct write-access to the psychopy repository, but you can get your changes included
in upstream by pushing your changes back to your github fork and then submitting a pull request. Communication is
good, and hopefully you have already been in touch (via the user or dev lists) about your changes.
When adding an improvement or new feature, consider how it might impact others. Is it likely to be generally useful,
or is it something that only you or your lab would need? (Its fun to contribute, but consider: does it actually need to
be part of PsychoPy?) Including more features has a downside in terms of complexity and bloat, so try to be sure that
there is a “business case” for including it. If there is, try at all times to be be backwards compatible, e.g., by adding a
new keyword argument to a method or function (not always possible). If its not possible, its crucial to get wider input
about the possible impacts. Flag situations that would break existing user scripts in your commit messages.
Part of sharing your code means making things sensible to others, which includes good coding style and writing some
documentation. You are the expert on your feature, and so are in the best position to elaborate nuances or gotchas. Use
meaningful variable names, and include comments in the code to explain non-trivial things, especially the intention
behind specific choices. Include or edit the appropriate doc-string, because these are automatically turned into API
documention (via sphinx). Include doc-tests if that would be meaningful. The existing code base has a comment /
code ratio of about 28%, which earns it high marks.
For larger changes and especially new features, you might need to create some usage examples, such as a new Coder
demo, or even a Builder demo. These can be invaluable for being a starting point from which people can adapt things
to the needs of their own situation. This is a good place to elaborate usage-related gotchas.
In terms of style, try to make your code blend in with and look like the existing code (e.g., using about the same level
of comments, use camelCase for var names, despite the conflict with the usual PEP – we’ll eventually move to the
underscore style, but for now keep everything consistent within the code base). In your own code, write however you
like of course. This is just about when contributing to the project.
18.1.9 Add a new feature branch
For more substantial work, you should create a new branch in your repository. Often whle working on a new feature
other aspects of the code will get broken and the master branch should always be in a working state. To create a new
18.1. Using the repository 211
PsychoPy - Psychology software for Python, Release 1.78.00
branch:
$ git branch feature-somethingNew
You can now switch to your new feature branch with:
$ git checkout feature-somethingNew
And get back to your master branch with:
$ git checkout master
You can push your new branch back to your fork (origin) with:
$ git push origin feature-somethingNew
18.1.10 Completing work on a feature
When you’re done run the unit tests for your feature branch. Set the debug preference setting (in the app section) to
True, and restart psychopy. This will enable access to the test-suite. In debug mode, from the Coder (not Builder) you
can now do Ctrl-T / Cmd-T (see Tools menu, Unit Testing) to bring up the unit test window. You can select a subset
of tests to run, or run them all.
Its also possible to run just selected tests, such as doctests within a single file. From a terminal window:
cd psychopy/tests/ #eg /Users/jgray/code/psychopy/psychopy/tests
./run.py path/to/file_with_doctests.py
If the tests pass you hopefully haven’t damaged other parts of PsychoPy (!?). If possible add a unit test for your new
feature too, so that if other people make changes they don’t break your work!
You can merge your changes back into your master branch with:
$ git checkout master
$ git merge feature-somethingNew
Merge conflicts happen, and need to be resolved. If you configure your git preferences (~/.gitconfig) to include:
[merge]
summary = true
log = true
tool = opendiff
then you’ll be able to use a handy GUI interface (opendiff) for reviewing differences and conflicts, just by typing:
git mergetool
from the command line after hitting a merge conflict (such as during a git pull upstream master).
Once you’ve folded your new code back into your master and pushed it back to your github fork then it’s time to Share
your improvement with others.
18.2 Adding documentation
There are several ways to add documentation, all of them useful: doc strings, comments in the code, and demos to
show an example of actual usage. To further explain something to end-users, you can create or edit a .rst file that will
automatically become formatted for the web, and eventually appear on www.psychopy.org.
212 Chapter 18. For Developers
PsychoPy - Psychology software for Python, Release 1.78.00
You make a new file under psychopy/docs/source/, either as a new file or folder or within an existing one.
To test that your doc source code (.rst file) does what you expect in terms of formatting for display on the web, you
can simply do something like (this is my actual path, unlikely to be yours):
$ cd /Users/jgray/code/psychopy/docs/
$ make html
Do this within your docs directory (requires sphinx to be installed, try “easy_install sphinx” if its not working). That
will add a build/html sub-directory.
Then you can view your new doc in a browser, e.g., for me:
file:///Users/jgray/code/psychopy/docs/build/html/
Push your changes to your github repository (using a “DOC:” commit message) and let Jon know, e.g. with a pull
request.
18.3 Adding a new Builder Component
Builder Components are auto-detected and displayed to the experimenter as icons (builder, right panel). This makes it
straightforward to add new ones.
All you need to do is create a list of parameters that the Component needs to know about (that will automatically
appear in the Component’s dialog) and a few pieces of code specifying what code should be called at different points
in the script (e.g. beginning of the Routine, every frame, end of the study etc...). Many of these will come simply from
subclassing the _base or _visual Components.
To get started, Add a new feature branch for the development of this component. (If this doesn’t mean anything to you
then see Using the repository )
You’ll mainly be working in the directory .../psychopy/app/builder/components/. Take a look at several existing Com-
ponents (such as ‘patch.py’), and key files including ‘_base.py’ and ‘_visual.py’.
There are three main steps, the first being by far the most involved.
18.3.1 1. File: newcomp.py
Its pretty straightforward to model a new Component on one of the existing ones. Be prepared to specify what your
Component needs to do at several different points in time: before the first trial, every frame, at the end of each routine,
and at the end of the experiment. In addition, you may need to sacrifice some complexity in order to keep things
streamlined enough for a Builder.
Your new Component class (in ‘newcomp.py’) will probably inherit from either BaseComponent (_base.py) or Visu-
alComponent (_visual.py). You may need to rewrite some or all some of these methods, to override default behavior.:
class NewcompComponent(BaseComponent): # or (VisualComponent)
def __init__(<lots of stuff>):
def writeInitCode(self, buff):
def writeRoutineStartCode(self, buff):
def writeFrameCode(self, buff):
def writeRoutineEndCode(self, buff):
You may need to edit settings.py, which writes out the set-up code for the whole experiment (e.g., to define the win-
dow). For example, this was necessary for ApertureComponent, to pass “allowStencil=True” to the window creation.
18.3. Adding a new Builder Component 213
PsychoPy - Psychology software for Python, Release 1.78.00
Your new Component writes code into a buffer that becomes an executable python file, xxx_lastrun.py (where xxx is
whatever the experimenter specifies when saving from the builder, xxx.psyexp). You will do a bunch of this kind of
call in your newcomp.py file:
buff.writeIndented(your_python_syntax_string_here)
You have to manage the indentation level of the output code, see experiment.IndentingBuffer().
xxx_lastrun.py is the file that gets built when you run xxx.psyexp from the builder. So you will want to look at
xxx_lastrun.py frequently when developing your component.
Name-space
There are several internal variables (er, names of python objects) that have a specific, hardcoded meaning within
xxx_lastrun.py. You can expect the following to be there, and they should only be used in the original way (or
something will break for the end-user, likely in a mysterious way):
’win’ = the window
’t’ = time within the trial loop, referenced to trialClock
’x’, ’y’ = mouse coordinates, but only if the experimenter uses a mouse component
Handling of variable names is under active development, so this list may well be out of date. (If so, you might consider
updating it or posting a note to psychopy-dev.)
Preliminary testing suggests that there are 600-ish names from numpy or numpy.random, plus the following:
[’KeyResponse’,’__builtins__’,’__doc__’,’__file__’,’__name__’,’__package__’,’buttons’,’core’,’data’,’dlg’,’event’,’expInfo’,’expName’,’filename’,’gui’,’logFile’,’os’,’psychopy’,’sound’,’t’,’visual’,’win’,’x’,’y’]
Yet other names get derived from user-entered names, like trials –> thisTrial.
Params
self.params is a key construct that you build up in __init__. You need name, startTime, duration, and several other
params to be defined or you get errors. ‘name’ should be of type ‘code’.
The Param() class is defined in psychopy.app.builder.experiment.Param(). A very useful thing that Param’s know is
how to create a string suitable for writing into the .py script. In particular, the __str__ representation of a Param will
format its value (.val) based on its type (.valType) appropriately. This means that you don’t need to check or handle
whether the user entered a plain string, a string with a code trigger character ($), or the field was of type code in the
first place. If you simply request the str() representation of the param, it is formatted correctly.
To indicate that a param should be considered as an advanced feature, add it to the list self.params[’advancedParams’].
The the GUI shown to the experimenter will initially hides it as an option. Nice, easy.
During development, I found it helpful at times to save the params into the xxx_lastrun.py file as comments, so I could
see what was happening:
def writeInitCode(self,buff):
# for debugging during Component development:
buff.writeIndented("# self.params for aperture:\n")
for pin self.params.keys():
try: buff.writeIndented("# %s:%s <type %s>\n"%(p, self.params[p].val, self.params[p].valType))
except:pass
A lot more detail can be infered from Jon’s code.
Making things loop-compatible looks interesting – see keyboard.py for an example, especially code for saving data at
the end.
214 Chapter 18. For Developers
PsychoPy - Psychology software for Python, Release 1.78.00
18.3.2 Notes & gotchas
syntax errors in new_comp.py: The PsychoPy app will fail to start if there are syntax error in any of
the components that are auto-detected. Just correct them and start the app again.
param[].val : If you have a boolean variable (e.g., my_flag) as one of your params, note that
self.param[”my_flag”] is always True (the param exists –> True). So in a boolean context you
almost always want the .val part, e.g., if self.param[”my_flag”].val:.
However, you do not always want .val. Specifically, in a string/unicode context (= to trigger the self-
formatting features of Param()’s), you almost always want “%s” % self.param[’my_flag’], without
.val. Note that it’s better to do this via “%s” than str() because str(self.param[”my_flag”]) coerces
things to type str (squashing unicode) whereas %s works for both str and unicode.
18.3.3 2. Icon: newcomp.png
Using your favorite image software, make an icon for your Component with a descriptive name, e.g., ‘newcomp.png’.
Dimensions = 48 x 48. Put it in the components directory.
In ‘newcomp.py’, have a line near the top:
iconFile =path.join(thisFolder, ’newcomp.png’)
18.3.4 3. Documentation: newcomp.rst
Just make a descriptively-named text file that ends in .rst (“restructured text”), and put
it in psychopy/docs/source/builder/components/ . It will get auto-formatted and end up at
http://www.psychopy.org/builder/components/newcomp.html
18.4 Style-guide for coder demos
OpenHatchers: Welcome! Each coder demo is intended to illustrate a key PsychoPy feature (or two), especially in
ways that show usage in practice, and go beyond the description in the API. The aim is not to illustrate every aspect,
but to get people up to speed quickly, so they understand how basic usage works, and could then play around with
advanced features.
As a newcomer to PsychoPy, you are in a great position to judge whether the comments and documentation are
clear enough or not. If something is not clear, you may need to ask a PsychoPy contributor for a description; email
psychopy-dev@googlegroups.com.
Here are some style guidelines, written for the OpenHatch event(s) but hopefully useful after that too. These are
intended specifically for the coder demos, not for the internal code-base (although they are generally quite close).
The idea is to have clean code that looks and works the same way across demos, while leaving the functioning mostly
untouched. Some small changes to function might be needed (e.g., to enable the use of ‘escape’ to quit), but typically
only minor changes like this.
• Generally, when you run the demo, does it look good and help you understand the feature? Where might there
be room for improvement? You can either leave notes in the code in a comment, or include them in a commit
message.
• Standardize the top stuff to have 1) a shbang, 2) utf-8 encoding, and 3) a comment:
18.4. Style-guide for coder demos 215
PsychoPy - Psychology software for Python, Release 1.78.00
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""Demo name, purpose, description (1-2 sentences, although some demos need more explanation).
"""
For the comment / description, its a good idea to read and be informed by the relevant parts of the API (see
http://psychopy.org/api/api.html), but there’s no need to duplicate that text in your comment. If you are unsure, please
post to the dev list psychopy-dev@googlegroups.com.
• Follow PEP-8 mostly, some exceptions:
–current PsychoPy convention is to use camelCase for variable names, so don’t convert those to underscores
–80 char columns can spill over a little. Try to keep things within 80 chars most of the time.
–do allow multiple imports on one line if they are thematically related (e.g., import os, sys, glob).
–inline comments are ok (because the code demos are intended to illustrate and explain usage in some detail,
more so than typical code).
• Check all imports:
–remove any unnecessary ones
–replace import time with from psychopy import core. and then use core.time() instead of time.time(), for
all time-related functions or methods not just time().
–add from __future__ import division, even if not needed. And make sure that doing so does not break the
demo!
• Fix any typos in comments; convert any lingering British spellings to US, e.g., change colour to color
• Prefer if <boolean>: as a construct instead of if <boolean> == True:. (There might not be any to change).
• If you have to choose, opt for more verbose but easier-to-understand code instead of clever or terse formulations.
This is for readability, especially for people new to python. If you are unsure, please add a note to your commit
message, or post a question to the dev list psychopy-dev@googlegroups.com.
• Standardize variable names:
–use win for the visual.Window(), and so win.flip()
• Provide a consistent way for a user to exit a demo using the keyboard, ideally enable this on every visual frame:
use if len(event.getKeys([’escape’]): core.quit().Note: if there is a previous event.getKeys() call, it can slurp up
the ‘escape’ keys. So check for ‘escape’ first.
• Time-out after 10 seconds, if there’s no user response and a timeout is appropriate for the demo (and a longer
time-out might be needed, e.g., for ratingScale.py):
demoClock =core.clock() # is demoClock’s time is 0.000s at this point
...
if demoClock.getTime() >10.:
core.quit()
• Most demos are not full screen. For any that are full-screen, see if it can work without being full screen. If it
has to be full-screen, add some text to say that pressing ‘escape’ will quit.
• If displaying log messages to the console seems to help understand the demo, here’s how to do it:
from psychopy import logging
...
logging.console.setLevel(logging.INFO) # or logging.DEBUG for even more stuff
216 Chapter 18. For Developers
PsychoPy - Psychology software for Python, Release 1.78.00
• End a script with win.close() (assuming the script used a visual.Window), and then core.quit() even though its
not strictly necessary
18.5 Adding a new Menu Item
Adding a new menu-item to the Builder (or Coder) is relatively straightforward, but there are several files that need to
be changed in specific ways.
18.5.1 1. makeMenus()
The code that constructs the menus for the Builder is within a method named makeMenus(), within class
builder.BuilderFrame(). Decide which submenu your new command fits under, and look for that section (e.g., File,
Edit, View, and so on). For example, to add an item for making the Routine panel items larger, I added two lines within
the View menu, by editing the makeMenus() method of class BuilderFrame within psychopy/app/builder/builder.py
(similar for Coder):
self.viewMenu.Append(self.IDs.tbIncrRoutineSize, "&Routine Larger\t%s"%self.app.keys[’largerRoutine’], "Larger routine items")
wx.EVT_MENU(self,self.IDs.tbIncrRoutineSize, self.routinePanel.increaseSize)
18.5.2 2. wxIDs.py
A new item needs to have a (numeric) ID so that wx can keep track of it. Here, the number is self.IDs.tbIncrRoutineSize,
which I had to define within the file psychopy/app/wxIDs.py:
tbIncrRoutineSize=180
Its possible that, instead of hard-coding it like this, its better to make a call to wx.NewId() – wx will take care of
avoiding duplicate IDs, presumably.
18.5.3 3. Key-binding prefs
I also defined a key to use to as a keybaord short-cut for activating the new menu item:
self.app.keys[’largerRoutine’]
The actual key is defined in a preference file. Because psychopy is multi-platform, you need to add info to four
different .spec files, all of them being within the psychopy/preferences/ directory, for four operating systems (Darin,
FreeBSD, Linux, Windows). For Darwin.spec (meaning Mac OS X), I added two lines. The first line is not merely
a comment: it is also automatically used as a tooltip (in the preferences dialog, under key-bindings), and the second
being the actual short-cut key to use:
# increase display size of Routines
largerRoutine =string(default=’Ctrl++’)# on mac book pro this is good
This means that the user has to hold down the Ctrl key and then press the +key. Note that on macs, ‘Ctrl’ in the spec
is automatically converted into ‘Cmd’ for the actual key to use; in the .spec, you should always specify things in terms
of ‘Ctrl’ (and not ‘Cmd’). The default value is the key-binding to use unless the user defines another one in her or his
preferences (which then overrides the default). Try to pick a sensible key for each operating system, and update all
four .spec files.
18.5. Adding a new Menu Item 217
PsychoPy - Psychology software for Python, Release 1.78.00
18.5.4 4. Your new method
The second line within makeMenus() adds the key-binding definition into wx’s internal space, so that when the key is
pressed, wx knows what to do. In the example, it will call the method self.routinePanel.increaseSize, which I had to
define to do the desired behavior when the method is called (in this case, increment an internal variable and redraw the
routine panel at the new larger size).
18.5.5 5. Documentation
To let people know that your new feature exists, add a note about your new feature in the CHANGELOG.txt, and
appropriate documentation in .rst files.
Happy Coding Folks!!
218 Chapter 18. For Developers
CHAPTER
NINETEEN
PSYCHOPY EXPERIMENT FILE
FORMAT (.PSYEXP)
The file format used to save experiments constructed in PsychoPy builder was created especially for the purpose, but
is an open format, using a basic xml form, that may be of use to other similar software. Indeed the builder itself could
be used to generate experiments on different backends (such as Vision Egg, PsychToolbox or PyEPL). The xml format
of the file makes it extremely platform independent, as well as moderately(?!) easy to read by a humans. There was
a further suggestion to generate an XSD (or similar) schema against which psyexp files could be validated. That is a
low priority but welcome addition if you wanted to work on it(!)
The simplest way to understand the file format is probably simply to create an experiment, save it and open the file
in an xml-aware editor/viewer (e.g. change the file extension from .psyexp to .xml and then open it in firefox). An
example (from the stroop demo) is shown below.
The file format maps fairly obviously onto the structure of experiments constructed with the Builder interface, as
described here. There are general Settings for the experiment, then there is a list of Routines and a Flow that describes
how these are combined.
As with any xml file the format contains object nodes which can have direct properties and also child nodes. For
instance the outermost node of the .psyexp file is the experiment node, with properties that specifiy the version of
PsychoPy that was used to save the file most recently and the encoding of text within the file (ascii, unicode etc.), and
with child nodes Settings,Routines and Flow.
19.1 Parameters
Many of the nodes described within this xml description of the experiment contain Param entries, representing different
parameters of that Component. All parameter nodes have a name property and a val property. Most also have a valType
property, which can take values ‘bool’, ‘code’, ‘str’ and an updates property that specifies whether this parameter is
changing during the experiment and, if so, whether it changes ‘every frame’ (of the monitor) or ‘every repeat’ (of the
Routine).
19.2 Settings
The Settings node contains a number of parameters that, in PsychoPy, would normally be set in the Experiment settings
dialog, such as the monitor to be used. This node contains a number of Parameters that map onto the entries in that
dialog.
219
PsychoPy - Psychology software for Python, Release 1.78.00
19.3 Routines
This node provides a sequence of xml child nodes, each of which describes a Routine. Each Routine contains a number
of children, each specifying a Component, such as a stimulus or response collecting device. In the Builder view, the
Routines obviously show up as different tabs in the main window and the Components show up as tracks within that
tab.
19.4 Components
Each Component is represented in the .psyexp file as a set of parameters, corresponding to the entries in the appropriate
component dialog box, that completely describe how and when the stimulus should be presented or how and when the
input device should be read from. Different Components have slightly different nodes in the xml representation which
give rise to different sets of parameters. For instance the TextComponent nodes has parameters such as colour and
font, whereas the KeyboardComponent node has parameters such as forceEndTrial and correctIf.
19.5 Flow
The Flow node is rather more simple. It’s children simply specify objects that occur in a particular order in time. A
Routine described in this flow must exist in the list of Routines, since this is where it is fully described. One Routine
can occur once, more than once or not at all in the Flow. The other children that can occur in a Flow are LoopInitiators
and LoopTerminators which specify the start and endpoints of a loop. All loops must have exactly one initiator and
one terminator.
19.6 Names
For the experiment to generate valid PsychoPy code the name parameters of all objects (Components, Loops and
Routines) must be unique and contain no spaces. That is, an experiment can not have two different Routines called
‘trial’, nor even a Routine called ‘trial’ and a Loop called ‘trial’.
The Parameter names belonging to each Component (or the Settings node) must be unique within that Component, but
can be identical to parameters of other Components or can match the Component name themselves. A TextComponent
should not, for example, have multiple ‘pos’ parameters, but other Components generally will, and a Routine called
‘pos’ would also be also permissible.
<PsychoPy2experiment version="1.50.04" encoding="utf-8">
<Settings>
<Param name="Monitor" val="testMonitor" valType="str" updates="None"/>
<Param name="Window size (pixels)" val="[1024, 768]" valType="code" updates="None"/>
<Param name="Full-screen window" val="True" valType="bool" updates="None"/>
<Param name="Save log file" val="True" valType="bool" updates="None"/>
<Param name="Experiment info" val="{’participant’:’s_001’, ’session’:001}" valType="code" updates="None"/>
<Param name="Show info dlg" val="True" valType="bool" updates="None"/>
<Param name="logging level" val="warning" valType="code" updates="None"/>
<Param name="Units" val="norm" valType="str" updates="None"/>
<Param name="Screen" val="1" valType="num" updates="None"/>
</Settings>
<Routines>
<Routine name="trial">
<TextComponent name="word">
<Param name="name" val="word" valType="code" updates="constant"/>
220 Chapter 19. PsychoPy Experiment file format (.psyexp)
PsychoPy - Psychology software for Python, Release 1.78.00
<Param name="text" val="thisTrial.text" valType="code" updates="set every repeat"/>
<Param name="colour" val="thisTrial.rgb" valType="code" updates="set every repeat"/>
<Param name="ori" val="0" valType="code" updates="constant"/>
<Param name="pos" val="[0, 0]" valType="code" updates="constant"/>
<Param name="times" val="[0.5,2.0]" valType="code" updates="constant"/>
<Param name="letterHeight" val="0.2" valType="code" updates="constant"/>
<Param name="colourSpace" val="rgb" valType="code" updates="constant"/>
<Param name="units" val="window units" valType="str" updates="None"/>
<Param name="font" val="Arial" valType="str" updates="constant"/>
</TextComponent>
<KeyboardComponent name="resp">
<Param name="storeCorrect" val="True" valType="bool" updates="constant"/>
<Param name="name" val="resp" valType="code" updates="None"/>
<Param name="forceEndTrial" val="True" valType="bool" updates="constant"/>
<Param name="times" val="[0.5,2.0]" valType="code" updates="constant"/>
<Param name="allowedKeys" val="[’1’,’2’,’3’]" valType="code" updates="constant"/>
<Param name="storeResponseTime" val="True" valType="bool" updates="constant"/>
<Param name="correctIf" val="resp.keys==str(thisTrial.corrAns)" valType="code" updates="constant"/>
<Param name="store" val="last key" valType="str" updates="constant"/>
</KeyboardComponent>
</Routine>
<Routine name="instruct">
<TextComponent name="instrText">
<Param name="name" val="instrText" valType="code" updates="constant"/>
<Param name="text" val="&quot;Please press;&#10;1 for red ink,&#10;2 for green ink&#10;3 for blue ink&#10;(Esc will quit)&#10;&#10;Any key to continue&quot;" valType="code" updates="constant"/>
<Param name="colour" val="[1, 1, 1]" valType="code" updates="constant"/>
<Param name="ori" val="0" valType="code" updates="constant"/>
<Param name="pos" val="[0, 0]" valType="code" updates="constant"/>
<Param name="times" val="[0, 10000]" valType="code" updates="constant"/>
<Param name="letterHeight" val="0.1" valType="code" updates="constant"/>
<Param name="colourSpace" val="rgb" valType="code" updates="constant"/>
<Param name="units" val="window units" valType="str" updates="None"/>
<Param name="font" val="Arial" valType="str" updates="constant"/>
</TextComponent>
<KeyboardComponent name="ready">
<Param name="storeCorrect" val="False" valType="bool" updates="constant"/>
<Param name="name" val="ready" valType="code" updates="None"/>
<Param name="forceEndTrial" val="True" valType="bool" updates="constant"/>
<Param name="times" val="[0, 10000]" valType="code" updates="constant"/>
<Param name="allowedKeys" val="" valType="code" updates="constant"/>
<Param name="storeResponseTime" val="False" valType="bool" updates="constant"/>
<Param name="correctIf" val="resp.keys==str(thisTrial.corrAns)" valType="code" updates="constant"/>
<Param name="store" val="last key" valType="str" updates="constant"/>
</KeyboardComponent>
</Routine>
<Routine name="thanks">
<TextComponent name="thanksText">
<Param name="name" val="thanksText" valType="code" updates="constant"/>
<Param name="text" val="&quot;Thanks!&quot;" valType="code" updates="constant"/>
<Param name="colour" val="[1, 1, 1]" valType="code" updates="constant"/>
<Param name="ori" val="0" valType="code" updates="constant"/>
<Param name="pos" val="[0, 0]" valType="code" updates="constant"/>
<Param name="times" val="[1.0, 2.0]" valType="code" updates="constant"/>
<Param name="letterHeight" val="0.2" valType="code" updates="constant"/>
<Param name="colourSpace" val="rgb" valType="code" updates="constant"/>
<Param name="units" val="window units" valType="str" updates="None"/>
<Param name="font" val="arial" valType="str" updates="constant"/>
</TextComponent>
19.6. Names 221
PsychoPy - Psychology software for Python, Release 1.78.00
</Routine>
</Routines>
<Flow>
<Routine name="instruct"/>
<LoopInitiator loopType="TrialHandler" name="trials">
<Param name="endPoints" val="[0, 1]" valType="num" updates="None"/>
<Param name="name" val="trials" valType="code" updates="None"/>
<Param name="loopType" val="random" valType="str" updates="None"/>
<Param name="nReps" val="5" valType="num" updates="None"/>
<Param name="trialList" val="[{’text’: ’red’, ’rgb’: [1, -1, -1], ’congruent’: 1, ’corrAns’: 1}, {’text’: ’red’, ’rgb’: [-1, 1, -1], ’congruent’: 0, ’corrAns’: 1}, {’text’: ’green’, ’rgb’: [-1, 1, -1], ’congruent’: 1, ’corrAns’: 2}, {’text’: ’green’, ’rgb’: [-1, -1, 1], ’congruent’: 0, ’corrAns’: 2}, {’text’: ’blue’, ’rgb’: [-1, -1, 1], ’congruent’: 1, ’corrAns’: 3}, {’text’: ’blue’, ’rgb’: [1, -1, -1], ’congruent’: 0, ’corrAns’: 3}]" valType="str" updates="None"/>
<Param name="trialListFile" val="/Users/jwp...troop/trialTypes.csv" valType="str" updates="None"/>
</LoopInitiator>
<Routine name="trial"/>
<LoopTerminator name="trials"/>
<Routine name="thanks"/>
</Flow>
</PsychoPy2experiment>
222 Chapter 19. PsychoPy Experiment file format (.psyexp)
CHAPTER
TWENTY
GLOSSARY
Adaptive staircase An experimental method whereby the choice of stimulus parameters is not pre-determined but
based on previous responses. For example, the difficulty of a task might be varied trial-to-trial based on the
participant’s responses. These are often used to find psychophysical thresholds. Contrast this with the method
of constants.
CRT Cathode Ray Tube ‘Traditional’ computer monitor (rather than an LCD or plasma flat screen).
csv Comma-Separated Value files Type of basic text file with ‘comma-separated values’. This type of file can be
opened with most spreadsheet packages (e.g. MS Excel) for easy reading and manipulation.
Method of constants An experimental method whereby the parameters controlling trials are predetermined at the
beginning of the experiment, rather than determined on each trial. For example, a stimulus may be presented for
3 pre-determined time periods (100, 200, 300ms) on different trials, and then repeated a number of times. The
order of presentation of the different conditions can be randomised or sequential (in a fixed order). Contrast this
method with the adaptive staircase.
VBI (Vertical Blank Interval, aka the Vertical Retrace, or Vertical Blank, VBL). The period in-between video
frames and can be used for synchronising purposes. On a CRT display the screen is black during the VBI and
the display beam is returned to the top of the display.
VBI blocking The setting whereby all functions are synced to the VBI. After a call to
psychopy.visual.Window.flip() nothing else occurs until the VBI has occurred. This is opti-
mal and allows very precise timing, because as soon as the flip has occured a very precise time interval is known
to have occured.
VBI syncing (aka vsync) The setting whereby the video drawing commands are synced to the VBI. When psy-
chopy.visual.Window.flip() is called, the current back buffer (where drawing commands are being executed)
will be held and drawn on the next VBI. This does not necessarily entail VBI blocking (because the system may
return and continue executing commands) but does guarantee a fixed interval between frames being drawn.
xlsx Excel OpenXML file format. A spreadsheet data format developed by Microsoft but with an open (published
format). This is the native file format for Excel (2007 or later) and can be opened by most modern spreadsheet
applications including OpenOffice (3.0+), google docs, Apple iWork 08.
223
PsychoPy - Psychology software for Python, Release 1.78.00
224 Chapter 20. Glossary
CHAPTER
TWENTYONE
INDICES
•genindex
•modindex
•search
A pdf copy of the current documentation is available at:
http://www.psychopy.org/PsychoPyManual.pdf
225
PsychoPy - Psychology software for Python, Release 1.78.00
226 Chapter 21. Indices
PYTHON MODULE INDEX
p
psychopy.core,93
psychopy.data,146
psychopy.filters,169
psychopy.hardware.crs,175
psychopy.hardware.egi,176
psychopy.hardware.emulator,176
psychopy.hardware.forp,178
psychopy.hardware.ioLabs,179
psychopy.hardware.joystick,179
psychopy.hardware.minolta,181
psychopy.hardware.pr,182
psychopy.info,186
psychopy.logging,187
psychopy.misc,194
psychopy.parallel,202
psychopy.sound,204
psychopy.visual,95
pylink,185
pyxid,174
227
PsychoPy - Psychology software for Python, Release 1.78.00
228 Python Module Index
INDEX
A
abort() (psychopy.data.ExperimentHandler method), 146
Adaptive staircase, 223
add() (psychopy.core.Clock method), 94
addData() (psychopy.data.ExperimentHandler method),
146
addData() (psychopy.data.MultiStairHandler method),
154
addData() (psychopy.data.QuestHandler method), 157
addData() (psychopy.data.StairHandler method), 151
addData() (psychopy.data.TrialHandler method), 148
addField() (psychopy.gui.Dlg method), 172
addFixedField() (psychopy.gui.Dlg method), 172
addLevel() (in module psychopy.logging), 188
addLoop() (psychopy.data.ExperimentHandler method),
147
addText() (psychopy.gui.Dlg method), 172
AdvAudioCapture (class in psychopy.microphone), 190
Aperture (class in psychopy.visual), 99
array2image() (in module psychopy.misc), 194
B
BatchSpeech2Text (class in psychopy.microphone), 193
BitsBox (class in psychopy.hardware.crs), 175
bootStraps() (in module psychopy.data), 162
BufferImageStim (class in psychopy.visual), 100
butter2d_bp() (in module psychopy.filters), 169
butter2d_hp() (in module psychopy.filters), 169
butter2d_lp() (in module psychopy.filters), 169
butter2d_lp_elliptic() (in module psychopy.filters), 170
ButtonBox (class in psychopy.hardware.forp), 178
C
calculateNextIntensity() (psychopy.data.QuestHandler
method), 157
calculateNextIntensity() (psychopy.data.StairHandler
method), 151
callOnFlip() (psychopy.visual.Window method), 96
cart2pol() (in module psychopy.misc), 194
cart2sph() (in module psychopy.misc), 194
checkOK() (psychopy.hardware.minolta.LS100 method),
181
Circle (class in psychopy.visual), 101
clear_response_queue() (pyxid.ResponseDevice method),
174
clearBuffer() (psychopy.hardware.forp.ButtonBox
method), 178
clearBuffer() (psychopy.visual.Window method), 96
clearEvents() (in module psychopy.event), 168
clearMemory() (psychopy.hardware.minolta.LS100
method), 181
clearStatus() (psychopy.hardware.forp.ButtonBox
method), 178
clearTextures() (psychopy.visual.ElementArrayStim
method), 109
clearTextures() (psychopy.visual.GratingStim method),
113
clearTextures() (psychopy.visual.ImageStim method),
117
clearTextures() (psychopy.visual.PatchStim method), 123
clearTextures() (psychopy.visual.RadialStim method),
129
clickReset() (psychopy.event.Mouse method), 167
Clock (class in psychopy.core), 93
close() (psychopy.visual.Window method), 96
cm2deg() (in module psychopy.misc), 194
cm2pix() (in module psychopy.misc), 194
complete() (psychopy.core.StaticPeriod method), 95
compress() (psychopy.microphone.AdvAudioCapture
method), 190
confInterval() (psychopy.data.QuestHandler method),
157
contains() (psychopy.visual.Circle method), 102
contains() (psychopy.visual.DotStim method), 106
contains() (psychopy.visual.GratingStim method), 113
contains() (psychopy.visual.ImageStim method), 117
contains() (psychopy.visual.Line method), 119
contains() (psychopy.visual.PatchStim method), 123
contains() (psychopy.visual.Polygon method), 125
contains() (psychopy.visual.RadialStim method), 129
contains() (psychopy.visual.Rect method), 136
contains() (psychopy.visual.ShapeStim method), 139
229
PsychoPy - Psychology software for Python, Release 1.78.00
contains() (psychopy.visual.TextStim method), 143
conv2d() (in module psychopy.filters), 170
copyCalib() (psychopy.monitors.Monitor method), 197
CountdownTimer (class in psychopy.core), 94
createXYs() (in module psychopy.misc), 194
critical() (in module psychopy.logging), 188
CRT, 223
csv, 223
CustomMouse (class in psychopy.visual), 104
D
data() (in module psychopy.logging), 188
debug() (in module psychopy.logging), 188
decrypt() (in module psychopy.contrib.opensslwrap), 166
deg2cm() (in module psychopy.misc), 194
deg2pix() (in module psychopy.misc), 194
delCalib() (psychopy.monitors.Monitor method), 198
disable() (psychopy.visual.Aperture method), 99
dkl2rgb() (in module psychopy.misc), 194
dklCart2rgb() (in module psychopy.misc), 195
Dlg (class in psychopy.gui), 172
DlgFromDict (class in psychopy.gui), 172
DotStim (class in psychopy.visual), 105
draw() (psychopy.visual.BufferImageStim method), 101
draw() (psychopy.visual.Circle method), 102
draw() (psychopy.visual.CustomMouse method), 104
draw() (psychopy.visual.DotStim method), 106
draw() (psychopy.visual.ElementArrayStim method), 110
draw() (psychopy.visual.GratingStim method), 113
draw() (psychopy.visual.ImageStim method), 117
draw() (psychopy.visual.Line method), 119
draw() (psychopy.visual.MovieStim method), 122
draw() (psychopy.visual.PatchStim method), 123
draw() (psychopy.visual.Polygon method), 126
draw() (psychopy.visual.RadialStim method), 129
draw() (psychopy.visual.RatingScale method), 135
draw() (psychopy.visual.Rect method), 136
draw() (psychopy.visual.ShapeStim method), 140
draw() (psychopy.visual.SimpleImageStim method), 142
draw() (psychopy.visual.TextStim method), 143
E
ElementArrayStim (class in psychopy.visual), 109
enable() (psychopy.visual.Aperture method), 99
encrypt() (in module psychopy.contrib.opensslwrap), 166
endRemoteMode() (psychopy.hardware.pr.PR655
method), 184
error() (in module psychopy.logging), 188
eval() (psychopy.data.FitCumNormal method), 161
eval() (psychopy.data.FitLogistic method), 160
eval() (psychopy.data.FitNakaRushton method), 160
eval() (psychopy.data.FitWeibull method), 160
exp() (in module psychopy.logging), 188
ExperimentHandler (class in psychopy.data), 146
extendArr() (in module psychopy.misc), 195
F
fadeOut() (psychopy.sound.SoundPygame method), 204
fatal() (in module psychopy.logging), 188
fileOpenDlg (class in psychopy.gui), 173
fileSaveDlg (class in psychopy.gui), 173
findPhotometer() (in module psychopy.hardware), 185
findPR650() (in module psychopy.monitors), 200
FitCumNormal (class in psychopy.data), 160
fitGammaErrFun() (psy-
chopy.monitors.GammaCalculator method),
200
fitGammaFun() (psychopy.monitors.GammaCalculator
method), 200
FitLogistic (class in psychopy.data), 160
FitNakaRushton (class in psychopy.data), 160
FitWeibull (class in psychopy.data), 159
flac2wav() (in module psychopy.microphone), 193
flip() (psychopy.visual.Window method), 96
float_uint16() (in module psychopy.misc), 195
float_uint8() (in module psychopy.misc), 195
flush() (in module psychopy.logging), 188,189
fps() (psychopy.visual.Window method), 96
fromFile() (in module psychopy.misc), 195
functionFromStaircase() (in module psychopy.data), 161
G
GammaCalculator (class in psychopy.monitors), 200
gammaFun() (in module psychopy.monitors), 201
gammaInvFun() (in module psychopy.monitors), 201
gammaIsDefault() (psychopy.monitors.Monitor method),
198
get_next_response() (pyxid.ResponseDevice method),
174
get_xid_device() (in module pyxid), 174
get_xid_devices() (in module pyxid), 174
getAbsTime() (in module psychopy.core), 93
getAllAxes() (psychopy.hardware.joystick.Joystick
method), 179
getAllButtons() (psychopy.hardware.joystick.Joystick
method), 179
getAllHats() (psychopy.hardware.joystick.Joystick
method), 180
getAllMonitors() (in module psychopy.monitors), 200
getAxis() (psychopy.hardware.joystick.Joystick method),
180
getButton() (psychopy.hardware.joystick.Joystick
method), 180
getCalibDate() (psychopy.monitors.Monitor method),
198
getClicks() (psychopy.visual.CustomMouse method), 104
getDeviceSN() (psychopy.hardware.pr.PR655 method),
184
230 Index
PsychoPy - Psychology software for Python, Release 1.78.00
getDeviceType() (psychopy.hardware.pr.PR655 method),
184
getDft() (in module psychopy.microphone), 193
getDistance() (psychopy.monitors.Monitor method), 198
getDKL_RGB() (psychopy.monitors.Monitor method),
198
getDuration() (psychopy.sound.SoundPygame method),
205
getEarlierTrial() (psychopy.data.TrialHandler method),
148
getEvents() (psychopy.hardware.forp.ButtonBox
method), 178
getExp() (psychopy.data.MultiStairHandler method), 154
getExp() (psychopy.data.QuestHandler method), 157
getExp() (psychopy.data.StairHandler method), 151
getExp() (psychopy.data.TrialHandler method), 148
getFutureTrial() (psychopy.data.TrialHandler method),
148
getGamma() (psychopy.monitors.Monitor method), 198
getGammaGrid() (psychopy.monitors.Monitor method),
198
getHat() (psychopy.hardware.joystick.Joystick method),
180
getHistory() (psychopy.visual.RatingScale method), 135
getKeys() (in module psychopy.event), 169
getLastColorTemp() (psychopy.hardware.pr.PR655
method), 184
getLastLum() (psychopy.hardware.pr.PR650 method),
183
getLastResetTime() (psychopy.core.MonotonicClock
method), 94
getLastSpectrum() (psychopy.hardware.pr.PR650
method), 183
getLastSpectrum() (psychopy.hardware.pr.PR655
method), 184
getLastTristim() (psychopy.hardware.pr.PR655 method),
184
getLastUV() (psychopy.hardware.pr.PR655 method), 184
getLastXY() (psychopy.hardware.pr.PR655 method), 184
getLevel() (in module psychopy.logging), 188
getLevelsPost() (psychopy.monitors.Monitor method),
198
getLevelsPre() (psychopy.monitors.Monitor method), 198
getLineariseMethod() (psychopy.monitors.Monitor
method), 198
getLMS_RGB() (psychopy.monitors.Monitor method),
198
getLoudness() (psychopy.microphone.AdvAudioCapture
method), 190
getLum() (psychopy.hardware.minolta.LS100 method),
182
getLum() (psychopy.hardware.pr.PR650 method), 183
getLumSeriesPR650() (in module psychopy.monitors),
201
getLumsPost() (psychopy.monitors.Monitor method), 198
getLumsPre() (psychopy.monitors.Monitor method), 198
getMarkerInfo() (psychopy.microphone.AdvAudioCapture
method), 190
getMarkerOnset() (psy-
chopy.microphone.AdvAudioCapture method),
190
getMeanLum() (psychopy.monitors.Monitor method),
198
getMovieFrame() (psychopy.visual.Window method), 97
getName() (psychopy.hardware.joystick.Joystick
method), 180
getNotes() (psychopy.monitors.Monitor method), 198
getNumAxes() (psychopy.hardware.joystick.Joystick
method), 180
getNumButtons() (psychopy.hardware.joystick.Joystick
method), 180
getNumHats() (psychopy.hardware.joystick.Joystick
method), 180
getNumJoysticks() (in module psy-
chopy.hardware.joystick), 179
getOriginPathAndFile() (psy-
chopy.data.MultiStairHandler method), 154
getOriginPathAndFile() (psychopy.data.QuestHandler
method), 157
getOriginPathAndFile() (psychopy.data.StairHandler
method), 152
getOriginPathAndFile() (psychopy.data.TrialHandler
method), 148
getPos() (psychopy.event.Mouse method), 167
getPos() (psychopy.visual.CustomMouse method), 104
getPressed() (psychopy.event.Mouse method), 167
getPsychopyVersion() (psychopy.monitors.Monitor
method), 198
getRAM() (in module psychopy.info), 187
getRating() (psychopy.visual.RatingScale method), 135
getRel() (psychopy.event.Mouse method), 167
getResponse() (psychopy.microphone.Speech2Text
method), 192
getRGBspectra() (in module psychopy.monitors), 201
getRMS() (in module psychopy.microphone), 193
getRMScontrast() (in module psychopy.filters), 170
getRT() (psychopy.visual.RatingScale method), 135
getSizePix() (psychopy.monitors.Monitor method), 198
getSpectra() (psychopy.monitors.Monitor method), 198
getSpectrum() (psychopy.hardware.pr.PR650 method),
183
getThread() (psychopy.microphone.Speech2Text
method), 193
getTime() (in module psychopy.core), 93
getTime() (psychopy.core.CountdownTimer method), 94
getTime() (psychopy.core.MonotonicClock method), 94
getUniqueEvents() (psychopy.hardware.forp.ButtonBox
method), 178
Index 231
PsychoPy - Psychology software for Python, Release 1.78.00
getUseBits() (psychopy.monitors.Monitor method), 198
getVisible() (psychopy.event.Mouse method), 168
getVisible() (psychopy.visual.CustomMouse method),
104
getVolume() (psychopy.sound.SoundPygame method),
205
getWheelRel() (psychopy.event.Mouse method), 168
getWidth() (psychopy.monitors.Monitor method), 198
getX() (psychopy.hardware.joystick.Joystick method),
180
getY() (psychopy.hardware.joystick.Joystick method),
180
getZ() (psychopy.hardware.joystick.Joystick method),
180
GratingStim (class in psychopy.visual), 112
H
haveInternetAccess() (in module psychopy.web), 205
hsv2rgb() (in module psychopy.misc), 195
I
image2array() (in module psychopy.misc), 195
ImageStim (class in psychopy.visual), 116
imfft() (in module psychopy.filters), 170
imifft() (in module psychopy.filters), 170
importConditions() (in module psychopy.data), 161
importData() (psychopy.data.QuestHandler method), 158
incTrials() (psychopy.data.QuestHandler method), 158
info() (in module psychopy.logging), 188
init_device() (pyxid.XidDevice method), 175
inverse() (psychopy.data.FitCumNormal method), 161
inverse() (psychopy.data.FitLogistic method), 160
inverse() (psychopy.data.FitNakaRushton method), 160
inverse() (psychopy.data.FitWeibull method), 160
isPressedIn() (psychopy.event.Mouse method), 168
J
Joystick (class in psychopy.hardware.joystick), 179
L
launchScan() (in module psychopy.hardware.emulator),
176
Line (class in psychopy.visual), 119
lineariseLums() (psychopy.monitors.Monitor method),
198
lms2rgb() (in module psychopy.misc), 195
loadMovie() (psychopy.visual.MovieStim method), 122
log() (in module psychopy.logging), 188
LogFile (class in psychopy.logging), 187
logOnFlip() (psychopy.visual.Window method), 97
loopEnded() (psychopy.data.ExperimentHandler
method), 147
LS100 (class in psychopy.hardware.minolta), 181
M
makeDKL2RGB() (in module psychopy.monitors), 202
makeGauss() (in module psychopy.filters), 170
makeGrating() (in module psychopy.filters), 170
makeImageAuto() (in module psychopy.misc), 195
makeLMS2RGB() (in module psychopy.monitors), 202
makeMask() (in module psychopy.filters), 171
makeRadialMatrix() (in module psychopy.filters), 171
maskMatrix() (in module psychopy.filters), 171
mean() (psychopy.data.QuestHandler method), 158
measure() (psychopy.hardware.minolta.LS100 method),
182
measure() (psychopy.hardware.pr.PR650 method), 183
measure() (psychopy.hardware.pr.PR655 method), 184
mergeFolder() (in module psychopy.misc), 196
Method of constants, 223
mode() (psychopy.data.QuestHandler method), 158
Monitor (class in psychopy.monitors), 197
MonotonicClock (class in psychopy.core), 94
Mouse (class in psychopy.event), 167
mouseMoved() (psychopy.event.Mouse method), 168
mouseMoveTime() (psychopy.event.Mouse method), 168
MovieStim (class in psychopy.visual), 121
MultiStairHandler (class in psychopy.data), 153
N
newCalib() (psychopy.monitors.Monitor method), 199
next() (psychopy.data.MultiStairHandler method), 154
next() (psychopy.data.QuestHandler method), 158
next() (psychopy.data.StairHandler method), 152
next() (psychopy.data.TrialHandler method), 148
nextEntry() (psychopy.data.ExperimentHandler method),
147
nextTrial() (psychopy.data.MultiStairHandler method),
154
nextTrial() (psychopy.data.QuestHandler method), 158
nextTrial() (psychopy.data.StairHandler method), 152
nextTrial() (psychopy.data.TrialHandler method), 149
O
overlaps() (psychopy.visual.Circle method), 102
overlaps() (psychopy.visual.DotStim method), 106
overlaps() (psychopy.visual.GratingStim method), 114
overlaps() (psychopy.visual.ImageStim method), 117
overlaps() (psychopy.visual.Line method), 119
overlaps() (psychopy.visual.PatchStim method), 123
overlaps() (psychopy.visual.Polygon method), 126
overlaps() (psychopy.visual.RadialStim method), 129
overlaps() (psychopy.visual.Rect method), 136
overlaps() (psychopy.visual.ShapeStim method), 140
overlaps() (psychopy.visual.TextStim method), 143
232 Index
PsychoPy - Psychology software for Python, Release 1.78.00
P
parseSpectrumOutput() (psychopy.hardware.pr.PR650
method), 183
parseSpectrumOutput() (psychopy.hardware.pr.PR655
method), 185
PatchStim (class in psychopy.visual), 123
pause() (psychopy.visual.MovieStim method), 122
pix2cm() (in module psychopy.misc), 196
pix2deg() (in module psychopy.misc), 196
play() (psychopy.sound.SoundPygame method), 205
play() (psychopy.visual.MovieStim method), 122
playback() (psychopy.microphone.AdvAudioCapture
method), 190
playMarker() (psychopy.microphone.AdvAudioCapture
method), 190
plotFrameIntervals() (in module psychopy.misc), 196
pol2cart() (in module psychopy.misc), 196
poll_for_response() (pyxid.ResponseDevice method),
174
Polygon (class in psychopy.visual), 125
PParallelDLPortIO (class in psychopy.parallel), 203
PParallelInpOut32 (class in psychopy.parallel), 203
PParallelLinux (class in psychopy.parallel), 203
PR650 (class in psychopy.hardware.pr), 182
PR655 (class in psychopy.hardware.pr), 183
printAsText() (psychopy.data.MultiStairHandler method),
154
printAsText() (psychopy.data.QuestHandler method), 158
printAsText() (psychopy.data.StairHandler method), 152
printAsText() (psychopy.data.TrialHandler method), 149
psychopy.core (module), 93
psychopy.data (module), 146
psychopy.filters (module), 169
psychopy.hardware.crs (module), 175
psychopy.hardware.egi (module), 176
psychopy.hardware.emulator (module), 176
psychopy.hardware.forp (module), 178
psychopy.hardware.ioLabs (module), 179
psychopy.hardware.joystick (module), 179
psychopy.hardware.minolta (module), 181
psychopy.hardware.pr (module), 182
psychopy.info (module), 186
psychopy.logging (module), 187
psychopy.misc (module), 194
psychopy.parallel (module), 202
psychopy.sound (module), 204
psychopy.visual (module), 95
pylink (module), 185
pyxid (module), 174
Q
quantile() (psychopy.data.QuestHandler method), 158
QuestHandler (class in psychopy.data), 156
R
RadialStim (class in psychopy.visual), 128
radians() (in module psychopy.misc), 196
RatingScale (class in psychopy.visual), 132
ratioRange() (in module psychopy.misc), 196
readPin() (in module psychopy.parallel), 202
record() (psychopy.microphone.AdvAudioCapture
method), 190
Rect (class in psychopy.visual), 136
requireInternetAccess() (in module psychopy.web), 205
resample() (psychopy.microphone.AdvAudioCapture
method), 190
reset() (psychopy.core.Clock method), 94
reset() (psychopy.microphone.AdvAudioCapture
method), 191
reset() (psychopy.visual.RatingScale method), 135
resetClicks() (psychopy.visual.CustomMouse method),
104
response_queue_size() (pyxid.ResponseDevice method),
175
ResponseDevice (class in pyxid), 174
ResponseEmulator (class in psy-
chopy.hardware.emulator), 177
rgb2dklCart() (in module psychopy.misc), 196
rgb2lms() (in module psychopy.misc), 196
rotate() (in module psychopy.contrib.opensslwrap), 167
RunTimeInfo (class in psychopy.info), 186
S
saveAsExcel() (psychopy.data.MultiStairHandler
method), 155
saveAsExcel() (psychopy.data.QuestHandler method),
158
saveAsExcel() (psychopy.data.StairHandler method), 152
saveAsExcel() (psychopy.data.TrialHandler method), 149
saveAsPickle() (psychopy.data.ExperimentHandler
method), 147
saveAsPickle() (psychopy.data.MultiStairHandler
method), 155
saveAsPickle() (psychopy.data.QuestHandler method),
159
saveAsPickle() (psychopy.data.StairHandler method),
153
saveAsPickle() (psychopy.data.TrialHandler method),
149
saveAsText() (psychopy.data.MultiStairHandler method),
155
saveAsText() (psychopy.data.QuestHandler method), 159
saveAsText() (psychopy.data.StairHandler method), 153
saveAsText() (psychopy.data.TrialHandler method), 150
saveAsWideText() (psychopy.data.ExperimentHandler
method), 147
saveAsWideText() (psychopy.data.TrialHandler method),
150
Index 233
PsychoPy - Psychology software for Python, Release 1.78.00
saveFrameIntervals() (psychopy.visual.Window method),
97
saveMon() (psychopy.monitors.Monitor method), 199
saveMovieFrames() (psychopy.visual.Window method),
97
sd() (psychopy.data.QuestHandler method), 159
seek() (psychopy.visual.MovieStim method), 122
sendMessage() (psychopy.hardware.minolta.LS100
method), 182
sendMessage() (psychopy.hardware.pr.PR650 method),
183
sendMessage() (psychopy.hardware.pr.PR655 method),
185
setAngularCycles() (psychopy.visual.RadialStim
method), 129
setAngularPhase() (psychopy.visual.RadialStim method),
129
setAutoDraw() (psychopy.visual.Circle method), 102
setAutoDraw() (psychopy.visual.DotStim method), 107
setAutoDraw() (psychopy.visual.GratingStim method),
114
setAutoDraw() (psychopy.visual.ImageStim method),
117
setAutoDraw() (psychopy.visual.Line method), 119
setAutoDraw() (psychopy.visual.MovieStim method),
122
setAutoDraw() (psychopy.visual.PatchStim method), 123
setAutoDraw() (psychopy.visual.Polygon method), 126
setAutoDraw() (psychopy.visual.RadialStim method),
129
setAutoDraw() (psychopy.visual.Rect method), 137
setAutoDraw() (psychopy.visual.ShapeStim method), 140
setAutoDraw() (psychopy.visual.TextStim method), 143
setAutoLog() (psychopy.visual.Circle method), 102
setAutoLog() (psychopy.visual.DotStim method), 107
setAutoLog() (psychopy.visual.GratingStim method), 114
setAutoLog() (psychopy.visual.ImageStim method), 117
setAutoLog() (psychopy.visual.Line method), 119
setAutoLog() (psychopy.visual.PatchStim method), 123
setAutoLog() (psychopy.visual.Polygon method), 126
setAutoLog() (psychopy.visual.RadialStim method), 129
setAutoLog() (psychopy.visual.Rect method), 137
setAutoLog() (psychopy.visual.ShapeStim method), 140
setAutoLog() (psychopy.visual.TextStim method), 144
setBuffer() (psychopy.visual.Window method), 98
setCalibDate() (psychopy.monitors.Monitor method), 199
setColor() (psychopy.visual.Circle method), 102
setColor() (psychopy.visual.DotStim method), 107
setColor() (psychopy.visual.GratingStim method), 114
setColor() (psychopy.visual.ImageStim method), 117
setColor() (psychopy.visual.Line method), 120
setColor() (psychopy.visual.PatchStim method), 123
setColor() (psychopy.visual.Polygon method), 126
setColor() (psychopy.visual.RadialStim method), 130
setColor() (psychopy.visual.Rect method), 137
setColor() (psychopy.visual.ShapeStim method), 140
setColor() (psychopy.visual.TextStim method), 144
setColor() (psychopy.visual.Window method), 98
setColors() (psychopy.visual.ElementArrayStim method),
110
setContrast() (psychopy.hardware.crs.BitsBox method),
175
setContrast() (psychopy.visual.Circle method), 102
setContrast() (psychopy.visual.DotStim method), 108
setContrast() (psychopy.visual.GratingStim method), 115
setContrast() (psychopy.visual.ImageStim method), 118
setContrast() (psychopy.visual.Line method), 120
setContrast() (psychopy.visual.MovieStim method), 122
setContrast() (psychopy.visual.PatchStim method), 124
setContrast() (psychopy.visual.Polygon method), 126
setContrast() (psychopy.visual.RadialStim method), 130
setContrast() (psychopy.visual.Rect method), 137
setContrast() (psychopy.visual.ShapeStim method), 140
setContrast() (psychopy.visual.TextStim method), 144
setContrs() (psychopy.visual.ElementArrayStim method),
110
setCurrent() (psychopy.monitors.Monitor method), 199
setData() (in module psychopy.parallel), 202
setDefaultClock() (in module psychopy.logging), 189
setDepth() (psychopy.visual.Circle method), 103
setDepth() (psychopy.visual.DotStim method), 108
setDepth() (psychopy.visual.GratingStim method), 115
setDepth() (psychopy.visual.ImageStim method), 118
setDepth() (psychopy.visual.Line method), 120
setDepth() (psychopy.visual.PatchStim method), 125
setDepth() (psychopy.visual.Polygon method), 127
setDepth() (psychopy.visual.RadialStim method), 131
setDepth() (psychopy.visual.Rect method), 137
setDepth() (psychopy.visual.ShapeStim method), 141
setDepth() (psychopy.visual.SimpleImageStim method),
142
setDepth() (psychopy.visual.TextStim method), 145
setDescription() (psychopy.visual.RatingScale method),
135
setDir() (psychopy.visual.DotStim method), 108
setDistance() (psychopy.monitors.Monitor method), 199
setDKL() (psychopy.visual.Circle method), 103
setDKL() (psychopy.visual.GratingStim method), 115
setDKL() (psychopy.visual.ImageStim method), 118
setDKL() (psychopy.visual.Line method), 120
setDKL() (psychopy.visual.PatchStim method), 125
setDKL() (psychopy.visual.Polygon method), 127
setDKL() (psychopy.visual.RadialStim method), 131
setDKL() (psychopy.visual.Rect method), 137
setDKL() (psychopy.visual.ShapeStim method), 140
setDKL() (psychopy.visual.TextStim method), 145
setDKL_RGB() (psychopy.monitors.Monitor method),
199
234 Index
PsychoPy - Psychology software for Python, Release 1.78.00
setEdges() (psychopy.visual.Circle method), 103
setEdges() (psychopy.visual.Polygon method), 127
setEnd() (psychopy.visual.Line method), 120
setExp() (psychopy.data.MultiStairHandler method), 155
setExp() (psychopy.data.QuestHandler method), 159
setExp() (psychopy.data.StairHandler method), 153
setExp() (psychopy.data.TrialHandler method), 150
setFieldCoherence() (psychopy.visual.DotStim method),
108
setFieldPos() (psychopy.visual.DotStim method), 108
setFieldPos() (psychopy.visual.ElementArrayStim
method), 110
setFieldSize() (psychopy.visual.ElementArrayStim
method), 110
setFile() (psychopy.microphone.AdvAudioCapture
method), 191
setFillColor() (psychopy.visual.Circle method), 103
setFillColor() (psychopy.visual.Line method), 120
setFillColor() (psychopy.visual.Polygon method), 127
setFillColor() (psychopy.visual.Rect method), 137
setFillColor() (psychopy.visual.ShapeStim method), 141
setFillRGB() (psychopy.visual.Circle method), 103
setFillRGB() (psychopy.visual.Line method), 120
setFillRGB() (psychopy.visual.Polygon method), 127
setFillRGB() (psychopy.visual.Rect method), 137
setFillRGB() (psychopy.visual.ShapeStim method), 141
setFlip() (psychopy.visual.TextStim method), 145
setFlipHoriz() (psychopy.visual.BufferImageStim
method), 101
setFlipHoriz() (psychopy.visual.SimpleImageStim
method), 142
setFlipHoriz() (psychopy.visual.TextStim method), 145
setFlipVert() (psychopy.visual.BufferImageStim method),
101
setFlipVert() (psychopy.visual.SimpleImageStim
method), 142
setFlipVert() (psychopy.visual.TextStim method), 145
setFont() (psychopy.visual.TextStim method), 145
setGamma() (psychopy.hardware.crs.BitsBox method),
175
setGamma() (psychopy.monitors.Monitor method), 199
setGamma() (psychopy.visual.Window method), 99
setGammaGrid() (psychopy.monitors.Monitor method),
199
setHeight() (psychopy.visual.Rect method), 137
setHeight() (psychopy.visual.TextStim method), 145
setImage() (psychopy.visual.ImageStim method), 118
setImage() (psychopy.visual.SimpleImageStim method),
142
setLevel() (psychopy.logging.LogFile method), 187
setLevelsPost() (psychopy.monitors.Monitor method),
199
setLevelsPre() (psychopy.monitors.Monitor method), 199
setLimit() (psychopy.visual.CustomMouse method), 104
setLineariseMethod() (psychopy.monitors.Monitor
method), 199
setLineColor() (psychopy.visual.Circle method), 103
setLineColor() (psychopy.visual.Line method), 120
setLineColor() (psychopy.visual.Polygon method), 127
setLineColor() (psychopy.visual.Rect method), 138
setLineColor() (psychopy.visual.ShapeStim method), 141
setLineRGB() (psychopy.visual.Circle method), 103
setLineRGB() (psychopy.visual.Line method), 120
setLineRGB() (psychopy.visual.Polygon method), 127
setLineRGB() (psychopy.visual.Rect method), 138
setLineRGB() (psychopy.visual.ShapeStim method), 141
setLMS() (psychopy.visual.Circle method), 103
setLMS() (psychopy.visual.GratingStim method), 115
setLMS() (psychopy.visual.ImageStim method), 118
setLMS() (psychopy.visual.Line method), 120
setLMS() (psychopy.visual.PatchStim method), 125
setLMS() (psychopy.visual.Polygon method), 127
setLMS() (psychopy.visual.RadialStim method), 131
setLMS() (psychopy.visual.Rect method), 137
setLMS() (psychopy.visual.ShapeStim method), 141
setLMS() (psychopy.visual.TextStim method), 145
setLMS_RGB() (psychopy.monitors.Monitor method),
199
setLumsPost() (psychopy.monitors.Monitor method), 199
setLumsPre() (psychopy.monitors.Monitor method), 199
setLUT() (psychopy.hardware.crs.BitsBox method), 176
setMarker() (psychopy.microphone.AdvAudioCapture
method), 191
setMarkerPos() (psychopy.visual.RatingScale method),
136
setMask() (psychopy.visual.ElementArrayStim method),
110
setMask() (psychopy.visual.GratingStim method), 115
setMask() (psychopy.visual.ImageStim method), 118
setMask() (psychopy.visual.PatchStim method), 125
setMask() (psychopy.visual.RadialStim method), 131
setMaxAttempts() (psychopy.hardware.minolta.LS100
method), 182
setMeanLum() (psychopy.monitors.Monitor method),
199
setMode() (psychopy.hardware.minolta.LS100 method),
182
setMouseVisible() (psychopy.visual.Window method), 99
setMovie() (psychopy.visual.MovieStim method), 122
setNotes() (psychopy.monitors.Monitor method), 199
setOpacities() (psychopy.visual.ElementArrayStim
method), 110
setOpacity() (psychopy.visual.Circle method), 103
setOpacity() (psychopy.visual.DotStim method), 108
setOpacity() (psychopy.visual.GratingStim method), 115
setOpacity() (psychopy.visual.ImageStim method), 119
setOpacity() (psychopy.visual.Line method), 120
setOpacity() (psychopy.visual.PatchStim method), 125
Index 235
PsychoPy - Psychology software for Python, Release 1.78.00
setOpacity() (psychopy.visual.Polygon method), 127
setOpacity() (psychopy.visual.RadialStim method), 131
setOpacity() (psychopy.visual.Rect method), 138
setOpacity() (psychopy.visual.ShapeStim method), 141
setOpacity() (psychopy.visual.TextStim method), 145
setOri() (psychopy.visual.Aperture method), 100
setOri() (psychopy.visual.Circle method), 103
setOri() (psychopy.visual.DotStim method), 108
setOri() (psychopy.visual.GratingStim method), 115
setOri() (psychopy.visual.ImageStim method), 119
setOri() (psychopy.visual.Line method), 120
setOri() (psychopy.visual.PatchStim method), 125
setOri() (psychopy.visual.Polygon method), 127
setOri() (psychopy.visual.RadialStim method), 131
setOri() (psychopy.visual.Rect method), 138
setOri() (psychopy.visual.ShapeStim method), 141
setOri() (psychopy.visual.TextStim method), 145
setOris() (psychopy.visual.ElementArrayStim method),
110
setPhase() (psychopy.visual.GratingStim method), 115
setPhase() (psychopy.visual.PatchStim method), 125
setPhase() (psychopy.visual.RadialStim method), 131
setPhases() (psychopy.visual.ElementArrayStim
method), 111
setPin() (in module psychopy.parallel), 202
setPointer() (psychopy.visual.CustomMouse method),
105
setPortAddress() (in module psychopy.parallel), 202
setPos() (psychopy.event.Mouse method), 168
setPos() (psychopy.visual.Aperture method), 100
setPos() (psychopy.visual.Circle method), 103
setPos() (psychopy.visual.CustomMouse method), 105
setPos() (psychopy.visual.ElementArrayStim method),
111
setPos() (psychopy.visual.GratingStim method), 115
setPos() (psychopy.visual.ImageStim method), 119
setPos() (psychopy.visual.Line method), 120
setPos() (psychopy.visual.PatchStim method), 125
setPos() (psychopy.visual.Polygon method), 127
setPos() (psychopy.visual.RadialStim method), 131
setPos() (psychopy.visual.Rect method), 138
setPos() (psychopy.visual.ShapeStim method), 141
setPos() (psychopy.visual.SimpleImageStim method),
142
setPos() (psychopy.visual.TextStim method), 145
setPsychopyVersion() (psychopy.monitors.Monitor
method), 199
setRadialCycles() (psychopy.visual.RadialStim method),
131
setRadialPhase() (psychopy.visual.RadialStim method),
131
setRadius() (psychopy.visual.Circle method), 103
setRadius() (psychopy.visual.Polygon method), 127
setRecordFrameIntervals() (psychopy.visual.Window
method), 99
setRGB() (psychopy.visual.Circle method), 103
setRGB() (psychopy.visual.GratingStim method), 115
setRGB() (psychopy.visual.ImageStim method), 119
setRGB() (psychopy.visual.Line method), 121
setRGB() (psychopy.visual.PatchStim method), 125
setRGB() (psychopy.visual.Polygon method), 127
setRGB() (psychopy.visual.RadialStim method), 131
setRGB() (psychopy.visual.Rect method), 138
setRGB() (psychopy.visual.ShapeStim method), 141
setRGB() (psychopy.visual.TextStim method), 145
setRGB() (psychopy.visual.Window method), 99
setRgbs() (psychopy.visual.ElementArrayStim method),
111
setScale() (psychopy.visual.Window method), 99
setSF() (psychopy.visual.GratingStim method), 115
setSF() (psychopy.visual.PatchStim method), 125
setSF() (psychopy.visual.RadialStim method), 131
setSfs() (psychopy.visual.ElementArrayStim method),
111
setSize() (psychopy.visual.Aperture method), 100
setSize() (psychopy.visual.Circle method), 103
setSize() (psychopy.visual.DotStim method), 108
setSize() (psychopy.visual.GratingStim method), 115
setSize() (psychopy.visual.ImageStim method), 119
setSize() (psychopy.visual.Line method), 121
setSize() (psychopy.visual.PatchStim method), 125
setSize() (psychopy.visual.Polygon method), 127
setSize() (psychopy.visual.RadialStim method), 131
setSize() (psychopy.visual.Rect method), 138
setSize() (psychopy.visual.ShapeStim method), 141
setSize() (psychopy.visual.TextStim method), 145
setSizePix() (psychopy.monitors.Monitor method), 200
setSizes() (psychopy.visual.ElementArrayStim method),
111
setSpectra() (psychopy.monitors.Monitor method), 200
setSpeed() (psychopy.visual.DotStim method), 108
setStart() (psychopy.visual.Line method), 121
setTex() (psychopy.visual.BufferImageStim method), 101
setTex() (psychopy.visual.ElementArrayStim method),
111
setTex() (psychopy.visual.GratingStim method), 116
setTex() (psychopy.visual.PatchStim method), 125
setTex() (psychopy.visual.RadialStim method), 131
setText() (psychopy.visual.TextStim method), 145
setupProxy() (in module psychopy.web), 206
setUseBits() (psychopy.monitors.Monitor method), 200
setUseShaders() (psychopy.visual.Circle method), 103
setUseShaders() (psychopy.visual.DotStim method), 108
setUseShaders() (psychopy.visual.GratingStim method),
116
setUseShaders() (psychopy.visual.ImageStim method),
119
236 Index
PsychoPy - Psychology software for Python, Release 1.78.00
setUseShaders() (psychopy.visual.Line method), 121
setUseShaders() (psychopy.visual.PatchStim method),
125
setUseShaders() (psychopy.visual.Polygon method), 127
setUseShaders() (psychopy.visual.RadialStim method),
131
setUseShaders() (psychopy.visual.Rect method), 138
setUseShaders() (psychopy.visual.ShapeStim method),
141
setUseShaders() (psychopy.visual.SimpleImageStim
method), 142
setUseShaders() (psychopy.visual.TextStim method), 145
setVertices() (psychopy.visual.Circle method), 103
setVertices() (psychopy.visual.Line method), 121
setVertices() (psychopy.visual.Polygon method), 127
setVertices() (psychopy.visual.Rect method), 138
setVertices() (psychopy.visual.ShapeStim method), 141
setVisible() (psychopy.event.Mouse method), 168
setVisible() (psychopy.visual.CustomMouse method),
105
setVolume() (psychopy.sound.SoundPygame method),
205
setWidth() (psychopy.monitors.Monitor method), 200
setWidth() (psychopy.visual.Rect method), 138
setXYs() (psychopy.visual.ElementArrayStim method),
111
ShapeStim (class in psychopy.visual), 138
show() (psychopy.gui.Dlg method), 172
shuffleArray() (in module psychopy.misc), 196
sign() (in module psychopy.contrib.opensslwrap), 167
SimpleImageStim (class in psychopy.visual), 141
simulate() (psychopy.data.QuestHandler method), 159
SoundPygame (class in psychopy.sound), 204
Speech2Text (class in psychopy.microphone), 191
sph2cart() (in module psychopy.misc), 197
StairHandler (class in psychopy.data), 151
start() (psychopy.core.StaticPeriod method), 95
startRemoteMode() (psychopy.hardware.pr.PR655
method), 185
StaticPeriod (class in psychopy.core), 94
stop() (psychopy.microphone.AdvAudioCapture
method), 191
stop() (psychopy.sound.SoundPygame method), 205
stop() (psychopy.visual.MovieStim method), 122
switchOn() (in module psychopy.microphone), 190
SyncGenerator (class in psychopy.hardware.emulator),
177
T
testProxy() (in module psychopy.web), 206
TextStim (class in psychopy.visual), 142
toFile() (in module psychopy.misc), 197
TrialHandler (class in psychopy.data), 147
U
u3 (in module labjack), 180
uint8_float() (in module psychopy.misc), 197
uncompress() (psychopy.microphone.AdvAudioCapture
method), 191
updateElementColors() (psy-
chopy.visual.ElementArrayStim method),
111
updateElementVertices() (psy-
chopy.visual.ElementArrayStim method),
111
updateTextureCoords() (psy-
chopy.visual.ElementArrayStim method),
111
upload() (in module psychopy.web), 205
V
VBI, 223
VBI blocking, 223
VBI syncing, 223
verify() (in module psychopy.contrib.opensslwrap), 167
W
wait() (in module psychopy.core), 93
waitKeys() (in module psychopy.event), 168
warn() (in module psychopy.logging), 189
warning() (in module psychopy.logging), 189
wav2flac() (in module psychopy.microphone), 193
Window (class in psychopy.visual), 95
write() (psychopy.logging.LogFile method), 187
X
XidDevice (class in pyxid), 175
xlsx, 223
xydist() (in module psychopy.event), 169
Index 237

Navigation menu