# Experiment Designer User's Guide

## Contents

- Overview
  - Units and Precision
  - Vocabulary
- Designing
  - Flow
  - Routines
  - Settings
- Running
  - Testing
  - Experiment Files
  - Instance Files
  - Starting

## Overview

ExpyVR Exerpiment Designer is part of the ExpyVR framework developed by the Laboratory of Cognitive Neuroscience at EPFL. ExpyVR is made for designing and running computerised experiments, most notably experiments in virtual-reality. It is based on the open-source project PsychoPy.

The Experiment Designer is the core user interface of the framework. It allows to define the general flow of the experiment and the detailed timing of all its components. Randomised experimental conditions can be set and the components can be configured to behave differently depending on the condition. Once an experiment is created, it can directly be started from the designer, or executed independently (e.g. using runexperiment.bat)

The ExpyVR framework is still in development. This guide might therefore not always be up-to-date.

Back to contents

### Units and Precision

Units used are always SI units. All times are therefore in seconds but the precision is in milliseconds.

Back to contents

### Vocabulary

- Component: A component encapsulates the code for displaying something (e.g. a picture) and/or performing some operations (e.g. reading a sensor).
- Routine: A routine defines the precise execution timelines of multiple components for one or more experimental conditions.
- ISI: An Inter-Stimulus-Interval represents a pause in between routines. It can have a variable duration.
- Flow: The flow of an experiment defines the sequence and loops of routines and ISI (not their timing).
- Experiment: An experiment is made of a flow (populated with routines and ISI) and of various components. It is stored in an experiment file with the suffix *.exp.xml.
- Experiment instance: An experiment instance is needed for executing an experiment. It defines the exact sequence of routines and ISIs, with all the randomisation from the loops decided. Eventually, running an experiment with multiple subjects will require several instances, one for each combination of conditions.

Back to contents

## Designing

The Experiment Designer is divided into two main areas: the smaller flow area on top and the routine area that fills up most of the screen.The latter is itself divided into three areas; the routine timeline in the center and the components creation and selection on the sides

Back to contents

### Flow

The flow area shows the big picture of the experiment; the different parts (routines, ISIs, loops), their order and possibly loops in the flow. On the left side there are three buttons to add the different elements to the flow:

- Add Routine: Enter the name of the new routine and set its position in the flow.
- Add Loop: Enter the name of the new loop, the start and the end position in the flow and the number of times this loop should be followed. Loops can have a random variable associated. Each time the loop is followed a value is associated to the variable. Based on these values, the experimental conditions of the routines inside that loop are generated. The value of the variable is selected from a set that can be specified as comma-separated values. It depends on the type of loop how exactly the available values are specified and later selected. The four types of loops are:
  - Fix: There is no loop variable. Simply repeat the elements inside this loop for a certain number of times.
  - Random: Randomly select an element from the set. This is selection with replacement and will create unbalanced selections.
  - Shuffle: Create a random permutation of the set. This is selection without replacement and will create balanced selections. If the number of values given is smaller than the number of repetitions, the set is repeated until it has enough elements and then only shuffled. If the number of repetitions is not divisible by the number of elements in the set, the selection will not be balanced.
  - Factorial: Has two sets. All possible combinations of the sets are automatically generated. The resulting set of values is then randomly permuted. The loop is repeated exactly once for every possible value. The same thing can be achieved with a shuffle loop, but the factorial loop makes it easier to create experiments with a factorial design.
- Add ISI: Enter the name of the new ISI, its position in the flow and the minimum and maximum duration in between which the actual duration will be selected uniform randomly from.

Each routine created can contain several experimental conditions. Every routine automatically generates all the conditions that are possible given the loop variables from the surrounding loops. As an example, we take a routine that inside two random loops. One of the loops has the set sync, async and the other left, middle, right. Our routine will have a total of six conditions: sync-left, sync-middle, sync-right, async-left, async-middle, async-right. Careful: When you change the names or amount of loop variables or the position of a routine, the conditions change automatically. Make sure that your condition timelines still look OK if you make such a change.

To change, move or remove an existing component in the flow simply left click (or right click, same effect) on it and select the appropriate action from the context menu. The context menu is placed in a way that you can double click on a component to select the first action in the list.

Back to contents

### Components

Each component that can be created corresponds to a module in the ExpyVR framework. For more detailed information on components and their parameters, see the Module Documentation section. New modules can be easily added by programming in Python. More details can be found in the Programmer's Guide.

Following is a quick description of the main components:

| HUD Text: Display a text in the 2D foreground of the window.
| Fixation Cross : Displays a cross in the 2D foreground of the window.
| HUD Image: Display an image in the 2D foreground of the window.
| Image : Displays an image (*.png, *.jpg, etc.) on a billboard in the 3D scene.
| Video: Displays a video (*.avi, *.mov, etc) on a billboard in the 3D scene.
| Webcam: Displays the image of a webcam on a billboard in the 3D scene.
| Sound: Plays an audio file (*.wav, *.mp3, etc.)
| Keyboard: Listen to keyboard events, log their timing, and possibly unpause the script.
| Joystick: Listen to joystick events, log their timing, and possibly unpause the script.
| Script: Generic placeholder for Python code.

On the right of the window there is a panel for all the components that can be created. On the left there is a panel of the instances of components which have been created. Each component that you create has to be given a unique name. Some components have other parameters used for their initialization (e.g. the id of the camera for a webcam module).

Different configurations can be created for a component, offering the possibility to change its behavior when inserted into a routine:

- There is always a configuration entitled standard which defines the normal behaviour of this component.
- The other configurations are based on the standard configuration, except the parameters where the flag 'as in standard' is unchecked and for which another user-defined value is used.

Back to contents

### Routines

The routine area, in the center of the window, has a tab bar on top which allows to define what is executed for each experimental condition. A component is inserted to the current condition of a routine by selecting add to condition or add to all conditions from the context menu when clicking on the component (left panel).

The parameters to define the timing of a component when inserted in the timeline of a routine are:

- Display times: Every component that can be displayed in the virtual scene has a set of display times. For every time you want the this component to be shown during the experiment you have to specify the start time and the duration of the display. Display times are represented in red in the timeline.
- Activation times: All components can be activated for certain time periods. What activation means exactly depends on the type of component and on the parameters you set. Activation times are represented in blue in the timeline.

Inside the main area you can see a timeline for each component of the condition of a routine: the red bar shows when a component is displayed and the blue bar when it is active. Timing properties of a component can be edited by clicking on the timeline and selcting edit. To remove an instance or move it up and down in the display order, select the appropriate action from the context menu.

For instance, the fixation cross module is displayable (draws a cross), but its activation is pretty useless as nothing changes (it is safe to put a zero duration activation time). To the contrary, the Audio module is not displayable, but the activation times are important as they define when to play the sound. Many active components need both display and activation times; the movie module will play the file during the activation times, but show it only during the display times.

A component inside a routine will be executed according to the configuration selected for this timeline in the combo-box under its name. Configurations can be created and edited in the component properties dialog. This dialog is opened at the creation time of the component, or by a clicking on its icon in the Experiment Components panel and selecting edit.

Back to contents

### General settings

In the tool bar of Experiment Designer are two buttons for general settings. These settings are used for the whole experiment and are defining how to log the events during the execution and how to setup the display window.

#### Logger

During the execution of an experiment all of the modules generate a lot of logging data to keep track of when they are turned on and off and what they are doing exactly. In the logger settings, you can set whether the logging should be done to standard output console and/or to a file.
It is also a good idea to configure where you want the logs to be saved by setting the 'savepath'.

#### Display

In the display settings you can define how and on which window the experiment should be displayed. You can add multiple windows that are rendered into different screens. The following parameters also set here:

- pos (X, Y, Z) : position of the camera in 3D world
- angle (X, Y, Z) : rotation of the camera as Euler angles (zeros means looking forward in Z)
- mode : rendering mode for monoscopic or stereoscopic screen (various stereo settings available)
- size : dimensions of the window in pixels (when not fullscreen)
- fov : horizontal field of view of the camera (in degrees)
- fullscreen : display in fullscreen mode (window dimension becomes the size of the screen)
- screenid : identifier of the screen where to show the fullscreen (from Windows display settings)
- flipscreen : flip the display vertically
- color : color of the background (RGB values in [0.0, 1.0]

Back to contents

## Running

During the development of the experiment you can easily test your experiment without generating an instance. The experiment always has to be saved though before running a test or generating an instance. After finishing the design of an experiment, you can create instances for your subjects.

Back to contents

#### Experiment files; *.exp.xml

Experiment files contain a description and the parameters of all the routines, the components, and experimental conditions. They can be saved and loaded in ExpyVR Experiment Designer program.

You should save your experiment file every time you change something in the configuration of your experiment.

Back to contents

#### Testing

You can use the Test Experiment button or press [CTRL]+[T] to test the experiment. You have to save the exerpiment before doing so. The randomisation of the loop variables and ISI lengths is performed for every separate test run of the experiment.
NB: When testing, the main window is frozen until you close the experiment window(s).

Back to contents

#### Instance files; *.inst.xml

Instance files contain the parameters selected by the computer according to the randomisations requested by the user in an experiment (e.g. randomization of loop conditions).

Instances can be generated by selecting Generate Instance from the Experiment menu or pressing the orange button in the toolbar. When generating an instance file, Experiment Designer goes through all the loops and does the randomisation to find the sequence of experimental conditions. Also all the durations of all the ISIs are randomly selected within the given bounds. This is stored to a file that can be loaded later to start the experiment. All the information present in the instance file is the sequence of routines and ISIs, the experimental conditions of the routines and the duration of the ISIs.

You should (re)generate an instance every time you change the flow. All the other parameters such as the timeline of the routines being stored in the experiment file, you do not have to regenerate the instances if you only change the settings of a component or its timing. In doubt, it is safe to re-generate and instance each time you save the experiment.

Back to contents

#### Starting

Instances can be executed by selecting Execute Instance from the Experiment menu or by pressing the green button in the toolbar. Once you selected an instance file, the experiment is immediately started. To quickly restart the last executed instance, select 'Re-execute last instance' in the menu, or just press [CTRL]+[R].

Instances can also be executed without ExpyVR Experiment Designer interface ; you can use the 'runexperiment.bat' batch file instead.

Back to contents

Last update: 11.10.2011 | Authors: Tobias Leugger, Bruno Herbelin