PXLab Manual

[Home]    [Content]    [Previous Chapter]    [Next Chapter]


Parameter Values and Expressions

The PXLab programs are controlled by a large set of experimental parameters. A subset of these are global in the sense that they are available in every experiment and exist independent of Display objects. Non-global experimental parameters are parameters of Display objects. Every experimental parameter has a default value which is defined in the PXLab code. New values may be assigned to experimental parameters by assignment statements. If the experimental parameter is a global parameter, then the respective assignment must be contained in an AssignmentGroup() node of the design file. A global parameter is a parameter which is not a parameter of a subclass of class Display. Most global parameters are defined in class ExPar. Currently the only additional classes which define global parameters are the classes PrimaryScreen and SecondaryScreen which define experimental parameters for a primary and a secondary display screen. Global experimental prameters which are not defined in class ExPar are currently not allowed in expressions.

There may be multiple AssignmentGroup() nodes, but all of them must be contained in the Context()-section of the design file. If an assigment refers to an experimental parameter of a Display object, then it must be contained in the Display object's declaration.

Experimental parameter values appear at two places in a design file:

Here is an example for the first case where experimental parameters of a Display object are set:

    Message() {
      FontSize = 40;
      Timer = de.pxlab.pxl.TimerCodes.RESPONSE_TIMER;
      ResponseSet = [de.pxlab.pxl.KeyCodes.LEFT_KEY, de.pxlab.pxl.KeyCodes.RIGHT_KEY];
    }

The first assignment sets the parameter Message.FontSize to the literal value '40'. The second assignment contains a symbolic class constant as a parameter value and the third assignment assigns an array value to an experimental parameter.

Here is an example for parameter values in argument lists:

    Procedure() {
      Session() {
        Block() {
          Trial("House", ?, ?);
          Trial("Garden", ?, ?);
          ...
        }
      }
    }

In this case the first argument of a Trial is a string valued parameter and the second and third argument are undefined.

Value Types

Experimental parameter values may be

Literals

Literals are of type integer, float or string. Integer, float, and string literals in PXLab expressions are defined identical to their definition in the Java programming language with the exception, that PXLab's float literals correspond to Java's double type.

Class Constants

Whenever the grammar allows a literal value then it also allows a named constant from a Java class or interface. These constants must be declared as

 
    public static final int 

within a class or interface file and are retrieved at runtime by their full name. Thus we may use an assignment like

 
   Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER; 

to assign the value of the constant CLOCK_TIMER which is defined in interface de.pxlab.pxl.TimerCodes to parameter Timer. Only class constants from the packages de.pxlab, java, or javax are allowed. In general class constants must be written with their full access name. An exception are class constants which are defined in an interface of the package de.pxlab.pxl whose name ends in 'Codes'. These constants may be used with their constant name only. Thus the above assignment may also be written as

 
   Timer = CLOCK_TIMER; 

Names of Experimental Parameters

In most cases the values of parameters may contain the names of other parameters. Since parameters may also be created new this allows variables as parameter values. As an example we may define one Timer to get the value of another timer by

   Timer = Trial.FixationMark.Timer;

Variables may appear within any expression. The only exceptions are array and replicator values. These may only contain literal values and named constants. Parameter names as values must be full instance names. The form of a full instance name depends on where the respective parameter is defined. Global parameters defined in the class ExPar exist only once such that their full instance name is identical to their variable name. An example is SubjectCode which is a global parameter defined in class ExPar. Its full instance name is 'SubjectCode'.

Experimental parameters of Display objects have a three part full instance name. The first part is the name of the DisplayList instance which contains the respective Display object. The second part is the Display instance name and the third part is the parameter name. Suppose we have declared a DisplayList named 'Trial:Study' which contains a Display object instance named 'Message:Attention' and the Message object contains a Parameter named 'Text'. Then the full instance name of this parameter is

    Trial:Study.Message:Attention.Text

Here 'Trial' is the DisplayList class name, 'Trial:Study' is the DisplayList instance name, 'Message' is the Display class name and 'Message:Attention' is the Display object instance name, and 'Text' is the parameter name. If the respective DisplayList or Display objects were unique children of their parents in the declaration then their instance suffixes may be missing and the full instance name of the Text parameter were 'Trial.Message.Text'.

Unknown Parameter Values

Parameters whose values are unknown before runtime and which appear in Procedure()-section argument lists may be assigned the value "?":

      Trial("Garden", ?, ?);

Unknown parameter values must not be used uin assignments but are only used in argument lists of procedure units. The respective parameter inherits the value of the next higher procedure unit or has its default value.

Expressions

Expressions are numeric or string expressions generated from literals or identifiers combined with simple operations like addition, subtraction, multiplication, division or string concatenation. Expressions must evaluate to an integer, float, or string value. Here is an example where a new parameter is defined with an expression as its value:

      new Correct = 100 * (TrialCounter - ResponseErrorCount) / TrialCounter;

This definition assigns the declared expression to the new parameter 'Correct'. This means that whenever the value of the parameter 'Correct' is computed then the expression is evaluated. Thus the expression value is the result of its component parameters at evaluation time.

Expression Evaluation Time

In order to understand expression evaluation it is important to known when expressions are evaluated. The Context()-section of a design file is purely declarative. The order of display list declarations does not have any effect on the order of evaluations. The order of assignments in an assignment section does have an effect and also is the order of evaluations. In general, expressions are evaluated only when they are needed. Thus suppose the previously defined parameter 'Correct' is used in a stimulus object. This means that the value of 'Correct' is evaluated only when the stimulus object's properties are computed. This may be at the begin of a display list presentation or, if the respective display object has the JustInTime parameter set, immediately before the stimulus object is shown. Also note that the parameter value has to be evaluated every time when it is used, since the expression is never replaced by its value in the declaration. This also is a consequence of the fact that design files are declarative and do not contain procedural properties. A good example for the power of PXLab's expression system is contained in the demo file monty_hall.pxd.

Chapter 'Design File Grammar' contains a complete description of PXLab expressions and the file ExDesignTreeParser.html contains a Backus-Naur-Form of the syntax.

Simple Expressions

Simple PXLab expressions and parameters do actually not have types but simultaneously have an integer, float, and string representation. If a parameter is assigned an expression which evaluates to a number, then the parameter has this numeric value. If the string representation of this parameter's value is accessed, then it is a string representation of this number. Thus if a parameter has been assigned the value 3.14:

    m = 3.14;

then the float representation of m is 3.14, the integer representation is 3 and the string representation is "3.14".

If a parameter is assigned an expression which does not evaluate to a number then the parameter holds the respective string as its string representation and its integer and float representations are 0 and 0.0 respectively. Thus if a parameter has been assigned the value "a24":

    m = "a24";

then the float representation of m is 0.0, the integer representation is 0 and the string representation is "a24".

Expression operations include the usual arithmetic operators as applied to numbers. Here are some examples:

    LocationY = messageLocationY + 116;
    WorkingTime = (Trial:Multiply.ClearScreen.TimeControl - BlockTime) / 1000;
    CorrectCode = Trial:Multiply.RandomGenerator:A.ResponseCode * Trial:Multiply.RandomGenerator:B.ResponseCode;
    Timer = de.pxlab.pxl.TimerCodes.CLOCK_TIMER | de.pxlab.pxl.TimerCodes.START_RESPONSE_TIMER;

The division operator is always computed with floating point values. The integer result is the floating point result rounded to the nearest integer. Use the function idiv() if you need integer division. The operator '|' is not a logical operator but a binary 'or' operator which combines binary bit patterns.

Logical Expressions

PXLab allows the usual logical expression operators. A parameter value is considered 'true' if it is nonzero and is considered 'false' if it zero. Many experimental parameters are flags. This means that they expect binary values. An example is the parameter Execute which has been explained earlier. These flag parameters are 'true' if nonzero and 'false' if zero. Here are some examples of logical expressions:

      Execute = Trial:Test.Message:ON.ResponseCode == 0;
      Execute = !Trial.Message.Execute;

Conditional Expressions

A conditional expression is a value which depends on the state of an experimental parameter at runtime. The general format is

    m = p? x: y;

The experimental parameter m is assigned the value x if the experimental parameter p has a nonzero integer value and m is assigned the value y if p has integer value zero. Here is an example

  Text = AppletSystem? "Start the Applet": "Start the Application";

The experimental parameter AppletSystem has the integer value 1 if the current program is running as an applet. Thus the experimental parameter Text is assigned the value "Start the Applet" if parameter AppletSystem is nonzero. This is the case if the program is running as an applet. If the program is running as an application the parameter Text gets the value "Start the Application". Here is another example using multiple conditional expressions:

    selectionSet = (firstChoice == 0)? set12: ((firstChoice == 1)? set02: set01);

Array Expressions

An array expression is a list of literals or named constants enclosed in square brackets:

    [0.313, 0.329, 60.0] 

Array expressions may be used as parameter values but array expressions cannot be elements of expressions. Thus it is not allowed to use array expressions in arbitrary expressions. It is, however, allowed to use a variable in an arbitrary expression even if the variable has an array as its value. This must be used carefully since whenever the expression is evaluated, it must make sense to have an array valued variable involved. Here is an example where array valued variables are used meaningfully in an expression:

    new set01 = [0, 1];
    new set02 = [0, 2];
    new set12 = [1, 2];
    new selectionSet = (firstChoice == 0)? set12: ((firstChoice == 1)? set02: set01);

The variable selectionSet is assigned an array value here which depends on the current value of the parameter firstChoice. In this case the expression does not access the internal value of the variables set01, set02, and set12.

Replicator Expressions

A replicator expression is similar to an array expression but uses angle brackets instead:

    <3, 6, 9> 

Replicator expressions may be used at all those places where array expressions may be used. Replicator expressions are expanded during run time by replicating the data collection unit whose argument list contains the replicator such that multiple copies of the block are created. In the list of units created the parameter with a replicator expression as its original value gets all the different values of the literal list in the replicator as its successive value. Thus

    Trial("a", <3, 6, 9>);

is equivalent to writing

    Trial("a", 3);
    Trial("a", 6);
    Trial("a", 9);

A data collection unit argument list may contain multiple replicators which generates copies for every possible combination of parameter values in the replicators.

A full description of the PXLab expression syntax is contained in the PXLab design file grammar.

Functions

PXLab knows some functions which may be used in expressions.
Screen Position Functions
screenTop()
returns the screen top border y-coordinate.
screenRight()
returns the screen right border x-coordinate.
screenBottom()
returns the screen bottom border y-coordinate.
screenLeft()
returns the screen left border x-coordinate.
screenWidth()
returns the screen width in pixels.
screenHeight()
returns the screen height in pixels.
Color Related Functions

The PXLab color software internally works with XYZ-coordinates but its main color object class PxlColor always simultanously stores the xy-chromaticity values also. Whenever internal color coordinates are stored into an experimental parameter then PXLab stores the Yxy-coordinates and whenever an internal color value is set by an experimental parameter then it expects to get Yxy-coordinates. This means that the user will only have to deal with Yxy-coordinates.

All functions named from...() convert a color specification into the Yxy-coordinates. This means that an assignment like

  Color = fromCIELab([80, 20, 20]);
will set the experimental parameter Color to a double array which contains the Yxy-coordinates of the color given in the CIELab coordinates argument. Correspondingly all functions named to...() convert from Yxy-coordinates to the target coordinate system specifeid by the function's name.
colorAtLum(a, b)
returns a color value which has the chromaticity of argument a and has argument b as its luminance.
fromCIELab(a)
converts color coordinates from the CIELab 1976 system to the CIE 1931 system.
toCIELab(a)
converts color coordinates from the CIE 1931 system to the CIELab 1976 system.
fromCIELabLCh(a)
converts color coordinates from the CIELab 1976 LCh system to the CIE 1931 system.
toCIELabLCh(a)
converts color coordinates from the CIE 1931 system to the CIELab 1976 LCh system.

The CIELab conversion uses the currently defined white point as its reference. The current white point may be defined by the global parameter CIEWhitePoint. If this parameter is not defined then the current color device's white point is used as a reference for the conversion.

fromDevRGB(a)
converts an array of device RGB-values to Yxy color coordinates.
toDevRGB(a)
converts color coordinates to an array of device RGB-values.
toDevRGBHex(a)
converts color coordinates to an array of device RGB-values in hexadecimal notation as it is used in HTML.

The device color conversions use the currently defined color device for computing the conversion. The color device(s) may be defined as described in the section on color calibration.

fromXYZ(a)
converts the XYZ-coordinates of its argument to Yxy-chromaticity coordinates.
addColors(a, b)
compute the additive mixture of two colors. The resultr is (a + b).
mixColors(a, b)
compute the convex mixture of two colors with equal weights. The result is (0.5*a + 0.5*b).

The following color functions return color values which are independent of the currently installed gamma correction and color calibration. They always refer to device coordinates for the currently active color device.

white()
returns the system color white.
lightGray()
returns the system color lightGray.
gray()
returns the system color gray.
darkGray()
returns the system color darkGray.
black()
returns the system color black.
yellow()
returns the system color yellow.
cyan()
returns the system color cyan.
magenta()
returns the system color magenta.
green()
returns the system color green.
red()
returns the system color red.
blue()
returns the system color blue.
String Functions
runtimeID()
returns a uniqe runtime identifier string.
cat(a, b)
returns the concatenation of the string value of a and the string value of b.
lang2(a, b)
returns a if the currently active message language is English and b if the currently active language is German. The currently active language is determined automatically or can be set on the command line.
lang3(a, b, c)
returns a if the currently active message language is English, b if the currently active language is German, and c if the currently active language is anything else.
Array and Expression Functions
arrayOf2(a, b)
returns an array which has the values a and b as its components.
arrayOf3(a, b, c)
returns an array which has the values a, b, and c as its components.
valueOf(a, i)
returns the literal value at index i of the value of experimental parameter a. It is a runtime error if a does not have a value at index i.
expressionFile(dir, file)
returns the expression value defined by the expression contained in 'file' in directory 'dir'. The file must contain a valid expression as defined by the non-terminal 'assignableParameterValue' of the PXLab design file grammar.
undefined()
returns an undefined value. This may be used in cases where a parameter should be reset to its undefined state. The function replaces the '?'-character in assignments. It is not allowed to assign the placeholder '?' to a parameter in an assignment.
Mathematical Functions
idiv(a, b)
returns the integer division of a by b. The numerical operator '/' always computes the floating point division and rounds the result to the nearest integer for the parameter's integer value.
sin(a)
cos(a)
tan(a)
atan(b, a)
atan(a)
sqrt(a)
log(a)
log10(a)
exp(a)
pow(a)
abs(a)
ceil(a)
floor(a)
round(a)
randomInt(n)
returns a random integer number x with 0 <= x < n with equal distribution. Note that this function returns a new random number on every call.
nextNumber()
returns an integer which is incremented by one at every call.

Constant Parameter Values

There exist some parameters whose values should be treated as constant values, since they are set at startup time and should not be changed by the user. Here is a list of these:
PXLabVersion
PXLab version string.
Date
Date string.
AppletSystem
Applet system flag. This flag is 1 if the experiment runs as an applet and is 0 if the experiment is running as an application. This parameter may be used for setting other parameters to runtime system dependent values.

The colors defined by the following color parameters are the default screen colors as they result from device coordinates. Thus as an example the color 'White' is that white which results from setting all three device channels to their maximum value. Thus these color values are independent of the currently installed gamma correction and color calibration.

White
White color coordinates.
LightGray
Light gray color coordinates.
Gray
Gray color coordinates.
DarkGray
Dark gray color coordinates.
Black
Black color coordinates.
Red
Red color coordinates.
Yellow
Yellow color coordinates.
Green
Green color coordinates.
Magenta
Magenta color coordinates.
Cyan
Cyan color coordinates.
Blue
Blue color coordinates.

String Substitution

Whenever a string parameter value contains the name of another experimental parameter enclosed between percent signs then the current value of the respective parameter replaces the parameter within the string.

    Text = "%Trial.Message.ResponseTime% ms";

defines the feedback text string in a previous example. Here the string '%Trial.Message.ResponseTime%' is replaced at runtime by the actual value of the parameter Trial.Message.ResponseTime.

String substitution can use a formatting specification defined by class StringSubstitutionFormat. This is done by inserting a '@'-character followed by a formatting character at the end of the parameter name. Currently only these formatting characters are supported:

The default formatting method tries to make a conjecture about the type of the parameter and adapts the format accordingly.

[This file was last updated on July 15, 2010, 12:07:01.]

[Home]    [Content]    [Previous Chapter]    [Next Chapter]