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.

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

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

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.

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.

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

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

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



Eyetracking Calibration Screen

The Eyetracking Calibration Screen is used to perform the initial face and eye detection algorithm before an eye-tracking task should be started. Upon experiment execution the subjects will see themselves within the calibration screen (live video stream inside) such they will get a visual feedback whether the calibration works.



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.



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

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.

Progressbar-Object

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

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.

Multiple-Choice

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

Likert Scale

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

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

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)

Paragraph

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

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.



Selection

A question with a drop down menu as answer option.

Sortable

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

Upload

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

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.

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).
GazeX Numeric The variable "GazeX" is used for webcam based Eyetracking stduies. The value holds the current estimated value of the Gaze/Eye Position in X coordinates. This value can be used for calibration and as a "fixation trigger".
GazeY Numeric The variable "GazeY" is used for webcam based Eyetracking stduies. The value holds the current estimated value of the Gaze/Eye Position in Y coordinates. This value can be used for calibration and as a "fixation trigger".
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).

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 --> Control Eyetracking
  • Effect: Starts, stops, or clears the webcam-based eyetracking

    • Parameters:
    • Effect: Choose a sub action
      • Start: Starts the Eyetracking
      • Pause: Pauses the Eyetracking
      • End: Ends the Eyetracking
      • Clear: Clear the Eyetracking data
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.

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.


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.

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.

Study Settings

text
text
text

Description

text

Variables Overview

text

Translate

text

Run

text

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.

Position

  • My Studies
  • Open Study
  • Within the Study Design:
  • 8th Item in the Navigation bar
Requirements

Before a study can be published some conditions must be met to ensure that the study is functional and can be displayed correctly.

Options

There are several settings for publishing, which are explained in more detail in this chapter.

Sharing

text

Data View & Export

Description

Under the "Data View" icon, the recorded data can be viewed, managed and exported (downloaded). The data is displayed per recording session. Incomplete records can be filtered out. Single sessions or all sessions can be exported as CSV or XLS files.

Position

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

Dashboard

TEXT

MyStudies

TEXT

Profile

TEXT

Files

TEXT

Experiment Library

TEXT

Account Settings

TEXT

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.

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 an operand value. Note that you can use all variables as the target variable. The operand 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.

Options

There are several settings for publishing, which are explained in more detail in this chapter.

License & Quotas

TEXT