Setting up an IIR experiment

This document takes you through the steps needed to set up a new IIR experiment using existing user interface (UI) components. If you want to create your own components, read Creating new IIR UI components.

Creating the experiment configuration file

Creating the PyIRE uses experiment configuration files to be able to host multiple experiments at the same time. To create an initial configuration file use the PyIRE utility:

> PyIRE generate-experiment -h

usage: PyIRE generate-experiment [-h] [--filename FILENAME]
                                 [--template {default,left_column,right_column,three_column}]

optional arguments:
  -h, --help            show this help message and exit
  --filename FILENAME   Configuration file name
  --template {default,left_column,right_column,three_column}
                        Template to use for the new configuration file

By default it will generate a configuration file ‘experiment.ini’, with a simple default template, but you can change that using the --filename and --template parameters. Running PyIRE generate-experiment -h will list the available templates.

The experiment configuration file uses a standard INI file style, in which sections are defined using square brackets [Section Name] and each section then has a number of configuration settings. The only section that PyIRE requires is the [General] section that acts as the entry point into the configuration:

[General]
layouts =

Loading the experiment

To load the experiment, the experiment configuration file created above must be linked in the main PyIRE configuration file. To do this, update the pyire.apps setting in the PyIRE configuration file to include the new experiment. For each experiment you want to load into PyIRE you must specify a application_name:config_file.ini pair:

pyire.apps = application_name:path/to/experiment.ini, ...

The application_name will be used to generate URLs, so should consist only of letters, numbers, and underscores. Restart PyIRE and the new experiment will be loaded into PyIRE. You can check that it has been loaded by browsing to the root URL at which you have installed PyIRE. That will bring up the status page, which lists all loaded experiments.

Structure of an experiment

PyIRE experiments consist of two parts. Layouts define a set of components that are shown as one page to the experiment participants. An experiment must have at least one, but can have as many layouts as required. Each layout consists of a set of components that generate the user interface (UI) that is shown to the experiment participants.

Components have a unique name which they use to store their current state for each participant. Components that are used in multiple layouts with the same unique name will share that participant state, making it possible to create multiple UI layouts where the displayed information is consistent. An example of where this could be used is to implement a post-experiment review layout. This would be implemented in a separate layout to the main experiment layout, but because the components would re-use the names, the review layout’s components’ initial state would be the final state of the main experiment layout’s components.

Configuring the experiment layouts

To add a layout to the experiment, add a new section to the configuration file with the new layout’s configuration name. Then add that name to the list of layouts in the General section:

[General]
layouts = MainLayout

[MainLayout]

Layout sections have two required configuration settings. Then name is the unique name that is used by PyIRE to generate the URL at which the layout is accessed. This can be the same as the section name, but it does not have to be. The components is the list of components to add to the layout:

[MainLayout]
name = main
components = ...

Configuring individual components

Individual components are added to the layout in the same way that the layout is added to the experiment. For each component, a new section is added to the configuration file and that section is listed in the layout’s list of components. Components have two required settings. The name used to store the component’s current state and the handler class that implements the desired component functionality:

[MainLayout]
name = main
components = LeftBar

[LeftBar]
name = left
handler = pyire.components.core.Container

Depending on the component, there might be further required settings. For the default components provided by PyIRE check below to see the available configuration settings.

Laying out components

PyIRE provides a 12 x 12 grid within which the components can be laid out. To specify how many grid cells a component uses add a class setting to the component’s section. In the class setting use grid-X and vgrid-Y values to specify the component’s extent:

[LeftBar]
name = left
handler = pyire.components.core.Container
class = grid-3 vgrid-12

In the example above a Container component is configured to cover a quarter of the available horizontal space and all of the vertical space. This creates a full-page bar, which due to this being the first listed component, will be placed on the left-hand side of the page.

Due to the way the grid is implemented, components will be place from left to right and top to bottom. Due to the way HTML layouts work, components in the next row will be placed vertically below the previous row’s component with the largest vgrid-Y value. To implement layouts where components in different columns have different heights, you must first add Container components for each of the columns and then add the actual UI components to the respective containers. Each Container implements its own 12 x 12 grid that is used to lay out its child components.

In addition to the vgrid-Y vertical extent setting, there are also a vgrid-fixed and vgrid-expand settings. vgrid-fixed ensures that the component’s height is fixed to the minimum required to show all its content. vgrid-expand is the opposite to this and will expand the components vertical space to the maximum amount of space left after laying out all vgrid-Y and vgrid-fixed components.

To see an example of this in action, create a new experiment using the sample_search template.

Linking together components

Default components

Container

Settings

Signals

Task

Settings

Signals

Search Results

Settings

Signals

Search Results Summary

Settings

Signals

History

Settings

Signals

Book Bag

Settings

Signals

Filler

Settings

Signals

Loading additional components