Roulette Element

Modified on 2018/08/03 05:00 by Administrator — Categorized as: Base Elements, Elements, Randomization

Summary

Element Icon Roulette
Info
Category: Randomization AddIn: Base Layer
Creator: OkazoLab Scope: Parent event
Owns Snippets: None Usage: Snippets

Properties

NameDescription                              ConstraintsTypeOn
runtime
change
colspan="5" bgcolor="#AADDDDD" |   
                  
Normal..
        		Dictio..         
                  
Normal..
        		Object         
Randomized Design
Open Design Editor        Opens a visual editor for the randomized design        
Design Time..
        		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        
Design Time..
        		enWith..         
Block Length        Indicates the total length of the generated random trial block (number of trials)        
Status..
        		Int32         
Treatment Frequencies        Defines the frequency (number of repetitions) of each treatment in generated random blocks        
Normal..
        		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.        
Normal..
        		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.        
Normal..
        		Double         
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.        
Normal..
        		Int32         
Current Block Seed        Returns the seed that have been used for generation of the current block        
Status..
        		Int32         
Trial Treatment
Treatment Index        Returns an index of the current treatment in the treatment pool, as it shown in the design editor.        
Status..
        		Int32         
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.        
Status..
        		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.        
Status..
        		Int32         
Block Number        Returns the number of the current random block. Blocks are counted since the start of the experiment        
Status..
        		Int32         
Total Trial Number        Returns the total number of actual trials since the start of the experiment. The values is accumulated across all blocks.        
Status..
        		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.        
Status..
        		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.        
Status..
        		Boolean         
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.        
Runtime Command..
        		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.        
Runtime Command..
        		Boolean         
Reset Block Now        Runtime command that generates a new random block.        
Runtime Command..
        		Boolean         
Control
Is Enabled        If set to false the element is completely omitted when the experiment is run        
Design Time..
        		Boolean         
Title        Title of the element        
Design Time..
        		String         

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.


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

Treatment combinations


TermDescription
FactorControlled 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 levelsPossible 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.
TreatmentUnique 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 FrequencyNumber 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 BlockThe 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 LengthThe 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:


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.

Design Editor

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

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

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

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

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

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