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).

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:

User Input Triggers

User input triggers refer to any trigger that can be manually activated by the user/participant. These include:

• Mouse Triggers
• Keyboard Triggers
• Button-Clicks
• Enter on Input
• Scroll Trigger

Mouse Trigger

The ‘Mouse Trigger’ option is a very popular event trigger as it initiates an event based on any mouse interaction, such as: moving the mouse up / down, clicking, hovering on a specific object, leaving a specific object, or any move at all!

The example below shows a ‘Mouse Trigger’ that will occur when a ‘Click’ is performed by the ‘Left’ mouse click on the ‘Target’ object called ‘Image_1’:

Below is a full overview of options you have when working with mouse triggers:

Menu Item	Menu Area	Mouse Trigger Options and Specifications
Action drop-down list:		The following mouse trigger options are available from the drop-down list: 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 drop-down list:		Left: Triggered by left mouse button Right: Triggered by right mouse button
Targets options:	In the example above, ‘Image_1’ is the target of the button click that will trigger the event. Multiple targets can be added by clicking the ‘+Add Target’ option at the bottom.	When specifying a target, the following options are available: 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

The ‘Keyboard trigger’ option is another popular way to have an event trigger. Essentially, any input from the keyboard can be used as a trigger. This includes: pressing, holding, or releasing a key.

In the example below, the trigger is set to be a keyboard press that occurs when the specified target numerical values (0, 2, or 6) are pressed:

Below is a full overview of keys and options you have when working with keyboard triggers:

Menu Item	Menu Area	Keyboard Trigger Options
Action drop-down list:		These are the keyboard action options available: PressKey: Triggered by key press (key is down) Press OR Hold Key: Triggers when either the key is being pressed or held ReleaseKey: Triggered by key release Note: A key needs to be released before it can ‘fire’ again as a trigger.
Keys which key triggers the event		Which key is used as a trigger is specified by selecting the options here by clicking +Add: 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 You can add multiple keyboard triggers by clicking the +Add: button again
Additional Options		The enable numpad buttons option allows for numpad keys to be used as triggers within the experiment. For the allows event propagation option, if multiple events have the same keyboard trigger then all fire/trigger without it. Only the first one will fire and the event execution will stop after the first event is done.

Button Click Trigger

If you have a button or navigation object placed in the editor, you can utilize them as a part of an event where clicking on the button acts as a trigger for an action.

Clicking this trigger shows the following menu where you can specify which specific button will act as the trigger:

Here is a closer look at the items featured:

Menu Item	Menu Area	Button-Click Trigger Options
Target: +Set Target		Selection of a button element as target
Button: option		Specify which specific button on the frame

Enter on Input Trigger

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

Parameters:

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

Scroll Trigger

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.

Note: For long text, in the 'Object Properties' panel under the 'Style' section, the Overflow-Xand/or the Overflow-Y options need to have scroll as the option selected.

Physiological Signal Triggers

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.

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

Note on Task and Frame Init Triggers: Because the Task and Frame Init triggers occur before the task or frame begins, variables created during this time will reset when the task/frame actually starts. A warning will appear when using this event:

Remember to uncheck the "Reset at Trial Start" box in the variable properties window if you do not want the variable values to be reset.

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

Variable Value Changed Trigger

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.

Media Object Triggers

Media Object Trigger

Formerly known as the separate "Control Audio/Video Trigger" and "Control Object" triggers.

Triggers On:

• Start, pause, or stop of a video or audio file
• File Upload Finished, File Selected, Recording Done of a recording object
• Snapshot Finished or Upload Complete of a camera snapshot object

Parameters:

• Target: Select an object element that exists on the frame
• Execute On: Select sub type of trigger
  • Audio or Video Object options:
    • Playback Started: Triggers when the element starts playing
    • Playback Stopped: Triggers when the element pauses
    • Playback Ended: Triggers when the element stops playing
  • Video, Audio, or Screen Recording Object options:
    • Recording Finished: Triggers when the audio recording has stopped
    • Upload Complete: Triggers when the file upload is complete
  • File Upload Object options:
    • File Selected: Triggers when a file is selected
    • Upload Complete: Triggers when the file upload is complete
  • Camera Snapshot Object options:
    • Snapshot Finished: Triggers when the camera has successfully taken a snapshot
    • Upload Complete: Triggers when the snapshot is finished uploading

API Triggers

If you need to send or communicate data from an external server into Labvanced, then ‘API Triggers’ and ‘API Actions’ can be used. The following can be used as triggers:

• Websocket Trigger
• OpenAI Trigger

Websocket Trigger

The Websocket Trigger is used when a message from the websocket/API that will be received and processed as the trigger for the Action.

Upon clicking this option, the following items appear.

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

For an example of how API Triggers / Actions are used, please check this demo https://www.labvanced.com/page/library/51053 by clicking the ‘Inspect’ option in the dialog box.

For more information about API Access, please visit this page.

OpenAI Trigger

The ‘OpenAI Trigger’ can be used to initiate an action based on incoming information from OpenAI.

Selecting this option will lead to the following parameters being displayed:

In the example below, the data frame that was assigned is called ‘df’ and the result from the ‘OpenAI Trigger’ will be appended to this data frame. This data frame needs to have two columns. The first column will denote the ‘role’ and the second column the ‘chat message.’ The values from the action will be automatically appended to the data frame that is linked here.

If you are also using the ‘Send to OpenAI’ action, then you need to utilize the same data frame there as you have indicated here.

Global Triggers

Global Triggers occur whenever a major change occurs within the experiment, ie. something that is ‘Global’ such as pausing the experiment or a participant leaving a multi user study! The following options are listed as Global Triggers:

• Pause / Resume Experiment
• Participant Left Multiuser Study

Pause/Resume Experiment

The ‘Pause / Resume Experiment’ trigger is an option that allows you to execute an event based on the experiment pausing or resuming.

Upon selecting this trigger, the following view appears where you can further specify the nature of the trigger, whether is should be executed on the experiment being paused or continued / resumed:

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

Participant Left Multiuser Study

If a participant leaves a multi user study, that can also be used as a trigger for an event. If a participant leaves a multiuser study, this affects the experiment on a global level because it prevents other participants from continuing the study.

By selecting this trigger, you can specify what kind of action will happen if a participant leaves a multi user study.

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.

Object Actions

Object actions refer to any manipulation that will occur on an object that exists within the task. There are several Object Action options:

• Set Object Property
• Control Media Object
• Copy Object
• ForEach Object

Set Object Property

With the ‘Set Object Property’ action you can change the appearance of an object however you want by specifying the object in question, the property to be changed, and the new value.

In the example below, the action will change two properties of the target image by setting the ‘visibility’ to ‘1’ and its ‘height’ to ‘400,’ all the while recording the time that this change occurred on the screen by storing the value in the numeric variable called ‘Object_Prop_Change_Time.’

Below is a full overview of the fields you encounter when working with the ‘Set Object Property’ action:

Menu Item	Menu Area	Set Object Property Trigger Options
Target object selection drop-down list:		The first drop-down list will display the objects you have in that frame for you to choose from. This indicates which specific object the action will be performed on.
Target property selection drop-down list:		The second drop-down menu indicates which object property is to be changed. For a full explanation of the available options and their parameters, please see the Object Properties Table.
Value-Select-Menu		Define the new value, ie. what the value of the new object property should be as a result of the action.
‘+ Add Property’		Multiple properties can be added and changed under the action by clicking this icon.
Checkbox - Record time when this change is reflected on the screen (measured in milliseconds from frame onset).		When a property is changed, it will take a short amount of time (approx ~10ms for the changes to be visible. With this option you can record more precisely the time when the changed property is really visible on the next display refresh. Note: Upon selecting this option, a dialog box will appear prompting you to indicate (or create a new variable) where this captured value should be stored. The variable should be numeric as the ‘data type.'

Control Media Object

Formerly the separate "Control Audio/Video" and "Control Object" actions.

Effect: Changes the playback of video/audio elements or changes the state of upload/recording elements.

Parameters:

• Target: Select one media object
• Effect: Select a sub action
  • Audio or Video Object options:
    • Start Playback: Starts playing the video / audio file
    • Stop Playback: Stops the video / audio file
    • Pause Playback: Pauses the video / audio file
    • JumpToTime: allows you to specify a time in milliseconds to jump to in the audio/video file
    • Mute: turns off the sound of the object
    • Unmute: restores the sound of the object
  • Audio, Video, or Screen Recording Object options:
    • 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
    • Pause Recording: pauses the recording of the object
    • Resume Recording: resumes the recording of the object
  • File Upload Object options:
    • Start Upload: starts the uploading process for the selected file
    • Clear File: Deletes the selected file
    • Choose File: allows the participant to choose the desired file
  • Camera Snapshot Object options:
    • Start Camera: turns on the participant's camera
    • Stop Camera: turns off the participant's camera
    • Start Upload: begins to upload the snapshot to the experiment
    • Take Snapshot: takes a picture using the participant's camera

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.

Read from/Write to Shared Variable

Effect: Reads from or writes to a variable that is shared across sessions of a study. The variable can be shared with all participants or private to each individual.

Parameters:

• Choose the variable to sync. Must be either scalar or an array.
• Advanced Options
  • Storage key: choose the name of a variable to serve as the key to access the synced variable.
  • Read or Write Method:
    • Read, modify, then write shared variable: reads the variable, makes a change, then sends the variable to the study.
    • Only read shared value from server: calls the variable that is shared within the study, but does not make any changes.
    • Only write variable to server: makes changes to the shared variable, but does not show it to participants.
    • Share values between different participants (not only between sessions): allows participants to see each other's synced variable values across sessions. This option is selected by default, but can be deselected by clicking the checkbox.
• Action Sequence:
  • Choose what happens to the shared/synced variable from the list of all available Actions.

Use Case: Longitudinal/Multi-Session Studies

• With this action, participant-specific data can be carried over from session to session and can be shared among participants across sessions.
• For example, you can use this action to record a score on a test and then allow the participant to compare their score to the mean score of the other participants who have completed the test.
• Another example (similar to the Read from/Write to Device Action) is to have participants pick 5 images they like from an array, perform a task, and then present those 5 images again in a later session. The difference is that this Action can be used to show other participants the images that were picked, or to exclude those images from another participant's available options.

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.

Action Group

Actions can also be organized into action groups. Action groups allow you to group certain actions together for easier visual structure, but also if you want to copy, duplicate, or delete several actions at once. To add an action group, you can find the option under Custom Actions:

API Actions

If you need to send or communicate data from an external server into Labvanced, then ‘API Actions’ and ‘API Triggers’ can be used. You have the following actions available under this category:

• Send To Websocket
• Send to OpenAI

In order for these actions to be ‘available’ or usable, you must input an API Key in the Study Settings under the ‘Experiment Features’ column. Once the API Key has been provided there, then these actions won’t be grayed out from the menu anymore.

Send to Websocket

When selecting this action, the following options appear:

The example above and the full event structure can be accessed here: https://www.labvanced.com/page/library/51053 by clicking ‘Inspect.’

Menu Item	Description
Send To:	Specified the Websocket Address which is listed in the ‘Study Settings’ under the ‘Experiment Features’ column.
Trigger / message to send:	Specify the trigger or message you want to be sent.
Send Variable (optional):	Indicate the variable that can also be sent out as a part of the action.

For more information about API Access, please visit this page.

Send to OpenAI

The ‘Send to OpenAI’ action allows you to send information, such as a string input value, to OpenAI. Please note that for this option to be available, you have to list your API Key under in the ‘Study Settings’ tab under the ‘Experiment Features’ column.

The following options will appear upon clicking this event:

Here is a functional example of how this event looks like when all the necessary information is provided:

For a deeper explanation of how you can utilize this feature and see it in action, please feel free to reach out to us for a demo by submitting this contact form.

Here is a deeper explanation of the fields included under the 'Send to OpenAI' action:

Menu Item	Menu Area	Set Object Property Trigger Options
Model Type		Specifies the AI model that is going to be used. Note: to specify the ChatGPT version, please see the ‘Study Settings’ under the ‘Experiment Features’ column.
Chat History Dataframe		Link to a data frame variable with two columns. The first column will denote the ‘role’ and the second column the ‘chat message.’ The values from the action will be automatically appended to the data frame that is linked here. The data frame can also be manipulated with data frame actions. For further reference, please check the docs from OpenAI.
Insert Message ‘+’		By clicking on this, the variable dialog box will appear. You will need to indicate which ‘Variable’ value is being sent out to OpenAI as well as the ‘role’ of the associated message: system: refers to the high-level ChatGPT system user: the participant assistant: refers to a specific sub-role created within the system

As OpenAI is evolving on a daily basis, please check the docs from OpenAI for further clarifications.

Code Actions

In some cases, your experiment may require you to use custom code. With these actions, you can do just that! The following options are available under the ‘Code Actions’ menu:

• Run JavaScript
• Set Global CSS

Run JavaScript

The ‘Run JavaScript’ action allows you to program specific events and to read/set Labvanced variables in your study by inputting custom JavaScript that will run as an action when triggered to occur.

When the above ‘Run JavaScript’ action is selected, you will see an area (a code editor) where the JavaScript code should be written, as well as instructions on how to use it:

Set Global CSS

With the ‘Set Global CSS’ action, you can use custom CSS code to change an aspect of the study upon a trigger.

The following field opens upon clicking this action:

An example for using the ‘Set Global CSS’ action 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.