Visual stimuli are the most basic aspect of the experimental protocol, and often the most critical one as the choice of stimuli and of their parameters may define and limit the scope of your experiments. Psykinematix provides convenient tools to specify their spatial, temporal, and chromatic properties. Most stimuli properties can be specified with values, variables, or mathematical expressions.

Psykinematix offers the possibility of creating a large variety of basic visual stimuli:

Shape Stimuli
Grating Stimuli
Checkerboard Stimuli
Custom Stimuli

To create a Visual Stimulus, create a new single event in the "Experiment Designer" window, set its kind to "Visual Stimulus", and display its properties by clicking on the "Info" icon (or press Apple-I). Once a stimulus has been selected, changing it by clicking on other tabs is disabled unless the Control key is pressed simultaneously. This is to prevent accidental changes because stimulus settings are then reset to default.

The specification panel for each stimulus category is divided into 4 parts:

  • Common properties (top part of the panel) which consist of the:

    • position of the stimulus center in degrees that can be specified in terms of Cartesian (x,y) or polar (r,theta) coordinates relative to the display center. For 2D rendering (single display) the x coordinate consists in a single expression. For Stereo or Anaglyph rendering (see Rendering Modes in Defaults Preferences), the x coordinate can take the following forms to specify whether it applies to the left or right display, to both displays or whether it also specifies a disparity value (always expressed in arcmin, positive for cross-disparity or 'in front' presentation, negative for uncrossed disparity or 'behind' presentation):

      • <expression>                             x coordinate to apply to both left and right displays
                                                        (binocular presentation on horopter or at zero disparity);
      • D = <disparity>                          the disparity to apply (with x = 0 by default);
      • <expression>; D = <disparity>    x coordinate along the disparity it is applied on;
      • L = <expression>                       x coordinate to apply to the left display only
                                                        (for monocular or dichoptic presentation);
      • R = <expression>                      x coordinate to apply to the right display only
                                                        (for monocular or dichoptic presentation).

    • stimulus duration in seconds.

    • chromatic appearance of the stimulus in terms of color space (achromatic, RGB, LMS, etc.), tri-stimulus values, modulation type (contrast or luminance), and modulation strength (in %). Note that some color spaces can only specify luminance or contrast. By setting the modulation type to dark or light contrast/luminance, it is possible to specify two chromatic directions for the dark/negative and light/positive parts of the stimulus, respectively. Note that contrast refers to Michelson contrast (defined as [maxlum-minlum]/[maxlum+minlum] or Δlum/meanlum).

  • Custom properties (central part of the panel) that customize the shape or type of stimuli.

  • Parameters (bottom-left quadrant of the panel) common to all shapes or types of stimulus category.

  • A preview (bottom-right quadrant of the panel) which is automatically updated with changes in parameter values. The preview can be zoomed in and out using the slider on its left. By control-clicking inside the preview, you can either copy the preview image, save it as an image file in TIFF format, save it as a movie, or preview it through the OpenGL rendering engine used during an actual experimental session. For custom stimuli the preview can display the stimulus either in the spatial or Fourier domain.

                

Shape Stimuli

Shape stimuli consist of simple shapes based on regular polygons characterized by their number of sides: triangle, square, pentagon, hexagon, etc. Approximated circles are formed using a very large number of sides.

These shapes can be filled or delineated by either plain lines, stippled lines or points. The available thickness for the lines and points depends on the graphics board. Pattern and scale are only used by stippled lines. The chromaticity, luminance or contrast of the filling or of the border can be specified; however, for the contrast the color appearance depends on its sign.

Note that for the points to appear as circles, the blending mode in the rendering settings has to be set to Transparent (Src: GL_SRC_ALPHA, Dst: GL_ONE_MINUS_SRC_ALPHA). This blending mode also provides antialiasing for the line mode.

The geometry of these shapes can be transformed by varying their size (through the radius between the center of the shape and its vertices), orientation, and aspect-ratio along the x-axis.

Grating Stimuli

Grating stimuli consist of a carrier pattern modulated by an optional envelope. They can be either contrast-defined or luminance-defined.

Carrier:

Several carrier types are available. The carrier type is selected through a pop-up menu:

Grating, Radial, Angular carrier types only differ by the spatial dimension along which their luminance profile is modulated (x-axis, radius-axis, angular-axis). This luminance profile follows a square-wave or a sinusoidal modulation at a given spatial frequency, a phase, and an orientation (orientation is only valid for the Grating type).

  

Noise carriers can either be 1D or 2D with a binary, uniform, or Gaussian distribution (based on contrast range) and a white or pink (1/f) spectral distribution in the Fourier domain.

  

Envelope:

The role of the envelope is to limit the visibility of the carrier. Its size, shape, orientation, and aspect-ratio can be customized to fit your needs:

Examples of envelopes with grating carriers

Stimulus generated by applying a hard-edge rotated square envelope with an aspect-ratio higher than 1 to produce its rectangular shape.

Stimulus generated by applying a hard-edge rotated circular envelope with an aspect-ratio higher than 1 to produce its elliptic shape.

Stimulus generated by applying a Gaussian rotated circular envelope with an aspect-ratio higher than 1 to produce its elliptic shape.

Stimulus generated by applying a rotated circular envelope with an aspect-ratio higher than 1 to produce its elliptic shape. Note that a Gaussian modulation has been applied to the border of the envelope (ie: both size and sigma parameters have been set to a value different from 0).

Checkerboard Stimuli

Checkerboard stimuli consist of Cartesian or polar 2D patterns with alternating and repetitive light and dark patches. They can be either contrast-defined or luminance-defined.

Cartesian type:

  

The number of rows and columns as well as the size for each of these in degree are specified here. Note that position is not used for the Cartesian type.

Polar type:

  

The number of rings and wedges as well as the size for each of these in degree are specified here. Position is used to shift the pattern along the radial direction (thus creating an annulus) and the angular direction (thus applying a rotation to the pattern).

Parameters:

The parameters for checkerboard stimuli are:

  • the phase in deg along each stimulus dimension: (x,y) for Cartesian, (r, theta) for polar

  • the shift in one direction as a function of the other direction: the continuous or discrete nature of this shift is set through the associated pop-up menu (C-C for continuous shift along both dimensions; C-D for continuous along the r,x axes and discrete along the y,theta axes; D-C for discrete along the r,x axes and continuous along the y,theta axes; D-D for discrete shift along both dimensions)

  • the modulation profile (square-wave or sinusoidal)

Examples:










Custom Stimuli

Custom stimuli are computed from the evaluation of a sequence of mathematical expressions. Virtually any stimuli that can be described analytically in 2D, either by Cartesian or polar coordinates, can be generated using Psykinematix. They can be either contrast-defined or luminance-defined.

Expression Box:

The analytical description of your custom stimuli should be entered and edited in the expression box. Reserved keywords (built-in constants, functions, and variables) are always displayed in blue while comments (starting with the # symbol) are in green. When the expressions contain a syntax error, the text background switches to red to indicate the problem, and automatically changes back to white once the problem is fixed. Unknown variables or functions are highlighted in red as well. When the expression cannot be evaluated because of evaluation errors (eg, "divide by zero"), the preview is replaced by a warning sign and a message is displayed above the expression with the source of the error:

Syntax:

Single line or multi-line assignment expressions can be used to describe how the stimulus is computed. Assignments on the same line should be separated by a semicolon and may be followed by a comment. Each assignment operation should follow the syntax:

<variable> = <expression>

with the last assignment being:

z = <expression>   or/and   za = <expression>

where:

  • <expression> is a mathematical expression described in the Mathematical Expressions section,

  • <variable> is a intermediary user-defined variable (ie other than a function name, reserved variables or constants),

  • z is a 2D array representing the contrast or luminance of the resulting stimulus, and za is a 2D array representing the alpha layer of the resulting stimulus. In other words, z defines the appearance of the opaque part of the stimulus, while za defines the opacity per se (ie opposite of transparency). The combination of z and za forms the final output of the expression evaluation for the custom stimuli.

    Important note: while the stimulus preview shows the product z . za to account for the specification of za, the actual stimulus may not appear identical as the effect of the za component on the stimulus appearance depends on the selected blending mode (see the rendering section of the "More Control" chapter). For example, when using the za component to create a spatial aperture, make sure to select the 'Transparent' blending mode so the za component filters out the parts of the background that needs to be replaced with the z component (see the spatial aperture section of the "Tips" chapter).

There are reserved variables that are unique to the expression box for custom stimuli. These predefined variables are 2D arrays describing coordinates for each pixel of the stimulus:

x , y        Cartesian coordinates
r , theta   polar coordinates

Note that all variables used as operands in the expression box should be either a temporary user-defined variable, one of the above reserved variables, or one of the parameters defined in the Parameter Table (see below). Dependent and independent variables of experimental design should never be directly used in the expression box, however they could be used to specify the values of the parameters defined in the Parameter Table.

There are also reserved operations that are unique to the expression box for custom stimuli. These functions only applies on 2D arrays:

Matrix operations:

shift(x,u,v)     Shift array x by u spatial units horizontally, and v spatial units vertically with wrapping
conv(x,y)       Convolution of x and y (done in Fourier space)
norm(x,m,u)   Normalization of x so its mean is m and its maximum value is u
ifft(m,p)         Inverse Fourier transform for magnitude array m and phase array p

Matrix to Scalar operations:

min(x)           Minimum value in matrix x
max(x)          Maximum value in matrix x
mean(x)        Mean value of matrix x
sum(x)          Sum value of matrix x

Special functions:

unoise(x,s,g)         2D uniform noise between -1 and 1 with seed s, granularity g, and the same size as x
gnoise(x,m,u,s,g)  2D Gaussian noise with mean m, std u, seed s, granularity g, and the same size as x
bessj0(x)              2D Bessel function of order 0

Note that all operations and functions used in the expression box are applied on a pixel basis when at least one of the operands consists of a 2D array. If the evaluation of the right part of an assignment results in a 2D array, the assigned temporary variable is internally represented as a 2D array as well; otherwise, it is simply represented as a scalar.

Although the evaluation of the expressions is highly optimized, typically several times faster than its Matlab® equivalent, here are few tips to further improve the evaluation performance for complex expressions:

  • The use of temporary variables is particularly helpful when the same sub-expression is reused several times in the evaluation.

  • However, do not overuse temporary variables as they may take a significant amount of memory if representing 2D arrays.

  • Instead use the built-in grating or checkerboard-based stimuli if appropriate as their generation is even more optimized in terms of speed and memory footage.

Parameter Table:

Parameters in this table are locally defined (ie: not available from outside the generation of the custom stimulus), and are used to specify some basic aspects of the custom stimulus. Their values are either fixed or under the control of an experimental method (dependent variables), subject specific variables, or independent variables. In addition to the parameters' names and values, their unit type should also be specified so their values get properly converted (eg: to pixel units if they represent spatial dimensions of the stimulus, or from degree units to radian units if they represent angular dimensions, see the table below for more details). Note that only these locally defined parameters can appear as operands in the expressions box.

Angle (deg): This unit expresses an orientation angle in degrees. It should be used in particular when manipulating the polar coordinate theta. The value is automatically converted to radians before use.
Angle (rad): This unit expresses an orientation angle in radians. It should be used in particular when manipulating the polar coordinate theta.
Integer: This unit expresses an integer value either negative or positive. If the provided value is real, then it is converted to an integer by discarding the fractional part (ie: the value is truncated toward zero).
Spatial: This unit expresses distance or angle of the visual field in degrees. It should be used in particular when manipulating the polar coordinate r or Cartesian coordinates x and y. The value is automatically converted to pixels for rendering purpose by using the geometry calibration data.
1/Spatial: This unit expresses the reciprocal of the distance or angle of the visual field in cycles per degree. It should be used in particular when manipulating the polar coordinate r or Cartesian coordinates x and y to express spatial frequency. The value is automatically converted to cycles per pixel for rendering purpose by using the geometry calibration data.
Unitless: This unit expresses any amount that does not require any conversion and that is not affected by the geometry calibration data.
Fourier: This unit expresses spatial frequency in cycles per degree when expressing visual stimuli in the Fourier domain and using the ifft function (inverse Fourier transform). Note that parameters with the Fourier unit should not be used to specify the size parameter (see below).

A parameter 'size' is present by default in the Parameter Table. This parameter specifies the spatial extent in degree of visual angle for the square texture representation of the stimulus in the video memory. This allows the stimulus generation to be restricted to the useful area covered by the stimulus rather than over the whole display. The value for the 'size' parameter can itself be an expression (without the = assignment) based on the other parameters. For example, if an annulus stimulus is parameterized with 'radius' and 'sigma' parameters, a size of '2*(radius+2*sigma)' for the generated texture will closely match the useful area covered by the stimulus. The boundaries of the area delimited by the 'size' parameter are represented by a black frame around the stimulus preview (zoom out if the surrounding frame does not show up).

Note that the evaluation of the other parameters should not depend on any parameters present in the table; otherwise, their evaluation results may be undefined. On the contrary, the evaluation of 'size' should depend on the parameters present in the table only (with the exception of the parameters in Fourier unit) and not on the experiment variables.

Examples:

z = cos(x/5)

z = cos(x/5)*sin(y/5)

z = cos(x/5+sin(y/10))

z = sin(r/5)

z = cos(theta*10)

z = sin(r/5)*cos(theta*10)

z = cos(r+theta)

z = cos(r+theta*10)

z = cos(r/5+theta*10)

z = cos(x/5)+cos(r)

z = sin(1000/(r+20))

z = sin(exp(r/20))*cos(theta*10)

z = e^(-(r^2)/1000)

z = cos(x/5)*e^(-(r^2)/1000)

z = unoise(x,irand,8)

Matlab is a registered trademark of The MathWorks, Inc.