retinotopy.py documentation

This program presents basic retinotopic mapping stimulus, localizers for MT (motion), LOC (objects), and VWFA (words) and a variety of flickering or drifting checkerboards. It reproduces the functions of the RET code which runs on Macs only. Retinotopy.py is a python script that uses the PsychoPy toolbox. For each scan, the code will wait for the subject to press a button indicating they are ready, then the code will wait for a trigger from the scanner. Some scans will present a third message to the operato before the ''subject ready'' message; this includes information about the length of the scan and number of TRs. The code expects keyboard presses for subject responses and trigger; the defaults are bygr for subject responses and t for trigger or 1234 for responses and 5 for trigger.

Required citation

If you use the stimuli in a publication, please cite the papers describing PsychoPy:

• Peirce, JW (2007) PsychoPy - Psychophysics software in Python. J Neurosci Methods, 162(1-2):8-13
• Peirce JW (2009) Generating stimuli for neuroscience using PsychoPy. Front. Neuroinform. 2:10. doi:10.3389/neuro.11.010.2008

The stimuli that use images have further citations (see ''Stimulus Types''); these are not available outside the CMRR, as I do not have rights to redistribute the processed images.

Contact information

Andrea Grant, gran0260@umn.edu

Running Modes

1. Predetermined scan sequence and timing details using a parameter file (details below)
2. Run "dynamically" by choosing the timing information and other details, then choosing each scan type after the previous scan finishes

Stimulus Types

1. Rotating wedge (drifting checkerboard).
   1. Wedge can be any width (22.5 and 45 are defaults)
   2. can rotate clockwise or counterclockwise
2. Expanding/contracting ring (drifting checkerboard).
   1. The ring can be any duty cycle (12.5% or 25% are defaults)
   2. can expand or contract
3. Motion localizer (field of drifting vs. static dots).
   1. The scan can start with moving or static dots
4. Object localizer (intact vs. scrambled images).
   1. The scan can start with the intact or scrambled images.
   2. Note: the scrambled images are available but still need some optimization.
   3. required citation: image are from Tarr Lab: " If you use any of these images in publicly available work - talks, papers, etc. - you must acknowledge their source and adhere to the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. You must also include the line Stimulus images courtesy of Michael J. Tarr, Center for the Neural Basis of Cognition and Department of Psychology, Carnegie Mellon University, http://www.tarrlab.org/."
5. Full field flickering checkerboard.
   1. Both checkerboard colors (and background color) and flicker frequency can be specified.
   2. Timing can be symmetric (X seconds on, X seconds off) or asymmetric
6. Full field drifting checkerboard (black and white on gray background)
   1. Stimulus on vs. off
   2. Drifting checkerboard vs. static checkerboard
   3. Center vs. surround checkerboard
   4. Center vs. inner surround vs. outer surround checkerboard (i.e., fovea vs. periphery localizer)
   5. Alternating halves checkerboard
   6. Timing can be symmetric (X seconds A, X seconds B) or asymmetric (X seconds A Y seconds B repeated N times followed by a rest of M. This block can be repeated)
7. Visual word form area (VWFA) localizer
   1. with images of words, chairs, houses, and faces in a block design (10 trials per block, 4 blocks of each type)
      • required citations:
        • faces are from AT&T Laboratories Cambridge: "When using these images, please give credit to AT&T Laboratories Cambridge."
        • chairs and objects are from Tarr Lab: " If you use any of these images in publicly available work - talks, papers, etc. - you must acknowledge their source and adhere to the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. You must also include the line Stimulus images courtesy of Michael J. Tarr, Center for the Neural Basis of Cognition and Department of Psychology, Carnegie Mellon University, http://www.tarrlab.org/."
        • houses are from MIT SUN database:"SUN Database: Large-scale Scene Recognition from Abbey to Zoo". J. Xiao, J. Hays, K. Ehinger, A. Oliva, and A. Torralba. IEEE Conference on Computer Vision and Pattern Recognition, 2010.
   2. with letters, emoticons, and ''wingdings'' (letter-like but non-letter symbols) in a block design (12 trials per block, 3 blocks of each type)
      1. Note: the emoticons and wingdings don't display correctly yet

Parameter File

Overview: The parameter file defines two variables that are used to control the stimuli. The first is a python "dictionary", a series of key:value pairs. Some key/values aren't used for some stimuli; they can be removed from the parameter file or left in (and will be ignored). The format for a dictionary is myDict = {'key1':value1,'key2':value2}

• The key is in single quotes.
• If the value is a single number, just type the number: 6.7
• If it's a sequence of numbers, such as an RGB triplet, enclose it in square brackets separated by commas: [1,1,0]
• If the value is a string, such as the monitor calibration name, enter it inside a pair of single quotes: '7TASwest'
• The key/value pairs can be in any order within the {} and are separated by a comma

The second variable is a "list" containing the stimulus types to be displayed, in order (# indicates the text following it will be ignored as a comment). The name of the stimulus type has to be entered exactly. The list is first declared to be the right length (don't edit this line)

• scanSeq = [0]*scanDict['numScans']

Then the individual scans are assigned:

• scanSeq[0]='full-field flickering checkerboard asymmetric'
• #scanSeq[1]='cw wedge'
• #scanSeq[2]='motionA'

List of stimulus types and their official names in the parameter file

• cw wedge: wedge rotating clockwise. Rotation speed is determined by the period, drift speed (of the internal wedge bits, normally 0.2Hz) is set by animFreq, wedge width is set by wedgeWidth. This is a travelling wave retinotopy scan
• ccw wedge: wedge rotating counterclockwise. Rotation speed is determined by the period, drift speed (of the internal wedge bits, normally 0.2Hz) is set by animFreq, wedge width is set by wedgeWidth. This is a travelling wave retinotopy scan
• contracting ring: ring which contracts. Contraction speed is determined by the period (and eccentricity limits), drift speed (of the internal wedge bits) is set by animFreq (normally 0.2Hz), duty cycle (eccentricity width of ring) is set by dutyCycle. This is a travelling wave retinotopy scan
• expanding ring: ring which expands. Contraction speed is determined by the period (and eccentricity limits), drift speed (of the internal wedge bits) is set by animFreq (normally 0.2Hz), duty cycle (eccentricity width of ring) is set by dutyCycle. This is a travelling wave retinotopy scan
• motionA: motion localizer consisting of moving vs static dots. The first half of each period is moving dots, the second half is static dots. If preScanRest is ½ period, it will show static dots.
• motionB: "inverse" motion localizer consisting of moving vs static dots. The first half of each period is static dots, the second half is moving dots. If preScanRest is ½ period, it will show moving dots.
• objectA: object localizer consisting of intact vs. scrambled images. The first half of each period is intact images, the second half is scrambled images. If preScanRest is ½ period, it will show scrambled images
• objectB: "inverse" object localizer consisting of intact vs. scrambled images. The first half of each period is scrambled images, the second half is intact images. If preScanRest is ½ period, it will show intact images
• full-field flickering checkerboard: full field flickering checkerboard, on-off, with symmetric timing. Colors of the checkerboard and background can be specified, as can animation (flicker) frequency (animFreq). Number of wedges and width of wedge rings can be specified. Timing can be controlled by clocktime or scanner triggers:
  • timebase=1: (clock control) Stimulus is off for preScanRest time, on for period/2 time, and off for period/2 time.
  • timebase=0: (trigger control) Stimulus/rest is shown until N triggers are received. Stimulus is off for N=preScanRest/Tr, on for N=(1/2)*period/Tr, off for N=(1/2)*period/Tr
• full-field flickering checkerboard asymmetric: full field flickering checkerboard, on-off, with flexible timing. Stimulus is off for preScanRest time, on for stimDuration time, and off for (period - stimDuration) time. Number of wedges and width of wedge rings can be specified. Colors of the checkerboard and background can be specified, as can animation (flicker) frequency
• drifting checkerboard on-off: full field drifting checkerboard (black and white), on-off with symmetric timing. Stimulus is on for period/2 time and then off for period/2. Drift rate is controlled by animFreq
• drifting checkerboard drift-static: full field drifting checkerboard (black and white), drift vs. static with symmetric timing. Stimulus is drifting for period/2 time and then static for period/2. Drift rate is controlled by animFreq
• drifting checkerboard center-surround: full field drifting checkerboard (black and white), center vs. surround with symmetric timing. Stimulus is center for period/2 time and then the surround for period/2. Drift rate is controlled by animFreq. Center/surround cutoff radius is fixed at 4 degrees
• drifting checkerboard center-inner-outer: full field drifting checkerboard (black and white), center vs. inner surround vs. outer surround with symmetric timing. Stimulus is outer surround for preScanRest time, center for period/3 time, inner surround for period/3 time, and outer surround for period/2. Drift rate is controlled by animFreq. Center/inner surround border is given by Ralpha, inner surround/outersurround border is defined by Rbeta.
• drifting checkerboard alternating halves: full field drifting checkerboard (black and white), alternating halves with symmetric timing. Stimulus is on the right side for period/2 time and then the left side for period/2. Drift rate is controlled by animFreq
• drifting checkerboard on-off asymmetric: full field drifting checkerboard (black and white), on-off with asymmetric timing. Stimulus is on for stimDurationA time and then off for stimDurationB. Drift rate is controlled by animFreq
• drifting checkerboard drift-static asymmetric: full field drifting checkerboard (black and white), drift vs. static with asymmetric timing. Stimulus is drifting for stimDurationA time and then static for stimDurationB. Drift rate is controlled by animFreq, number of AB repetitions per block is controlled by numReps, number of blocks is controlled by numBlocks, and inter-block rest is controlled by stimDurationRest
• drifting checkerboard center-surround asymmetric: full field drifting checkerboard (black and white), center vs. surround with asymmetric timing. Stimulus is center for stimDurationA time and then the surround for stimDurationB. Drift rate is controlled by animFreq. Center/surround cutoff radius is fixed at 4 degrees, number of AB repetitions per block is controlled by numReps, number of blocks is controlled by numBlocks, and inter-block rest is controlled by stimDurationRest
• drifting checkerboard alternating halves asymmetric: full field drifting checkerboard (black and white), alternating halves with asymmetric timing. Stimulus is on the right side for stimDurationA time and then the left side for stimDurationB. Drift rate is controlled by animFreq, number of AB repetitions per block is controlled by numReps, number of blocks is controlled by numBlocks, and inter-block rest is controlled by stimDurationRest
• VWFA localizer: VWFA localizer using letters, non-letter symbols, and emoticons. Timing is hardcoded to present 12 trials per block and 3 blocks of each type, with 12s of rest in before starting, between blocks, and after the last block(restArestBrestCrestBrestArestCrestBrestCrestArest). Stimulus is presented for 0.75s with an ISI of 0.25s.
• VWFA localizer images: VWFA localizer using words and pictures of chairs, houses, and faces. Timing is hardcoded to present 10 trials per block and 4 blocks of each type, with 10s of rest in before starting, between blocks, and after the last block (restABCDrestBADCrestCBDArestDCABrest). Stimulus is presented for 0.75s with an ISI of 0.25s.
  • List of Parameters
    • Tr in seconds
    • preScanRest duration of ''rest'' to show before the stimulus starts. For retinotopy traveling waves (a,b), this will start the stimulus earlier in the period. For MT and LOC, this will start with the ''off'' condition. For checkerboard scans, this will show rest (blank gray screen with fixation). This time is not part of the number of full cycles
    • postScanRest duration of ''rest'' to show after the last stimulus ends.
    • stimDuration in seconds. Used for asymmetric flickering checkerboard scans
    • stimDurationA in seconds. Used for asymmetric drifting checkerboard scans
    • stimDurationB in seconds. Used for asymmetric drifting checkerboard scans
    • stimDurationRest in seconds. Used for asymmetric drifting checkerboard scans
    • period in seconds (stimulus duration + rest, or full cycle for traveling waves)
    • numCycles how many full cycles of stimulus+rest or traveling waves to show. This doesn't include the preScanRest time
    • numReps number of AB repetitions per block for asymmetric drifting checkerboard scans
    • numBlocks number of (ABABrest) blocks for asymmetric drifting checkerboard scans
    • contrast 0 to 1
    • innerRadius in degrees. The fixation mark size is fixed at 0.5*innerRadius, so innerRadius smaller than about 0.4 degrees could become too small to see.
    • outerRadius in degrees. This can be as large as desired, but will be obviously be limited by the size of the screen
    • wedgeWidth in degrees. The width of the rotating wedge
    • dutyCycle in percent. The eccentricity width of the expanding/contracting ring, in percent (of outerRadius)
    • fixFraction the fraction of time (on average) that the fixation point could change. The task is for the subject to hit a button anytime the fixation mark ( + ) rotates by 45 degrees ( x ). The mark could change every 100 frames; this fraction determines whether or not it will.
    • animFreq the flicker frequency in Hz for the flickering checkerboard, or the drift frequency for drifting checkerboards (normally 0.2Hz for retinotopic mapping)
    • colorA first color of the checkerboard for flickering checkerboards only. Specify as an RGB triplet ranging from 0 to 1. E.g., [1,0,0] or [0.5,1,0]
    • colorB second color of the flickering checkerboard, RGB triplet
    • colorBackground background color for the flickering checkerboard, RGB triplet
    • monitor the ''monitor'' file (projector) to use. These will load up the linearized gamma table for that projector. This will populate a list of monitor files that have been created in monitor center on the local stimulus machines. At the CMRR, valid options are (depending on the scanner)
      • 7TASwest
      • 7TASeast
      • 7TPS
      • 3TA
      • 3TB
      • other loads up PsychoPy's ''testMonitor'', without gamma linearization
    • operatorScreen screen number for the operator, normally 0 for the primary display on the computer. Only used for flickering checkerboards, which display a graph of subject responses during the scan
    • subjectScreen screen number for the subject, normally 1 for the secondary display which is routed to the projector. If the two displays are mirrored, this should be 0 and the flickering checkerboards can't be run.
    • numScans the number of scans to be run. This number is used to initialize the variable containing the sequence of scans in the parameter file
    • timeBase whether the stimulus timing is controlled via computer's clock (1) or scanner triggers (0). Available only for flickering checkerboards with even timing (not for the asymmetric checkerboards)
    • Ralpha eccentricity border between center and inner surround for center/inner surround/outer surround drifting checkerboard, in degrees
    • Rbeta eccentricity border between inner surround and outer surround for center/inner surround/outer surround drifting checkerboard, in degrees
    • pairWedge Option to display a pair of wedges (for improving fixation) in rotating wedge
    • fixationStyle Option to have fixation mark change color (and rotate) for flickering checkerboard scans; 1 for rotation only, 2 for rotation and color change
    • trigger allowed characters for trigger signal from scanner; defaults to 5t
    • subject responses allowed characters for subject responses; defaults to 1234bygr
    • numWedgePairs number of pairs of wedges in a flickering checkerboard
    • ringWidth width of each ring (in degrees of visual angle) for flickering checkerboards
  • Instructions for running the code
    • Launch the standalone PsychoPy application
    • Open the file "retinotopy.py" located on the desktop in the folder pythonret
    • Set up your parameter file, if desired (see full documentation or retinotopyParamsExample.py)
    • Click the green run button or type CTRL-R (windows) or CMD-R (mac)
    • Click on your desired running mode (parameter file or dynamic)
      • parameter mode:
        • Choose the parameter file from the file-open dialog
      • dynamic mode:
        • Specify the general details for the scans.
        • Choose the stimulus type for the next scan.
        • Specify the specific parameters for that scan
        • When you are done, choose QUIT