Page History: Roulette Element
Compare Page Revisions
Page Revision: 2012/06/25 19:05
|
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.
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 randomized trial blocks based on the predefined design. In each trial the roulette withdraws random values that can be directly used to set up a trial content.
There are multiple scenarios of using 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
|
Using Roulette at runtime
In the most cases the Roulette element is used for a read-out of its properties. However, the element can be also adjusted at runtime. Fro example, the randomized designs
Controlling event flow
In the simplest case it works as a random number generator. For more complicated scenarios it can generate the balanced random blocks of integer numbers and provides a runtime control over them. A simple roulette random number generator can be created by choosing an appropriate event and selecting
Event –
Add Element command and selecting
Roulette under the
Design section.
Snapshots
 Snapshot 1
| Snapshot 2 |
Practical Use
A Simple Random Number Generator ¶
Many experiments require the use of simple random number generators for independent, non-blocked features of the design. In a visual task for example it may be necessary to randomly rotate the stimuli on each trial. This factor is unrelated to the experimental factors that will be manipulated in the design (see next section). Once the new Roulette element has been added, it is necessary to amend certain properties in order to get it to behave as appropriately. If the random number generator is simply that, then it is necessary to set the range of the random numbers that are desired in the Factors box by specifying the highest number in the range and placing the letter x behind it. If a stimulus is going to be rotated by a random number of degrees upon each trial for example, then we would set the factors box to read “360x”.
It is of course necessary to specify via code, the parameter that will be controlled by the random number that has been generated.
Experimental Factors and Blocking ¶
Most experiments will have a roulette counter to ensure that the main experimental factors are randomly presented, a specific number of times, within each block. If, under the Roulette properties, the property for
Blocking is set to ‘True’, then the main levels of the experimental variables can be defined. Under
Factors the levels of each experimental variable should be written as ‘2x3x3’ or ‘2x2’ etc. The
Block Length will then be calculated, and if a certain variable should be more frequent then others, then this can be manipulated via the
Value Frequencies option.
It is of course necessary to assign the output of the
Factored Random Value as a multiparameter array (see Parameters and then in the code snippets, assign the individual parameters of this array to variable names. It is then necessary to specify what the properties of these parameters should be, in the differing levels of each variable. See the bottom of this page for a more detailed example.
In the example below,
Blocking is set to "true", and the experimental design in outlined in the Factors box as 2x2x2x3x4. A multi parameter array named ‘fRandomValue’ (visible in orange) has been assigned to the property
Factored Random Value.
The individual parameters of this array have been assigned specific names in the snippets box.
The last factor (x4) has not been defined. This means that each of the conditions that have been defined, will be repeated 4 times – thus lengthening the duration of each block.
Given that the first parameter in the array ‘TContrast’ can be only one of two values (as defined in the Factors box), only four simple lines of code are required to specify what EventIDE should do for each of the 2 levels of this factor. In this example, the shared ‘Colormask’ property of three different elements has been assigned as a multi-parameter array, and the RGB values of this color mask manipulated as required. See the section parameters for more information on manipulating the properties of individual elements.
TContrast=fRandomValue[0];
DContrast=fRandomValue[1];
OContrast=fRandomValue[2];
Distance=fRandomValue [3];
Properties
Generic Properties
| Name | Description | Attributes | Value Type | Proxy Reflex |
|---|
| Checkboard Settings |
| Ring Count | Number of rings in the patch | | Double | |
| Slice Count | Number of slices in each ring | | Double | |
| Inner Radius | Inner radius of the patch in percentages (0..100) | | Double | |
| Slice Phase | Angular position of the first slice in the inner ring (0..360) | | Double | |
| Slice Shift | Relative slice shift (in percentages) between neighboring rings. | | Double | |
| Ring Scale Ratio | Common ratio of a geometric progression that is applied to the ring scales, starting from the inner ring. 1 denotes equal scales. | | Double | |
| Low patch color | Lowest RGB color for the patch | | stColor | |
| High patch color | Highest RGB color for the patch | | stColor | |
+=== Properties inherited from clElement ===
Inherited properties of clElement
| Name | Description | Constraints | Value Type | Upon Change |
|---|
| Control |
| Is Enabled | If set to false the element is completely omitted when the experiment is run. | | Boolean |
|
| Title | Title of the element. | | String |
|