Roulette Element

Modified on 2018/08/03 05:00 by Administrator Categorized as Base Elements, Elements, Randomization
<div style="margin-right: 10px; margin-left: 16px; margin-bottom:10px; float: right; width: 500px; overflow: hidden; height: auto; padding: 0px; background: #fafafa; background: -webkit-gradient(linear, left top, left bottom, from(#fbfbfb), to(#fafafa));background: -moz-linear-gradient(top, #fbfbfb, #fafafa);border: 1px dashed #ddd;box-shadow: 0 0 0 3px #fff, 0 0 0 5px #ddd, 0 0 0 10px #fff, 0 0 2px 10px #eee;">
== Summary ==
{s:Element Info Panel
| title=Roulette
| category=Randomization
| icon=[image|Element Icon|{UP(Roulette-Element)}Roulette-Element-Icon.png]
| author= OkazoLab
| addin= Base Layer
| scope= Parent event
| usage= Snippets
| ownsnippets= None
}
== Properties ==
{|
|-
! Name
! Description                              
! Constraints
! Type
! On<br/>runtime<br/>change
|-
| colspan="5" bgcolor="#AADDDDD" |   
|-
|          
|          
| {s:atNormal}        
| Dictio..        
|  
|-
|          
|          
| {s:atNormal}        
| Object        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Randomized Design
|-
| Open Design Editor        
| Opens a visual editor for the randomized design        
| {s:atDesign}        
| String        
|  
|-
| Withdrawal Mode        
| Defines the roulette withdrawal mode. When Auto Withdrawal is true, the roulette automatically withdraws fresh factor values from a trial block on onset of the parent event. In that mode the element also derives a number of trials and blocks from a number of made withdrawals. In the manual mode, trial blocks also have to be regenerated manually, via the Reset Block property        
| {s:atDesign}        
| enWith..        
|  
|-
| Block Length        
| Indicates the total length of the generated random trial block (number of trials)        
| {s:atStatus}        
| Int32        
|  
|-
| Treatment Frequencies        
| Defines the frequency (number of repetitions) of each treatment in generated random blocks        
| {s:atNormal}        
| Int32[]        
|  
|-
| Is Balanced        
| Defines whether withdrawal of treatments from the generated trial block is balanced. If true, the treatments will be withdrawn in blocks, with the fixed frequency for each treatment within a block (as defined by the design). If false, the treatments will be withdrawn independently, trial by trial, from random positions in the trial block with possible repetitions. The treatment frequencies are still relevant in the unbalanced withdrawal, but not guarantied over a short time.        
| {s:atNormal}        
| Boolean        
|  
|-
| Design Fraction        
| Defines a faction of the current design that is use to make the actual random block. The fraction is created by random sampling from the full design. The default value for the property is 100%, which corresponds to the full design. The lower values can be used for testing, when performing the actual number of trials is too long.        
| {s:atNormal}        
| Double        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Random Seed
|-
| Block Seed        
| Defines the random seed for generation of the consequent random block. The default value is zero, which denotes that different autogenerated seeds will be used for each block. When the seed is non-zero and fixed, the same random blocks are generated in a row. Runtime changes of the property affect only the consequent blocks.        
| {s:atNormal}        
| Int32        
|  
|-
| Current Block Seed        
| Returns the seed that have been used for generation of the current block        
| {s:atStatus}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Trial Treatment
|-
| Treatment Index        
| Returns an index of the current treatment in the treatment pool, as it shown in the design editor.        
| {s:atStatus}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Status
|-
| Treatment Number        
| Returns the number of withdrawn treatments since the start of the current random block. The value does not include the recalled treatments and, therefore, can be less than the number of actual trials made in the current block.        
| {s:atStatus}        
| Int32        
|  
|-
| Trial Number        
| Returns the number of actual trials presented since the start of the current random block. The number includes the recalled treatments and, therefore, can be greater that Treatment Number.        
| {s:atStatus}        
| Int32        
|  
|-
| Block Number        
| Returns the number of the current random block. Blocks are counted since the start of the experiment        
| {s:atStatus}        
| Int32        
|  
|-
| Total Trial Number        
| Returns the total number of actual trials since the start of the experiment. The values is accumulated across all blocks.        
| {s:atStatus}        
| Int32        
|  
|-
| Is First Trial        
| Indicates whether the current trial is the first trial in the random block. This status property is designed to control event flow conditioning at the start of a new trial block.        
| {s:atStatus}        
| Boolean        
|  
|-
| Is Last Trial        
| Indicates whether the current trial is the last trial in a block. This status property is designed for signaling the end of each trial block. The value can be used, e.g. in as a condition of a flow route to a pause event.        
| {s:atStatus}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Commands
|-
| Recall Treatment Now        
| Runtime command that recalls the current trial treatment (combination of the factor levels) back to the random block. The recall reshuffles the treatment in the random block assuring that the same treatment will be withdrawn later, in one of the subsequent trials. The command is initiated by assigning 'true' to this property in code snippets.        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| Repeat Treatment Now        
| Runtime command that repeats the current trial treatment (combination of the factor levels) in the next trial (technically, on the next onset of the parent event). The command is initiated by assigning 'true' to this property in code snippets and can be called from any event.        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| Reset Block Now        
| Runtime command that generates a new random block.        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Control
|-
| Is Enabled        
| If set to false the element is completely omitted when the experiment is run        
| {s:atDesign}        
| Boolean        
|  
|-
| Title        
| Title of the element        
| {s:atDesign}        
| String        
|  
|-            
|}
== ==
</div>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''Roulette Element''' helps creating a flexible randomized factorial design for experiments 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.

{TOC}

== 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 [^http://en.wikipedia.org/wiki/Factorial_experiment|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.
{|
|| [imageleft|Treatment combinations <br/>|{UP}/pictures/elements/roulette/GlossaryExample.png|{UP}/pictures/elements/roulette/GlossaryExample.png]
|}

{|
|-
! 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 [^http://en.wikipedia.org/wiki/Factorial_experiment|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 the 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 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 the UI, and click on the Design Editor property in the property panel. The editor window will appear in a view.

{|
|| [imageleft|Design Editor <br/>|{UP}/pictures/elements/roulette/sm_editor.png|{UP}/pictures/elements/roulette/editor.png]
|}

==== 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.
{|
|| [imageleft|Lookup Editor for Factor levels <br/>|{UP}/pictures/elements/roulette/sm_lookup_editor.png|{UP}/pictures/elements/roulette/lookup_editor.png]
|}
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 [http://en.wikipedia.org/wiki/Python_%28programming_language%29|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.
{|
|| [imageleft|Treatment Table with two factors and 6 treatment <br/>|{UP}/pictures/elements/roulette/sm_treatment_table.png|{UP}/pictures/elements/roulette/treatment_table.png]
|}
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.

{|
|| [imageleft|Generated example of a trial block with the uniform treatment frequencies <br/>|{UP}/pictures/elements/roulette/sm_trial_block.png|{UP}/pictures/elements/roulette/trial_block.png]
|}

=== 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.

{|
|| [imageleft|Dynamic properties of Roulette element <br/>|{UP}/pictures/elements/roulette/sm_treatment_properties.png|{UP}/pictures/elements/roulette/treatment_properties.png]
|}

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|Report]. The names of other status properties are self-explanatory.

{|
|| [imageleft|Status properties of Roulette element <br/>|{UP}/pictures/elements/roulette/sm_status_properties.png|{UP}/pictures/elements/roulette/status_properties.png]
|}

=== 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 scenarios and examples ==

==== Simple random block generator ====

In the simplest case the element can works as a random number generator. To implement the generator, create a design with single factor and define factors level within a planned range of a random values. To emulates a conventional random generator, set Is Balanced property to false. Then use


==== Full factorial design with multiple factors ====

Section is under construction

==== Subset sampling ====

Section is under construction
Meta Keywords:
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Roulette Element
