Conditions Files

Introduction to Conditions Files
TaskObjects
Charting Blocks & Conditions
The generate_condition Function

Introduction to Conditions Files

Conditions Files are text files which specifiy explicitly each possible combination of stimuli ("TaskObjects") within a trial. Each of these stimulus combinations comprising a unique trial type is referred to as a "condition." During experiment execution, conditions are selected to run as determined by the options set in the main menu. Each condition specifies an associated Timing File. This timing file will then specify when and under what circumstances a stimulus is presented, calling up each one by its columnar location (i.e., TaskObject number).

A conditions text file consists of a header followed by consecutively numbered conditions. All columns are tab-delimited (multiple tabs without text will be reduced to one, and no intervening blank columns are permitted):

This is an example of a conditions file for a DMS (delayed match-to-sample) task using a total of 4 picture stimuli, 2 of which appear in each block. The Frequency column gives the weight or likelihood of that particular condition being selected randomly relative to other conditions. For example, if a condition has a relative frequency of 3, it is as if that condition is listed 3 times; that is, it has 3 times the chance of being selected as a trial with a relative_frequency of 1. The block, meanwhile, is specified in the "Block" column, which specifies those blocks in which the condition can appear. Here, for instance, block 1 uses only images A and B, block 2 uses C and D, and all images are used in block 3. The Timing File refers to the Matlab m-script which calls up each stimulus at the appropriate instant and checks for fixation, target acquisition, etc. Each condition can be associated with a different timing file, if desired. The Info column is here being used to pass labels to the timing file about which image is being used for the sample, and where the matching image is being displayed; this column is intended to make deciphering the conditions easier for the user, and does not affect actual task execution.

Each TaskObject consists of a three-letter symbol (fix, dot, pic, mov, crc, sqr, snd, stm, ttl, or gen - see TaskObject table below), and parameters for its generation or display.

In principle, any experiment can be designed such as to work with one condition containing all possible stimuli and a timing file that chooses among these stimuli as needed, on-the-fly. This is workable, but not ideal for several reasons. First, in order to know what actually happened in a given trial, an event marker would need to be sent representing each stimulus or event as it actually occurs within a trial, because this information would no longer be apparent from the condition number alone; furthermore, searching through the data stream to retrieve these codes is a cumbersome task, and is more error-prone than simply checking the condition number stored in the behavioral data file. Therefore, although it is not unusual for a seemingly simple task to require hundreds of conditions, this is nevertheless usually preferable to having hundreds of variations represented by a slew of event markers scattered throughout the data file (i.e., by assigning each of the possible sequences of events to a single condition number, one can simply look at that number and know immediately what transpired on that particular trial). Second, relying solely on the timing file to select the sequence of events bypasses the options available in the main menu to alter the way conditions and blocks are selected (e.g., random, random-without replacement, etc.); such functionality will therefore need to be replicated from within the timing file. Third, using separate conditions allows one to easily change the relative frequency of particular conditions to compensate for biases or learning deficits exhibited by the subject (see the Relative Frequency column, above). Lastly, because the creation of a conditions table requires the explicit enumeration of all possible stimulus sequences, its creation is often a good opportunity to catch and re-work unbalanced features of the task.

As designed here for this DMS task, a timing file would likely first display TaskObject#1, which in all conditions is the fixation point. After a certain interval (specified in the timing file), TaskObject#2 would be called up and displayed. After this stimulus is turned off, TaskObject#1 can be displayed again during a delay. Then TaskObject#3 and TaskObject#4 (the target and distractor) are displayed. The timing file can assume that the correct target is always TaskObject#3 (because of how this Conditions file is designed), and so can monitor that object (regardless of where-ever it happens to be placed on the screen by this Conditions file) to see if it is correctly chosen by the subject.

Conditions tables should reside in simple text files. They can be manually created using a simple text-editor (such as "Notepad") or with a spreadsheet such as Microsoft Excel (the quotes added to each field will be automatically removed). In addition, Matlab can be employed to generate these text files in an algorithmic fashion using the generate_condition function.

TaskObjects

Within each TaskObject field of the conditions file, a particular type of object is specified by a 3-letter name followed by arguments within parentheses. The specific arguments for each type of object are listed in this table:

For visual stimuli, a TaskObject with a lower number (towards the left of the list) will layer atop those to its right. Therefore, most users will want fixation point images, for example, to be the first item listed, so that it will remain visible over any images that might appear at the same location.

Charting Blocks and Conditions

For any given conditions file, to see the relationship between particular conditions and the blocks in which they can appear one can use the "chart blocks" function found within the task submenu of the main menu. This will produce a graph similar in nature to one of these:

The figure above shows the organization of a conditions file which describes an experiment in which no condition may appear in more than one block (no column contains more than one condition), and each block consists of a set of conditions which uses a unique timing file (the different colors in each row). Clicking on a particular box will call up specific information about that condition / block combination to the right.

This figure shows the organization of a conditions file in which any condition can appear in more than one block (for instance, block 5 is the set of all conditions while blocks 1 through 4 contain non-overlapping sets of conditions). These graphs provide a useful way to get a quick overview of how a conditions file is structured.

The generate_condition Function

Generating conditions files using a Matlab script or function can be very helpful whenever a task involves many conditions. To assist this process, the "generate_condition" function is available:

textline = generate_condition(cond_number, relative_frequency, cond_in_block, timing_file, TaskObject, [fid])

TaskObject(n).Type
TaskObject(n).Arg{k}

in which n is the TaskObject number, the field Type is a string containing the 3-letter object type, as above, and the field Arg is a cell array containing each of the arguments for the indicated TaskObject type.

The optional input argument, fid, can specify the FID of the text file to which this condition should be written.That file should have already been opened (using the Matlab "fopen" command), and should be closed (using "fclose") once all the conditions have been generated.

In addition, the syntax:

textline = generate_condition('header', [fid])

can be used to generate a conditions file header. This form of the function should be called first when creating a conditions text file, as a header is always assumed to occupy the first line.

The output, textline, is the text as it is to be printed (or has been printed, if the fid were specified) to the conditions text file.

Example:

TaskObject(1).Type = 'Fix';
TaskObject(1).Arg{1} = xpos;
TaskObject(1).Arg{2} = ypos;

TaskObject(2).Type = 'Mov';
TaskObject(2).Arg{1} = 'Grating.AVI';
TaskObject(2).Arg{2} = xpos;
TaskObject(2).Arg{3} = ypos;

TaskObject(3).Type = 'Crc';
TaskObject(3).Arg{1} = radius;
TaskObject(3).Arg{2} = [red green blue];
TaskObject(3).Arg{3} = fill;
TaskObject(4).Arg{4} = xpos;
TaskObject(5).Arg{5} = ypos;

When fed into the generate_condition function, these assignments are equivalent to these three TaskObjects:

     Fix(xpos, ypos)      Mov(Grating.AVI, xpos, ypos)     Crc(radius, [red green blue], fill, xpos, ypos)

where the variables will be replaced with actual values in the conditions table text file.