Stimuli

WM     Working Models     www.iModel.org/wm

CONTENTS
Introduction to stimuli
Frame parameters
Varying parameters
Adding a new 3D stimulus

Introduction

Visual stimuli of the 3d type are represented as a 3D array [xn,yn,tn] with values typically in the range [0,1] where 0 is black and 1.0 is maximum luminance. The 3d_b type is for binocular stimuli, and is represented in two 3D arrays, one for the left eye and one for the right.

Most of the parameters for any stimulus are stimulus specific, such as dot_density, contrast, bar_length, and are not described here. To find out about stimulus specific parameters, it is best to work from an existing stimulus file to customise the stimulus. The parameters described below are mostly those that can be, or must be, specified for any stimulus.

One of the most confusing parts of using a stimulus with a model involves the temporal sampling and the duration of the stimulus. A full discussion will require a dedicated web page, but it should be remembered that tn times tscale (from the model file) sets an absolute limit, in seconds, on how long the simulation, and thus the stimulus can last. No stimulus-specific parameters can cause a stimulus to last longer, just as no parameter that governs, say, the length of a bar can change the spatial limits of the model, which are set by xn and yn. Temporal sampling is discussed under stim_samp below.

Another subtle point about the stimulus is the location of the center position. By convention, the center of the grid will be at (xn-1.0)/2.0 and (yn-1.0)/2.0, and any pixel in the grid is considered to be centered at its position in [0..xn-1][0..yn-1]. For example, a stimulus centered at cx = cy = 0 (deg) will have its center at (1.5, 1.5) in pixel coordinates on a 4x4 grid.

General parameters

  • stim_type - type of stimulus, e.g. 'sine', 'bar', 'dots'

  • stim_form - stimulus data format, default is '3d'
    • 3d - data is a 3D float array. Often processed by FFT conv.
    • 3c - data is a 3D int array, packed w/ 3bytes of RGB color. Array indexing starts at 0.
    • 3d_b - binocular 3D data.
    • 1d - data is a 1D float array.

  • stim_samp - stimulus sampling rate (frames/s). This can be used to allow black frames to be interleaved between regular frames to emulate a CRT. For example, if tscale is 0.002 (two milliseconds) and stim_samp is 100, impling that the stimulus is defined once every 10ms, then there will be four empty frames between each regular stimulus frame. The four empty frames could be set to black, as they would be on a CRT with a very fast phosphor decay, or you can set stim_phtau below to simulate a decaying phosphor signal. More typically, one is not trying to emulate the flashing of conventional CRTs, and stim_samp is set to a value faster than or equivalent to that implied by tscale, in which case the mapping from stimulus frames to temporal frames in the model is 1-to-1. Until more complete documentation on this feature is developed, it is recommended to email Wyeth if you are unsure about this feature.

  • stim_shuff_seed - if non-zero, the value is used to block-wise randomise the stimuli. This has the important implications:
    • Stimuli must be recreated for each repeat; therefore, this is less efficient than running all repeats of one stimulus before moving to the next.
    • Currently this is ignored in 'mm', because it does not make sense to randomise stimuli unless they are processed in sequence.
    • The 'write_stim_num' option is ignored.

  • stim_phtau - phosphor decay time constant (s) for CRT emulation, default value is 0.006. Currently implemented for the following stimuli:
    • sine
    • sine_seq
    • ransinphase, ransinori, ransindir

  • stim_smooth - (deg, 0.0 default - none) SD for Gaussian smoothing, beware wrap-around.

  • stim_smooth_t - (s, 0.0 default - none) peak of Maxwell function (sec), beware wrap-around.

  • stim_adapt - 'none' (default) or 'meangray'. Currently, this is not widely used.

    THE FOLLOWING parameters can be used with stim_form 3c to convert a grayscale '3d' stimulus into a color ('3c') stimulus:

  • color0_r - red component of color associated with amplitude 0
  • color0_g - green component of color associated with amplitude 0
  • color0_b - blue component of color associated with amplitude 0
  • color1_r - red component of color associated with amplitude 1
  • color1_g - green component of color associated with amplitude 1
  • color1_b - blue component of color associated with amplitude 1


Other parameters.
  • stim_nrpt - number of repeats of each stimulus. When this is greater than 1, the same visual stimulus will be presented multiple times, but any noise that is added will be differnt.
  • write_stim_num - (-1 no dump) stimulus ID number for 3D data dump
  • write_stim_rpt - (0) repeat number for 3D data dump


Frame Parameters

Frame parameters. Normally, stimuli are defined without these frame parameters, because values of xn, yn, tn, sscale and tscale will be imposed from the model file. However, when a stimulus is to be manipulated independently of a model, for example when making a demo movie of a stimulus, then these stim_frame_ parameters should be used to set the spatiotemporal size and scale for building the stimulus. These parameters will be ignored when the stimulus is submitted to a model.
  • stim_frame_xn - width of frame in which to place stimulus (pix)
  • stim_frame_yn - height of frame in which to place stimulus (pix)
  • stim_frame_tn - duration of frame in which to place stimulus (pix)
  • stim_frame_sscale - degrees/pixel
  • stim_frame_tscale - sec/pixel


Varying Parameters

These constructs are added at the end of a stimulus file to specify values for parameters that should be varied. Any parameter to be varied using one of these methods must be specified already in the normal way in the upper portion of the stimulus file. Some examples are given followed by definitions. For example, if you wanted to vary one parameter, such as contrast, use the following 
     VAR_contrast  0 0.25 0.5 0.75 1.0
which will create 5 stimuli. If you want to make a matrix of stimuli, for example 3 spatial frequencies and 2 temporal frequencies, 
     VAR_sf  0.5 1 2
     VAR_tf  6 12
which will create 6 stimuli. If you want two parameters to vary together, rather than independently, then use, 
     VARLINK_sf    0.5  1  2.0
     VARLINK_size  2.0  1  0.5
which will create 3 stimuli, the first of which has sf 0.5 and size 2.0. If you added a VAR_ line to the above with, say, 2 values,then you would end up with 6 stimuli, where each VAR_ value was used with each of the 3 VARLINK_ stimuli.

If you want to create many random values for a parameter without typing out an explicit list, then you can allow the computer to generate those values using 

     #            type   dec  n  mult add  seed
     VARGEN_seed uniform  0  20 10000   1  1777
which will generate 20 stimuli having random values for 'seed', each value having 0 places after the decimal point and chosen from a uniform distribution between 1 and 10000, inclusive. The random sequence is determined by the value 1777. Note, in the above example, the line beginning with # is simply a comment and is ignored.

To add a single extra stimulus to a set of stimuli, for example adding a baseline control, use, 

     VARSINGLE_contrast 0
then in addition to any other stimuli, for example those defined with a set of VAR_ or VARLINK_ commands, one extra stimulus will be added, which has contrast set to 0.

Here are the formal definitions:

  • VAR_[pname] - followed by a list of values, where [pname] is replaced by the name of a stimulus parameter that must already appear in the stimulus-specific parameter section of the .stm file.

  • VARLINK_[pname] - followed by a list of values. All varlink parameters must have the same number of values specified.

  • VARGEN_[pname] [type] [decimal] [n] [mult] [add] [seed]
    • type - "uniform"
    • decimal - number of decimals to store, used as: %.[decimal]f
    • n - number of values to generate
    • mult - multiplier, used to scale the raw RV, between [0..1)
    • add - offset added after multiplier is applied
    • seed - randomization seed, positive integer

  • VARGENPAIR_[pname] [pname2] [n] [type]
    • pname2 - second parameter in pair
    • n - number of paired values to generate
    • type - "list_tap_11_opp", ...
      • list_opp_mseq_tap_11 [i] - Pick values from the built in order-11 m-sequence tap register list, starting with index 'i' in a list of 40 (i=0,1,...39). The value for 'pname2' will have the opposite index in the list, thus offset by 20 indices. Values will wrap around as more trials are accumulated.

  • VARSINGLE_[pname] [value]
    • pname - parameter name
    • value - value to use in place of the default for this param


Adding a new 3D stimulus

  • Add a C routine get_stim_3d_ppl_XXX to stim_util.c (.h)
  • Add a call to the routine get_stim_3d_ppl_XXX in the routine get_3d_stim_data in the file stim_util.c