Variables and expressions allow you to customize an experiment or to dynamically control how the stimuli appear during your experiment. We recommend assigning descriptive names to the variables as they may be used in the legends, graph labels, or column headers in the Plotter Panel. Note that variables in upper case ALWAYS refer to system variables and that variable names should only contain alphabetic characters (ie with no numerals, punctuation marks, symbols or space).
IMPORTANT: Variable names may sometimes appear between brackets. The rule about brackets is to use them only when the variable specifies a value (e.g., when specifying a stimulus parameter, or inside expressions), and to not use them when indicating the variable name for control purpose (e.g., dependent variable in method and procedure properties).
Control Variables
Response Variables
Specifying Parameters with Variables
Defining Values with Expressions
Syntax of Mathematical Expressions
System-Defined Constants & Variables
Control variables are typically used to customize a session for each subject or to simplify the parameterization of the experiment. They should be the independent variables of your experimental design. Control variables are declared either under the "Control Settings" tab of the "Experiment" events or the "Conditions" tab of "Method" events when creating experimental conditions.
Declaring independent variables in "Control Settings"
A table is available under "Control Settings" to declare independent variables:
An unlimited number of variables can be entered in the table, along with their values and locking status:
Each variable can either specify:
-
a single numerical value (e.g. as in the above example with the 'coherence' and 'contrast' variables):
' number '
- values
from which the variable is randomly assigned, that can take several forms:
- a set of numerical values separated by a comma (e.g. the 'direction' variable taking the value -1 or 1):
' val1, val2 , ..., valn '
-
a continuous range with minimum and maximum separated by a colon (e.g. the 'sf' variable taking any real value between 1. and 6.):
' minimum value : maximum value '
-
a discrete range defined by a minimum value, the number of samples, and a maximum value separated by colons (e.g. the 'x' variable taking one of the 6 uniformly sampled values between -10 and 10 inclusive in increments of 4):
' minimum value : step : maximum value '
' (probability) val1, val2, ..., valn '
' (probability) minimum value : maximum value '
' (probability) minimum value : step : maximum value' - a set of numerical values separated by a comma (e.g. the 'direction' variable taking the value -1 or 1):
Note that random variables take new values each time they are used. Hence one should not assume identical values when the same random variable specifies several parameters of the same stimulus (see Defining Values with Expressions below and the use of the $ prefix to access the last variable value without generating a new one).
The locking status indicates whether the variable values can also be specified as subject-specific values at each start of an experiment session. In the example above, only the unlocked variables 'coherence' and 'contrast' can be modified in the "Session Information" panel when running the experiment:
The subject-specific values are shown in the “Subject-Specific Parameters” table where they can be edited, and are used instead of the default values specified in the “Independent Variables” table under the "Control Settings" tab of the Experiment Properties panel.
Declaring independent variables in "Conditions" method events
Control variables can also be specified when creating "Condition" events (see "Conditions" tab of "Method" event). Several variables can be defined along with multiples values to specify each experimental condition as illustrated below:
In the example above, two variables are defined for the condition named "Condition 1" selected in the "Conditions" table: 'size' and 'sf'. The selected variable in the "Variables" table, 'size', can take any of the specified values in the "Values" table ('2', '4' or '8'). Note that these variables values have to be specified with scalars (ie: expressions are not supported yet).
It is important to note as well that independent variables should be declared only once in your experiment design: an error will be emitted at run-time if the same variable is declared both in the "Control Settings" of the "Experiment" events and inside a "Condition" event.
Methods and procedures typically modify the stimuli properties based on the subject's responses and the stimuli intervals. Response variables should be the dependent variables of your experimental design. In each panel where the selection of a response variable is required, a selection box similar to the one shown below appears:
Once a dependent variable is declared, it can then be used to specify some stimulus properties. Failing to correctly specify the response variables and their instances in stimuli parameters (see Specifying Parameters with Variables below) will result in incorrect or undefined control of the stimuli parameters. However, warnings displayed in the "Experiment log" are likely to provide clues about the abnormal behavior of the experiment. Consequently, it is crucial to verify that no warning or error has been logged after the experiment is terminated (remember that pressing the ESC key on the primary keyboard will abort the experiment). For example if the same variable is declared as both a control and response variable, an error will be emitted at run-time.
Specifying Parameters with Variables
Once a variable has been declared either as a control or response variable, it should be used to specify the value taken by a parameter in the different events. Most event parameters can be edited through a text field. To specify a parameter value with a variable, simply replace the numerical value in its text field with the variable name in brackets (ie: [variable]). The variable name can also be chosen by control-clicking on the parameter text field and selecting the variable from the contextual menu (both user-defined variables and system variables are available). The text field is then automatically filled in with the variable in brackets as illustrated below:
Note that for randomly-defined variables (see "Control Variables" above), the reference to its value through the [variable] format will trigger the generation of a new random value at run-time. This can be a problem when using the same random variable to specify different properties of the same stimulus or keeping some properties synchronized across different stimuli, because one would expect the same value to be used. To prevent this problem, one can use the format [$variable] (note the $ symbol before the variable name) to indicate to use the last generated value rather than generating a new random value. In other words to ensure a correct behavior, the first reference to a random variable for a given trial should be done through the format [variable] and all subsequent references to this variable should be done through the format [$variable].
For stimuli event, the variable format can also take optionally the form [variable:defaultvalue] where defaultvalue is the value used by default to generate the stimulus preview. If not specified, the parameter value is 0 by default. Note that if an appropriate default value is not provided, the stimulus preview may either lead to an unexpected result or a warning sign due to a computation error (eg: a division by zero). So it is highly recommend to always provide explicit default values for your stimulus parameters to check the validity of your stimuli during your experimental design.
In addition to single numerical values and variables, parameter values can be specified with complex mathematical expressions as described in the next section using the "Math Editor" (also available from the contextual menu).
Tip to remember: control-click on any parameter text field to access the list of available variables or the math editor from the contextual menu.
Defining Values with Expressions
Psykinematix allows most of the stimuli parameters to be defined as mathematical expressions of arbitrary complexity. These expressions may depend on dependent or independent variables of the experimental design, be a function of time to create dynamic stimuli, or even be randomly selected from a specified range. The creation of Custom Stimuli relies entirely on the evaluation of a sequence of such mathematical expressions with the specificity that they make use of built-in 2D variables (x, y, r, theta). These computing capabilities makes Psykinematix a powerful and very versatile stimulus generator.
Expressions are used to specify the numerical values taken by most stimuli parameters as well as the decision evaluations in procedures. Valid formats for expressions are:
-
a single numerical value (scalar):
' number '
- a variable name between brackets [ ]:
' [variable] ', '[variable:defaultvalue]', '[$variable]' or '[$variable:defaultvalue]' - a single mathematical formula (see syntax and available functions below). This formula can include variables with the above formats.
-
an expression between curly braces { } to specify properties for individual elements in multi-element stimuli (RDK, MEF and SSS):
{ expression }When the expression is surrounded with the { } symbols, the expression is evaluated independently for each element that composes the multi-element stimulus. This capability is only available to the speed and direction parameters in RDK stimuli, the element rotation in MEF and SSS, and the distribution coordinates in SSS. The expression between { } can also refer to the position of each element using the x and y Cartesian coordinates, the r and theta polar coordinates relative to the center of their embedding zone, or the special variables k and i that refer to the local curvature and index of each element respectively:
{i}, {x}, {y}, {r}, {theta} or {k} - a complex expression made of mathematical formulas separated
by semicolons: local variables can be assigned and the expression value
results from the evaluation of the last formula without assignment as illustrated
in the example below.
Note that by selecting the "Editor" command in the contextual menu opened by control-clicking on a parameter text field, the expression is presented inside a rudimentary Math palette where it can be more easily edited (semicolons are converted to new lines for better legibility). The expression background turns to red when it is syntactically incorrect, and the changes made in the palette are only reflected in the parameter text field when its syntax is correct. Predefined formulas can be selected using the pop-up menu and appended to the edited expression (time-varying expressions can be also graphed inside this Math palette, see below).
Stimuli parameters can be set as time-varying. Several formats are available for specifying time-varying expressions:
- implicitly as a function of time, with three possible forms using the colon separator to express the samples range and with the dynamic factor between parentheses:
min : max(speed)
min : nbsamples : max(duration)
sample :: (duration)
where min and max define the starting and ending values of the parameters, speed is the rate of change (represented in units per second), nbsamples defines the number of samples between the starting and ending values (inclusive), and duration defines the duration of each sample in seconds. In the third form, sample denotes the expression to be evaluated every duration period (Tip: this form is particularly useful for generating temporal sequence of random values).
-
explicitly through a time-varying mathematical expression by using the system-defined variable [TIME] that specifies the time relative to the stimulus onset. If necessary, the duration of the currently-edited stimulus can be accessed through the system-defined variable [DURATION].
Note that a time-varying expression edited in the Math palette is automatically plotted in the graphing window below it (to access the palette control-click on the parameter text field and select the "Editor" command in the contextual menu). Each time sample corresponds to a video frame at the frame rate specified for the current experiment (see "Display Settings" tab of the Experiment Properties panel). As illustrated below, there are already some predefined time-varying formulas available though the pop-up menu that can be appended to the edited expression. The plot can be printed, copied to the pasteboard or save to a file by control-clicking onto the graph.
Syntax of Mathematical Expressions
A single mathematical expression should follow the <expression> syntax which can have any of the following forms (parentheses can be used to specify the order of operations):
<expression> :=
<numerical value>
<constant>
<variable>
<function>(<expression 1>, ... , <expression n>)
<expression 1> <operator> <expression 2>
where <variable> is either:
[<name>] any user- or system-defined variable (note that system-defined variables are always in uppercase)
<parameter> a parameter name defined in the Parameter Table for Custom Stimuli
<reserved> a reserved 2D array coordinate only available for Custom Stimuli (x, y, r, theta)
<constant> is any of the predefined scalar constants:
e 2.71828182845904523536 Euler's constant
pi 3.14159265358979323846 Archimedes' constantirand Random integer number (can be used as the seed parameter in the unoise function, see below)
rnd Random real number in [0,1] range
<operator> is any of the following elementary operators:
Arithmetic operators
+ addition
- subtraction
* multiplication
/ division
% modulo
^ exponent (faster than the power function pow below)
Comparison operators
> "larger than"
< "smaller than"
≥ "larger than or equal to" (option+. keystroke)
≤ "smaller than or equal to" (option+, keystroke)
≈ "equal to" (option+x keystroke)
≠ "different from" (option+= keystroke)
Logical operators
& "and"
| "or"
Operators grouped by precedence (evaluation priority can be changed using parentheses)
Unary operators: +, - , !
Power: ^
Multiple, divide, modulo: *, /, %
Add, subtract: +, -
Comparisons: >, ≥, <, ≤
Comparisons: ≈, ≠
Logical and: &
Logical or: |
<function> is any of the following built-in functions:
Trigonometric functions:
sin(x) sine (x given in radians)
cos(x) cosine (x given in radians)
tan(x) tangent (x given in radians)
asin(x) arcsine ⇒ [-π/2, π/2]
acos(x) arccosine ⇒ [0, π]
atan(x) arctangent ⇒ [-π/2, π/2]
atan2(y,x) arctangent of y/x ⇒ [-π,π]
sinh(x) hyperbolic sine
cosh(x) hyperbolic cosine
tanh(x) hyperbolic tangent
asinh(x) inverse hyperbolic sine
acosh(x) inverse hyperbolic cosine
atanh(x) inverse hyperbolic tangent
dist(x,y) Euclidean distance: sqrt(x^2+y^2)
deg(x) convert from radian to degree units
rad(x) convert from degree to radian units
degtopix(x) convert from degree to pixel units
pixtodeg(x) convert from pixels to degree units
Monotonic functions:
exp(x) exponential
log(x) natural logarithm
log10(x) base 10 logarithm
sqrt(x) square root
pow(x,y) power
Non-continuous functions:
floor(x) floor
ceil(x) ceiling
round(x) nearest int
Non-differentiable functions:
abs(x) absolute value
sign(x) sign (-1 if x<0,1 if x≥0)
rect(x) rectification (x if x>0, 0 if x≤0)
cmin(x,m) minimum clamping (x if x>m, m if x≤m)
cmax(x,m) maximum clamping (x if x<m, m if x≥m)
cminmax(x,min,max) clamping in the range [min,max] (x if min<x<max, min if x≤min, max if x≥max)
Special functions:
randg(m,s) generate a random number from Gaussian distribution with mean m and standard deviation s
randseries(a,b,c,d) generates a binary time series based on some uniform distribution of its ON and OFF segments where a is the minimum number of consecutive ON bits, b is the random number of additional ON bits (set it to 0 to specify a fixed number of consecutive ON bits, that is a), c is the minimum number of consecutive OFF bits, d is the random number of additional OFF bits (set it to 0 to specify a fixed number of consecutive OFF bits, that is c). To create a time-varying expression based on such a stochastic sequence it is important to include the system-defined [TIME] variable even if it does not appear to be necessary (for example by simply adding '+[TIME]*0' to the expression). Note that this function cannot be directly used inside the expression box of Custom Stimuli, but can specify the values of any stimulus parameter in a text field (eg: Contrast).
2D functions only available for Custom Stimuli:Matrix operations:
conv(x,y) Convolution of x and y (done in Fourier space)
ifft(m,p) Inverse Fourier transform for magnitude array m and phase array p
norm(x,m,u) Normalization of x so its mean is m and its maximum value is u
clip(x,a,b) Clip x with minimum value a and maximum value b
shift(x,u,v) Shift array x by u spatial units horizontally, and v spatial units vertically with wrapping and subpixel resolution through bilinear interpolation
dshiftp(x,d) Shift array x horizontally by array d on a pixel by pixel basis with subpixel resolution (positive shift only!)
Matrix to Scalar operations:
min(x) Minimum value in matrix x
max(x) Maximum value in matrix x
sum(x) Sum value of matrix x
mean(x) Mean value of matrix x
std(x) Standard deviation 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 are applied on a pixel basis when at least one of the operands consists of a 2D array as it is the case for Custom Stimuli. The evaluation of the expressions is also highly optimized, typically several times faster than its Matlab® equivalent.
System-Defined Constants & Variables
Psykinematix uses special built-in constants and variables to keep track of particular values. All system-defined constants and variables are in uppercase to differentiate them from user-defined variables.
System-defined constants
System-defined constants are those values that do not change inside an experimental session and that depend on the experimental setup. Here is a list of these constants:
[NYQ]: Nyquist frequency of the display in cycle per degree (cpd) (see Display Preferences and Experiments sections). This could be used to set a maximum limit to the spatial frequency of visual stimuli.
[FRATE]: Frame rate of the display in Hz (see Display Preferences and Experiments sections). This could be used to set a maximum limit to the temporal frequency of visual stimuli (eg, [FRATE]/2 ).
[WFOV]: Width of the display field of view in deg (see Display Preferences and Experiments sections). This could be used to set a maximum limit to the horizontal eccentricity of visual stimuli (eg, [WFOV]/2 ).
[HFOV]: Height of the display field of view in deg (see Display Preferences and Experiments sections). This could be used to set a maximum limit to the vertical eccentricity of visual stimuli (eg, [HFOV]/2 ).
[XFIXPOS]: x coordinate of the fixation mark relative to the display center expressed in deg (see Experiments section). This could be used to specify the stimulus position relative to the fixation mark.
[YFIXPOS]: y coordinate of the fixation mark relative to the display center expressed in deg (see Experiments section). This could be used to specify the stimulus position relative to the fixation mark.
System-defined dependent variables
System-defined dependent variables are read-only variables whose values change inside an experimental session and that depend on some properties of the experimental events currently run or edited. Here is a list of these read-only variables:
[DURATION]: duration of the currently edited stimulus. This should be used when defining stimuli parameters as expressions of functions of time (see Expressions section above).
[FIXCHANGED]: binary value that indicates that a fixation change has occurred in the current trial when 2 stimulus fixations are specified in the Experiment Control Settings. This can be used to introduce a fixation task (change detection) to control for attention in experiments where a succession of stimuli are presented: [FIXCHANGED] should be used as the stimulus correlated expression in a Yes/No Procedure (the writable system-defined variables FIXDURATION and FIXPROB specify the fixation duration and probability, see below).
[NFC]: index of the current target interval or position in a n-Forced Choice procedure. This could be used to report the procedure target position to an external device for example.
[NFCINDEX]: index for each stimulus instance in a n-Forced Choice procedure. This could be used to customize the appearance of each instance.
[SELECTION]: value of the currently selected stimulus when the stimulus is chosen from amongst a list (such as for multimedia stimuli through the 'Random selection' presentation mode). For example, it could be used when sending trigger information to an external device (see Trigger section).
[TIME]: relative time to stimulus onset. This should be used when defining stimuli parameters as expressions of functions of time (see Expressions section above).
[TRIAL]: index of the current trial. This could be used when presenting stimuli that need to be customized for each trial, for example when performing a retinotopic mapping with expanding rings and rotating wedges with each trial triggered by an external device (eg, fMRI scanner).
[XMOUSEDEG], [YMOUSEDEG]: current mouse position in visual field coordinates (ie: deg relative to fixation).
[XMOUSEPIX], [YMOUSEPIX]: current mouse position in screen coordinates (ie: pixels).
System-defined independent variables
System-defined independent variables are writable variables whose values can be specified in the independent variable table of the Experiment Control Settings. These variables allow the customization of some experimental aspects that do not have a counterpart in the graphical user interface. Here is a list of these writable variables:
[FIXDURATION], [FIXPROB]: fixation duration in seconds, fixation probability (in [0-1] range) when specifying 2 stimulus fixations in the Experiment Control Settings. These variables can be used to introduce a fixation task (change detection) to control for attention in experiments where a succession of stimuli are presented. The read-only system-defined variable [FIXCHANGED] should then be used as the stimulus correlated expression in a Yes/No Procedure (see above).
[TAPERIOD]: period of the trial alarm timer in seconds. The "Trial Alarm" feature is only available for some button boxes with an internal timer (see the "Supported External Devices" chapter).