Page History: Roulette Element
Compare Page Revisions
Page Revision: 2012/06/25 14:06
|
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
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 code for assignment of the trial content with random values, withdrawn by the Roulette. Make sure that the assignment code is executed once per trial, right after the actual withdrawal.
- Using the status properties of Roulette, such as "Trial number", "Block number", "Is Last Trial", write code to control the event flow in an experiment. For instance, a stop condition can be implemented as Block Number increases to 10.
Creating Randomized Design ¶
Controlling event flow
Using Roulette in runtime
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];
Generic Properties
| Name | Description | Attributes | Value Type |
|---|
| Randomization |
| Show demo block | Example of a random block generated with the current settings. | Design-time action |
| Min Value | The minimal integer value that generated random numbers can take. Has to be less than the Max Value property. Change in runtime causes generating a new block of random numbers. | D,R | Int32 |
| Max Value | The maximum integer value that generated random numbers can take. Has to be greater than the Min Value property. Change in runtime causes regeneration of a block. | D,R | Int32 |
| Value frequencies | The frequencies that denote a relative probability for each integer number in the range Min Value-Max Value to be included in a block.The frequencies and the total amount of possible integer numbers define the block size. Change in runtime causes regeneration a block. | D,R | Collections.IList |
| Block Length | Total length of the random block estimated with the current properties. | D,R | Int64 |
| Blocking | If true, the random values are generated one by one, not to a block and can be unbalanced. | D,R | Boolean |
| Factors | Factorial design for random numbers. Each random number is represented decomposed on factors in Factored Random Value property. | D,R | String |
| No repetition | If true, the last value of each block will be always different with the first value of the following block. | D | Boolean |
| Runtime Status |
| Index in block | Index of the current random value in a random block. | R, Read-only | Int32 |
| Current Block | Index of the current random block. | R, Read-only | Int32 |
| Block Completed | Is true when the last value for the current random block is just taken. A new block will be generated for the next activation of the parent event. | R, Read-only | Boolean |
| Runtime Actions |
| Force new block | Set to true in order to generate a new block immediately (note: new values will be accessible on the next activation only). | Runtime command | Boolean |
| Cancel value | Set this parameter to true in runtime in order to cancel the current random value withdrawal. | Runtime command | Boolean |
| Runtime Output |
| Random value | Returns a random value in the current position of the random block. Each activation of the parent event shift this position to the next number in a random block. | R, Read-only | Int32 |
| Random values | Returns an entire block of random values as an ordered array of integers. This property changes only when the block is regenerated. | R, Read-only | Int32[] |
| Factored random value | Returns the current random value as an array of factors. | R, Read-only | Int32[] |