Navigation¶

Create Account

Search the wiki

Page History: Roulette Element

Compare Page Revisions

« Older Revision - Back to Page History - Newer Revision »

Page Revision: 2012/06/25 20:20

	Roulette Element
Info
Category:	Scenario Control	AddIn:	Base Elements
Creator:	OkazoLab Team	Scope:	Parent Event
Owns Snippets:	no	Usage:	Runtime Screen,Snippets

Roulette element is a core and "must have" element in most of the EventIDE experimental designs. The element helps in creating flexible randomized factorial designs for experiment and, simultaneously, in controlling the block and trial event flows. The element is aimed to replace laborious randomization coding with an easy construction process in a visual editor.

Table of Contents [Hide/Show]

Description
Glossary
Practical Use
    Short Guide
    Creating Randomized Design
       Defining the factors
       Defining the factor levels
       Defining the trial block
       Evaluation of the created design
    Applying the randomized design
       Accessing the withdrawn random values
       Controlling event flow
    Adjusting Roulette at runtime
    Common randomization scenarios
       Simple random block generator
       Full factorial design with multiple factors
       Subset sampling
Properties
    Generic Properties

Description ¶

Randomization designs are very important in behavioural experiments, e.g. in assuring that stimuli are presented in a random and balanced order to avoid a bias in the statistical results. In many cases randomization is required across several discrete variables, called factors or independent variables. For example, behaviour measurements can be made for different shapes shown over different positions on the screen. The shape and position are factors in such design.

The roulette element allows creating single and multi-factorial randomization designs, with full or partial combinatorics of a number of factors. When an experiment is run, the elements generates a randomized trial block based on the predefined design. In each trial the roulette withdraws random values, or trial treatment, that can be directly used to set up a trial content. When end of the current block is reached and all treatments are withdrawn, the element automatically generates a new trial block with the same design settings. Thus, the Roulette allows to implement the common block-based experimental scenarios.

There are also other scenarios supported by the Roulette element, starting from making a simple random number generator and ending with complex hierarchical designs with dynamically adjusted factor probabilities.

Glossary ¶

A list of the statistical terms, used within Roulette, is explained on the example of the Treatments table in Roulette's design editor.

Treatment combinations

Term	Description
Factor	Controlled independent variable; a variable whose levels are set by the experimenter. In the above example there are 3 factors: Image Index, Polar Angle and Shape Color
Factor levels	Possible values of the given factor, defined explicitly (lookup list). In the example levels are: {1, 2} for Image Index, {90,180} for Polar Angle and {Red,Green,Blue} for Shape Color.
Treatment	Unique combination of factor levels. In the example the treatments make the table columns and the number of unique treatments in the current design is shown at the right-top.
Treatment Frequency	Number of times that a particular treatment is included into the generated random block. In the example, all frequencies are 1 (by default), except for the doubled frequency in the column 5. Frequency value defines the treatment probability in the block (shown in the dark row).
Trial Block	The finite block of indexed trials where a random treatment is withdrawn on each trial. Treatment withdrawal is balanced such that a particular treatment occurs as many times in the block as defined by the treatment frequency.
Block Length	The length of the trial block in the current design. The length is estimated automatically taking in account the number of treatments and the treatment frequencies. In the example the block length is greater than the treatment number because of the doubled frequency for the treatment 5. In the full factorial designs the block length is equal to the number of treatments. The length can be less than that number if some treatments are excluded (by assigning the zero frequency)

Practical Use ¶

Short Guide ¶

There are several major steps in adding the Roulette element:

Add a new Roulette element preferably to the first event in a looped trial flow. The selection of the parent event for Roulette is important, because the element makes withdrawal of new random values on onset of the parent event. The event onset indicates a new trial for Roulette's internal logic and causes an update of its properties.
Define a custom randomized design using Roulette's editor.
Write a snippet code for assignment of the trial content with random values, withdrawn by the Roulette. The Roulette element automatically provides proxy variables that returns the trial values for each factor. Make sure that the assignment code is executed once per trial, after the actual withdrawal.
Using the runtime status properties of Roulette, such as "Trial number", "Block number", "Is Last Trial", write a code to control the event flow in an experiment. For instance, a stop condition can be implemented as Block Number increases to 10.

In the following sections these steps are described in details.

Creating Randomized Design ¶

The roulette element provides an integrated visual editor for building the randomized designs. To open the editor, select the element in UI, and click on the Design Editor property in the property panel. The editor window will appear in a view.

Design Editor

Defining the factors ¶

Start with defining a list of the factors in the left table. To add new factor, type its name in the last empty row (to remove a factor, select its row and press Del). Define a value type for the created factor in the second column. Available types are: Int32, Double, Single, String and Boolean. Type selection depends on a planned use of the factor values in an experiment. Order of the factors in the table is not relevant for randomization.

Defining the factor levels ¶

The levels (possible value) for the created factors have to be defined explicitly. Open a lookup editor for the factor levels by double-clicking on a cell in the last column of the factor table.

Lookup Editor for Factor levels

The loop-up editor contains a column (at the left) where levels values can be entered. There are three options to enter values- first, the values can be edited manually; secondly, they can be pasted from the clipboard (the pasting supports lists, e.g. taken from Excel); and, finally, he values can be generated with a Python script. To run a script, write it in the code editor at the right (or modify the template script) and press the Run button at the bottom-right. The script must contain at least one parameterless function, which output will be taken as list. The script-based generation is the most continent for large or customisable lists.

Defining the trial block ¶

Once all factors and their levels are defined, the editor automatically forms the treatment table (the right panel in the editor) where all possible combinations of factors values are shown in separate columns.

Treatment Table with two factors and 6 treatment

In the treatment table frequencies for each of treatment can be entered. By default, each treatment has the frequency 1, which means that it will occur once in a generated random block. To modify frequencies, select cells in the last row of the treatment table and type new values. Alternatively, pasting values lists from the clipboard is also supported. If multiple cells are selected, the entered value will be applied to all selected cells.

Evaluation of the created design ¶

Once all factors, their levels and treatment frequencies are defined, the randomized design is completed and the element can generate random trial blocks. In order to evaluate the results you can press the "dice" button at the left-bottom of the editor window. An example of the trial block will be generated and presented in an expanding panel. Note that, randomization of the trial block actually means shuffling the treatment order.

Generated example of a trial block with the uniform treatment frequencies

Applying the randomized design ¶

Accessing the withdrawn random values ¶

Once the randomized design is created, the Roulette elements updates two groups of element's properties, called Trial Treatment and Block Treatments. Under these groups the dynamic properties are created, with names matching to the factor names defined in the current design.

Dynamic properties of Roulette element

Using the dynamic properties is straightforward. The trial treatment properties returns levels of a random treatment withdrawn in the current trial. The trial properties have the type as the corresponding factor and are updated automatically in each trial. Note that the Roulette element can automatically create the Proxy variables for the treatment properties so that they can be directly accessed in code snippets.

The block treatments properties allow to access all values in the current trial block, regardless of number of the current trail. The block properties are arrays, where the factors levels are ordered by the trial index (from 0 to (Block Length-1)). The block treatment properties are updated only on generation of a new trial block (it occurs after the last trial or, after a manual block reset).

Controlling event flow ¶

The Roulette element can be naturally used to control the event flow in experiments. The element has a group of status properties, called "Runtime Status". If the element's logic is aligned with the trial flow in an experiment (by placing the element in the first trial event) then the status properties can be used to track the current state of the experiment. For example, "Is Last Trial" property becomes true when the last treatment is withdrawn from the current trial block, "Trial Number" increments on every trial, "Block Number" grows when a new trial block is generated and so on. The values of the status properties can be, therefore, directly used to in the event flow conditioning and/or can be recorded into Report. The names of other status properties are self-explanatory.

Status properties of Roulette element

Adjusting Roulette at runtime ¶

In the most cases the Roulette element is used to build fixed randomized design, which stay unchanged in a course of entire experiment. However, the Roulette can be also adjusted at runtime, when needed. For example, the current trial block can be reset at any moment with Reset Block command. Moreover, the randomized design can be changed itself by changing design-related properties in a snippets. If it happens, the element automatically regenerates a trial block and withdraw new values in the following trials. Check the property descriptions below for all properties that can be adjusted at runtime.

Common randomization scenarios ¶

Simple random block generator ¶

In the simplest case it works as a random number generator.

Full factorial design with multiple factors ¶