Variables

Description

Variables can be used for different purposes in the experiment creation process on Labvanced. Variables hold and update values that are created either in the editor by the experimenter or during the experiment execution by different means. Importantly, all variables within a study are defined and can be used globally throughout the experiment. There is a "Variables" tab in the main navigation panel, where all variables of a study are listed. By default, variables are not added to the global list to avoid cluttering the system. A variable can be added to the global list in the variables tab (click "view in global list" under Variable properties) so that it can be used throughout the experiment.

Within the task editor, the variables that are used on the currently selected frame are listed under the "Variables" tab in the top right corner of the screen. Here, each variable is shown with its most important properties: the main category, data type, and name. Variables can be copied, deleted, and selected to inspect and change further properties. Within the Labvanced task editor, and especially within the event system, there are several places where a variable has to be selected in order to achieve a desired function. When you are asked to select a variable, you can usually select an existing one, but you can also create a new variable at that time. You can also create a new variable independent of selecting / using it. This can be done by clicking on the "New Variable" icon in the variables tab.

A change made to a variable can trigger an event, but the reverse is also true: events can change the value of a variable. Furthermore, variables can directly change the state of certain objects. Variables are grouped into 5 main categories: System Variables, Factor Variables, Object Variables, Custom Variables, and Unused Variables.

Variable Properties

For each variable, users can determine different properties and provide a short text description that summarizes what the variable is used for. The “name” and the “data type” properties are mandatory, while the other properties are optional or cannot be altered depending on the data type. Below is a list of all properties, their values, and descriptions.

Name

• Description: The name is used as a handle for the variable in events, objects, when copying tasks, and later also in the data-view. The name MUST BE UNIQUE (there cannot be 2 variables with the same name). Otherwise, severe errors can occur! The name property can be changed in all variables except System Variables.
• Possible Values: Any ASCII string.

Data Type

• Description: The data type of a variable determines what kind of values the variable can have. The data type also determines what kind of mathematical operations can be applied to a variable (multiplication only works with numeric variables, etc.).
• Possible Values:
  • String: Any text can be stored in the variable, including numbers, special characters, etc.
  • Numeric: Only numeric values can be stored in the variable.
  • Boolean: The variable can only have the values “true” or “false.”
  • Categorical: The variable has a set of fixed predefined levels and one of the levels must be the variable value. This is mostly used for factor variables.
  • Date: The variable can only hold date values in the format (yyyy/mm/dd).
  • Time: The variable can hold only time values in the format (hours/minutes/seconds).
  • File: The variable can hold file data of images, videos, or audio files.

Scale

• Description: The scale of a variable determines the "level of measurement" of the variable. This distinction is useful for variables with a numeric data type and defines the relation of the variable values. The property may have more uses in a future Labvanced extension, such as an analyzing module.
• Possible Values:
  • Undefined: No selection
  • Nominal: Nominal Scaled value (categories).
  • Ordinal: Ordinal Scaled value (ranks).
  • Interval: Interval Scaled value (scale without a true zero point, e.g. temperature).
  • Ratio: Ratio Scaled value (scale with a true zero point, e.g. weight).

Format

• Description: The format of a variable determines whether the variable is a single (scalar) value or an array of values. Some operations /actions can only be applied to arrays and others only to scalar variables.
• Possible Values:
  • Scalar: The variable is a single value.
  • Array: The variable holds a range of values.
  • Data Frame: There are several variables nested in a CSV file. Choosing Data Frame opens a dialog box to specify the CSV data, where each column is a variable. Users can choose between string, numeric, boolean, or file as a variable type.

Start Value

• Description: The start value of a variable determines the default / reset value of the variable. The start value can be used to reset a variable’s value at the start of each trial to a certain value. The start value can also be used to permanently store information in a variable (e.g text, image, video or audio data).
• Possible Values: Depends on the data type. Use the reset Icon to remove the start value.
  • Variables with data format "array": For "array" variables, it is possible to not only define one start value, but to fill a complete array with values. For instance, the user can upload a list of words (CSV file), images, videos, audio files, etc. into an array variable. The position of the items / entries within the array can also be adjusted.

Reset at Trial Start

• Description: The “reset at trial start” option determines whether the variable will be reset to the start value for each new trial or not. Typically, this option should be activated for variables that record a participant’s response or reaction time. However, variables which accumulate data over trials (for feedback or other purposes) or data arrays storing information persistently should not be reset.
• Possible Values: If checked (true), the variable will be reset to start value. If unchecked (false), the variable will not be reset.

Record Variable

• Description: The record variable option determines whether the variable will be recorded or not. All variables where this option enabled will be recorded at the end of each trial.
• Possible Values: If checked (true), the variable will be recorded. If unchecked (false), the variable will not be recorded.

Record Type

• Description: The record type of a variable determines whether all value changes of a variable during a trial will be recorded, or just the final value of the variable in each trial. If all changes are recorded, each variable change will be saved together with a timestamp. This option can be used to record a time series of data (e.g. for mouse or eyetracking)
• Possible Values:
  • All changes / time series: Records all changes of a variable including timestamps.
  • Final value only: Records only the last value of a variable at the end of the trial.

System Variables

System variables are important for experiment execution and data export. They are created automatically and cannot be modified or deleted. System variables are also very useful in requirements (e.g If-Else Actions). For instance, they can be used to refer to a specific trial number, to use a subject counter, or to separate events for multi-user studies between participants. All system variables are shown in the main variable menu on the Labvanced platform.

Factor Variables

Factor variables are those variables that are linked to a factor in the trial system. Each factor has one linked variable with a categorical data type. The levels of the factor are also possible value states of the variable. When creating a new factor, users can choose to either create a new variable (automatically) or re-use an existing variable. When linking factor variables, it should be noted that changes to the variable / factor levels will change the trial structure in all linked tasks / trial groups. Factor variables can be used in the event system, for example to create events which are executed only in certain conditions (e.g. do something only if factor "image category" equals "house"). Furthermore, on each trial during the experiment execution, each factor variable will always have a new level value stored in the data view. This way, it is easier to reconstruct the condition of each recorded trial when viewing the data output or repeating the procedure.

Object Variables

Object variables are created automatically when an object is added to the frame. Most of these variables arise from adding "questionnaire items", like checkboxes, Likert scales, dropdowns, etc. Upon the creation of such an object, you will be asked to enter a name for the associated variable. After you have entered a valid (unique!) name, the variable will be created automatically. In the object property view, you will see the reference to the associated variable under "linked variable". Here you can also change the linkage / association to a different variable. However, we suggest to use this option with special care. Upon experiment execution, the participant's response will be stored within the variable. Object variables will be recorded by default and most properties of object variables cannot be changed to ensure their functionality.

Custom Variables

Custom variables are actively created by the user. The reasons to create custom variables can be quite diverse. They can be used to record participants' decisions (mouse clicks or keystrokes) or reaction times. They can also be used as counters or indices in while-loops or array actions, to store (image, video, audio) file data, and for many further purposes.

When a variable is created without being used, or when its usage (object or event) is deleted, the variable will be listed as unused.

Array Variables

Arrays are very different from the scalar variables discussed above. Think of an array as one column in a spreadsheet: it holds entries in a specified order. When creating an array, you can click the folder next to "Use CSV file" to upload a .csv file with a column of information, or you can manually add entries using the plus icon.

For a list of actions associated with arrays, see Array Actions

Data Frame Variables

Data frames are different from arrays in that if an array is one column of a spreadsheet, a data frame is an entire spreadsheet with multiple columns. Data frames can hold string (text), numeric, boolean, or file values, but cannot be directly edited in the data frame dialog window. You can add columns and files, but cannot type text or numbers:

To add a new data frame, click Upload 2D CSV Data. When adding information to your data frame, only .csv files are accepted. After choosing your file, several import options will appear:

Choose all that apply:

• Map Strings to Files allows you to include the names of your files as strings, then use the map function to point to the folder where the files are stored. This will allow that column of file names to search for the corresponding files in a folder, provided the values in the data frame exactly match the names of the desired files. This function is only available if the column is populated by string values.
• Use First Row as Header takes the values in the first row of your data frame and uses them as the variable names for each of the columns.
• Transpose Data simply uploads the data frame as it is. This is useful if your data frame does not contain any file names.

If your data frame consists entirely of string values that correspond to the names of files in a folder, you can map the entire data frame to a folder using the map all strings to files function.

To add more information to an existing data frame, choose the Add variable/column option at the top of the Data Frame Dialog box.

For a list of actions associated with data frames, see Data Frame Operations

Variable References and Deleting Variables

To provide a better overview of where each variable is used, there is a list called USED IN at the bottom of the variable properties panel. Here, all usages of the variable are listed, including a reference to the frame on which the variable is used (name), for what purpose (Used as), and whether the usage is a read operation (R), a write operation (W), or both (RW). For each frame where a variable is used, there will be one extra entry in the usage table with a "use type" named "local workspace". All variables in the local workspace of a frame will then be shown under "local variables" section in the variable selection menu.

When you wish to delete a variable, it must be done with special care. Deleting variables that are still used as factors, objects, or used in events can lead to serious problems and (in the worst case) can disrupt the entire experiment structure. Hence in the variables tab, only those variables which have no referred use besides being within one (or more) local workspace(s) can be deleted. Variables that are only defined on the local workspace (with no further use) are listed as unused and a deletion icon is shown next to them.

Variable Selection Menu

User-controlled use of variables is mainly based on event logic. Within the event system there are 3 (visually) different menus which will allow you select a variable: the "Value-Select Menu", the "Green Select Button", and the "Variable-Reference Menu." While these menus are visually different, they open up the same menu (the Variable-Selection Menu) to select a variable.

Overall, the Variable-Selection Menu contains three different tabs: "Local Variables", "All Variables" and "New Variable." Under "Local Variables," you can see and select all the variables that are defined in the local workspace of the frame (already used on the frame). Under "All Variables," all variables in the global list of the study are listed and can be selected. Both of these menus have a search function to directly find a desired variable. The "New Variable" tab can be used to create (and consequently select) a new variable.

Recording Data

For each variable, users can use a checkbox to decide whether the variable value will be recorded or not. For system variables, factor variables, and object variables, the recordings are activated by default. Hence many parts of the data recordings will work automatically. When you aim to record a certain object property, a response of the participant, or something else which is not recorded by default, you have to use the event system to set the variable value appropriately. Here is a short example of event logic for recording reaction time:

1. Add an image to the frame.
2. Create a new Event and name it.
3. Define the trigger that determines when the variable value should be set. For example, Select --> User Input --> Mouse Trigger. Set the trigger action as Click and the Button as Left. Click the + sign next to Add Targets to add the image as a clickable target. Click Next at the bottom of the window.
4. Select the action Variable Actions --> Set / Record Variable. Then click on "Select" button.
5. Click on the "New Variable" tab and create a new variable by giving it a name (data type: numeric, reset = true, record = true). Click "Ok."
6. Click on the Value-Select (pen) icon --> Trigger(Mouse) --> Time From Frame Onset. Click Finish.

Now you have saved the reaction time for clicking on an image. You can use a similar procedure to record other properties like decision (which image was clicked from a variety), etc.