Difference: DocsSectionsBuildingExperiments (12 vs. 13)

Revision 1305 Oct 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"
<---Start1--->

Building Experiments

Line: 10 to 10
 

Experiment definition tables

Changed:
<
<
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 DataSelection 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.
>
>
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 DataSelection 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:

Changed:
<
<
marker time function feval looptick client
>
>
marker time function feval looptick client
 
mrk1 EVENT fnc1,fnc2      
  1 fnc3      
mrk2,mrk3 EVENT fnc4      
Changed:
<
<
Table 1: Actions table

The first column of the Actions table, the marker column, contains the names of all markers that elicit the execution of certain actions. If actions for the same marker are listed in different rows of the table, the marker name only needs to be specified in the first row. For example, in table 1, the actions for marker mrk1 are specified in two different rows, and the marker column can remain empty for the second of these rows. Multiple markers can be specified, separated by commas. Any of the markers from this list will trigger the execution of the associated actions. For example, in table 1, function fnc4 will be executed whenever either marker mrk2 or mrk3 arrives. The marker column can also contain a reference to another table (see Plug-ins).
>
>
Table 1: Actions table

The first column of the Actions table, the marker column, contains the names of all markers that elicit the execution of certain actions. If actions for the same marker are listed in different rows of the table, the marker name only needs to be specified in the first row. For example, in table 1, the actions for marker mrk1 are specified in two different rows, and the marker column can remain empty for the second of these rows. Multiple markers can be specified, separated by commas. Any of the markers from this list will trigger the execution of the associated actions. For example, in table 1, function fnc4 will be executed whenever either marker mrk2 or mrk3 arrives. The marker column can also contain a reference to another table (see Plug-ins).
  The second column (time) specifies at which timepoints, relative to the time of the incoming marker, the 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 functions fnc1 and fnc2 are executed at the onset of marker mrk1 whereas function fnc3 takes place one second after marker onset.
Line: 34 to 34
  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. One second after the onset of marker mrk1, fnc3 will be executed. A number of BrainStream functions can be used in the function column. Alternatively, you can write your own user defined functions, which will be discussed in detail below.
Changed:
<
<
The next three columns are optional. The feval column allows for specification of any functions that take global variables as input argument, but do not process any of them. The looptick column is optional and serves to define a special function that 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).
>
>
The next three columns are optional. The feval column allows for specification of any functions that do not process any of the global variables. The looptick column is optional and serves to define a special function that 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).
  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 defined variables (more on this later).
Line: 42 to 42
 

DataSelection table

Changed:
<
<
Sometimes a marker signals a time point around which data should be collected. For example, if you are building an ERP-based BCI, you might want to collect a certain amount of data after each stimulus. For that purpose, each marker can specify a segment of data that should come along with the event. The DataSelection table indicates which markers call for data selection and also the time period of data selection relative to marker onset.
>
>
Sometimes a marker signals a time point around which data should be collected. For example, if you are building an ERP-based BCI, you might want to collect a certain amount of data after each stimulus. For that purpose, each marker can specify a segment of data that should come along with the event. In the Actions table, markers calling for data selection have a DATA statement in the time column. The DataSelection table lists the markers that call for data selection and specifies the time period of data selection relative to marker onset.
  The DataSelection table consists of a marker column, a begindata column, and an enddata column. Data selection may start before or after onset of the marker, indicated by negative and positive numbers respectively. The end of data selection can be before or after the onset of the marker specified in the marker column, when a new marker arrives (with or without extra timing), or when nothing happens for a specified period of time (timeout). If multiple endtimes, seperated by a comma, are specified, the one that happens first will end the data selection.
Changed:
<
<
marker begintime endtime datasource
>
>
marker begintime endtime datasource
 
mrk1 -0.5 2  
mrk2 0.5 mrk3+1  
mrk4 0 mrk4, mrk5, timeout(3)  
Line: 68 to 68
  The substitute and datasource columns are optional. More information about the substitute column can be found in the section on dependent plug-ins. If multiple data sources are used in the experiment, the datasource column specifies for which data source the dictionary information is meant. If only one datasource is involved, this column can be left out and BrainStream will apply the definitions to the single data source.
Changed:
<
<
marker type value substitute datasource
>
>
marker type value substitute datasource
 
tone stimulus 10    
voice stimulus 11    
button response 128    
Line: 86 to 86
 

User defined functions and variables

Added:
>
>

Functions in the 'function' column

  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 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.
Changed:
<
<
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:
>
>
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:
 
Changed:
<
<
marker time function feval looptick client var1 ........ varN
>
>
marker time function feval looptick client var1 ........ varN
 
mrk1 EVENT my_fnc1       get ........  
mrk2 2 my_fnc2(c1)         ........ get,put
Line: 101 to 102
 User defined functions must be written in the following format:
event = my_function(event,c1,c2,...)
Changed:
<
<
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. For example, in table 5, function my_fnc2 needs the constant c1 as an input argument. Note that in the Actions table you do not need to enter 'event' as the first input argument to your functions, as BrainStream will automatically pass the event structure to all functions.
>
>
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. For example, in table 5, function my_fnc2 needs the constant c1 as an input argument. Note that in the Actions table you do not need to enter 'event' as the first input argument to your functions, as BrainStream will automatically pass the event structure to all functions.
 
Changed:
<
<
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). For more information about loading, modifying and saving user defined variables, see Modifying variables.
>
>
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). For more information about loading, modifying and saving user defined variables, see Modifying variables.

Functions in the 'feval' column

In the feval column, you can specify functions that do not process any of the user defined variables. Examples are Matlab's tic/toc or disp functions. In the example below, tic and toc are used to evaluate the time it takes to execute function my_fnc1:

marker time function feval
mrk1 EVENT   tic
    my_fnc1 toc

As usual, functions are executed in the order in which they appear in the table, first in the order in which they appear within each row and then in the order of the different rows. In the example above, the order of function execution is: tic - my_fnc1 - toc. The tic/toc function will therefore measure the time it takes to execute function fnc1.

In the following table, the execution time of multiple functions will be measured:

marker
time
function
feval
mrk2 EVENT fnc2 tic
    fnc3,fnc4 toc,tic
    fnc5 toc

In this example, the order of function execution is: fnc2 - tic - fnc3 - fnc4 - toc - tic - fnc5 - toc. Therefore, the first tic/toc combination will measure the time it takes to execute function fnc3 and fnc4, whereas the second tic/toc combination measures the time it takes to execute function fnc5.

Functions specified in the feval column can take user defined variables as input arguments, as in the following example:

marker
time
function
feval
Var1
mrk1 EVENT   disp(Var1) get

In this table is specified that the value of Var1 is displayed when marker mrk1 arrives. As is the case for functions in the function column, a get statement is required to copy the content of Var1 from the global variables into the event structure.

 

Block files and common block files

 
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