Varying ParametersΒΆ

To vary stimulus parameters over a set of values, and thereby specify a series of stimuli rather than a single stimulus, you must place lines within the .stm file that specify the variable parameter names and values. Examples are given below.

Varying a single parameter

For example, if a parameter named contrast is defined in the .stm file, it can be varied by adding the line “VAR_contrast ...” as shown below:

contrast     0.8   # Stimulus contrast [0..1]
...
VAR_contrast  0 0.25 0.5 0.75 1.0

This specifies a series of five stimuli in which the variable parameter contrast will take the values listed from 0 to 1.0. Note that the original value, 0.8, assigned to contrast by the regular parameter line (the first line in the example) becomes irrelevant when the VAR_contrast line is added. Nevertheless, there must be a regular parameter definition line for any parameter that is varied using the “VAR_” construct.

Varying multiple parameters independently

To specify a matrix of stimuli by varying two or more parameters, simply use multiple “VAR_” lines:

VAR_sf  0.5 1 2
VAR_tf  6 12

The above two lines specify six stimuli, one for each of the three values of sf crossed with each of the two values of tf.

To tie the values of two variable parameters together, use “VARLINK_” lines as follows:

VARLINK_sf    0.5  1  2.0
VARLINK_size  2.0  1  0.5

This specifies only three stimuli, the first of which has sf 0.5 and size 2.0. By adding a “VAR_” line to the above with, say, two values, there would then be six stimuli in total, where each “VAR_” value was used with each of the three VARLINK_ stimuli.

For longer lists of values, an external file can be used (see next section).

Using a separate text file to specify linked values

To define a set of stimuli using an exhaustive list of all of the variable parameter names, the VARFILE parameter can be set:

VARFILE  foo.txt

This can be used in combination with some of the other VAR... commands described here. In particular, with “VAR_” and “VARSINGLE_”. An example of the text file format (foo.txt in the above example), is as follows:

npar 3
sf tf size
nstim 5
1.0 2.0 3.0
2.0 3.0 5.0
2.5 3.5 5.5
4.0 4.0 4.0
8.0 2.0 1.0

where the first line states that the number of parameters is 3 (the line must begin with the four letters, “npar”, followed by white-space before an integer). The second line lists the parameter names in order and separated by white-space. Here, the names happen to be “sf”, “tf” and “size”. The third line states the number of stimuli, which is 5 here (the line must begin with the five letters, “nstim” followed by white-space before an integer). The remaining lines, one for each stimulus specified by “nstim”, must contain the values of the parameters in order (set by the second line of the file) and separated by white-space.

Using an in-line table to specify linked values

Rather than using a separate file, as with the VARFILE parameter above, the contents of the VARFILE can be included at the very end of the .stm file, following this line:

INLINE VAR_TABLE
npar 3
sf tf size
nstim 5
1.0 2.0 3.0
2.0 3.0 5.0
2.5 3.5 5.5
4.0 4.0 4.0
8.0 2.0 1.0

See comments for VARFILE above.

Generating random values

To create many random values for a parameter without typing out a long list of values, use “VARGEN_” to allow the computer to generate the values, as follows:

#            type   dec  n  mult add  seed
VARGEN_seed uniform  0  20 10000   1  1777

This specifies 20 stimuli with randomly chosen values for “seed”, each value having 0 places after the decimal point and being chosen from a uniform distribution between 1 and 10000, inclusive. The random sequence is determined by the seed value 1777. In this example, the line beginning with # is a comment and is ignored.

Generating pairs of generated values

For stimuli that require two sequences of random numbers, it can be convenient to generate two lists of random seeds that are linked together, rather than having to type these values out using VARLINK.

To create a linked pair of computer-generated values, use “VARGENPAIR_”, as follows:

#          PAR1 PAR2    N    TYPE      SEED
VARGENPAIR_seed seed_r 20 unif_100000  1777

This specifies 20 pairs of values that are chosen from a uniform distribution in [0,100000). The variable names are seed and seed_r, and the value 1777 is used as a seed to generate the random sequence.

There is a special form of this command to generate m-sequence tap register values for two random sequences, as follows:

#          PAR1    PAR2   N         TYPE          START INDEX
VARGENPAIR_seed1  seed2  25  list_opp_mseq_tap_11      0

This command generates 25 pairs of values for seed1 and seed2, using a predefined (within WM, having length N) list of m-sequence tap register values for order 11 sequences. The “0” value for “START INDEX” determines which index within the list to use when choosing the first value for seed1. Values for seed2 are chosen to be N/2 indices further along in the list. Index values are advanced sequentially, and wrap around when they exceed the length of the list.

One-off stimulus

To add a single extra stimulus (often used as a baseline control) to a set of stimuli generated with variable parameters, 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.

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 - “unif_100000”, “list_opp_mseq_tap_11”, ...
      • unif_100000 [seed] - where [seed] specifies a random seed to generate the list of values. Generate pairs of random values distributed uniformly in 0 to 99,999.
      • list_opp_mseq_tap_11 [i] - where [i] specifies an initial index into an internal list. Pick values from WM’s internal order-11 m-sequence tap register list, starting with index ‘i’ (i = 0,...,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
  • VARFILE [filename]
    • filename - the name of the file with a list of parameter values
  • INLINE VAR_TABLE
    • This line is then followed by the data, which must be the last thing in the file.

Linking to model variation

To allow a stimulus parameter to affect the computation of the model, beyond the direct effect that it has on the stimulus image data, one can design the model code to read stimulus values. This is not recommended, but it can be useful. One example of this is the me_v5 model type, which makes use of a dummy stimulus parameter that allows the user to specify the stimulus contrast. The dummy parameter is then VARLINK’d to other stimulus parameters.