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.


.. _stimvarsing:

**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.

.. _stimvarmult:

**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*.


.. _stimvarlink:

**Varying multiple parameters together**

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).


.. _stimvarfile:

**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.

.. _stimvarinline:

**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.

.. _stimvarrand:

**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.


.. _stimvargenpair:

**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.

.. _stimvarsingle:

**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.


.. _stimvardef:

**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.

.. _stimvarmod:

**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.