Welcome Guest, you are in: Login

ScrewTurn Wiki



Search the wiki


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


Generic Properties

NameDescriptionConstraintsValue TypeUpon Change
Trial Treatment
Factor A,B.. A set of dynamic properties that return the factor values (levels) of the treatment withdrawn from a random trial block in the current trial. Custom
Report Lines Returns an auto-generated string composed of the separated factor values of the current trial treatment. The property serves as a trial statistics aggregator that can be directly saved in the Report. String
Block Treatments
Factors A,B.. A set of dynamic properties that returns blocks of factor values (levels) of the all the treatments randomly ordered within the current trial block. Custom
Randomized Design
Design Editor Opens a visual editor for the randomized design.
Block LengthIndicates the total length of the generated random trial block (number of trials). Int32
Treatment FrequenciesDefines the frequency (number of repetitions) of each treatment in generated random blocks.Int32[]Resets the current trial block
Is BalancedDefines whether withdrawal of treatments from the generated random block is balanced. If true, the treatments are withdrawn in blocks, with the fixed frequency for each treatment within a block (as defined by the design). If false, the treatments are withdrawn independently, trial by trial, from random positions in the same block and possible repetitions (also, Block Number does not increase). The treatment frequencies are still relevant in the unbalanced withdrawal, but not garantied over a short time.BooleanResets the current trial block
Design FractionDefines a faction of the current design that is used 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.DoubleResets the current trial block.
Random Seed
Block Seed Defines the random seed for generation of the consequent random block. The default value is zero, which denotes that auto-generated seeds will be applied for each block. Keep the property value as zero in the most cases. 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. Int32Runtime changes affect only the consequent random block, after the current block is completed.
Current Block Seed Returns the seed that have been used for generation of the current trial block. Int32
Runtime Status
Treatment Number Returns the number of withdrawn treatments since the start of the current trial block. The counter does not include the recalled treatments and therefore it can be less than the number of actual trials made in the current block. 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 it can be greater that Treatment Number. Int32
Block Number Returns the number of the current random block. Blocks are counted from the start of the experiment Int32
Total Trials Returns the total number of actual trials since the start of the experiment. The value is accumulated across all blocks. Int32
Is First Trial Indicates whether the current trial is the first trial in the trial block. This status property is designed to control the event flow conditioning by indicating the start of a new trial block. Boolean
Is Last Trial Indicates whether the current trial is the last trial in the trial block. This status property is designed to control the event flow conditioning by indicating the end of each trial block. Boolean
Runtime Commands
Recall Treatment Runtime command that recalls the current trial treatment back to the trial block (cancelling the made withdrawal). The recalled treatment gets reshuffled in the trial block, assuring that it will be withdrawn again later, in one of the subsequent trials. The command is initiated by assigning 'true' to this property in code snippets. BooleanRecalls the withdrawn treatment back to the trial block.
Reset Block Runtime command that resets and restarts the current trial block. BooleanResets the current trial block

+=== Properties inherited from clElement === Inherited properties of clElement
NameDescriptionConstraintsValue TypeUpon Change
Is EnabledIf set to false the element is completely omitted when the experiment is run.Boolean
TitleTitle of the element.String

The Roulette element is a core and "must have" element in most of the EventIDE experimental designs. The 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.


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.


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

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

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

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

ScrewTurn Wiki version Some of the icons created by FamFamFam.