Summary

The Labvanced platform consists of various functions to create, run, and share online experiments and psychological studies directly in the browser. For a better overview, the different functions are separated into various sections or tabs. You can navigate between these different tabs and functions by using the navigation panel of the left side. New studies can either be created by adding a new (empty) study in the "My Studies" Tab or by looking through the Experiment Library to find a suitable template study as a starting point. After creating/importing the study you can make use of the "Study Design" and the "Task Editor" to add and adjust the experimental content and logic. Using the "Study Settings" tab you can adjust further settings, e.g. customize the experiment startup, change browser and device settings, as well as a few more general settings. The "Description" tab can be used to add information regarding the study participation, e.g. study title, participation time, keywords, related publications, and the "Variables" tab provides an overview about all variables used in the study. The "Translate" tab can be used to create multilingual studies, and to perform local test runs (with or without data recordings) you can use the "Run" tab. Once you have completed the the study implementation and test recordings you can generate participation links via the "Publish & Record" tab to recruit subject worldwide over the internet. To share your study with your colleagues, and/or the whole community use the "Sharing"tab. Once the data is recorded you can inspect and download it using the "Dataview & Export" tab. There are some further tabs in the navigation panel, which are related to your account, license, profile etc. However, these are not directly important for creating and publishing your study on Labvanced.

Tutorial Video


Study Design

Description

Experiments created with Labvanced have a hierarchical structure, with several nested levels. The "Study Design" defines this overall structure and hierarchy of the study. The smallest building block on the Study Design level are tasks. Hence new (empty) tasks can be created or existing tasks can be imported from other studies. Tasks are then assigned to blocks in order to group related tasks (e.g. 1. instructions, 2. behavioral loop, 3.questionnaire). Blocks in turn are then assigned to sessions and session are assigned to groups. Hence, groups are at the top level, sessions are defined inside groups, blocks are defined inside sessions, and tasks are defined inside blocks. Tasks, Blocks and Sessions can be re-used multiple times, to create different experiment versions based on the same building blocks. When the experiment is executed each participant will be assigned to one group and one session and then be presented with the first task in the first block of that session. After the first task is finished the next task in this block will be executed. Once the block is finished the next block will be executed until all blocks are done. This logic can be adjusted using event logic and the property settings for blocks and sessions.

Note: As a minimal requirement each study has to have at least one group with one session, one block, and one task.

Position

  • My Studies
  • Open a study

  • In the opened study
  • First option in navigation bar

Tutorial Video

Components


Tasks


Description

A "task" is the main instance within a study, in which the content and logic is created. For example, a simple study could consist of the following tasks:

  1. Introduction-Task (Explanation of the task)
  2. Main-Task (Interactive Task with several trials)
  3. Questionnaire-Task (Questionnaire and demographics)
  4. Debriefing-Task (Feedback).

Usage

Creation: A new task can be added via the "New Task" button and can be opened/edited via the "Edit" button. You can also rename tasks via the "pen" icon and delete tasks using the "delete" icon. If a task gets deleted from the "Available Tasks" list, it will also be deleted from each block where it was assigned to.

Assignment: In order for a task to be shown in the experiment, it must be assigned to a block. Multiple assignments one task to the same or different blocks are possible.

Copy / Import: An existing task from another study can be imported via the "ImportTask" button. Also, you can make copies of each task within a study using the copy icon. When copying or importing tasks you will be asked for each variable whether to link (reuse) or copy it (make a new). If you think that the value of the variable in the new task should be independent from the value of the variable old task then choose the option New (copy). In this case a new variable will be created and you will have 2 independent variables / values. However, if you think that the values should be the same, then choose reuse (link). Reusing variables will help to avoid variable clutter in the experiment, however especially for factors variables, copying variables can be the saver option. In general managing variables properly is essential to keep a clean experiment structure.

Step by step

  1. Create a new task by clicking on "New Task".
  2. Give the task a unique name.
  3. Choose a canvas frame for a free design, or a page frame for a static questionnaire, and confirm with "Ok".
  4. Assign the task to a block in the "Blocks" column via the "Add Task" button.
  5. Use Drag & Drop to adjust the order of the task within the block.
  6. Open the task in the task editor via "Edit" button.

Blocks


Description

A block consists of one or several tasks. The order of the individual tasks within a block can be adjusted via drag & drop. Furthermore, by clicking on the properties icon you can choose to use the fixed task order (as defined), or randomize the task order each time the block is executed.

Usage

Creation: A new block can be added using the "New Block" icon and renamed using the "pen" icon.

Assignment: Within a block, a task can be assigned to the block via the "add task" icon and removed using the "delete" icon. In order for a block to be shown in the experiment, it must be assigned to a session. Multiple assignments of one block to the same or different sessions are possible.


Sessions


Description

A session represents a one-time participation of one participant in a study. Hence is also counts as one respondent or recording session. One session can thereby consist of one or several blocks. The order of the individual blocks within a session can be adjusted via drag & drop. Furthermore, by clicking on the properties icon you can choose to use the fixed block order (as defined), or randomize the block order each time the session is executed.

Usage

Creation: A new session can be added via the "New Session" icon, renamed using the "pen" icon, and deleted using the "delete" icon.

Assignment: Within a session, the "add block" icon can be used to assign a new block to the session. In order for a session to be shown in the experiment, it must be assigned to a group. Multiple assignments of one session to the same or different groups are possible.


Groups


Description

A group is the topmost instance in the hierarchical experiment structure. A study must have at least one group but can consist of arbitrary many groups. Each group also must have at least one assigned session, but can also include several sessions. By assigning multiple sessions to one group you can create longitudinal studies (repeated measures). The properties panel of each group can also be used to restrict / differentiate subject participation based on demographic variables such as age, gender, first language, and location.

Usage

Creation: A new group can be added via the "New Group" icon, renamed using the "pen" icon and deleted with the "delete" icon.

Assignment: Within each group one can assign a session to the group via the "Add session" icon. The order of sessions within a group can be changed by drag & drop. However, only longitudinal studies will have more than one session per group.

Demographic Criteria & Group Selection: The group property panel can be opened and be used to define demographic participation requirements individually for each group. The following criteria are possible:

  • Gender: (male, female)

  • Age: minimum and maximum (1 to 120)

  • First Language (selection of all languages)

  • Location / Country (IP based location or participant selected location)

  • Custom Requirement (text-string which has to be approved by the subject)

Based on the participants responses (and IP localization) it will be determined for which groups the subject fulfills the participation requirements. IP address will not be stored but only be used for localization. If no requirements are used or a participant meets the participation requirements for several groups, the group with the fewest participants so far is chosen for that subject. This guarantees an equal number of participants in the different groups (balancing of subjects groups). If a participant does not meet the participation criteria for any of the groups, the subject will not be allowed to participate in the study.

Groups for Between Subject Balancing: Groups can be used for between subject balancing in two ways. First, to (exactly) counter balance the order of tasks or blocks, and second to present slightly different tasks versions to different subject groups. In both cases one can create different groups, and respectively add different sessions, with various blocks and tasks. The automatic balancing of subjects groups will guarantee that there are the same number of subjects in each group.

Longitudinal Studies & Session Order: If several sessions are defined within a group, the session execution order for each participant is strictly chronological. Each participants will first do session nr. 1, then session nr. 2, then session nr 3, and so on. To insure this, new participants will always start with the first session. When the first session is finished, a participant will receive an email which says when the next session will be due, as well as another reminder email once the next session can be started. Within these emails there will be a link which directs each subject then to the next (correct) session. In order to send out these reminder emails Labvanced will ask for the participants' email for longitudinal studies. However, this information will only be stored internally, and not given away to the experimenter or and other person, but only be used for reminding the participants.

Participation Time Settings: For each assigned session within a group, it is possible to determine when this session can be started / executed by the subject. If this participation time has not yet come, or is already over, participants will see (upon website visit) a message and / or a countdown when the session will be available. This is mostly useful for longitudinal studies, but can also be applied for single session studies (e.g if the study should run only at a specific time point). The following settings are available for each assigned session:

  • Participation always allowed / anytime (default value)
  • One specific starting point:
    • earliest starting point (date, time)
    • latest starting point (date, time)
  • Repeated starting point:
    • earliest starting point (date, time)
    • latest starting point (date, time)
    • restart interval: daily/weekly/monthly
  • Depending on former session:
    • earliest starting point (days, hours, minutes after completion of the former session)
    • latest starting point (days, hours, minutes after completion of the former session)


Task Editor

Description

The task editor is where all the experimental content and logic is created and edited. Hence each task can be separately opened and edited with the task editor. Tasks can vary and be modified in many different ways, however the arguably two most important aspects are the frame type(s) which is/are used, and whether there are several trials defined for a task (trial loop activated) or not. Each task can have several frames, which will typically be presented one after the other (this can be changed with event logic). Also, there are two different frame types, a "page frame" and a "canvas frame". On a canvas frame objects /elements such as images, videos, text elements, questionnaire elements etc. can be placed and resized freely using drag&drop. On a page frame the objects / elements automatically flow below each other, but the order of elements can be changed. Hence page frames are ideal to create questionnaires, while canvas frames are perfect to create interactive behavioral tasks. All the interactive / programmatic logic is created by using events separately for each frame. In particular events can be used to change objects (properties) or variables in different kind of ways. In order to create (behavioral) tasks with several trials (repeated presentations of the frames) one can use the build-in trial system. The trial system is another hierarchical structure, which is situated between the task and the frames defined. The main function of the trial system is that is it will generate several runs (trials) of the task which can vary in different ways (e.g. different stimuli, logic, object properties etc.). The defined trials can then be randomized in various ways, i.e. to achieve within or between subject balancing of stimuli, object properties, and much more. Overall, the task editor constitutes most of the functionality of Labvanced and has several submenus. The following documentation will describe the task editors' functionality separated by it's main feature components.

Position

  • My Studies
  • Open a study
  • Within the opened study:
  • Second item in the navigation bar.

Hierarchy

In congruence to the study design, also the task is structured hierarchically. Overall, there are 8 hierarchy levels, which can be grouped into 3 main functions: On the top level is the task, a task can have several trialgroups. Factors are inserted into the trialgroup and all factors have levels which cross with each other (their levels are combined). From the crossing of the factor levels the conditions are created automatically. Within each condition one can specify the number of trials. For each defined trial the frames are shown, and typically each frame has several objects. So the overall task hierarchy looks like this:

  1. The Task (highest instance, contains trialgroups)
  2. Trialgroups (contain factors and frames)
  3. Factors (contain level)
  4. Level (are crossed to create conditions)
  5. Conditions (contain trials)
  6. Trials (modify frames)
  7. Frames (contain objects)
  8. Objects (lowest instance)

Components

Main Functions & Task Settings

At the top left of the task editor are the main functions: saving, start a test run of the task, and switching the task. Also you will see the study name and whether editing is enabled or disabled (locked). Below are the "Task Settings", in which all task-level settings can be changed. In particular these settings are: Display Mode, Randomization, Trial Activation, Initial Countdown, Sync Task, and Editing Language.


Main Functions & Task Settings


Main Functions

The main functions are located at the top left corner of the task editor. Here you can save the whole study using the "Disk" icon, test (run) it via the "Play" icon, and also switch the task you are currently editing.

Task Settings

Under the "Task Settings" you can change the following properties: Display Mode, Randomization, Trial Activation, Initial Countdown, Sync Task, and Editing Language.

  • Display Mode: This settings changes how the study is rendered on the screen.
    • Fullscreen / zoom (default option): When choosing this option, the sizes are in "Design Units" (unit-less). Upon experiment execution all frames are rescaled until a maximum size is reached either horizontally or vertically. So the experiment will always "use the whole screen". All objects on the frames are also rescaled (smaller on small displays, larger on large displays).
    • Fixed in Visual Degree: If this option is selected, all sizes are re-calculated to visual degree. Therefore, the experimenter has to specify a re-calculation factor, which says how many "design units" are 1 visual degree. For instance, if an object is 120 "design units" wide and the re-calculation factor is 20, then the object will be 6 visual degrees wide when the experiment is executed. To insure this, an external size calibration is carried out before starting the experiment. So in the beginning the participant has either to specify the size of the screen in inches, or use a standard plastic card to determine the size of the screen. Additionally, the participant needs to select his/her distance to the screen. Based on these two values all frames and objects are then re-calculated to visual degrees.
    • Fixed in Millimeter: If this option is selected, all sizes are re-calculated to millimeter. There is no re-calculation factor, but all values are directly in millimeter. Similar to the "Visual Degree" option, there is a calibration in the beginning of the experiment to determine the screen size. However, distance is not needed in this case. All objects and frames are then rescaled based on their millimeter values.
    • Fixed in Pixels: If this option is selected, all sizes are re-calculated to pixels. There is no re-calculation factor, but all values are directly in pixels. There is also no calibration needed. Frames and objects will be smaller or larger depending on the participants' screen resolution and the screen size.

  • Randomization / Edit: By pressing the "Edit" button the trial randomization menu will open up. All details about trial randomization are described here.

  • Activate Trials: This option will enable or disable the trial loop / the trial system.
    • Checked / Yes: The trial loop is activated. There can be more than 1 trial / repeated presentation of frames.
    • Unchecked / No: The trial loop is deactivated. There can be only 1 trial (1 run of the task) / no repeated presentation of frames.

  • Display Initial Countdown: Turns the initial task countdown on or off.
    • Checked / Yes: There is an initial countdown (3,2,1..) before the task task.
    • Unchecked / No: There is no countdown, the task starts directly.

  • Sync Task Start: This option is only important for multi participant studies. It will turn on or off the synchronization of the start of the task between participants.
    • Checked / Yes: The start of the task is synchronized between participants. If one participants starts this task earlier, he / she will have to wait until all participants are ready to start this task.
    • Unchecked / No: The start of the task is not synchronized between participants. Each participant can start / execute this task independent of the other participants and does not have to wait.

  • Edit Language: This option is only important for multi lingual studies (studies in several languages). By changing the the "Edit Language" one can switch which language is shown in the task editor.


Trial System


Description

In the task editor, the trial system is located on the left side. In general, the trial system is used to create several repetitions (trials) of a task . The trial system consists of two parts, the "Factortree" and the "ConditionTable". When the "Factortree" is edited by the Experiment Designer (changing trialgroups, factors or levels), the "ConditionTable" is automatically updated based on the settings in the "Factortree".

Tutorial Video

Factortree

The factortree can be used to change and modify the top hierarchical structure of a task. Specifically, it is there to modify the 3 top elements of the task hierarchy which are:

  • Trialgroups (contain factors and frames)
  • Factors (contain level)
  • Level (are crossed to create conditions)

Trialgroup

The trialgroup acts as a container for a group of trials within the task which are roughly similar. Most importantly, all trials within a trialgroup have the same series of frames, with the same objects and events on them (although properties of objects can events can change from trial to trial). So in other words, the trialgroup sets the overall structure of a trial. Each task needs at least one trial group.
As in some tasks, very different types of trials should be intermixed (e.g normal and catch trials), multiple trialgroups within a task can be used to create and intermix very different trials within a task.

Factors

By adding factors (with levels) to a trialgroup, one can create different versions of a trial. Typically, the name of the factor thereby says which aspect of the trial should be varied, (e.g. position, size, image catetory etc). The levels of the factor then describe the characteristics of the change (left / right, small/medium/large, houses,faces etc). The more levels a factor has the more (trial) variations exist and the larger is the stimulus space. This also means a factor must have at least 2 levels to extend the overall stimulus space. Importantly, each factor is at the same time also (linked to) a variable, a factor variable. This is useful for two main reasons. First, because events can thereby be be customized to certain conditions (e.g. you can specify: do something ONLY IF Factor "Image Category" equals level "house"). Second, for each trial it is recorded, which value a factor had on that trial, so that later the experimenter can easily separate different conditions. When adding a factor to a triagroup, you can choose to reuse an existing factor variable, or create a new variable. One can link factor variables within or across tasks, but it is important to know that a change of a linked factor variable will trigger changes is all tasks and trialgroups where the factor is used.
Furthermore, factors can be either fixed or random. This distinction does not affect how many trial variations are defined. but it will affect how many trials a subject sees when the task is executed. Fixed factors do generate more trials when the task is executed, random factors only generate more trial possibilities to choose from for each trial. So if the factor "position" with the levels "left" and "right", is fixed, a subject would see a "left" variation AND a "right" variation of the trial. However, if the factor position would be random the subject would see a "left" variation OR a "right" variation of the trial. For more information on factor randomization see the chapter on trial randomization.
A trialgroup must have at least one fixed factor and each factor must has at least one level.

Levels

The levels are the possible values for each factor and thereby determine the characteristics of each factor. The factor "image-category" could, for instance, have the three levels "houses, faces, cars". If this factor is the only factor in the trial group a condition is created for each level, which is displayed in the "Condition Table" at the bottom left. If several factors are created, each level of a factor is combined with all the levels of the other factors within the factor group (factors cross). In a 3 factor design with factor "image-category" having 3 levels, factor "position" with 2 levels, and factor "size" with also 2 levels, there would be 3 x 2 x 2 = 12 conditions in total.

Usage: To define which exact influence a factor level will introduce, one can directly select (click on) the factor level in the Factortree and then modify the objects on the current frame. The respective changes will affect all trials and conditions in which the respective factor has the chosen level. So this approach is particularly useful when a stimulus variation is dependent on the level of factor, but not on a condition or a single trial.

Condition Table

The "Condition Table" can be used to modify the middle layer(s) of the task hierarchy, specifically, conditions and trials. Due to the hierarchical nature of a task, the crossing of the factor levels generates the conditions separately for each trialgroup. These are then shown in the Condition Table at the bottom left of the task editor. So whenever there is a change in the factor tree, the Condition Table will update automatically. For each condition, the number of trials can be defined separately. It can also be set to 0 in case some condition should not be shown at all.

Default Trial

The Condition Table is also grouped according to trial-groups and each trial group has exactly one "default-trial" in the Condition Table. The default trial is located in the first row for each trial group, above the conditions. When the default trial is selected all the changes which are made are applied to all trials in the trial group. Any (trial, condition, level) variations, which were made before will be overwritten by changes in the default trial. Hence modifying the default trial resets all trials in a trial-group to the same "default" value. In other words, via the default trial, all trials within a trial group are selected ánd edited simultaneously. This is mostly useful to define the rough overall structure of a frame.

Usage: It is most reasonable to place new elements first in the default trial and then adjust the variation, using the condition or trial selection.

Conditions

The conditions are determined by the number and crossing of factor levels. Therefore, each condition is clearly defined by the values (factor levels) of all factors in it's trial group. For instance, one condition could be defined by the following three level values: face image, left, small; while another condition could be defined by the values: face image, left, large, and so on.

Usage:To make changes to the individual conditions, one can select (click on) the condition, and then make changes to objects on the canvas. The changes made will then apply only to the selected condition (i.e. all the trials in that condition). Thereby, it is possible to adjust the interactions of the individual levels more precisely.

Trials

Trials are located within the conditions and therefore are the most basic unit in the trial system hierarchy. Each condition is created by default with one trial. However the number of trials per condition can be adjusted in the Condition Table.

Usage: If there are several trials within one condition, the condition can be opened (expanded) in the "Condition Table" and individual trials can be selected. Consequent changes to the canvas and objects will then only apply to this particular trial.

Workflow

  1. Setup the general task structure in the default trial by adding frames and objects.
  2. Create factors and levels in the "Factortree". Name them appropriately to make changes later more easy to understand.
  3. Select a factor level in the Factortree and make changes on to the frame /objects that correspond to the level. Repeat this process for the other levels.
  4. Select a condition in the condition table and make the corresponding changes for the selected condition.
  5. Set the number of trials (# trials) for each condition.
  6. To edit individual trials, expand the condition and select a single trial.
  7. To add or edit elements again for the entire trialgroup, select the default trial again.

Generate Trials By Adding Stimuli

The trial structure can also be created (automatically) via the file manager and the integrated multi-select function. This is mostly useful if the variation is produced by different stimulus content (different images, videos, sounds etc.). To do so, an image, video or sound object (container) must be selected, and then the file manager must be opened via the folder icon in the properties panel. Then select several (2 or more) pictures/videos/audio files and click on the "Assign" icon (grid symbol with arrow) in the lower right corner.
A new menu will open up asking you how to use these multiple selected files. Here you have 3 main options how to assign / use the selected files, with some sub-options:

  • 1.Trials: Assign the files to trials.
    • 1.1. Assign files to existing trials: The image/video/audio files will be assigned to already existing trials in the selected condition.
    • 1.2. Create as many trials as files selected: The image/video/audio files will be matched to the number of trials in the selected condition. There will be exactly 1 trial for each selected file. Former trials in the condition will be removed.
    • 1.3.Create a new trial for each selected file: For each selected image/video/audio file a new trial will be added to the selected condition. The new trials will be appended to existing ones.

  • 2.Conditions: Assign the files to existing conditions.

  • 3. Factor Levels: Assign the files to factor levels.
    • 1.1. Assign files to existing factor levels: The images/video/audio files will be assigned to already existing levels in the selected factor.
    • 1.2. Create new levels within an existing factor: For each image/video/audio file a new level will be added to the selected factor. The new levels will be appended to existing ones.
    • 1.3. Create a new factor and new levels: A new factor will be create. Then for each image/video/audio file a new level will be added to this newly created factor. Hence there will be exactly 1 factor level for each selected file.

After choosing the overall assignment method, you can determine which file should be assigned to which trial, condition, or factor level. The respective menu will display two lists, one for the selected files (right), and another for the assignment items (left). You can then drag & drop individual files from the right to the left, and thereby manually determine which file should be associated to which trial, condition, or factor level. However, you can also use the "Auto Assign" button, which will assign all files automatically in a random order. This way you can setup your stimulus associations very fast.

Working with Trials

If the factorgroups, factors, levels, conditions, and trials are setup and frames and objects were added, the main task for the experimenter is to modify the object properties such that different trials will show different stimuli, in different positions, with different sizes etc. Here it is of central importance to select the appropriate modification level for each modification made. Overall, there are 4 levels of modification:

  • Trial-Group-Modifications using the "Default Trial":
  • Changes all trials with the selected trialgroup.

  • Factor-Level-Modification:
  • Changes all conditions (and trials within these) in which the selected factor possesses the selected factor level.

  • Condition-Modification:
  • Changes all trials within the selected condition.

  • Trial-Modification:
  • Changes Only the selected trial.

Frames


Description

Frames are the second lowest instance in the task hierarchy, and for each trial a series of frames will be shown during experiment execution. However, frames are not created within trials but within each trial group, hence different trialgroups have completely independent frame sequences. Trials can then modify the frame properties and objects on each frame. Typically, one trialgroup has several frames. Dy default the different frames are presented sequentially (one after the other) upon experiment execution, but the order can also be completely customized, by using the event system. There are two different frame types: canvas frames and page frames, and they can be used intermixed in each trialgroup (although many times it will make sense to keep them separate). Both can be added to the current selected trial group via a click on the respective icons in the "Trial Timeline". Furthermore, frames can also be deleted, copied, and imported from other tasks / studies. Similar when importing tasks, when importing frames you have to specify for each variable, how it should be used on the newly copied frame. You can choose either to copy it (create a new one), or re-use it (link it to the existing one). The default oder of frames can be changed by dragging each frame to a specified position. The "current selected frame" be selected via a mouse click and is shown in the center of the task editor. Both canvas and page frames share a few frame properties, these are:

  • Name (String): Name of the frame.
  • Duration (Enabled/Disabled): If enabled one can specify a fixed display duration for the current frame in milli seconds. After this time is over the next frame will be shown automatically. HINT: This is an easy option to "jump to the next frame". However, it might lead to problems if you additionally add event logic to jump to the next frame or other frames. Hence, enabling this option is only recommended, if the frame duration is always fixed, and there is no custom "jumpTo" event to jump to a different frame.
  • Color (Hex-String): Background color of the frame
  • Hide Mouse: (Enabled/Disabled): If enabled the mouse will not be shown.

Tutorial Video

Differences Between Canvas & Pages Frames

Canvas and page frames differ in various ways. Most importantly, on a canvas frame, objects can be positioned freely, be rescaled, and modified using drag & drop. One can also zoom in and out on canvas frames. Optional auxiliary lines help to position the objects and this "grid" can be shown or hidden in the editor (checkbox below the frame). All in all, the canvas frame allows you to edit the content very individually.
Page frames are used in particular to create questionnaires, which can be designed very efficiently by a pre-defined layout. Hence objects on a page frame cannot be positioned freely, but instead automatically flow below each other, while the order of elements can be changed easily. Instead of zooming in and out, one can scroll up and down using the mouse-wheel. Also, instead of a auxiliary grid lines one can activate a preview mode to see show a page frame will look like during experiment execution (checkbox below the frame).
A further difference is that (first class) media objects such as images, videos, and audio files can only be added to the canvas frame. However, by using the text editor (above the current frame), images can be inserted within text elements and thereby also appear on a page frame. The two types of frames also have a few different general properties, these are:

Special Canvas Frame Properties:
  • Frame Height (Numeric): Determines the height of the frame in Design Units.
  • Frame Width (Numeric): Determines the width of the frame in Design Units.
Special Page Frame Properties:
  • Max-Width (Numeric): Determines the maximum width of the frame in Pixels.
  • Border-Size (Numeric): Determines the border size of elements within the page frame.
  • Element Margin (Numeric): Determines the lower margin of elements within the page frame.

Finally, there are further differences in the properties of objects, which are added onto the two different frames. These properties and differences are completely described in the object section.

Usage

All frames in the selected trial group are shown in the "Trial Timeline" (bottom center). The frame which was clicked on last is the current selected frame and it's content is shown in the center frame. Objects and events can be added separately to each frame. The "properties" of the current selected frame are shown to the right of the Trial Timeline. The order of frames can be changed using drag&drop and existing frames can be can be copied, deleted and imported.


Objects


Description

Objects are the lowest instance in the task hierarchy as they are placed onto the frames. In the task editor objects are grouped into 7 groups ( 1. Media-Objects, 2. Shapes, 3. Text-Object, 4. Buttons&Navigation, 5. Question-Options, 6. Question-Inputs, 7. Various ). Objects can be added to the frame via the object toolbar, which is located left to the frame. A list of all objects on the current selected frame is shown on the right side under the "Objects" tab. Here one can also change the z-index of an object (which object is shown in front), copy and delete objects. The "current selected object" can be chosen either by clicking on it directly via the frame, or by clicking on the respective object in the object list. After selecting an object and the appropriate modifier (Default Trial, Factor Level, Condition or Single Trial) changes / modifications can be made directly on the canvas or by using the "Object-Properties" panel on the right. In this panel, all properties of the currently selected object are displayed and can be modified using the input fields, checkboxes, etc.

Position

All available objects are listed in the toolbar, left to the canvas. By clicking on toolbar icon, the corresponding object is added to the current selected frame.

Tutorial Video

Object Properties

The object properties are shown on the right for the current selected object. These properties determine how each frame (i.e. the objects on the frame) will look like and hence they are very important in the experiment creation process. Many object properties can be modified between trials, while some properties (e.g the object's name) are fixed and cannot be different between trials. Properties which are modified (different from the default value) are indicated by having a dark gray background color. Furthermore, all the properties, which can be modified between trials can also be modified dynamically during the event execution, using the "set obj property" action. This allows for very interactive and dynamic experiments. All objects share many general properties. However, most objects also have some custom, unique properties. Furthermore, the properties for the same object can vary between canvas and page frames. Below is a list of all general object properties, also highlighting the differences between canvas and page frames.

General Object Properties
Property Name Data Type Modifiable Frame Type Description
Name String No Canvas & Page The name of the object. The name is used many times as reference to the object (i.e. within events).
Anchor Categorical (1-9) No Canvas The anchor sets the "position reference point" of the object. By default this is the top left corner.
Keep aspect ratio Boolean (true / false) No Canvas Determines whether the objects aspect ratio is kept when the object is rescaled.
Overflow-X Categorical (Hidden,Auto,Visible) No Canvas Determines whether the object will have a visible scrollbar in the X dimension.
Overflow-Y Categorical (Hidden,Auto,Visible) No Canvas Determines whether the object will have a visible scrollbar in the Y dimension.
Active Boolean (true / false) Yes Canvas & Page Determines whether the object is active and can be changed during the experiment execution. If set to false the object will not elicit any actions.
Visibility Numeric (0-1) Yes Canvas The transparency value of the object. With a value of 0 the object will the completely invisible, 1 is completely visible.
X Numeric (0- width of frame) Yes Canvas The X position of the object.
Y Numeric (0-height of frame) Yes Canvas The Y position of the object.
Width Numeric (0-width of frame) Yes Canvas The width of the object.
Height Numeric (0-width of frame) Yes Canvas The height of the object.
Scaling Numeric (0-Inf) Yes Canvas Changes the scale / zoom of the element. Larger values will zoom in the element.
Rotation Numeric (0-359) Yes Canvas Changes the objects' rotation. 0 will be the upright position.
Border-Size Numeric (0-INF) Yes Canvas Changes the objects' border size. 0 will show no border.
Border-Color Hex String (Color) Yes Canvas Changes the objects' border color.
Background-Color Hex String (Color) Yes Canvas Changes the objects' backgrounds size. By default there will be no color / transparent.
Roundness Numeric (0-1) Yes Canvas Changes the objects' roundness. 1 will be a complete round object, 0 will be a squared object.
Selectable Boolean (true / false) Yes Canvas Determines whether the object can be selected / highlighted during the experiment execution.
Draggable Boolean (true / false) Yes Canvas Determines whether the object can be dragged during the experiment execution.
Resizable Boolean (true / false) Yes Canvas Determines whether the object can be rescaled during the experiment execution.
Visible Boolean (true / false) Yes Page Determines whether the object is shown or not. If the object is not shown other objects will re-flow automatically.
Shuffle Page Position Boolean (true / false) No Page Determines whether the objects' position on a page will be randomized for between subject balancing.
Margin Numeric (0-Inf) No Page Changes the left, right, top and bottom margin properties for the element.
Padding Numeric (0-Inf) No Page Changes the left, right, top and bottom padding properties for the element.

Object List & Custom Properties

Media-Objects

Image-Object

The image object can be used to show an image on a canvas frame. The image which is shown can be set manually via the file-manager, but can also be changed dynamically during experiment execution using events and variables (data type file).



Tutorial Video

Video Object

The video object can be used to show /play a video on a canvas frame. The video which is shown can be set manually via the file-manager, but can also be changed dynamically during experiment execution using events and variables (data type file).



Tutorial Video

Audio Object

The audio object can be used to show /play an audio file on a canvas frame. The audio file which is shown can be set manually via the file-manager, but can also be changed dynamically during experiment execution using events and variables (data type file).



Tutorial Video



Audio Recording Object

The Audio Recording Object acts as a visual interface / handle for sound recordings during the experiment execution. Via buttons the recording can be started and and stopped, and the recording can also be uploaded to the Labvanced server.

Tutorial Video



I-Frame Object

The I-Frame Object can be used to display an I-Frame (embedded other website) inside the experiment.

IMPORTANT: In order that the I-Frame can be displayed, the server controlling target URL must:

  • set the http header "Access-Control-Allow-Origin" to be either "*" or it must include "labvanced.com"
  • NOT set the http header "X-Frame-Options"


Media Objects Properties:
Property Name Data Type Modifiable Object Type Description
Filename String Yes Image, Video & Audio The file name is the given name of the file.
Filedata File Variable Yes Image, Video & Audio The filedata represents the actual data (image,video,audio). It can be stored directly in the element or within a variable using the data-type "file".
Select File (Folder Icon) Function Yes Image, Video & Audio A click on the folder icon opens the file manager, so that a file-association can be chosen for an (image,video,audio) element.
Stimulus Info String Yes Image The Stimulus Info is a modifiable property an can be used to store dynamic stimulus information during the experiment execution.
Stretch to Fit Bounding Box Boolean (true / false) No Image When activated Stretch to Fit Bounding Box will stretch the image inside to completely fill-up the bounding box.
Bounding Box Fit Function No Image Upon a click the bounding box will be cropped to reach the dimension on the image inside.
Show Media Controls Boolean (true / false) No Video & Audio Via this option it can be selected whether the control panel should be visible during experiment execution.
Play/Pause File Function No Video & Audio This can be used to Play/Pause a video or audio file within the task editor.
Show Question Header Boolean (true / false) No Audio Recording This options will show or hide the integrated header text element.
Required Boolean (true / false) No Audio Recording When activated this element will be required to be answered / used. "Jump To" actions will check whether all required answers are fulfilled before being executed.
Linked Variable Variable No Audio Recording The Linked Variable field points to the variable where the path to the recorded file is stored.
Show Recording Button Boolean (true / false) No Audio Recording This option will show or hide the Recording Button.
Show Play Button Boolean (true / false) No Audio Recording This option will show or hide the Play Button.
Show Upload Button Boolean (true / false) No Audio Recording This option will show or hide the Upload Button.
Show Seekbar Boolean (true / false) No Audio Recording This option will show or hide the Seekbar.
Target URL String Yes I-Frame This determines the target URL for the I-Frame
Shape-Objects
Text-Objects
Shape & Text Object Properties:
Property Name Data Type Modifiable Object Type Description
Linked Variables Variable Array No Display Text The Linked Variables field lists all variables with are inserted / rendered within the Display Text Element.
Buttons & Navigation

Button-Object

A standard button whose text can be edited and which can trigger events using the trigger "ButtonClick".


Tutorial Video

Navigations-Object

A prefabricated button set that is created with two buttons and two associated events, allowing the subject to navigate to the next and to the previous frame.

Tutorial Video

Progressbar-Object

The progress bar which can be used to display the progress of the experiment in percent.


Tutorial Video

Buttons & Navigation Object Properties:
Property Name Data Type Modifiable Object Type Description
Add Button Function No Button & Navigation Adds a new button to the element.
Remove Button Function No Button & Navigation Removes a button from the element.
Default Color Hex String (Color) No Button & Navigation The Default Color is the color, which is shown when the mouse is not over the element.
Hover Color Hex String (Color) No Button & Navigation The Hover Color is the color, which is shown when the mouse hovering over the element.
Progress Type Categorical (Fixed / Variable) No Progress Bar This option can be used to set either a fixed progress value or a dynamic progress values by linking the value to a variable.
Progress Numeric (0-100) No Progress Bar Fixed progress value of the progress bar element.
Linked Variable Variable No Progress Bar The Linked Variable field points to the variable where the current value of the progress bar is stored.
Question Objects

Checkbox Element

A question element which can be checked or unchecked. One checkbox element can have several checkboxes.


Tutorial Video

Multiple-Choice

A question element in which only one answer from several alternatives can be selected.


Tutorial Video

Likert Scale

A question or statement where the agreement is provided on a numeric scale.



Tutorial Video

Matrix Element

An element where several questions or statements can be inserted (into rows). Each questions / statement is answered within same scale (shown in the columns).

Tutorial Video

Question Objects Properties:
Property Name Data Type Modifiable Object Type Description
Show Question Header Boolean (true / false) No Checkbox, Multiple Choice, Likert, Matrix This options will show or hide the integrated header text element.
Required Boolean (true / false) No Checkbox, Multiple Choice, Likert, Matrix When activated this element will be required to be answered / used. "Jump To" actions will check whether all required answers are fulfilled before being executed.
Randomize Item Order Boolean (true / false) No Checkbox, Multiple Choice Activating this option will lead to a "position reshuffling" of the items inside this element (i.e. for the purpose of between subject balancing).
Linked Variables Variable Array No Checkbox,Matrix The Linked Variables field is a list of all variables which are associated /linked to the respective element. Each variable points to the current answer / selection of the associated element.
Linked Variable Variable No Multiple Choice,Likert The Linked Variable field points to the variable where current answer / selection of the element is stored.
Add Checkbox Function No Checkbox Adds a new checkbox to the checkbox element.
Remove Checkbox Function No Checkbox Removes the last checkbox element from the checkbox element.
Add Option Function No Multiple Choice Adds a new option to the multiple choice element.
Delete Option Function No Multiple Choice Removes the last option from the multiple choice element.
Entry / Variable Value String No Multiple Choice The table lists all option of the multiple choice elements. The "Variable Value" field can be use to change the associated variable value for each option.
Allow Custom Answer Boolean (true / false) No Multiple Choice When this option is activated a custom input element will be shown as an "custom answering option" .
Show only if last option selected Boolean (true / false) No Multiple Choice When this option is activated the "custom answering option" will only be shown once the last option of the multiple choice element is selected.
Balance Label Sides Boolean (true / false) No Likert Activating this option will lead to a label/position reshuffling of this element (i.e. for the purpose of between subject balancing).
Show Numbers Boolean (true / false) No Likert This option controls whether the numbers will be shown above the element or not.
Numbers from Categorical (1-12) No Likert This chooses the starting number of the element.
Numbers to Categorical (1-12) No Likert This chooses the end number of the element..
Inner Margin Numeric (0-Inf) No Likert This can be used to adjust the horizontal margin between the options inside the element.
Add (Matrix Choice/Column) Function No Matrix Adds a new choice / column to the element. The text of this choice can be edited using the text editor.
Delete (Matrix Choice/Column) Function No Matrix Removes a choice / column from the element.
Add (Matrix Question/Row) Function No Matrix Adds a new question / row to the element. The text of this question can be edited using the text editor.
Delete (Matrix Question/Row) Function No Matrix Removes a question / row from the element.
Insert / Delete from Categorical (top, bottom, left, right) No Matrix This can be used to specify from where entries should be added or removed. Insert / remove elements from the top/button (for questions), left/right (for choices).
Left-Right Ratio Numeric (0-100) No Matrix This can be used to adjust how much space (in %) the choice columns should have compared to the questions.
Outer Margin Numeric (0-Inf) No Matrix This can be used to adjust the outer margin of the element.
Input Objects

Input

the input element can be used to answer questions in different formats (Numeric, String, Date, Time, Color)

Tutorial Video

Paragraph

The paragraph element is suited to answer longer text based questions.

Tutorial Video

Input Object Properties:
Property Name Data Type Modifiable Object Type Description
Show Question Header Boolean (true / false) No Checkbox, Multiple Choice, Likert, Matrix This options will show or hide the integrated header text element.
Required Boolean (true / false) No Checkbox, Multiple Choice, Likert, Matrix When activated this element will be required to be answered / used. "Jump To" actions will check whether all required answers are fulfilled before being executed.
Input Type Categorical(Number, Text, Date, Time Color) No Input Depending on input type, the input field will either ask for a text input, a numeric input, a date, a time, or a color. The input type also decides which data type the associated variable wll have.
Linked Variable Variable No Input,Paragraph The Linked Variable field points to the variable where current answer / selection of the element is stored.
Min-Value Numeric (-Inf + Inf) No Input The Min-Value is optional for numeric inputs, and will set the requirement for the minimum value that is regarded valid.
Max-Value Numeric (-Inf + Inf) No Input The Max-Value is optional for numeric inputs, and will set the requirement for the maximum value that is regarded valid.
Max-Nr-Chars Numeric (0-Inf) No Input The Max-Nr-Chars is optional for text inputs, and will set the requirement for the maximum number of characters which can be used.
Inner Height Numeric (0-100) No Paragraph This option will change the relative inner height of paragraph elements.
Inner Width Numeric (0-100) No Paragraph This option will change the relative inner width of paragraph elements.
Outer Height Numeric (0-Inf) No Paragraph This option is only available on page frames. It can be used to change the total height of paragraph elements.
Various Objects

Range

A question with a slider as a response option.



Tutorial Video

Selection

A question with a drop down menu as answer option.



Tutorial Video

Sortable

A question and several elements which can be sorted using drag & drop.



Tutorial Video

Upload

The upload element can be used by subjects up upload files to the Labvanced server. The experimenter can later access these files.

Tutorial Video

Various Object Properties:
Property Name Data Type Modifiable Object Type Description
Show Question Header Boolean (true / false) No Range,Selection,Sortable,Upload This options will show or hide the integrated header text element.
Linked Variable Variable No Range,Selection,Sortable,Upload The Linked Variable field points to the variable where current answer / selection or file-path of the element is stored.
Required Boolean (true / false) No Selection,Upload When activated this element will be required to be answered / used. "Jump To" actions will check whether all required answers are fulfilled before being executed.
Values from Numeric (0-Inf) No Range The minimum value of the range element.
Values to Numeric (0-Inf) No Range The maximum value of the range element.
Show Numbers Boolean (true / false) No Range This option can be used to show or hide the numbers above the range element.
List Use Categorical (Predefined List / Create Manually) No Selection This option determines whether the selection list is created manually or a pre-defined list (i.e language, country) will be used.
Add (Selection Item) Function No Selection Add a new selection option to the list
Available Options (Text Entry) String No Selection The text entry depicts the text string which is shown as an selectable option in the dropdown list.
Available Options (Variable Value) String No Selection The variable value depicts the value of the associated variable when this option is selected in the dropdown list..
Activate Sorting Boolean (true / false) No Sortable This option switches between the possibility to actively sort the elements in the sortable list, and editing their content using the text editor.
Add (Sortable Item) Function No Sortable This add another item to the sortable list.
Current Sorted State Table No Sortable The Current Sorted State table list all items in the sortable list with their respective indices. The associated variable values are shown in the "Element Names" column. Here entries can also be edited and deleted.
Show Selected Filename Boolean (true /false) No Upload This option will show or hide the Selected File Name.
Show Browse Button Boolean (true /false) No Upload This option will show or hide the Browse Button.
Show Upload Button Boolean (true /false) No Upload This option will show or hide the Upload Button.

Variables


Description

Variables can be used for different purposes in the experiment creation process on Labvanced. As a general description one can say that variables hold and update values / information, which is created either in the editor (implementation time) or during the experiment execution (run time) by different means. Importantly, all variables within a study are defined, and can be used globally, which means from everywhere in the experiment. Hence there is an own "Variables" tab in the main navigation panel, where all variables of a study are listed.
However, for a better understanding where variables are used, each frame within the task-editor lists all variables that are used on this frame. Of course one variable can therefore be used on different frames and tasks throughout the whole experiment.
A change of a variable can trigger an event, but events can also change a variables' value. Furthermore, variables can also directly change the state of certain objects. For for a better overview and to some extend differentiate the different use cases, variables are categorized into 5 main categories:
1.System Variables, 2.Factor Variables, 3.Object Variables, 4.Custom Variables, 5.Unused Variables.
While the overall properties and functionality is identical for variables within different categories, there are quite a few differences, in the way how they are created, used, updated, recorded and so on. The next paragraphs will describe these functions and their differences in more detail.

Position

Within the task editor, the variables, which are used on the current selected frame are listed under the "Variables" tab on the right corner. Here each variable is shown with it's most important properties: The main category, it's data type, and it's name. Variables can also 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 (e.g. for a certain action). However, when you are asked to select a variable you usually can select an existing one, but you can also create a new variable. Furthermore, 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.

Tutorial Video

Tutorial Video

Variable Properties

For each variable one can select / determine different properties and one can also provide a short text description that summarises what the variable is used for. The name and the data type properties are mandatory the other properties are optional or cannot be "unset". Below is a list of all properties their values and descriptions.

Name

Description: The name is used as a handle to the variable in events, objects, when copying tasks, and later also in the data-view. Hence, the name MUST BE UNIQUE (there may not be 2 or more variables with the same name). Otherwise severe errors can occur! The name property can be changed in all variables but 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. A Boolean variable can only have two possible values, true or false, a numeric variable must have a number as a value and so on. As a result the data type also determines what kind of mathematical operations can be applied to a variable (e.g. multiplication only works with numeric variables).

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 hold only 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, video or audio files.
Scale

Description: The scale of a variable determines the "level of measurement" of the variable. This distinction is mostly useful for variables with a numeric data type and defines the relation of the variable values. The property is not yet used further in the Labvanced platform, but in future extension, i.e. an analyzing module this property might play an important role.

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 an array of values.
Start Value

Description: The start value of a variable determines the default / reset value of the variable. The start value can thereby be used to reset a variable value each trial to a certain value. Also, the start value can 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 of course possible to not only define one start value, but to fill the complete array. For instance one can upload a list of words (CSV file), images, videos, audio files, etc. in to 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, which code / record a participants response or reaction time. However, variables which accumulate data over trials (e.g for feedback) or data arrays storing information persistently, should not be reset.

Possible Values:
  • Checked (true): Variable will be reset to start value.
  • Unchecked (false): 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:
  • Checked (true): Variable will be recorded.
  • Unchecked (false): Variable will not be recorded.
Record Type

Description: The record type of a variable determines whether all value changes (during a trial) of a variable will be recorded or just the final value in each trial. If all changes are recorded, each variable change will be saved together with a timestamp. Hence, 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 the correct experiment execution, and for data the export. Hence are created automatically and cannot be modified or deleted. Furthermore, system variables are also very useful to use 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 listed below with an explanation, but they are also shown in the main variable menu.

List of System Variables:
Variable Name Data Type Description
Subject_Code String The variable "Subject_Code" is a unique string for each subject / session across all experiments running on Labvanced. This can be used to uniquely identify each participant or session.
Subject_Nr String The variable "Subject_Nr" is a global counter of participants in a study. This can be used to do custom between subject randomization and to infer the overall number of participants in a study.
Subject_Nr_Per_Group Numeric The variable "Subject_Nr_Per_Group" is a counter per subject group in a study. This can be used to do custom between subject randomization and to infer the current number of participants within each subject group.
Group_Name String The variable "Group_Name" holds the value of the "subject group name" for each participant. This can be used to infer to which subject group each participant is assigned to.
Session_Start_Time Date The variable "Session_Start_Time" records the start time of the current participant session in UNIX time.
Session_End_Time Date The variable "Session_End_Time" records the end time of the current participant session in UNIX time.
Session_Name String The variable "Session_Name" holds the value of the "session name" for the current session. This can be used to infer which session is currently performed by the participant.
Session_Nr Numeric The variable "Session_Nr" holds the current value of the "session nr" for the current session. This can be used to infer whether the participant currently performs the first, second, third,(and so on) session.
Block_Name String The variable "Block_Name" holds the current value of the "block name" for the current session. This can be used to infer which block is currently performed by the participant.
Block_Nr Numeric The variable "Bock_Nr" holds the current value of the "block nr" for the current session. This can be used to infer whether the participant currently performs the first, second, third,(and so on) block in this session.
Task_Name String The variable "Task_Name" holds the current value of the "task name" for the current block. This can be used to infer which task is currently performed by the participant.
Task_Nr Numeric The variable "Task_Nr" holds the current value of the "task nr" for the current block. This can be used to infer whether the participant currently performs the first, second, third,(and so on) task in this block.
Trial_Id Numeric The variable "Trial_Id" holds the current value of the "trial id" for the current task. This can be used to infer which Trial is currently performed by the participant.
Trial_Nr Numeric The variable "Trial_Nr" holds the current value of the "trial nr" for the current task. This can be used to infer whether the participant currently performs the first, second, third,(and so on) trial in this task.
Condition Id Numeric The variable "Condition_Id" holds the current value of the "condition id" for the current trial. This can be used to infer which condition is currently performed by the participant.
Browser_Spec String The variable "Browser_Spec" holds the value of the browser used by the participant to perform the experiment. This can be used to later analyze possible differences between browsers. Allowing/forbidding certain browsers can be done via the study settings.
System_Spec String The variable "System_Spec" holds the value of the operating system/device used by the participant to perform the experiment. This can be used to later analyze possible differences between operating systems/devices. Allowing/forbidding certain operating systems/devices can be done via the study settings.
Agent_Spec String The variable "Agent_Spec" holds the complete String of the "User-Agent-Browser-Specification". This can be used to get some more detailed information about the participants system specifications.
BrowserVersion_Spec String The variable "BrowserVersion_Spec" holds the value of the browser version used by the participant to perform the experiment. This can be used to later analyze possible differences between browser versions.
Always_Fullscreen Boolean The variable "Always_Fullscreen", is a boolean value, which is true as long as the participant keeps the experiment running in fullscreen mode. This can be used to pause/quit the experiment when a participant leaves the fullscreen mode.
TimeMeasure_Mean Numeric The variable "TimeMeasure_Mean" provides an estimate of how precise (fast) reaction times can be measured by the participants computer/device. The provided value is a mean offset of several reaction time measurements in milliseconds. It can be used to infer how precisely stimuli were shown on the screen.
TimeMeasure_Std Numeric The variable "TimeMeasure_Std" provides an estimate of how reliable/consistent reaction time measurement is throughout the experiment. The provided value is a standard deviation of several reaction time measurements in milliseconds. It can be used to infer how comparable reaction time measurements are across trials and conditions.
Crowdsourcing_Code String The variable "Crowdsourcing_Code" holds the value of the unique "crowdsourcing code", typically shown to the subject at end of the experiment to complete the crowdsourcing session and claim the payment.
Crowdsourcing_SubjId String The variable "Crowdsourcing_SubjId" holds the value of the unique "identification code" for each crowdsourcing participant. This can be used to later on create a reference between crowdsourcing data on Labvanced and the external crowdsourcing service (e.g Mechanical Turk).
Role_Id Numeric The variable "Role_ID" is used for multi user/multi participant studies to refer uniquely to one of the participants of the study. This can be used to present different frames and roles to different participants within the same task/experiment.
Displayed_Language String The variable "Displayed Language" holds the value of the selected display language, only if there were 2 or more languages to select from. This value can be used to show different content, i.e. texts for different language settings.

Factor Variables

As the name suggests factor variable are linked to a factor in the trial system. In fact, each factor has one linked variable with a categorical data type. The levels of the factor are also the possible value states of the variable. When creating a new factor, one can choose to either create a new variable (automatically) or re-use an existing variable. When linking factor variables it should be noticed that changes to the variable / factor levels will change the trial structure in all linked tasks / trial groups. Factor variables can then be used in the event system, for instance 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, which is also stored in the data view. This way, it is made easy to later reconstruct the condition of each recorded trial.

Object Variables

Besides system variables and factor variables there is a third class of variables which are created automatically - object variables. Object variables are created together with objects. Most of these objects are "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 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 input / selection of the participant 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

All variables which are created actively by the user are listed as custom variables. The reasons to create custom variables can be quite diverse. For instance they 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 fore 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.

Variable References & Deleting Variables

To provide a better overview where each variable is used there is a list (USED IN) at the bottom ob the variables properties panel. Here all usages of the variable are listed, including a reference on which frame 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). Furthermore, 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 variables are to be deleted, it must be done with special care. Deleting variables, which are still used as factors, objects, or used in events can lead to serious problems and in the worst case can break the entire experiment structure. Hence in the variables tab, only those variables can be deleted, which have no referred use besides being within one (or more) local workspace(s). Variables that are only defined on the local workspace (and not further use) are listed as unused, and a deletion icon is shown next to them.

Variable-Selection Menu

The (self-controlled) use of variables is mainly based on events / actions. Within the event system there are 3 (visually) different menus which will ask / allow you select a variable . 1. the "Value-Select Menu", 2. the "Green Select Button", 3. 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 of the study are listed and can be selected. Both of these menus have a search / filter 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 it can simply be checked or unchecked 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. However, 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 how it could be done for saving "reaction time" .

  1. Add an image to the frame.
  2. Create a new Event.
  3. Define the trigger that determines when the variable value should be set (e.g after a left click on the image). Then click "Next".
  4. Select the action "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 icon, and then choose: Event Parameter--> Time From Frame onset.
  7. Now you have saved the reaction time for clicking on an image. You can repeat this procedure to record other properties like the decision (which image was clicked) etc.

Event System


Description

The event system handles the execution of all the functionality, logic, and interactions in a task. Events here often act as a mediator between objects and variables. An event always consists of 2 components: 1. A trigger 2. A set of actions.
Events are defined on a frame level and are also separate for each frame. Therefore, an event is always defined for all trials within a trial group. However custom logic allows to execute events only in certain trials, conditions, or in other circumstances.
Events are managed in the Task Editor under the "Event" 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 - events with the same trigger, which are further up in the list, 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 the name field).

Tutorial Video

Tutorial Video

Tutorial Video

The Trigger

The trigger defines when the event is triggered / executed. For instance, 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

Mouse
    Triggers On:
  • Mouse up, down, click, or hover on a specific object

  • Parameters:
  • Target: Select one or more objects as target
  • Action: Which mouse action triggers the event
    • Click: Triggered by mouse click
    • PressDown: Triggered by mouse down
    • PressDown: Triggered by mouse up
    • Hover: Triggered by mouse over object
  • Mouse-Key: Which mouse key triggers the event
    • Left: Triggered by left mouse button
    • Right: Triggered by left mouse button
Button Click
    Triggers On:
  • A button click

  • Parameters:
  • Target: Selection one button element as target
  • Button: Sub-selection, which specific button
Keyboard
    Triggers On:
  • Pressing 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 Arrow Keys
    • Numbers: Numbers from 0-9
    • Letters: All letter in the english alphabet
    • Special: Special Keys (Enter, Space, Short etc.)
    • F-Keys: F1 to F10
    • any key:any key
  • Enable alphanumeric characters (true / false): Enables numbers & letters
Frame Start
    Triggers On:
  • Start of the frame (before frame is visible)

  • Parameters: None
Frame End
    Triggers On:
  • End of the frame (after frame is no longer visible)

  • Parameters: None
Enter / Return on Input
    Triggers On:
  • Pressing Return within the selected input field(s)

  • Parameters:
  • Target: Select one or more input objects as target
Variable Value Changed
    Triggers On:
  • The change a variable from a set of variables

  • Parameters:
  • Variables: Select one or more variables, where you wan to "listen" to changes.
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 stopped
    • Upload Complete: Triggers when the file upload is complete
    • File Selected: Triggers when a file is selected
Audio/Video Trigger
    Triggers On:
  • Start, pause or stop of a video or audio fle

  • 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

Actions

The actions define what should happen when the event is executed. For instance, actions can be used to change variables and object properties, record data, read and write data from / to arrays, or jump to the next trial or task. Often there are several actions per event. Moreover, using "ControlActions" one can use logical operations (If-Else statements), Loops, callback functions, as well as nesting of actions within each other (e.g a while loop within an if statement etc). 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 setup in the second step of the event dialog box and there 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 an objects' appearance

    • Parameters:
    • Target: Select one object
    • Property Selection: Select one object property
    • Value-Select-Menu: Define a new value by using the Value-Select-Menu
Object Actions --> Control Video/Audio Obj
  • 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
      • Stop: Stops the video / audio file
Object Actions --> Control Upload/Recording Obj
  • 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
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
Variable Actions --> 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.
Variable Actions --> 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 & Statistical Tests
    • Operation: Choose a math operation (e.g. sum, min, stdev, etc.)
    • Input: 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.
Variable Actions --> Save Variables Instantly
  • Effect: Creates a snapshot of all variables values and send this to the Labvanced server

    • Parameters: None
Variable Actions --> Moving Average Filter
  • Effect: Will calculate a moving average 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: Weights 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.
Variable Actions --> 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 Operations --> Select from Array (Read)
  • Effect: Will read out one variable from an array and stores 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.
      • Variable: Use a numeric variable as an index for the read operation.
      • End of Array: Read from the end of the array.
    • Fixed Index: In case a fixed index was chosen, type in the position from where the information should be read out (1 based).
    • Index Variable: In case a variable was chosen as an index, select a (scalar, numeric) variable, which will determine the position of the readout.
    • Output variable: Select a (scalar) variable where the read out value will be stored.
Array Operations --> 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.
      • Variable: Use a numeric variable as an index for the insert / delete operation.
      • End of Array: Insert / delete from the end of the array.
    • Fixed Index: In case a fixed index was chosen, type in the array position where the entries should be inserted / deleted. (1 based).
    • Index Variable: In case a variable was chosen as an index, select a (scalar, numeric) variable, which will determine the where the entries should be inserted / deleted.
    • 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.
Array Operations --> Change Array Entry (Replace)
  • 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.
      • Variable: Use a numeric variable as an index for the replace operation.
      • End of Array: Replace the last entry in the array.
    • Fixed Index: In case a fixed index was chosen, type in the array position which should be changed (1 based).
    • Index Variable: In case a variable was chosen as an index, select a (scalar, numeric) variable, which will determine the position of the replace operation.
    • Input variable: Select a (scalar) variable which holds the new value.
Array Operations --> Shuffle Array Entries
  • Effect: Will re-shuffle the entries /order within an array.

    • Parameters: None
Jump Actions --> Jump To
  • Effect: Jumps to a different part in the experiment.

    • Parameters:
    • Jump To: Determines where to Jump to in the experiment.
      • Next Frame: Jumps to the next frame. If there is no more frame defined, it will jump to the next trial.
      • Next Trial: Jumps to the next trial. If there is no more trial defined, it will jump to the next task.
      • Next Task: Jumps to the next task. If there is no more task defined, it will jump to the next block.
      • Next Block: Jumps to the next block. If there is no more block defined, the session will end.
      • Previous Frame: Jumps to the previous frame. If there is no previous frame the action will not be executed.
      • Specific Frame: Jumps to a specific frame. You have to select the frame where to jump to.
      • Specific Trial: Jumps to a specific trial. You have to select the trial number where to jump to.
      • Specific Task: Jumps to the first instance of the specified task in the current block. You have to select the task where to jump to.
      • Specific Block: Jumps to the first instance of the specified block. You have to select the block where to jump to.
    • Check Required Answers Before: If enabled it will be checked whether all required answers have already been answered. If not, the jump to action is not executed.
Jump Actions --> End Session
  • Effect: Will end the recording session.

    • Parameters:
    • Record trial data before finish session: If enabled the most recent trial data will be stored (send 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 showing the current frame / site.
Control Actions --> Requirement Actions (If... Then)
  • Effect: Evaluates an if-else statement and executes a series of action 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 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. Hence 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. Hence 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". So 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 was fulfilled.
    • Add Else-If Case: The Requirement Action can consist of several separate If / Else-If --> Then statements. However, not more than one can be executed. If one If / Else-If statement is evaluated positively (returns true) the actions in the Then block are executed and afterwards 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 is executed (returns true), the actions defined in the else case will be executed.
Control Actions --> Repeated Actions (While Loop)
  • Effect: Repeatedly executes a series of actions, either immediately or with 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).
    • 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 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.
Control Actions --> 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.

The Value Select Menu

Via the Value Select Menu different kinds of values can be read out and set. Hence the Value Select Menu is used at various places / actions in the event system. Some examples are: "Set / Record Variable", "Set Object Property", "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.

The Value Select Menu has the following options:
  • Constant: Assigns a fixed value depending on the data type.
    • String: Assigns a string / text value.
    • Numeric: Assigns a numeric / number value.
    • Boolean: Assigns 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 of the time 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 image which was clicked).
    • Stimulus Info: The stimulus info of the object which triggered the event.
    • Time From Frame Onset: The time from frame onset, mostly 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.

Trial-Randomization


Description

While the trial system defines how many trials (trial variations) there are defined in total, the trial randomization menu regulates how many trials are seen by each subject and how these are selected and ordered. For the best understanding it is useful to know that "trial selection" and "trial ordering" are two different consecutive processes. The trial randomization settings are located in the task editor in the left panel under "Randomization". A click on "Edit" opens the setting dialog, in which all relevant settings can be made. The complete randomization settings consist of 6 separate menus. The "Trial Order" menu and the "Condition Order" menu are used to determine the overall trial order, while the menus "Factor Randomization", "Trial Per Subject", and "Resulting Condition Groups & Trials" are used to for trial selection.

Tutorial Video
Trial Order

The trial order is the main setting, which will influence how trials are ordered /randomized. There are 5 possible settings:

  • Random (default option): When this option is selected the Labvanced randomization settings will be most adjustable. The core feature of this option is that all selected trials will be randomly reshuffled for each new subject / session. If there is more than one trialgroup the trials of different trialgroups will be presented intermixed.
  • Fixed by Design: If this option is selected the trials will be presented in the order of how they are defined in the task editor (lower trial numbers will be shown first). This order will be the same for all subjects.
  • Fixed by Hand: If this option is activated, one can type a self-selected trial sequence. The sequence should be typed in the box "Specify Fixed Trial Sequence". To type in the sequence use the trial numbers as defined in the editor and separate each number by a comma. This sequence will be the same for all subjects. As this option will specify both which trials are shown as well as the order of trials, the settings in other randomization menus will be ignored in this case.
  • Dynamic: This option can be used to create adaptive / dynamic trial sequences (e.g. jump to different trials based on the answer of the participant). Select a start trial number and then use the event system "Jump to specific trial" for deciding on the dynamic trial sequence.
  • Upload Trial Sequences: If you select this option you can specify an individual trial sequence for each subject using an external CSV file (trials separated by comma, subjects by a newline CR-LF). Then upload these sequences and and select how you want to count the subjects (have a separate counter for each subject group, or use a global subject counter).

Condition Order

The menu Condition Order, also influences the order of trials. More specifically, this option determines whether the individual conditions are presented in a block-wise order, or randomly intermixed (Random).
The "Random" option will show all trials of the various conditions in an intermixed way. To further enforce "randomness" the number of trials which are from the same condition can be limited. Choose the Randomization constraint "Limit Successive Repetitions" and type in the maximum number of repeating conditions.
The "blockwise" option will separate the trials, such that first all trials from one condition will be shown, then another condition and so on. The order of the conditions can be either based on the design in the trial editor (fixed by design), or it can be randomly reshuffled (unbalanced permutation).

Factor Randomization

The Factor Randomization settings determine which trials will be seen by a subject. The most important setting here is whether a factor will be fixed or random. While "fixed factors" will generate more trials for a subject (all levels of a fixed factors will be shown), "random factors" will only increase the "trial variations" from which only one version will be selected (only one of the levels of a random factor is shown). Hence depending how these trial variations are chosen (settings within random factor), random factors allow for within and / or between subject balancing. Overall, there are 5 possibilities how the random factors can select their level and thereby choose a certain trial variation. These 5 options are listed below:

  • Unbalanced within task: When choosing this option, for each trial the level of the random factor is chosen randomly every time from all available options (levels).
  • Balanced within task: When choosing this option, for each trial the level of the random factor is chosen such that each level will occur equally often within the whole task.
  • Balanced within other Factors: This balances one factor within another one or within several other factors. If, for instance, the factor "position" is balanced within the factor "image content", then for each level of the factor "image content" the factor position is balanced (e.g. level=left and level=right appear equally often in both cases image=face and image=house). A factor can also be balanced within several other factors, however, no circular dependencies may arise.
  • Unbalanced between subjects: When choosing this option, the level of the random factor will be always the same for one subject / execution of the task, but randomly vary between subjects / executions of the task.
  • Balanced between subjects: When choosing this option, the level of the random factor will be always the same for one subject / execution of the task, but systematically vary in balanced vary between subjects / executions of the task. As a result, when the factor has 3 levels, subject 1 will see level_1 of the factor, subject 2 level_2 of the factor, and subject 3 level 3 of the factor. Subject 4 will see again level_1 of the factor.

A further important concept to understand the trial selection process is the so called "condition group". The condition groups are calculated by crossing all the fixed factors within a trial group, excluding the random factors. As a result, one condition group consists of several conditions (and trials), which vary only in their levels of random factors. Many times the trials within the individual conditions of a condition group are almost identical (e.g. they show the same stimuli but vary in their position). Hence many times it is important to prohibit that 2 trials are selected, which are identical besides their difference in one or more random factors. To change these settings, in the Factor Randomization section, one can change how the trials are selected within condition groups. Here two options are available:

  • Balanced within each condition group: When this option is selected, trials which vary only with respect to one or more random factor cannot be chosen more than once.
  • Unbalanced within each condition group: When this option is selected, there is no restriction on the trial selection process within condition groups.

We believe that for the vast majority of cases the "Balanced within each condition group" option is the best choice.

Example:

As the factor randomization (trial selection) process can be quite complex to understand let us create / look at an example. In this example task, subjects will see 2 images, one which they have seen before (target), the other one is unfamiliar (distractor). The task is to click on (identify) the target stimulus. Overall there are 4 factors, 1 fixed factor and 3 random factors:

  • 1. Fixed Factor "Presentation Time / Difficulty": This factor has 3 levels, 2 seconds (hard), 4 seconds (medium), and 6 seconds (easy). Each condition should be presented 20 times.
  • 3. Random Factor "Position of Correct": This factor has 2 levels, target image is left, and target image is right. Overall (in the whole task) there should be the same amount of "left correct answers" and "right correct answers" to avoid any bias.
  • 2. Random Factor: "Image Orientation": This factor has two levels, horizontal, and upsideDown (images are rotated 180°). This factor should be balanced within the fixed factor "Presentation Time" to insure that for each difficulty level there are equally many trials rotated and normal.
  • 4. Random Factor "Image Category": This factor has 3 levels, houses, cars, and faces. This factor will be used to generalize the findings. Hence each subject should only see one category / type, but this factor should be balanced across subjects.

Now let us do the settings:
Presentation Time --> Fixed Factor As this is the only fixed factor there are only 3 condition groups (easy,medium, hard). Each condition group has 12 sub-conditions, with each 20 trials inside. 60 trial will be presented in total to each subject.
Position of Correct --> Random Factor --> Balanced within task The factor "Position of Correct" will be set to "balanced within task". This way, the target image will appear equally often in the left and the right position in the overall task. However this is not balanced within each condition / presentation time (difficulty level).
Image Orientation --> Random Factor --> Balanced within other factors --> "Presentation Time" The factor "Image Orientation" will be set to "Balanced within other factors" and then the factor "Presentation Time" is selected. This way, for each of the 3 levels of the factor "Presentation Time" there will be an equal amount (10) of images that are presented normally and images that are presented upside down (10).
Image Category --> Random Factor --> Balanced between subjects The factor "Image Category" will be set to "Balanced between subjects. This way, each subject will only see one image category (houses, cars, OR faces), but the category selection will be balanced across subjects (Subject 1 will be houses, subject 2 cars, subject 3 faces, subject 4 houses, and so on).

Resulting Condition-Groups & Trials

The displayed information at the "Resulting Condition-Groups & Trials" menu is strongly dependent on the settings in the "Factor Randomization" menu. Mainly, this menu will show a table of the condition groups, together with some additional information. Furthermore, there are 2 additional settings, which influence the trial selection process.
1. Nr trials to show per condition group: This option will influence how many trials are shown per condition group. This setting is only important if the number of trials should be different within one condition group (between conditions). In general the nr or trials per condition group will be based on the condition which has the fewest number of trials defined. For instance, if there are 3 conditions in a condition group, and for 2 of them 20 trials are defined, while for the 3rd condition only 10 trials are defined, then only 10 trials will be shown. However, when 0 trials are defined, such conditions can be excluded from the calculations, such that when there are 2 conditions with 20 trials and 1 condition with 0 trials defined, there are still 20 trials shown. This option can be useful for nested designs.
1. Select trials in conditions by: This option will influence how trials are selected within one condition. This setting is only important if the number of trials should be different within one condition group (between conditions). For instance, if there are 20 trials defined in 2 conditions (of a condition group) but only 10 in the third one, only 10 trials are shown (as described above). However, for the 2 conditions which have 20 trials defined, one can choose whether only the first 10 trials can be selected, or whether the trial 11-20 could (as alternatives) also be selected. This option can be useful if you want to draw trials from conditions with different likelihoods.
The resulting table then shows for each condition group the following properties:

  • Factor-Group: The factor group where the factors of the condition group are defined.
  • Condition-Group: The condition group index.
  • #Conditions: The number of conditions inside the condition group.
  • #Shown Trials: The number of trials shown for the condition group.
  • #Trial Variations: The number of trials (variations) defined within the condition group.
On the bottom of this menu you will see the total number of trials (variations) within the overall task.


Trials Per Subject

By default the number of trials per subject is calculated automatically. However, by choosing the option "Set Nr of Trials manually" one can set the number of trials per subject by hand. When the manual option is activated this will also affect the internal functions of other randomization settings (i.e. Factor Randomization and Resulting Conditions-Groups & Trials).

Simulation of trial sequence

As the name suggests, the "simulation of trial sequence" can be used to simulate a possible trial sequence for one subject. By clicking on the "Refresh" icon, a new possible sequence is calculated. Thereby the current settings are taken into account. Here, one can also see the trial ids, which were chosen and the condition number for each trial.
On the bottom of this menu you will see the total number of trials shown to each subject.

Eyetracking


Description

In the top left side panel of the task editor, you can open the Eyetracking settings of the task (see figure).

To enable eyetracking in the task, please check the "Enable eye tracking in this task" checkbox. This will do the following:

  • The main eyetracking calibration will automatically happen before the start of the first task with eyetracking enabled.
  • Furthermore, if you enable eye tracking for this task, the head pose will be checked before each trial.
Between-Trial Fixations

In the Eyetracking Settings dialog of the task you can also define the number of fixations to show between trials. These between-trial fixations have the following purpose:

  • They are used to calculate the accuracy of the eyetracking before each trial.
  • If you enable "per trial drift correction", the drift is calculated as the median difference between the shown fixation points and the predicted gaze locations. Every gaze prediction during the following trial will then be automatically corrected by this estimated offset.
Recording of Eyetracking
The following is the recommended way to record a timeseries of [X,Y] coordinates of gaze locations. You should create an Event with trigger "Eyetracking", which will automatically execute every time a new gaze location is predicted. To record the new gaze location, you should add an action "Set / Record Variable". In this action, on the left side create a new recorded variable to store the gaze locations. In order to store a pair of x- and y-coordinates, it is best to choose format "Array". If you want to record all gaze locations over time, then switch the Record Type to "All changes / time series". On the right side of the action in the value select menu you can then select "Last Coordinate [X, Y] Array" from the "Eye Tracking" submenu (see figure).

The resulting recorded gaze coordinates will be in the design units that you use to position elements on your frames, such that you can easily associate coordinates to your stimulus locations.
Accuracy of Eyetracking
Please note, that the accuracy of the predicted gaze coordinates varies over different subjects and their corresponding environment (i.e. lightning and camera). Therefore, we provide estimates of the prediction errors. These estimated errors can be accessed in the value selection menu (for example on the right side of a "Set / Record Variable" action). The error values are mean euclidean distances between predicted gaze coordinates and the shown target fixation locations. In addition to these euclidean distances, there are also error estimates for only the horizontal ([X]) or vertical ([Y]) error components. Furthermore, there are two types of error values:
  • "Error Calibration ..." values are calculated using a validation set of fixations captured during the initial calibration period.
  • "Error Trial ..." values are calculated using the inter-trial fixations.

The Text Editor


Description

The text editor is located on top of the current frame and can be used to format and edit any (editable) text element on the frame. Also the text editor can be used to render / display variables, and to insert / combine images and tables within text elements. The most obvious text element is the text object itself, however, many other objects do also have (editable) text elements, either as an optional header, or as text answering options (e.g in checkboxes and multiple choice elements). Each of these text elements can be edited by a click into the text. A small blue border shows the element boundaries of the editable text element. Once the cursor focus is within the text, a text toolbar will appear above the current frame. Here one can make several text formatting choices, but also insert variables, images, tables etc.
While it is possible to change the text content and the style of an (editable) element from trial to trial, it is currently NOT possible to change the text content or styles dynamically during the experiment execution using the event system. If you want to show different texts or different styles (in one object / element), the best solution is to make two versions / two objects and then dynamically show and hide them based on your custom logic.

Tutorial Video

Text Formatting Options

The text editor has similar formatting / editing options as most word processors, although we decided not to include too many options to avoid misunderstandings. These options are listed below (from left to right in the text editor).

  • Insert Variable: Inserts / renders a variable value.
  • Underline: Underlines the text.
  • Subscript: Makes the text appear below normal text.
  • Superscript: Makes the text appear above normal text.
  • Clear Formatting: Clear all formatting.
  • Spelling Check: Performs a spelling check.
  • Numbered List: Makes a numbered list.
  • Bullet Lis:t Makes a bullet list.
  • Text Align Left: Aligns the text to the left.
  • Text Align Center: Centers the text.
  • Text Align Right: Aligns the text to the right.
  • Text Align Block: Makes the text use the whole line.
  • Insert Image: Inserts an image.
  • Insert Table: Inserts a table.
  • Insert Symbol: Inserts a symbol / special character.
  • Font type: Changes the font type. Can also be used to make the text bold and italic.
  • Font size: Changes the font size.
  • Font color: Change the font color.

Display / Rendering Variables

To display a variables' value click within a text element and then click on the first (red variable) icon within the text editor toolbar. The variable-select menu will open up and you can select a variable, which you want to display. After you press "ok" the variable will be inserted within the text element and a placeholder showing either the variables name or it's start value will be placed into the text as a handle. Hence the nice thing is that you can combine static text with dynamic variable values (e.g. you can provide feedback by doing something like this: "your score is: 'variableX'") A variables' value can also be formatted (style changes can be applied to a variable) when the handle is selected and then respective changes are made. However, typically it is better to first apply all the style changes and after that insert the variable(s). The variable value will then automatically adapt the surrounding style. Upon experiment execution, the variable values will be updated automatically. In other words, the value which is shown will always be the current value / state of the variable.

Inserting Images & Tables

One can also insert images and tables within editable text elements by clicking on the respective icons in the text editor toolbar. When inserting an image click on the "Browse Server" button to select an image from your Labvanced file repository. Also, you must provide the height and the width of the image in pixels and then press "ok". Inserting images into editable text elements can for instance be useful if you want to combine image selection within a multiple choice element, or when you want to combine images and text for some kind of description / explanation.
When you insert a table into an editable text element you have to provide the overall width, the number of rows, and the number of columns. You can also make a few further settings, such as adding a header row or making a border around the table or not. Each cell of the table can then be edited separately.


Multi-Participant Studies


Description

With the task editor it is also possible to create studies with multiple subjects participating in one experiment at the same time. For this purpose the editor provides a number of additional functionalities in order to enable synchronization and data exchange during a running multi-participant experiment.

Tutorial Video

Enabling Multi-Participant Functionalities

By default the necessary tools for creating multi-participant studies are hidden in the task editor. If you want to enable them, you can do this under the menu item Study Settings in the right column. By clicking on the Transform-button all relevant tools will be enabled and visible. Also the number of participants per experiment can then be set. Note that once the Transform-button is clicked there is no possibility to undo this switch. If you later decide that you don't need these additional tools, just ignore them and make sure to remove all related actions and synchronizations manually.

Role Ids

Since multiple subjects are participating at the same time it is necessary to distinguish between them. This can be done with the help of the numeric system variable "Role_Id". As soon as a new multi-participant experiment starts every participant gets a unique Role_Id in ascending order starting at one. By using requirement actions it is possible to execute actions depending on the Role_Id assigned to a specific subject. An example for the requirement action could be: if the Role_Id equals one, the subject will see image x and if the Role_Id equals two, the subject will see image y.

Frame Synchronization

The synchronous start of an upcoming frame can be arranged by activating the checkbox Sync Frame Start under the menu item Frame Settings. If activated, participants must wait before starting the target frame until all other participants have reached the synchronized frame.
While creating a study, make sure that all participants reach a synchronized frame. Otherwise some participants might reach a dead end and wait endlessly because another participant skipped the synchronized frame for example due to a conditional jump.

Task Synchronization

Also the start of a new task can be synchronized by activating the corresponding checkbox under the menu item Task Settings. Note that this option only synchronizes the task start and therefore the first frame of a task. Other frames within the tasks are not affected. As for frame synchronization, ensure that all participants reach a synchronized task.

The Distribute Value Action

With the help of the distribute variable action the actual information exchange can be realized. Dependent on a trigger of an event, an arbitrary value can be sent from one participant to a target variable of one or more other participants of the same running experiment.

Action Options

Once the Distribute Variable action is selected as the action of an event there
are some options to chose from:

  • The first option specifies whether the variable distribution should affect all or only selected participants.
  • The second option specifies the target variable together with a value. Note that you can use all variables as the target variable. The value could for example be a constant value, a current variable value or a more complex arithmetic operation.
  • The third option indicates whether the affected action should make use of the blocking system. (see below)

It is important to point out that the arrow (second option) does not represent an
equal sign but rather a potential assignment of the target variable.
In some cases the action might be refused (see below) and the target variable
remains unchanged, which also holds for the initiating participant of this action.

The Blocking System
Since distributions might affect the behaviour of other participants, if two or more participants want to distribute their values to the same target variable at almost the same time, the study designer must decide whether allowing all distributions or rejecting all but one until it's processed.
By activating the third distribute variable option, the blocking system is enabled. In this case the first incoming distribution will be executed. Other distribution attempts will be blocked until it is processed, which means that all participants which are affected by the action have confirmed the receipt of this action.
By deactivating the third option all incoming distribution attempts will be executed unconditionally.


Study Settings


Description

The Study Settings determine all general settings in the study / experiment. To provide a better overview the settings here are divided into three different categories: 1, Main Settings, 2. Browsers & Devices, 3. Experiment Features. All the settings are described below

Tutorial Video

Position

  • My Studies
  • Open a study
  • In the opened study
  • Third option in navigation bar

Main Settings:

  • Select timezone for the study in UTC: Determines the timezone for this study.
  • Main Study Language: Determines the main study language. This setting will influence multi lingual studies (translations).
  • Static Text Language: This show in which language static texts (i.e. information, consent etc.) will be shown during experiment execution. Currently the available languages are English and German.
  • Overall Background Color: This setting will change the overall background color of the study. The background will only shortly be visible between tasks, or when the display mode is not set to zoom (fullscreen) mode.
  • Allow fast forward in player by pressing CTRL+Q : If this option is enabled subjects can press CNTL+Q to directly jump to the next task. This way the correct presentation of the stimuli can be tested ver quickly. Uncheck it before publishing to avoid that subjects can skip tasks.
  • Ask for consent before participation: If this option is enabled the Labvanced consent agreement will show before starting the experiment. Subjects have to agree to the consent in order to start the experiment. If you uncheck / disable the Labvanced consent, we ask you to make an own consent informing the subjects about the data collection procedure.
  • Display link to library during startup: If this option is enabled a link to the experiment library is shown during the startup / loading of the experiment.
  • Participant Group Selection: This setting determines how participants are assigned to a group and hence it is only relevant if there is more than 1 group defined. If the automatic selection is chosen, participants will be assigned to a group based on their initial survey responses. If there is no initial survey, and /or there is more than 1 matching group, participants will be assigned to the group which currently has the fewest participants. If the manual selection is chosen the participants will be able to choose the group by themselves.
  • Session Selection: This setting determines how participants are assigned to a session and hence it is only relevant if there is more than 1 session defined (it's a longitudinal study). If the automatic selection is chosen, participants will always be assigned to the next session (in their group). If the manual selection chosen, the participants will be able to choose the session by themselves.
  • Initial survey items: This table will show which questions will be be included in the initial survey. If a group is setup with a demographic requirement (gender, age, location, first language, email) the respective question(s) will be mandatory (for the group selection process). The Email field will be required if there is more than one session defined, in order to send participants a reminder email for taking part in the next session. Other questions can also be made required (mandatory), be enabled or disabled.
  • Location based on IP: This setting will influence how the location detection will work. Overall, there are 3 options.
    • 1.IP location is not used. If this option in chosen IP localization will not be used.
    • 2.The initial survey is pre-filled based on IP location. If this option in chosen IP localization is performed to fill out the location field on the initial survey. However subjects are allowed to change the location field afterwards by themselves.
    • 3. Location is only based on IP. If this option is chosen the location-query will be only based on the IP localization. Subjects cannot influence the location field by themselves.
  • Custom participation requirement(s): This paragraph input field can be used to type in one or more custom participation requirements for the subjects (e.g. 'subject has to be vegetarian', 'subject has to have a BMI of 25 or up' etc.). Before the experiment starts this text will be presented to the participants, and they will be asked to read and confirm (click a checkbox) that they fulfill these requirements.
  • Browsers & Devices

    Browsers

    The browser and devices section can be used to determine on which devices and browsers the experiment can be executed. Regarding browser selection, each browser can be checked or unchecked (in which case it will not be allowed). As an overall benchmark Chrome, Firefox, Microsoft Edge and Opera work best, with Chrome typically having the fewest reported issues in total. Microsoft Internet Explorer and Safari do many times cause smaller or larger problems and hence we encourage all experimenters to test the functionality with these browsers before publishing the study! We also advise everyone to consider whether the "All Other browsers" option should be enabled or not. If enabled, the study can also be executed with less known browsers (i.e integrated browsers). The following browsers can be selected:

    • Google Chrome
    • Mozilla Firefox
    • Microsoft Internet Explorer
    • Microsoft Edge
    • Safari (Apple)
    • Opera
    • All Others

    Devices

    The selection of allowed devices works similarly compared to the browser selection. For each device type it can be determined, whether it will be accepted for the study (checked) or not (unchecked). We advice all experimenters to think about whether the study is mobile / touch compatible. For instance if keystrokes are used as triggers the study will not work on any mobile devices. Also we advice to consider whether "All Other devices" should be enabled or not. If enabled, the study can also be executed with less known devices (e.g. game consoles, IoT devices etc.). The following device types can be selected:

    • Android Mobile
    • Android Tablet
    • IPhone
    • IPad
    • Mac
    • PC Windows
    • PC Linux
    • All Others

    Resolution

    Besides browsers and devices one can also define a "Minimum Resolution (in Pixels)". If the device / browser screen has a smaller resolution, the study will not be able to be executed on that device. For instance, this option can be useful if some stimuli need to be presented with a certain minimal size. To set a minimum resolution, first check the checkbox "Set Minimum Resolution", and then define a minimum width and/ or minimum height in pixels.

    Experiment Features:

  • Multi User Study: When the "transform" button is clicked the study will be transformed to a multi-participant study. Once the study is transformed to a multi-participant study, the study cannot be transformed back to a single user study, but at least 2 participants will be required to take part in the study. When the multi-user functionality is activated, the following sub-options will be shown:
    • Number of participants: This setting determines how many subjects need to / will take part in the experiment.
    • Action on User Leaves Study: This setting determines what will happen (to the remaining participants) if one participant leaves the study (e.g closes the browser window).
    • Allow websocket reconnection: This setting determines whether participants are allowed to reconnect to the study after a temporary disconnect / connection loss. This option will be particularly useful for participants with an instable internet connection.
    • Check internet connection of participants before allowing participation: If this option is enabled there will be a connection / ping test before the start of the experiment. Only participants who pass the connection test will be able to take part in the study. The two following parameters can be adjusted for this test.
      • Maximum ping allowed: This setting will determine what will be the maximal acceptable ping (in milli seconds) for passing the connection test.
      • Average ping allowed: This setting will determine what will be the maximum for the average ping (in milli seconds) for passing the connection test.
    • Allow to invite friends in lobby: If this option is enabled, there will be a form field in the experiment lobby which participants can use to invite their friends to the study by entering their name and their friends' email address. If disabled the invitation form will not be shown.
  • Multi Lingual Study: When the "transform" button is clicked the study will be transformed to a multilingual study. Once the study is converted to a multi lingual study the "Translate" can then be used to add / adjust translations for all text elements in the study." At the beginning of the experiment execution a drop-down box will appear, which subjects can use to choose their preferred language. Multilingual studies cannot be transformed back to a single language study.
  • Audio Recordings via Microphone: If enabled the study will access (and require) the the microphone for voice recordings during the experiment execution.
  • Eye Tracking via Webcam: If enabled the study will access (and require) the webcam for webcam-based eye-tracking during the experiment execution.

  • Description


    Description

    In the "Description" section one can make adjustments, which will determine how the study will look like in the experiment library, under which keywords etc. it can be found, and what will be be shown when the experiment is in the loading / startup screen.

    Position

    • My Studies
    • Open a study
    • In the opened study
    • Forth option in navigation bar

    Information

    The information provided in this section will be used to create a customized visual entry for your study, which is shown in the experiment library. Hence most of the information here is mandatory to publish the experiment.

  • Publication Name: Determines the experiment name shown to the participants during the loading / startup of the study.
  • Keywords: Determines the keywords which will be associated with the study. Within the experiment library, you can filter based on these keywords to find experiments within your area of interests. There has to be at least 1 keyword, but not more than 3 keywords per study are allowed.
  • Author or Affiliation: Determines who is shown as the author / main affiliation of the study within the experiment library.
  • Minimum Duration: In order to provide an estimate how long an experiment will take you have to provide the minimum participation duration and the maximum participation duration.
  • Maximum Duration: In order to provide an estimate how long an experiment will take you have to provide the minimum participation duration and the maximum participation duration.
  • Description: (Optional) The description is an optional field in which you can write any text to introduce /advertise your study. This text will be shown during the experiment loading screen.
  • Image

    You have to upload or generate an image for your study. This image will be shown within the experiment library as well as during experiment startup / loading screen. In general you have two options here: You can use an auto generated image (a click on the "generate" button will generate a new random image) or upload an individual / own image. The image size should be 250px by 250px.

    Links & References

    To provide further information for your study, you can add links to related published articles (under references) and also links to other important information sources, such as links to external storages (e.g. open science framework), your personal or institutes website, or any other source, which might be relevant for people reviewing / trying out your study.


    Variables (Overview)


    Description

    In the "Variables" section all variables of the study are shown in one list (on the left). Here the most important variable properties (Name, Scale, Data Type, Data Format, Is Recorded, is Reset) are displayed. So the main difference to the variables shown in the task editor is that here you have all variables of your study shown in one list. Each variable can be selected such that the variables' properties are shown and can be edited on the right side. Reviewing / inspecting all variable properties is usually a good idea before publishing the study and starting the data recordings (e.g check whether all relevant variables are recorded etc).

    Position

    • My Studies
    • Open a study
    • In the opened study
    • Fifth option in navigation bar

    Variable Types

    In the Variables overview the variables are divided by their main type. There are 4 main variable types:
    • Custom Variables: Here all self / user created variables are listed.
    • Object Variables: Here all variables are listed which were created together with a (questionnaire) object (e.g checkbox, slider etc.)
    • Factor Variables: Here all variables are listed which function as factors within trial groups.
    • System Variables: Here all automatically created variables (pre-created by Labvanced) are listed.

    Deleting Variables

    Deleting variables should be done with extreme care. Before deleting a variable make sure that this variable is not used anymore anywhere in your study. The variable usages are shown in the variable properties on the lower right. While Labvanced tries to update these variable usages please also check by yourself (looking into the different tasks and frames) whether a variable is really unused ot not before deleting it. In case you are not 100% sure, it might be enough to disable the recording of the variable. This way the variable will not appear in the dataview, and also there is no risk to damage your study.
    IF A VARIABLE IS DELETED, WHICH IS STILL USED SOMEWHERE (E.G. IN EVENTS OR OBJECTS) THIS MIGHT CAUSE IRREVERSIBLE DAMAGE TO YOUR STUDY! So Please be careful!


    Translate


    Description

    The translation section can be used to create multi-lingual studies (studies which are translated into multiple languages). As a first step, the study has to be transformed into a multi-lingual study. Once a study is transformed to a multi-lingual study the "Translate" section will be activated. Importantly, upon experiment execution there will be a dropdown selection in the very beginning asking the participant to choose the preferred language. They will be able to select from all languages which were defined / added to the study. All translated text elements will then be shown in the selected language.

    Position

    • My Studies
    • Open a study
    • In the opened study
    • Sixth option in navigation bar

    Task & Frame Selection

    The "Translate" menu has 2 columns. On the left side is the Task & Frame Selection menu. Here you will see a hierarchical list of all frames inside your study. That means you will see a list of tasks and for each task there will be an entry for each frame. You can click on each frame and thereby select the current frame.

    Translations

    On the right side you will see a list of all text elements which are located on the current selected frame. For each text element you will see its name and there is a column for each language with the respective text string for this language. You can edit each cell entry / text element manually by clicking into the text. When you have clicked within one text element the text editor (same as within the task editor) will appear. Hence you can also style and change all text elements within the Translate view.
    To add a new language to your study click on the "New language" button. A small dialog will open up in which you have to make two choices. 1) You have to select which language you want to add (dropdown selection next to "New Language") 2) You have to choose how the "translation should work". Here you have the following 3 options:

    • Create empty fields: If this option is selected for each text element an empty field will be created for the new language. This is best if you want to do all the translations manually.
    • Copy text from translate language: If this option is selected there will be a new field for each text element for the new language. The text element for the new language will be filled with the text string from the main language.
    • Translate using Google Translate: If this option is selected there will be a new field for each text element for the new language. The text elements for the new language will be translated from the main language using Google Translate. Currently this only works for a few / or short text elements.
    If you delete all the text within a text element, you will see two buttons appear "Copy Fom English" and "Translate From English". When you click on the respective buttons you can copy / translate the single text entry. This typically works nicely also for Google Translate.

    You can also delete all translations and return to single language study design by clicking on "Delete Translations" icon. However, please be aware that by doing so, all text entries besides the main language will be deleted.


    Run


    Description

    The "Run" Tab can be used to do both test recordings and also real data recordings of your study. The Run tab is separated into 3 columns / sections. In the left most column you can test the execution of the whole study without data recordings being made, in the center column you can start a real recording session with data recordings enabled, and in the right most column you can enable or disable the the data recording status.

    Position

    • My Studies
    • Open a study
    • In the opened study
    • Seventh option in navigation bar

    Enabling / Disabling Recording & Locking Editing

    In order to keep a consistent data structure, each study can be in two different states, either in the creation / editing state OR in the recording state. A newly created study will always be in the editing state. A press on the enable / disable recording button will switch the state back and forth. Only when a study is in the recording state, data can actually be recorded. At the same time once a study is in the recording state, the editing of the study will be locked such that no more changes to the experiment structure will be allowed.
    If you still make changes to a study which is in the recording state (editing is locked) and aim to save these changes you will be asked to select one of the following three options:

    • 1. Delete all recorded data, disable publishing, and switch back to the editing state: If you choose this option, please make sure to download and store any relevant data beforehand.
    • 2. I know what I am doing and save anyway: Please be very careful with this option, and only choose it if you are sure that the changes you have made will not change the data-output (i.e. variables) of your study. Otherwise you might cause severe damage to your study. The study will keep in the recording state.
    • Cancel editing and reload from server: Choosing this option will discard your changes and reload the locked version from the server. The study will keep in the recording state; this is the safest option.
    You can also switch back from the recording state to the editing state within the "Run View". If you do that you will also have to delete all the data, which has been recorded so far (and un-publish your study).

    Group & Session Selection

    Experiments can be setup with multiple subject groups and / or multiple sessions. However one execution of the experiment is always fixed to one specific subject group and one session. When you start the experiment outside from the "Run tab" (e.g. via the link or the experiment library) the group and session assignment will typically be done automatic (can be set to manual in the study settings. For more information read the "Groups" section under "Study Design"). However, when you start the study "yourself" from with Run tab you can also determine the group and session by yourself. This can be useful either for testing the experiment for a specific group or session, or when doing local recordings and you need to assign a participant to a specific group and /or session based on your custom choices. Hence when you press "Start A Test Run", or "Start the Experiment" a dialog will appear in which you can determine the Subject Group and the Session. Additionally, you can provide a "Subject Code", which will work as a custom identifier for a participant (you will see the "Subject Code" later within the data view).

    Subject Counters

    Labvanced has two types of subject / participant counters for each study. 1. there is a global participant counter, which will always be incremented when a new subject starts the experiment. 2. There is a subject counter for each subject group. This counter will be incremented when a subject starts the experiment and is assigned to that subject group. Functionally, the counters are most important for between subject balancing. For instance, if a factor with 3 levels is set to be random and balanced between subjects, then for subject nr 1 factor level 1 will be chosen, for subject 2 factor level 2, for subject 3 factor level 3, and for subject nr 4 again level 1 (and so on). One can view and also reset the subject counters (set all counters to zero), in the central column of the Run section. But please be aware that this might interfere with your between subject balancing.

    Recording Limits (Before Publishing)

    For users which are using Labvanced under the free or single study plan, the number of recordings which can be stored within the data-view is limited as long as the study is not published. Currently there can be maximally 3 recordings in the data-view under the free / single study plan before publishing the study. However, you can download and then delete your current recordings from the data-view to be able to record more data before publishing. However, most of the time it will be easier to publish your study if you want to conduct more data recordings. Most importantly, there is no limit of how many data sets can be hold in the data view for published studies (even for free / single study plan users). For published studies, the number of possible recordings (per month) is dependent on your license plan.


    Publish & Record


    Description

    After the design of the study has been completed, it can be published under "Publishing". This makes it possible to share the studies in different ways. The study can be advertised in the LabVanced Library, a link to the study can be send to prospective subejcts per mail, or it can be shared on social media platforms. In addition, a large number ob subject can be recruited using our Crowdsourcing Feature . Of course, the study can also be published privately such that only selected subjects are able to participate.

    Tutorial Video

    Position

    • My Studies
    • Open a study
    • In the opened study
    • Eighth option in navigation bar

    Publishing Requirements (Before Publishing)

    Before a study can be published a few conditions must be met to ensure that the study is functional and can be displayed correctly upon execution. In particular, the Publishing Requirements consist of the following 3 parts:

    • Description: The Description of the study must be valid, which means that in the "Description" Section one has to specify the following parts:
      • Set a publication name
      • Add at least 1 keyword
      • Set an author or affiliation
      • Set minimum and maximum duration time
      • Generate or upload an image
    • Study Design: The study design must be valid, which basically meany that there should be no errors (e.g missing references, variables), or duplicate names within the study design. In the future Labvanced will provide here even more feedback.
    • Data Recordings: The data recordings must be enabled.
    Once all publishing requirements are met the Publishing Wizard can be started by clicking on "Review & Publish".

    The Publishing Wizard

    The Publishing Wizard can be used to publish the study and thereby make it accessible for online data collection. Overall, there are several options in the Publishing Wizard, which determine how the participation works, which quotas apply, etc. Once the study is published one can access and distribute the participation links to start the online data recordings. The publishing wizard can also be re-opened in order to make changes regarding the data collection process.

    Recruiting Options & Participant Requirements

    The recruitment options determine which channels are used to recruit participants for your study. A first general distinction here is whether you want to protect your study with a password or not. By default this option is disabled. If you enable the password protection you have to set a password for your study. When a participants then later opens the link to your study he/she will need to enter the correct password to be able to start your experiment. Overall Labvanced distinguishes 4 possible ways to recruit subjects. 1) Custom participation, 2) Own Crowdsourcing, 3) Labvanced Library, and 4) Labvanced Crowdsourcing. However, when choosing a password protected study the last two options (Labvanced Library, and Labvanced Crowdsourcing) won't be available as a password protection does not go well together with a public experiment library or Crowdsourcing to our understanding. Here is a list of the four available options and how they work.

    • Custom participation: This option is always selected and means that you will get a custom link to your study. You can even generate individual links for different subjects, sessions and groups (see "Participation Links" in the "After Publishing" section for more information).
    • Own Crowdsourcing: This option is also always available and means that you can use your own Crowdsourcing account(s), e.g. (Amazon Mechanical Turk, Profilic, or Clickworker) to recruit participants. Read the "How-To" to find out how to do Crowdsouricng with mTurk. If you have more questions (e.g how to use other Crowdsourcing platforms) please feel free to contact us.
    • Labvanced Library: This is an optional way to recruit participants. If this option is enabled your study will be listed in the Labvanced experiment library and all the visitors of the our library will be able to participate in your study.
    • Labvanced Crowdsourcing: This is another optional way to recruit participants. If this option is enabled Labvanced will recruit subjects for you using different Crowdsourcing platforms. You will also have the possibility to specify how may subjects you want us to recruit for you and how much compensation you want to pay per subject (This will be shown on the next page)..

    Besides the recruiting options this first screen of the publishing wizard will also show the participant (demographic) requirements. The information you will see here is based on the demographic group settings you specified in the "Study Design". This information is mostly relevant if you want to use Labvanced Crowdsourcing, as demographically customized participants are more expensive to recruit compared to when no demographic requirements are made.

    Crowdsourcing

    The Crowdsourcing section will only show up if "Labvanced Crowdsourcing" has been selected (You want Labvanced to recruit participants for you). Here you can make the following settings:

    • Number of Crowdsourcing Participants: Please choose here how many subjects you want us to recruit for you.
    • Payment per Participant: Please choose here how much money you want to spend per participant. There is a minimum based on the time duration of your study. Fees will be deducted from this amount.
    • Set maximum duration (true/ false): If this option if selected you an specify a time when the Crowdsourcing should be completed / disabled. The minimum time span here is 14 days.
    • Accept terms and conditions (true /false): In order to use / purchase Labvanced Crowdsourcing you have to accept our terms and conditions.
    When you select Labvanced Crowdsourcing you will receive a separate invoice, in which everything you selected here is listed and explained again and more details are provided. Typically 24 hours after we received your transaction, we will start the Crowdsourcing process. Depending on the demographic criteria, and the reward per subject, we will be able to recruit a few dozens up to several thousand subjects per day.

    Quota, License Selection & Customization

    On the 2nd page (or 3rd page if you selected Labvanced Crowdsourcing) of the publishing wizard you have to choose the license under which you want to publish the study. Here you will always see two options 1) "Use my current license." and 2) "Upgrade my account license / get recordings." Next to the first option you will see your current (study) license. Using the free license plan you can publish 1 study for free, however you can also record only 10 data sets + 1 data sets every 3 days. This means in the first month you can record up to 20 datasets for free, and for the following months 10 datasets for free. If you want to record more data, or if you want to publish another study you can upgrade your account license or also buy individual recordings for a single study. If you click on the respective option you can choose between our three license types "premium", "lab/department" and "single study".
    The prices which are shown on the selection page are valid for certain conditions / settings, which are listed below the price. If you select a license and press "next", you can customize the license features (adjust these settings). For instance you can adjust your student status, the time the license should be valid, your country, etc. If you prefer a complete overview you can also visit our license overview page. The final price for the license will be shown on the right side of the license customization page.

    Address

    The address section will only show up if you either selected / purchased Labvanced Crowdsourcing or if you bought a new license or recordings. The address will then be used to write you the respective invoice. Please fill out here all the required fields.

    Confirm & Publish

    In case you bought a new license or Labvanced Crowdsourcing, you will see a summary of your selections and the total amount you will have to pay / transfer. Please review this carefully. In order to publish your study on the Labvanced server you also have to confirm and accept a 3 things:

    • Accept our general terms and conditions.
    • Confirm that the uploaded content (i.e. Images, Video, Audio files) does not contain violent, sexual or otherwise illegal content.
    • Confirm that you hold the full copyright of all used materials (i.e. Images, Video, Audio files) or that they were already part of the public domain.
    When all three checkboxes are set you can click "Publish" or "Buy and Publish" thereby your study will be publicly available.

    After Publishing

    After the study is published the (online) data acquisition can start. In general the experiment execution starts via different kind of links. These links are visible and activated after publishing. Also you can see the license under which the study is published, the recording quota for the study (how many data sets can still be recorded), and the Orders which were made (Crowdsourcing, and License orders).

    Participation Links

    After the study is published you will have 4 different types of links to start the experiment:

    • Direct Link (General): This link is the main link to the study and can be distributed via email, social media etc.
    • Direct Link (Crowdsourcing): In fact we provide here 2 different links, which are distinguished by the URL parameter "type". The first link (with completion code) can be used for Crowdsourcing platforms like mTurk which require that a code will be shown to the subjects at the end of the experiment. Participants have then to copy and paste this code into the Crowdsourcing platform. Using this link the code will be visible once the experiment is completed. The second link (with completion url) can be used for Crowdsourcing platforms like Profilic which require that an URL will be shown to the subjects at the end of the experiment. Participants have to click on the URL to claim their reward. Copy and paste the completion URL from the Crowdsourcing platform into the respective field below.
    • Participation via Labvanced Library: Here you will see the link to your study in the experiment library. The nice thing about this link is that it will direct you to the "Study Preview Screen". On this screen you also see other information and functions for for study, such as importing or inspecting the experiment. Hence this link is useful to use in a publication, or when sharing your study with other researchers.
    • Custom Participation: Using the custom participation functionality you can create custom links to your study. Mainly you can provide the following 3 three parameters for the custom link generation.

    Recording Quotas and Orders

    On the right side of the Publishing page you will see your current license and the quota (how many subjects can still be recorded). In fact there will be two types of licenses 1 for your account and one for the study. Many times these are the same, however, for instance if you buy a single study license your study license will be "Single Study" but your general account license will still be Free, as this license is only for one study. In the lower right you will see a list of all the order you placed / purchased for this study.


    Sharing

    Description

    The "Sharing" section can be used to share both the study design (experimental methods) and the recorded data (of your study) in the Labvanced experiment library. Furthermore, the Open View access can be used to grant other researchers and reviewers access to inspect your experiment, but without the possibility to copy your study or use it as a template. Labvanced highly encourages all researchers to be open and share their designs and data.

    Position

    • My Studies
    • Open Study
    • Within the Study Design:
    • Ninth Item in the Navigation bar

    Sharing the Experiment as a template

    Overall, each study has one out of three possible "sharing states" which determine how / whether this study will be available for other researchers as a template / for import. On the left side of the Sharing section one can inspect and change this sharing state by clicking on the respective buttons and then saving the change. These are possible states:

    • Share Publicly: When this option is selected, your study will be listed in the Labvanced experiment library and all researchers (registered Labvanced users) can import your study and hence use it as a template. The data will not be shared / not be included in the template.
    • Decide Upon Request: When this option is selected your study will be listed in the Labvanced experiment library. Other researchers cannot import your study, but they can send you a message and ask for your permission to import it. You will then receive a message (visible in the dashboard) and can decide from case to case whether you want to allow a particular other researcher / user to import your study or not.
    • Don't Share: When this option is selected, your study will not be listed in the Labvanced experiment library. Other researchers / users will not be able to import it.


    Open View Access

    The open view access determines whether other researchers / users can inspect your study and data. When activating this option, other users will not be able to import your study, but will only be granted view access to your own study. This option is particularly interesting for researchers, which want to be open (i.e to reviewers and the community) about their applied methods, but do not want that their study design can be easily re-used by someone else. Furthermore, other people (reviewers, colleagues) inspecting your study do not need to have a Labvanced account in order to be able to inspect your study. Overall, there are three different states, which determine how the view access is handled.

    • Methods and Data: When this option is selected, your study will be listed in the Labvanced experiment library and people can inspect both your experiment design and the recorded data. However, they cannot change anything in your experiment and also not change or delete any data.
    • Only Methods: When this option is selected, your study will be listed in the Labvanced experiment library and people can inspect your experiment design but not your data. However, they cannot make any changes to your experiment.
    • No Access: When this option is selected, your study will not be listed in the Labvanced experiment library. Nobody can inspect your experiment design or data.

    Dataview & Export

    Description

    Under the "Dataview & Export" section, all the recorded data can be inspected, managed, and exported (downloaded). Furthermore, the Dataview & Export section can be used to download the experiment specification as a JSON file, one can unlock / purchase data which has been recorded exceeding quota limits, and also clean and filter the recorded data.

    Tutorial Video

    Position

    • My Studies
    • Open Study
    • Within the Study Design:
    • Last Item in the Navigation bar

    Data View, Variable and Task Selection

    The Dataview & Export section has two data tables. The upper data table displays a new entry (row) for each recording or subject. The information in the upper table shows all recorded system variables, as well as two identifiers (exp_subject_id, exp_session_id) and the information whether the recording session was completed or not. Importantly the rows in the upper table can be selected (with a mouse click), upon which the respective row is highlighted in blue.
    All the recorded task / trial data for the current selected recording is shown in the lower data table. Here you will see a new data entry (row) for each new trial; the variables are separated by columns. Each task has least 1 trial (even instruction tasks etc). As many variables are recorded only in 1 task, but the data view lists all variables by default, there will be quite a few empty entries, for many tasks / trials, because a particular variable was not recorded on that task.
    Both data tables can be sorted, with respect to a selected column. A double-click on a column will re-sort all the table data alphabetically based on that column (e.g. sorting according to the trial number in the lower table). Furthermore, both tables have an input-filter function. This can be useful if you want to search for a particular recording entry or if you only want to see / select a certain subset of the recorded data. The search can be even more customized by opening the search dialog box ("search..."). Here you can enter a search query / desired value individually for each recorded variable.

    Variable & Task Selection

    To provide an even more intuitive data view, one can also filter in and out both variables (table-columns) and tasks (table-rows). The variable filter can be opened via a click on the icon with the 3 vertical bars (|||). Each variable can be selected or deselected via a checkbox. You will only see (and later export) variables which are selected. There is also a toggle option / button (toggle all), which will show / hide all variables. This toggle option can be particularly useful if you have many variables but only want to see / export a few of them. In this case, fist deselect all variables using the toggle button, and then check the variables, which you would like to inspect /download.
    You can also filter in and out entire tasks. This can be useful if you want to ignore certain tasks such as instruction tasks etc., or if you want to analyze only one particular task. You can open the task filter by a click on the respective button on the left-column menu. Here you will see a list of all tasks in your experiment and you can select or deselect each task individually. Data for deselected tasks will not be shown or exported.

    Downloading Recordings & Specification

    You can export / download all the data visible in the Dataview & Export section. Regarding the data format you have 2 options, you can download the data either as "comma separated value", or as "tab separated value". The later is best suited for opening it with MS Excel or Libre Excel.

    Please note: You will only download the recordings, which you selected via checkbox.

    You can select a recording (e.g. for downloading) by checking the left most checkbox of the respective recording (row) in the upper data table. A click on the uppermost checkbox will toggle (select/deselect) all recordings. Once you have selected all the data sets, which you want to download you can click on "Download Data" to start the download. In the downloaded file, the upper and lower data tables are combined to achieve a 2 dimensional representation of the data. In fact, for each trial in the lower table the respective upper table row is appended in the downloaded file. Furthermore, the variables (columns) will be alphabetically sorted.
    Please note that variables with a time-series data format will not be included in the downloaded file. To download the time-series data, you have to click on "Download Timeseries".
    Finally, you can also download the Experiment Specification File (in JSON format), which stores all the information about your experimental setup / structure.

    Unlocking & Deleting Recordings

    When you recorded data under the free license and exceeded the data recording quota, the respective trial data will not be accessible to you. However, you can unlock this data by a purchase. To do so, first select the data sets, which you want to access / purchase in the upper data table. Then click on "Unlock Selected Recordings". Upon this a dialog box will appear, where you will see how much the data-unlocking will cost you. You will have to confirm the purchase and provide your name address etc. during this procedure. The data will then be unlocked right away, and we will send you an electronic invoice within the next days.
    A last option in the data view is to delete selected data sets. For this again first select the data sets which should be deleted and then click on "Delete Selected Data". To avoid unintentional deletion of data, there will be another dialog box, where you have to confirm the deletion process. Please be aware that data, which is deleted cannot be recovered by Labvanced.