Condition List Element

Modified on 2018/08/03 04:57 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=Condition List
| category=Randomization
| icon=[image|Element Icon|{UP(Condition-List-Element)}Condition-List-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" | Randomized Design
|-
| Condition List Editor        
| Opens a visual editor for the condition list        
| {s:atDesign}        
| 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        
| {s:atDesign}        
| 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.        
| {s:atDesign}        
| Boolean        
|  
|-
| Block Length        
| Indicates the total length of the generated random trial block (number of trials)        
| {s:atStatus}        
| Int32        
|  
|-
| Condition Frequencies        
| Defines the frequency (number of repetitions) of each Condition in generated random blocks        
| {s:atNormal}        
| 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.        
| {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" | 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.        
| {s:atStatus}        
| Int32        
|  
|-
| Block Number        
| Returns the ordinal number of the current trial block. Blocks are counted from the start of the experiment        
| {s:atStatus}        
| 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.        
| {s:atStatus}        
| 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.        
| {s:atStatus}        
| 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.        
| {s:atStatus}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | 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.        
| {s:atRuntimeAction}        
| 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.        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| Reset Block Now        
| Runtime command that generates a new random block.        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" |   
|-
|          
|          
| {s:atNormal}        
| Dictio..        
|  
|-
|          
|          
| {s:atNormal}        
| Object        
|  
|-
| 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>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''Condition List Element''' randomizes a custom condition list made of combinations of independent variables.<br><br>
{TOC}

== 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 ==
{|
| [imageleft|Condition List Properties |{UP(Condition-List-Element)}CondListProp_sm.jpg|{UP(Condition-List-Element)}CondListProp.png]
| [imageleft|Condition List|{UP(Condition-List-Element)}CondListList_sm.jpg|{UP(Condition-List-Element)}CondListList.png]
|}

== 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)
[imageleft||{UP(Condition-List-Element)}condListIcon_sm.jpg|{UP(Condition-List-Element)}condListIcon.png]<br><br><br><br><br><br><br>

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).<br>

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. <!-- Where to put the code? Into which snippet? -->

=== 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.
[imageleft||{UP(Condition-List-Element)}ConListTrailTreat_sm.jpg|{UP(Condition-List-Element)}ConListTrailTreat.png]<br><br><br><br><br><br><br>


4) Write code that carries trial preparations (for example stimulus and color selection) using values returned by these proxy variables:
@@ csharp
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.
@@ csharp
RecallTreatment=true;    
@@ 

6) Navigate to the status properties of the randomization element located in the ‘Runtime Status’ group:
[imageleft||{UP(Condition-List-Element)}ConListStatProp_sm.jpg|{UP(Condition-List-Element)}ConListStatProp.png]<br><br><br><br><br><br><br>

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:
[imageleft||{UP(Condition-List-Element)}DynProp_sm.jpg|{UP(Condition-List-Element)}DynProp.png]<br><br><br><br><br><br><br>

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

@@ csharp
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.
<!-- Does this apply to the condition list? -->
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: <br>
1) Switch the randomization element into the manual mode. <br>
2) Define a complete list of color values in a one-factor randomized design. Then, create two proxy variables on the following element properties:

# For the color name property that appears under the ‘Block’ group
# For ‘Reset Block’ property under the ‘Runtime Commands’ group


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

@@ csharp
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.
@@
Meta Keywords:
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Condition List Element
