Usage guide

Global defaults panel

The rightmost panel contains global defaults for the program. These are window properties along with parameters that apply to all stims. The selections made in the global panel can be saved.

For the parameters to be applied, the window instance must be regenerated by recreating the window. The exceptions to this are:

  • log
  • start trigger wait
  • protocol reps
  • preferred dir
  • capture
  • background

These parameters can be changed without having to regenerate the window. Most parameters are self explanatory. The rest are described below:

  • center offset (pix)
    Number of pixels in x and y directions to move the center of the window. This is useful in case the window size is larger than the monitor size, but the center of the screen should correspond to the center of the window.
  • scale (xy)
    A scale factor applied to all sizes in each direction. A scale of -1 can be used mirror the window along an axis.
  • pix per micron
    Conversion ratio to go between pixels and microns. Used to convert distances to pixels behind the scenes.
  • frame rate (fps)
    This is the actual frame rate of the monitor, not the desired frame rate. This value is used to determine how many frames stims should last for.
  • protocol reps
    Number of repetitions the stim(s) will run through. This is equivalent to pressing the Run button several times.
  • start trigger wait (s)
    If triggering is desired, this is the delay between a first trigger being sent and the onset of the stims. If set to 0, stims will start immediately, and only trigger if set to do so.
  • gamma monitor
    The gamma correction applied to all colors in the window. If set to default, no gamma correction will be applied. See GammaCorrection module for documentation.
  • capture
    If set to True, will generate a movie on each run. This movie is generated from screenshots of the window at each frame, so is a direct copy.

Stim parameter panel

The stim parameter panel is where the parameters for stims are set. The entire list of parameters and their descriptors can be found here. All parameters are passed to the program for every stim, however the program only uses the necessary parameters for each stim and ignores the others.

Dropdown menus and text boxes can be right clicked, which will bring up the parameter’s associated table and make the control uneditable.

Stim list panel

The panel second from the left holds the list of stims that will be displayed. The stims are drawn to the window in the order that they appear in the list. The order can be changed using the Move up and Move down buttons. Stims are added to the list using the Add button, and removed using the Remove button. When removing, if a stim is selected, it will be removed, else the entire list will be cleared. Thus a double click on Remove will always clear the entire list.

The parameters of a stim can be seen by double clicking on a stim in the list. When double clicked, the parameters for that stim are populated into the parameter panel. Editing the parameters while a stim is selected does not edit the parameters of that stim. Once a stim is added, its parameters are set. To change an existing stim, double click on it, change the desired values, then remove and re-add the stim, and move it up as needed.

Directory panel

The leftmost panel contains a file browser. Pressing the Save button saves the current list of stims. The stims can later be loaded back into the list using the Load button. Stims can also be loaded by double clicking them.

Log files generated by the program also contain a record of the stims run, and can be loaded using the load button. Double clicking on a log file will open it for viewing.

The default directory displayed in the file browser can be set in the .ini file, found at:

./psychopy/config.ini

Tables

Tables are used to go through stim repetitions while changing the value of a specific parameter on each repeat. Each row in the table represents a repetition. The program will continue to repeat until the last row with no more values beneath it. Empty rows will default to the last used value. The first row cannot be left blank. If a dropdown parameter is used in a table, the value entered must exactly match one of the available choices.

To add more rows, right click the top left corner of the table. To remove a cell, row, or column, right click either the cell or the column/row header. Removing a column removes that parameter from the table and makes the parameters editable again.

Triggering

Triggering is achieved via a LabJack U3, using port FIO4. When a trigger command is sent, the LabJack briefly sends a voltage spike. If connected via high speed USB (2.0+), the spike will last approximately 0.4 ms. Ensure a high enough sampling rate or spikes could go undetected (~ 2.5 kHz).

Triggering is set for each individual stim in the timing panel. Different stims have different triggering behaviors. If set to trigger, all stims will send a trigger the moment before the first frame in which they are animated.

Moving stims and randomly moving stims will also trigger at the beginning of each new direction. Table stims will trigger on the first and last frames, and also at any other frames set to trigger. In the global defaults panel, if trigger wait is not zero, then when the run button is pressed, a trigger will be sent, the trigger wait period will elapse, then stims will start as normal and trigger and begin their animations.

Framepacking

pyStim is able to produce stimuli running at fps in excess of 60 hz. This is accomplished through the use of framepacking with a projector capable of interpreting such data (ex: LCR 4500). Individual monochrome frames are packed into the 3 RGB planes of a single 24 bit frame, thus allowing speeds of 3 times the actual framerate. The following directions are for using pyStim with an LCR 4500 using such framepacking.

  1. In “options”, enable the “framepack” options
  2. Set the resolution to 912x1140 and select the proper output (ex: screen num 2)
  3. Set the framerate to the target value (i.e. if running at 3x 60 hz for 180 hz, set to 180 hz)
  4. If the window was already generated, it needs to be regenerated. Stims should now be packing.