Condition List Element

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

Summary

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

Properties

NameDescription                              ConstraintsTypeOn
runtime
change
Randomized Design
Condition List Editor        Opens a visual editor for the condition list        
Design Time..
        		String         
Withdrawal Mode        Defines the withdrawal mode. When Auto Withdrawal is true, the element 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..         
Shuffling        Defines whether the condition order becomes reshuffled as new trial block is generated. Set to 'false' only, when you define an already reshuffled condition list and would like to apply it as it is.        
Design Time..
        		Boolean         
Block Length        Indicates the total length of the generated random trial block (number of trials)        
Status..
        		Int32         
Condition Frequencies        Defines the frequency (number of repetitions) of each Condition in generated random blocks        
Normal..
        		Int32[]         
Is Balanced        Defines whether withdrawal of Conditions from the generated trial block is balanced. If true, the Conditions will be withdrawn in blocks, with the fixed frequency for each Condition within a block (as defined by the design). If false, the Conditions will be withdrawn independently, trial by trial, from random positions in the trial block with possible repetitions. The Condition 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         
Runtime Status
Trial Number        Returns the ordinal number of the current trial in a present block, as it is counted by the element. The number includes the recalled conditions and, therefore, can be greater than Block Length.        
Status..
        		Int32         
Block Number        Returns the ordinal number of the current trial block. Blocks are counted from the start of the experiment        
Status..
        		Int32         
Total Trial Number        Returns the total number of trials counted since the start of the experiment. The value is accumulated across all made blocks.        
Status..
        		Int32         
Is First Trial        Indicates whether the current trial is the first trial in the present trial block. This status property is proposed for signaling the start of a new trial block.        
Status..
        		Boolean         
Is Last Trial        Indicates whether the current trial is the last trial in the random 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 Condition Now        Runtime command that recalls the current trial Condition (combination of the factor levels) back to the random block. The recall reshuffles the Condition in the random block assuring that the same Condition 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 Condition Now        Runtime command that repeats the current trial Condition (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.        
Runtime Command..
        		Boolean         
Reset Block Now        Runtime command that generates a new random block.        
Runtime Command..
        		Boolean         
colspan="5" bgcolor="#AADDDDD" |   
                  
Normal..
        		Dictio..         
                  
Normal..
        		Object         
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         

Condition List Element randomizes a custom condition list made of combinations of independent variables.


Description

The condition list Element randomizes a custom list of conditions, that are made out of a of combinations of independent variables.

It is commonly used to insert randomized conditions that were prepared in excel files.

Snapshots

Condition List Properties

Condition List Properties

Condition List

Condition List


Practical Use

Creating a Randomized Design with the Condition List Element

1) First, Let us create an example condition list for the visual Simon task (available in the EventIDE Demo gallery). Add a new Condition List element (Add element -> SCENARIO CONTROL -> Condition List) and select it to access element’s properties in the property grid: (See 'Condition List Properties' screen shot)
Image








2) Open the Condition List Editor by clicking on the green play button (next to the 'Condition List Editor' property). The condition list is show in the middle grid. There are three independent variables in the Simon task, each having 2 possible values and 4 conditions (shown in the rows). (See Condition List screenshot)

3) Notice that not all possible value combinations are presented in the list. The Correct Key value is fixed for certain combination of the Stimulus Side and Color. Each of the 4 conditions is repeated 2 times and will occur in 25% of the trials (see the Freq and probability columns), such that the total trial number in a block is 8. The condition names are edited to make trial labels denoting the congruency of the stimulus and response sides in a trial. The condition list grid works like a data sheet and allows to create and rearrange any number of independent variables (of any data type) in the columns. The cell values can be entered manually or copied from a clipboard contains multi-column text data. In a typical scenario with a large number of conditions you start by creating columns in the condition list. Once the columns (variables) are defined, you copy an entire data array that you have prepared elsewhere (for example from an excel file).


4) Once you close the condition list editor, the Condition List element will automatically create dynamical properties (and proxy variables, if chosen) that will return the variables values at runtime. By dynamic, it means that the properties will be the column names that were entered in the condition list. You need to write code to read these properties and adjust your trial parameters (for example a stimulus color) in each trial.

Using the Condition List Element in Experiments

To carry the withdraw of random values on a per trial basis, the randomization element prepares a randomized trial block at the start of an experiment. The resulting trial block contains conditions or treatments in a randomized order. The trial block can be read at runtime, when the element operate in the manual mode (defined by “Withdrawal Mode” property). The individual conditions or treatments in the trial block can be obtained by their index (trial number). The trial block can be regenerated at request.

More conveniently, in the ‘repeated trials’ mode the randomization element can automatically withdraw a random condition/treatment for every new trial in your experiment. In this mode you have to add the element into the first event in a trial loop. Then the element can detect the start of a new trial, as the onset of its parent event. The element will count a number of trials and when all conditions/treatments in the trial block are withdrawn, it automatically generates a new trial block to continue withdrawals.

Follow the steps below to set up the randomization element in each of two modes:

Automatic withdraw mode for repeated trials (default)

1) Add the Condition List Element to the first event of your looped trial structure. This gives an alignment point for element’s trial counting. The element will automatically withdraw a new condition/treatment on the onset of the parent event and also its trial counter.

2) Create a condition list/randomized design with the element’s visual editor.

3) Locate the trial properties of the element in the Trial group and check which proxy variables are linked to it (these proxies are created automatically). These proxy variables will return trial values at runtime.
Image








4) Write code that carries trial preparations (for example stimulus and color selection) using values returned by these proxy variables: 

StimulusText=Letter;//StimulusText is a proxy on the Text property of the Text element.
TextColor=Color;// TextColor is a proxy on the Text Color property of the Text element. 

Make sure that the preparation code is called after the onset of the Roulette's event, but before a randomized stimulus is presented. Usually, the best location for trial preparations is the ‘After Onset’ snippet of the first event in a trial. 5) When you need to cancel a particular trial withdrawal and repeat the same treatment in later trials (this approach is often used after the incorrect participant’s response), use the Recall Treatment property of the Roulette. Assign ‘true’ to the property in the code, before a new trial starts. 

RecallTreatment=true;    
 

6) Navigate to the status properties of the randomization element located in the ‘Runtime Status’ group:
Image








These read-only properties return runtime trial statistics, which can be used to control the flow of an experiment. For example, the property ‘Is Last Trial’ returns true, when the element withdraws the last condition/treatment from the current trial block. You can use this property, as a condition to pause a trial loop between blocks. The properties showing trial and block numbers are handy automatic counters that can be used anywhere in your code.

7) When the randomization element returns the trial values for the last trial in a block, it automatically generates a new trial block with the same design parameters. The only difference is that trial block conditions/treatments are reshuffled in a new order.

Manual withdraw mode

1) Add the randomization element to any event in your experiment. In manual mode the element does not need to be aligned with the parent event's onset, because the trial block will be accessed manually. 2) Create a randomized design with the visual editor of the randomization element. 3) Locate dynamic properties of the element under the ‘Block’ group and add proxy variables for the factors:
Image








4) The dynamically created proxies allow you to read any condition/treatments within a trial block by an index. For example:


int n=7;                       // seventh trial in the block.  
StimulusText=Letters[n-1]; // StimulusText is a proxy on the Text property of the Text element
TextColor=Colors[n-1]; // TextColor is a proxy on the Text Color property of the Text element. Note, n-1 is used because indices begin at zero. 

Since conditions/treatments are already randomly shuffled in the trial block, you can use an incremental index from trial to trial. 6) When you need a new trial block, assign ‘true’ to the Reset Block property of the randomization element. A new trial block will be generated with the same design parameters.



Using the Randomization Element to obtain a Random Subset of a Larger Value Pool

Imagine that in each trial of your experiment you need to select a subset of 5 non-repeated colors that come from a larger pool of predefined colors (for example to present random and unique color targets). For this task you have to:
1) Switch the randomization element into the manual mode.
2) Define a complete list of color values in a one-factor randomized design. Then, create two proxy variables on the following element properties:

  1. For the color name property that appears under the ‘Block’ group
  2. For ‘Reset Block’ property under the ‘Runtime Commands’ group

The following code shows how these proxy variables can be used:


for (int i=0;i<5;i++){  
StimulusColor[i]=Colors[i]; //assign random colors, taken by the index from                                element’s trial block, to stimuli.  
}  
ResetBlock=true; // force the randomization element to regenerate a new block, so that a new subset of colors will be available on the next trial.