TWiki> BrainStreamDocs Web>BrainStreamDocs? >DocsSectionsBuildingExperiments (revision 3)EditAttach

Building Experiments

An experiment in BrainStream consists of experiment definition tables, block files and common block files, and, in some instances, user defined functions. In the following, each of these components will be discussed.

Experiment definition tables

The experiment definition tables (.edt) form the core of your BCI experiment. In these tables is specified which actions need to be executed at what time. For each experiment, three different tables are needed: the Actions table, the Data Selection table and the Dictionary table. Together, the experiment definition tables are called the experiment definition file. Brainstream has its own internal editor for creating the tables, however, for backwards compatibility reasons it also supports excel files (.xls extensions only) where each table is put in a different sheet, or a set of separate text files (.txt), one for each table. In the following, the experiment definition tables will be discussed in more detail.

Actions table

Table 1 is an example of an Actions table:

marker time function feval looptick client var1 ........ varN
mrk1 EVENT fnc1,fnc2       get,put ........ $self+1
mrk2 2 fnc3       [],put ........ get,put

Table 1: Actions table

The first three columns in an Actions table are reserved to specify marker, time, and function. The three following columns feval, looptick, and client are optional and will be discussed later. Although the order of these first columns in the table is arbitrary, it is best to keep it as described here. All subsequent columns are free to use for an arbitrary number of user specified variables (stored internally in BrainStream's user state, i.e. the global variables).

The first column of the Actions table is the marker column. The marker column contains the names of all markers that elicit the execution of certain actions. For example, marker mrk1 in table 1 could mark a response made by the participant. Perhaps the experimenter wants the response to be followed by feedback about the response. In that case, marker mrk1 should be in the marker column of the actions table.

The second column (time) specifies at which timepoints, relative to the time of the incoming marker, actions should be executed. The exact timing of execution can be specified in several ways. The action can be executed directly at marker onset, when a certain amount of data becomes available, some time after the marker, or when another marker arrives (see table 2). For example, table 1 specifies that certain actions are executed at the onset of marker mrk1 and two seconds after marker mrk2.

a number
another mrk
Executed at marker onset
Executed as data becomes available
Executed number seconds after marker onset
Executed at onset of marker mrk

Table 2: specifying time of action execution

The third column (function) can contain one or more functions that will be executed in the order in which they appear in the table. So, in table 1, at the onset of marker mrk1, first function fnc1 and then function fnc2 will be executed. Two seconds after the onset of marker mrk2, fnc3 will be executed. A number of BrainStream functions can be specified in the function column. Alternatively, you can write your own user defined functions, which will be discussed in detail below.

The next three columns are optional. The feval column allows for specification of any functions that do not need to process any of the global variables and do not return output arguments, but can take global variables as input argument. The looptick column is optional and serves to define a special function that always executes on another client and will be put into a loop by BrainStream, click here for more information on how to use this. The client column can be used to direct execution of functions to another remote Matlab session (see Running BrainStream in Parallel Mode.

All subsequent columns are free to use for an arbitrary number of user specified variables (more on this later).

DataSelection table

Dictionary table

User defined functions and variables

In the Actions table, certain actions are assigned to markers. You can define the actions directly in the table, but it is also possible to specify actions by adding user defined Matlab functions to your table. The functions that you write may need certain variables as input. An arbitrary number of columns in the Action table can be used for these user defined variables.

If a function needs a user defined variable, you first need to get it from the global variables. This is done by putting a ‘get’ statement in the corresponding cell. For example, consider the following Actions table:

marker time function feval looptick client var1 ........ varN
mrk1 EVENT my_fnc1       get ........  
mrk2 2 my_fnc2         ........ get,put

At the onset of marker mrk1, user defined function my_fnc1 will be executed. This user defined function needs the user defined variable var1 as input. In order to make this variable available to my_fnc1, a 'get' statement is placed in the var1 column. Note that variable var1 is not available to the user defined function my_fnc2 that is executed after marker mrk2, as no 'get' statement is present in the var1 column after this function.

User defined functions) need to be written in the following format:

event = my_function(event,c1,c2,...)

The input and output argument 'event' is obligatory. Event is a Matlab type structure variable. The fields of this structure contain copies of the current content of the variables with a 'get' statement in the table. In the above example, var1 was made available to function my_fnc1 with a 'get' statement. Thus, the my_fnc1 input argument 'event' will contain the field event.var1, which holds a copy of var1. In contrast, the input argument 'event' of function my_fnc2 will not contain the field event.var1 (no 'get' statement in the Actions table), but it will have a field called event.varN, which contains a copy of variable varN.

The additional input arguments (c1, c2, ...) are optional. You can enter constants there, if your function needs them.

Your user defined function might change the content of some the variables you use as input. If you want to save these changes, you can place a 'put' statement in the corresponding cell in the Actions table, which updates the modified variables to the global variables. In the example above, changes that my_fnc2 makes to varN are saved, but changes that my_fnc1 makes to var1 are not (no 'put' statement).

In addition to serving as input for user defined functions, user defined variables can be modified and saved as well. For more information, see Modifying variables.

Edit | Attach | Print version | History: r35 | r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r3 - 21 Sep 2011 - 10:26:28 - MarjoleinVanDerWaal
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback