PsychoPy - Psychology software for Python Release 3.0.2 Jonathan Peirce Jan 29, 2019 Contents 1 About PsychoPy 1 2 General issues 3 3 Installation 29 4 Manual install 31 5 Getting Started 35 6 Builder 43 7 Coder 75 8 Running studies online 95 9 Reference Manual (API) 103 10 Troubleshooting 325 11 Recipes (“How-to”s) 329 12 Frequently Asked Questions (FAQs) 341 13 Resources (e.g. for teaching) 343 14 For Developers 345 15 PsychoPy Experiment file format (.psyexp) 359 Python Module Index 363 i ii CHAPTER 1 About PsychoPy 1.1 Citing PsychoPy If you use this software, please cite one of the publications that describe it. • Peirce, J. W., & MacAskill, M. R. (2018). Building Experiments in PsychoPy. London: Sage. • Peirce J. W. (2009). Generating stimuli for neuroscience using PsychoPy. Frontiers in Neuroinformatics, 2 (10), 1-8. doi:10.3389/neuro.11.010.2008 • Peirce, J. W. (2007). PsychoPy - Psychophysics software in Python. Journal of Neuroscience Methods, 162 (1-2):8-13 doi:10.1016/j.jneumeth.2006.11.017 Citing these papers gives the reviewer/reader of your study information about how the system works and it attributes some credit for its original creation. Academic assessment (whether for promotion or even getting appointed to a job in the first place) prioritises publications over making useful tools for others. Citations provide a way for the developers to justify their continued involvement in the development of the package. 1 PsychoPy - Psychology software for Python, Release 3.0.2 2 Chapter 1. About PsychoPy CHAPTER 2 General issues These are issues that users should be aware of, whether they are using Builder or Coder views. 2.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. 2.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 width/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) 3 PsychoPy - Psychology software for Python, Release 3.0.2 2.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. 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. 2.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. 2.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 2.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. 4 Chapter 2. General issues PsychoPy - Psychology software for Python, Release 3.0.2 Spatial frequency: cycles per stimulus (so will scale with the size of the stimulus). Requires : No monitor information 2.2.3 Centimeters on screen Set the size and location of the stimulus in centimeters on the screen. 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). 2.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 There are actually three variants: ‘deg’, ‘degFlat’, and ‘degFlatPos’ ‘deg’ : Most people using degrees of visual angle choose to make the assumption that a degree of visual angle spans the same number of pixels at all parts of the screen. This isn’t actually true for standard flat screens - a degree of visual angle at the edge of the screen spans more pixels because it is further from the eye. For moderate eccentricities the error is small (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 most studies this form of calculation is preferred, as it does not result in a warped appearance of visual stimuli, but if you need greater precision at far eccentricities then choose one of the alternatives below. ‘degFlatPos’ : This accounts for flat screens in calculating position coordinates of visual stimuli but leaves size and spatial frequency uncorrected. This means that an evenly spaced grid of visual stimuli will appear warped in position but will ‘degFlat’: This corrects the calculations of degrees for flatness of the screen for each vertex of your stimuli. Square stimuli in the periphery will, therefore, become more spaced apart but they will also get larger and rhomboid in the pixels that they occupy.