Event System

Description

Users can create an event system to execute all of the functionality, logic, and interactions in a task. An event often acts as a mediator between objects and variables. Each event will always consist of 2 components: a trigger and an action (or set of actions).

Events are defined on a frame level and can be separate/specific for each frame or duplicated/the same on each frame across a trial. Either way, an event is always defined for all trials within a trial group for the specified frame(s). However, custom logic allows users to execute events only in certain trials, conditions, or in other circumstances.

Events are managed in the Task Editor under the "Events" tab in the top right corner. New events can be created via a click on "New Event" and all existing events are displayed in a list view. Here, the execution order of events can be adjusted. By default, events with the same trigger are further up on the list and will be executed first. Events can also be copied and deleted. When selecting an existing event, the specifics are shown in the lower right (Event Properties) panel. For a better overview, existing events can also be re-opened (icon next to the name field). events

Triggers

The trigger defines when the event will be executed. This could be a mouse click on a particular object, a certain keyboard input, a change of a variable, the start of a video file, or many other things. All triggers and their settings / parameters are explained in the following list:

List of Triggers: User Input

Mouse

Triggers On:

  • Mouse up, down, click, hover on a specific object, leave a specific object, or move at all.

Parameters:

  • Action: Which mouse action triggers the event
    • Click: Triggered by mouse click
    • PressDown: Triggered by mouse down
    • PressUp: Triggered by mouse up
    • Hover: Triggered by mousing over object
    • Leave: Triggered by mousing off of an object
    • Move: Triggered by any mouse movement
  • Button: Which mouse key triggers the event
    • Left: Triggered by left mouse button
    • Right: Triggered by right mouse button
  • Targets:
    • Trigger on Frame Background: the mouse trigger can be activated without clicking on an object or element.
    • Any Element: the mouse trigger can be activated when clicking on any element on the frame.
    • Add Targets: select the specific element(s) that must be clicked to activate the trigger.

Keyboard

Triggers On:

  • Pressing, pressing and holding, or releasing a key on the keyboard

Parameters:

  • Action: Which keyboard action triggers the event
    • PressKey: Triggered by key press (key is down)
    • ReleaseKey: Triggered by key release
  • Keys: Which keys triggers the event
    • Arrows: the four Arrow Keys
    • Numbers: Numbers from 0-9
    • Letters: All letters in the English alphabet
    • Special: Special Keys (Enter, Space, Control, Tab, Shift)
    • F-Keys: F1 to F10
    • any key: any of these keys is acceptable
  • Enable alphanumeric characters (true / false): Enables numbers & letters

Button Click

Triggers On:

  • A button click

Parameters:

  • Target: Selection of a button element as target
  • Button: Specify which specific button on the frame

Enter on Input

Triggers on:

  • The Enter/Return key is pressed on the keyboard while a specific element is active.

Parameters:

  • Add Targets: Add a text element to the Event.

Scroll

Triggers on:

  • The scroll bar, scroll on track pad, or scroll wheel on the mouse is used on a specific element.

Parameters:

  • Choose whether the scroll is on the Y axis or the X axis (vertical scroll or horizontal scroll).
  • Target: Set the target element that the scroll trigger will apply to.

List of Triggers: Physiological Signals

These triggers will only apply if eyetracking and/or headtracking has been enabled for the task.

Eyetracking Gaze

Triggers on:

  • Overall, this trigger will apply when eyetracking has been enabled.
  • Only trigger when looking at specific elements

Parameters:

  • If you have selected to only trigger on specific elements, add those elements as targets.

Eyetracking Fixation (BETA)

This trigger is still in its BETA phase.

Headtracking

Triggers on:

  • Changes in head orientation or head movement.

List of Triggers: Trial and Frame Triggers

Task Init

Triggers on:

  • The first frame of the first trial of a task. Will only be executed once per task, despite being shown in the Events tab for all instances of that frame.

This Trigger pairs well with the Shuffle and Read From actions. With these combinations, you can shuffle array entries or data frames as the task starts and assign subjects to sets of stimuli without having to create multiple events to read out stimuli or data.

Parameters: None

Frame Init

Triggers on:

  • The initialization of the frame, before it becomes visible to the participant.

This trigger pairs well with the Shuffle, Read From, and Draw Random Number actions. With these combinations, these actions can be completed before the frame appears, leaving a clear pathway for other actions to begin as the frame starts.

Note: Do not use the Frame Init trigger with events that record a variable or that involve system variables such as Trial Number or Condition Number. This is because the Frame Init trigger occurs in between trials, so there is not a fully accurate count of the trial or condition about to be displayed.

Parameters: None

Frame Start

Triggers On:

  • Start of the frame

Parameters: None

Frame End

Triggers On:

  • End of the frame (after frame is no longer visible)

Parameters: None

List of Triggers: Variable Value Changed

Variable Value Changed

Triggers On:

  • The value of a variable changes from its starting value

Parameters:

  • Variables: Select one or more variables where you want to "listen" to changes. Any change in the value of these variables will trigger the corresponding Action immediately.

List of Triggers: Object Trigger

Audio / Video Trigger

Triggers On:

  • Start, pause, or stop of a video or audio file.

Parameters:

  • Target: Select one audio or video element
  • Execute On: Select sub type of trigger
    • Started: Triggers when the element starts playing
    • Paused: Triggers when the element pauses
    • Stopped: Triggers when the element stops playing

Upload Recording / Playback Trigger

Triggers On:

  • File Upload Finished, File Selected, Recording Done

Parameters:

  • Target: Select one upload or recording element
  • Execute On: Select sub type of trigger
    • Audio Recording Finished: Triggers when the audio recording has stopped
    • Upload Complete: Triggers when the file upload is complete
    • File Selected: Triggers when a file is selected

List of Triggers: Global and External Trigger

Pause/Resume Experiment

Triggers On:

  • Global experiment event.

Parameters:

  • Participant pauses (exits fullscreen) the study.
  • Participant resumes the study.
    • This trigger works well for eyetracking studies. It can be used to send the participant back to a previous trial or frame if they have left their Virtual Chinrest.

Websocket/API Trigger

Triggers on:

  • Add the message from the websocket/API that will be received and processed as the trigger for the Action.

Parameters:

  • Accept/Receive from: Auto-detects the IP address of the local host. Can be changed manually in the Study Settings.
  • Trigger/message: input the message that will serve as the trigger. Type 'any' to accept more than one message as a trigger.

Participant Left Multiuser Study

Triggers on:

  • One of the participants exits the study, preventing the other participants from continuing.

Parameters:

  • Can only be used for a multiuser study. This can be changed in the Study Settings.

Actions

Actions define what should happen when the event is executed. They can be used to change variables and object properties, record data, read and write data to / from arrays, or jump to the next trial or task. Often there are several actions per event. Using "ControlActions," one can use logical operations (If-Else statements), Loops, callback functions, as well as nesting actions within each other (e.g a while-loop within an if-statement). Hence, the event system can be seen as a graphical programming environment. In this view, triggers act as the function invocations, while actions describe the functional logic. This approach guarantees that almost any experimental logic can be implemented without the use of certain programmatic / syntactical structures.

The actions are set up in the second step of the event dialog box and are subdivided into 5 major categories: Object Actions, Variable Actions, Array Operations, Jump-Actions, and Control Actions. A list of all actions, their parameters, and effects is listed below:

List of Actions

Object Actions

Set Object Property

Effect: Changes the appearance of an object.

Parameters:

  • Target: Select one object
  • Property Selection: Select one object property
  • Value-Select-Menu: Define a new value by using the Value-Select-Menu

Control Audio / Video Object

Effect: Changes the playback of video/audio elements.

Parameters:

  • Target: Select one audio or video object
  • Effect: Select a sub action
    • Start: Starts playing the video / audio file
    • Pause: Pauses the video / audio file
    • End: Stops the video / audio file
    • jumpToTime: allows you to specify a time in milliseconds to jump to in the audio/video file

Control Object

Effect: Changes the state of upload/recording elements.

Parameters:

  • Target: Select one upload or (audio) recording object
  • Effect: Select a sub action
    • Start Recording: Starts a new (audio) recording
    • Stop Recording: Stops the (audio) recording
    • Start Upload: Starts uploading of the file
    • Clear Recording: Deletes the (audio) recording data.
    • Start Playback: Starts playing the recorded file
    • Stop Playback: Stops playing the recorded file
    • Clear File: Deletes the selected file

Copy Object

Effect: Copies an object, replacing the need for several separate objects and duplicate events.

Parameters:

  • Source: Choose the object on the frame to copy.
  • No of copies: Input the number of copies to make of the source object.
  • Set new element name: Choose from several parameters to determine the names of the copies.
  • Assign name with incrementing postfix: Adds a numeric tag to the end of the new element name to differentiate the copies.
  • Action Sequence: Allows you to choose (from the usual list of actions) what will happen to the copies. Select "CurrentObject" as the target to apply the action to all of the copies.

ForEach Object

Effect: Applies an action to several objects of the same type.

Parameters:

  • Filter: Choose the type of element to target.
  • Allow Additional Name Filter: Type the name of the object(s) to target. For several objects on a frame where some have identical names, this works well.
  • Action Sequence: Allows you to choose (from the usual list fo actions) what will happen to the selected elements. Select "CurrentObject" as the target to apply the action to all of the elements meeting the above specified criteria.

Variable Actions

Set / Record Variable

Effect: Writes / sets a variable value

Parameters:

  • Variable-Select: Use the Variable-Select Menu to choose a variable
  • Value: Define a new value by using the Value-Select-Menu

Draw Random Number

Effect: Draws one or multiple random number(s) and saves them in a variable

Parameters:

  • Type: Choose Between continous and discrete values
  • Distribution: Choose between gaussian and uniform distribution
  • Multiple Draws (boolean true/false): Choose to draw once or multiple times.
  • Nr of Draws: Select the number of draws
  • Min: Define the minimum value for the uniform distribution
  • Max: Define the maximum value for the uniform distribution
  • Mean: Define the mean value for the gaussian distribution
  • Standard Deviation: Define the standard deviation for the gaussian distribution
  • Save in Variable: Select a variable where the value(s) are stored.

Get URL Parameter

Effect: saves a value from the unique URL of the participant

Parameters:

  • Parameter name: input the name of the desired parameter
  • Save in Variable: select the variable in which to save the parameter value

This Action could be combined with other Actions to construct unique URLs for participants or extract information necessary for data analysis.

Read from/Write to Device

Effect: Reads or writes a variable to/from the local device's storage. This Action saves data to the participant's device instead of sending the data to the Labvanced servers.

Parameters:

  • Choose read from or write to the local device.
  • Choose the variable to read or write.

Use Case: Longitudinal/Multi-Session Studies

  • With this action, device-specific data can be carried over from session to session, provided the same participant is using the same device for every session.
  • For example, you can use this action to record which images were presented to each participant in Session 1 and ensure that different images are presented to them in Session 2.
    • Create an array of images and randomly select a few to present in each session.
    • Write to Device: the index number of the images presented in Session 1.
    • Read from Device: in Session 2, read out the indexes of the images from Session 1 and include a JavaScript action that prevents those indexes from being selected for the second session.

Math & Statistics

Effect: Performs a mathematical operation of some input variable (array) and saves the result in an output variable.

Parameters:

  • Type: Choose between Array Operations, Linear Algebra, and Statistical Tests
  • Operation: Choose a math operation (e.g. sum, min, stdev, etc.)
  • Input Array: Choose an input variable (Array) on which the operation is executed
  • Parameters: Some operations have additional parameters.
  • Output: Select an output variable where the result will be stored.

Record Variables Instantly

Effect: Creates a snapshot of all variables values and send this to the Labvanced server.

Parameters: None

Moving Average Filter

Effect: Calculates a moving average (a constantly updating average of the data) of some input and stores the result in a new variable.

Parameters:

  • Filter Shape: Select the filter type
    • Simple Moving Average: Calculates a simple moving average, where all samples have the same weight.
    • Linear Weighted Moving Average: Weighs the samples such that the weights of the samples decrease linearly.
    • Exponential Moving Average: Weights the samples such that the weights of the samples decrease exponentially.
  • Number of Samples: Determines how many samples are used per step.
  • Input: Choose an input variable (Array) on which the moving average is calculated
  • Output: Select an output variable where the result will be stored.

Distribute Variable

Effect: Will send a value to other participants. The value is stored in a variable.

Parameters:

  • Distribute Value to: Choose to which other participants the value should be send to.
    • All participants: Send this value to all participants
    • Selected Participants: Send the value to selected participants.
  • Value: Determine the value which should be send to other participants.
  • Target Variable: Choose a target variable where the value will be stored.
  • Block (true / false): If enabled, the Target Variable cannot be changed until the current value distribution is completed.

Array Actions

Select (Read) from Array

Effect: Will read out one variable from an array and store this value in a scalar variable.

Parameters:

  • Array Variable: Input Array for reading out the value.
  • Index Type: Determines what kind of index is used.
    • Fixed: Use a fixed index for the read operation. In this case, type in the position from where the information should be read out (1 based).
    • Variable: Use a numeric variable as an index for the read operation. In this case, select a scalar numeric variable to determine the position of the readout.
    • End of Array: Read from the end of the array.
  • Output variable: Select a scalar variable where the read out value will be stored.

Add / Remove Array Entries

Effect: Will add and/or remove entries from /to an array.

Parameters:

  • Array Variable: Array variable where the add or remove operation should be executed.
  • Index Type: Determines what kind of index is used.
    • Fixed: Use a fixed index for the insert / delete operation. In this case, type in the array position where the entries should be inserted / deleted. (1 based).
    • Variable: Use a numeric variable as an index for the insert / delete operation. In this case, select a scalar numeric variable to determine the where the entries should be inserted / deleted.
    • End of Array: Insert / delete from the end of the array.
  • Nr or entries to delete: Will remove the array entries (before inserting new entries) starting at the defined index position. 0 indicates that no values will be removed.
  • Variable(s) to Insert: Select one or more scalar variable(s), which will be added to the array variable at the defined index position.

Change (Replace) Array Entry

Effect: Will replace / change one value within an array.

Parameters:

  • Array Variable: Array variable in which one value should be modified
  • Index Type: Determines what kind of index is used.
    • Fixed: Use a fixed index for the replace operation. In this case, type in the array position which should be changed (1 based).
    • Variable: Use a numeric variable as an index for the replace operation. In this case, select a scalar numeric variable to determine the position of the replace operation.
    • End of Array: Replace the last entry in the array.
  • Input variable: Select a (scalar) variable which holds the new value.

Shuffle Array Entries

Effect: Will re-shuffle the entries /order within an array.

Parameters: None

Data Frame Operations

Read from / Write to Data Frame

Effect: Reads out values from or writes values into a data frame and saves them in a new array variable.

Parameters:

  • Data frame variable: select the variable of the data frame to read.
  • Read or Write: Choose to read from the selected data frame or write to the selected data frame.
  • By row or column: Choose how the data should be read.
  • Index type: Choose the type of index variable that will be used to read the data frame. Can be fixed, variable, or the last row.
  • Index variable: Choose the variable that will be used as the index to read the data frame.
  • Output variable: Choose the variable where the read/written data will be stored as an output. Must be an array variable.

Shuffle Data Frame Entries

Effect: Shuffles the order of entries in the data frame.

Parameters:

  • Select the data frame to shuffle.
  • Select if the data frame should be shuffled by rows or columns.

Jump Actions

Jump To

Effect: "Jumps" the participant to a different step in the experiment. This action can change the order of trials and tasks in an experiment and can be used to create individualized experimental logic for each participant.

Parameters:

  • Jump To: Determines where to jump to in the experiment.
    • Next Frame: Jumps to the next frame. If there are no more frames defined in a trial, it will jump to the first frame of the next trial.
    • Next Trial: Jumps to the next trial. If there are no more trials defined, it will jump to the first trial of the next task.
    • Next Task: Jumps to the next task. If there are no more tasks defined, it will jump to the first task of the next block.
    • Next Block: Jumps to the next block. If there are no more blocks defined, the session will end.
    • Previous Frame: Jumps to the previous frame. If there are no previous frames, the action will not be executed.
    • Specific Frame: Jumps to a specific frame. Users directly select the frame to jump to.
    • Specific Trial: Jumps to a specific trial. Users directly select the trial number to jump to.
    • Specific Task: Jumps to the first instance of the specified task in the current block. Users directly select the task to jump to.
    • Specific Block: Jumps to the first instance of the specified block. Users directly select the block to jump to.
  • Check Required Answers Before: If enabled, the experiment will check whether all required answers have already been answered. If not, the jump to action is not executed.

Accept/End Session

Effect: Will accept the participant's data, end the recording session, and show the crowdsourcing code.

Parameters:

  • Record trial data before finish session: If enabled, the most recent trial data will be stored (sent to the server) before exiting the study.
  • Show default ending page: If enabled, the default Labvanced end-screen will appear. If this is a crowdsourcing session (crowdsourcing link was used), the compensation code will be shown to the participant. If disabled, the experiment will finish after showing the current frame and will not show the default end screen with compensation code.

Reject/End Session

Effect: Ends the recording session, does NOT mark the participant's data as complete, and does NOT show the default end screen with compensation code.

When using this action to reject a participant's data, users should display an appropriate message to participants that explains the reason they will not be rewarded for their time.

Parameters: None

Control Actions

Requirement Actions (If... Then... Else If)

Effect: Evaluates an if-then statement and executes a series of actions dependently. Each If /Else-If statement consists of nested AND / OR comparisons to evaluate whether all requirements are met (statement is true) or not (statement is false). If the statement is true, the actions under "Then" are executed.

Parameters:

  • Add Requirement: Add a new requirement to a statement. The "value-select" menu will appear on both sides to make a logical comparison. In the middle of the statement, you can choose how both sides should be compared (e.g. equal, smaller than, unequal, etc.).
  • Add OR Group: Only one out of all requirements within an OR Group has to be true for the whole group to be true. Add an OR group if the sub-actions should be executed in several cases.
  • Add AND Group: All requirements within an AND Group have to be true for the whole group to be true. Add an AND group if the sub-actions should be executed only when several requirements are met.
  • Action Sequence: Each If / Else-If statement has a list of actions, which are defined under "Then". The action sequence lists all the actions for a certain If / Else-If statement. A new action can be added via the "Add Action" icon. The action sequence will be executed only if the requirement(s) of the associated If / Else-if statement are fulfilled.
  • Add Else-If Case: The Requirement Action can consist of several separate If / Else-If --> Then statements. However, only one statement can be executed. If one If / Else-If statement is evaluated positively (returns true), the actions in the Then block are executed and the rest of the Requirement Action is skipped.
  • Add Else Case (true / false): If enabled, a default / fallback option is added to the requirement action. If none of the If / Else-If statements are executed (returned true), the actions defined in the else case will be executed.

Repeated Actions (While Loop)

Effect: Repeatedly executes a series of actions, either immediately or within a defined interval. A stop condition can be specified so that the loop execution will be stopped.

Parameters:

  • Execution Type: Choose between immediate execution or timed execution
    • Execute complete loop: This will execute the loop continuously until the stop condition is fulfilled.
    • Execute every ... ms: This will execute the loop with defined interval (e.g. the loop is executed every 50 ms).
  • Define the number of loops: When "Execute every ... ms" is selected, users have the option of assigning a numeric integer value for the number of times the loop should be executed. This replaces the need to define a stop condition.
  • Execution Interval: This determines the execution interval.
  • Start immediately (true / false): If enabled, this will execute the loop right away. If disabled, the loop will be started on the next execution interval.
  • Allow multiple starts (true / false): If enabled, several loop instances can be started in parallel. If disabled, only one loop instance can be executed at a time.
  • Enable stop condition (true / false): If enabled, a stop condition for the loop can be specified.
  • Stop Condition: The stop condition can be used to specify a logical expression for when the loop execution should be stopped. Similar to the If / Else-If statements, one can combine AND groups, OR groups, and Requirements for the logical comparison.
  • Action Sequence: The action sequence lists all the actions which are executed at each iteration of the loop. A new action can be added via the "Add Action" icon.

Delayed Actions (Time Callback)

Effect: Executes a series of actions after a certain time delay

Parameters:

  • Delay Type: Choose between a fixed delay or a variable delay
    • Fixed Delay: The actions will be executed after a fixed delay.
    • Variable Delay: The actions will be executed after a delay specified in a (numeric) variable.
  • Delay: The length of the delay in milliseconds (ms).
  • Action Sequence: The action sequence lists all the actions which are executed after the specified time delay. A new action can be added via the "Add Action" icon.

Custom Actions

Run Java Script

Effect: Inputing custom Java Script will allow you to program specific events and save them as Labvanced variables.

Set a Global CSS

Effect: Using custom CSS code, users can change an aspect of the study when the Trigger occurs. An example of this would be to change the background color of the study when a participant selects a specific color from a multiple choice question.

Paste Action

This option allows you to paste an Action that you have previously created and copied.

The Value Select Menu

Via the Value Select Menu, different kinds of values can be read out and set. It is used for various actions in the event system, such as the actions "Set / Record Variable", "Set Object Property", and "Requirement Actions (If... Then)". It is depicted by a white small button with a pen icon. Overall, there are 8 different categories in the Value Select Menu.

Constant

Assigns a fixed value depending on the data type.

  • String: Assigns a string / text value.
  • Numeric: Assigns a numeric / number value.
  • Boolean: Assigns a value of true or false.
  • Categorical: Assigns a level value (mostly for factors).
  • Date: Assigns a date value.
  • Time: Assigns a time value:
  • Color: Assigns a color (hex-string) value.

Variable

Reads out the value of a specified variable.

Arithmetic

Extends the formula by one more parameter (another Value Select menu). The two values can then be combined by using 5 different mathematical operations: addition (+), subtraction (-), division (/), multiplication (*), and modulo (%).

Object Property

Reads out an object property.

UNIX Timestamp

Returns the UNIX timestamp in milliseconds.

Frame Properties

Return specific frame properties.

  • Time From Frame Onset: Returns the Time From Frame Onset. Most often, this is equivalent to the reaction time.
  • Mouse X: Returns the current Mouse X position in frame coordinates.
  • Mouse Y: Returns the current Mouse Y position in frame coordinates.

Event Parameter

Returns different properties depending on the trigger type.

  • Stimulus Name: The name of the object which triggered the event (e.g which image was clicked).
  • Stimulus Info: The stimulus info of the object which triggered the event.
  • Time From Frame Onset: The time from frame onset, usually this is equivalent to the reaction time.
  • Mouse X: The current Mouse X position in frame coordinates.
  • Mouse Y: The current Mouse Y position in frame coordinates.
  • Id of Key: The Key that was pressed triggering the event.
  • totalFrameTime: The total time the frame was shown.
  • newValue: The new value of the variable after the change.
  • timeOfAudioVideo: The current time of the audio or video file.
  • Coordinate X: The current Eye X position in frame coordinates.
  • Coordinate Y: The current Eye Y position in frame coordinates.

Math Operation

Performs a math operation on a scalar value.

  • Abs: Returns the absolute number of a value.
  • Sqrt: Returns the Square-Root of a value.
  • Round: Returns the rounded value with 0 to 3 decimal places.
  • Floor: Returns the floored value.
  • Ceil: Returns the ceiled value.