Difference: DocsSectionsBuildingExperiments (1 vs. 35)

Revision 3527 Feb 2015 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 44 to 44
 

Trigger table

While actions give meaning to the events, the Trigger table implements the logic of the experiment program flow. It defines how each event possibly triggers the execution of other events. Conditional expressions implement runtime dependent triggered events, made possible by allowing global variables to be used in these expressions. An example would be to either trigger the next_trial event or next_sequence event based on the current state of the num_acquired_trials variable. Table 3 demonstrates corresponding Trigger table.
Changed:
<
<
marker time fire datasource delay condition
trial EVENT next_trial eeg 0 num_acquired_trials <= 10
trial EVENT next_sequence eeg 0 num_acquired_trials > 10
>
>
marker time fire datasource delay condition triggeraction
trial EVENT next_trial eeg 0 num_acquired_trials <= 10  
trial EVENT next_sequence eeg 0 num_acquired_trials > 10  
-   print_output eeg 0 num_acquired_trials==10 mod
  Table 3: Trigger table
Changed:
<
<
As long as the number of acquired trials doesn't exceed 10, a next_trial event is triggered by the trial event, otherwise a next_sequence event is triggered. If no conditional expression is specified, corresponding event will always be triggered. Optionally, a delay can be specified, which value is default referenced relatively against the events timepoint time that triggers it. If it should be referenced against actual moment of execution of the event, instead specify for the delay: 0,'now'. The datasource is only relevant if corresponding triggered event defines data (it has a DATA timepoint) in order to collect the correct data epochs. For example useful if a single marker triggers periodic data collection or a limited number of data epochs as determined by logic incorporated in the conditional expression .
>
>
As long as the number of acquired trials doesn't exceed 10, a next_trial event is triggered by the trial event, otherwise a next_sequence event is triggered. If no conditional expression is specified, corresponding event will always be triggered. Optionally, a delay can be specified, which value is default referenced relatively against the events timepoint time that triggers it. If it should be referenced against the actual moment of execution of the event, instead specify for the delay: 0,now. The datasource is only relevant if corresponding triggered event defines data (it has a DATA timepoint) in order to collect the correct data epochs. For example useful if a single marker triggers periodic data collection or a limited number of data epochs as determined by logic incorporated in the conditional expression.

Markers can also be triggered based on the state of the variables, i.e., watchdog triggered markers. Each time a global variable involved in the conditional expression is being modified, the conditional expression is evaluated and if true, corresponding marker is triggered. This is the default behaviour, however, the user can control which global variable(s) modifications and which actions ( mod, put, or mod and put) will start the evaluation of the expression. For instance: mod(num) means evaluate the expression only a mod-action for variable num. For watchdog triggered markers the marker information can be left empty or specify a dash -, the time column information can be left empty since triggering is not time-dependent.

 

Revision 3426 Feb 2015 - Main.PhilipVanDenBroek

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

Building Experiments

Revision 3318 Nov 2014 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 48 to 48
 
trial EVENT next_trial eeg 0 num_acquired_trials <= 10
trial EVENT next_sequence eeg 0 num_acquired_trials > 10
Changed:
<
<
Table 4: Trigger table
>
>
Table 3: Trigger table
 
Changed:
<
<
As long as the number of acquired trials doesn't exceed 10, a next_trial event is triggered by the trial event, otherwise a next_sequence event is triggered. If no conditional expression is specified, corresponding event will always be triggered. Optionally, a delay can be specified, which value is default referenced relatively against the events timepoint time that triggers it. If it should be referenced against actual moment of execution of the event, instead specify for the delay: 0,'now'. The datasource is only relevant if corresponding triggered event defines data (it has a DATA timepoint) in order to collect the correct data epochs. For example useful if a single marker triggers periodic data collection or a limited number of data epochs as determined by logic incorporated in the conditional expression.
>
>
As long as the number of acquired trials doesn't exceed 10, a next_trial event is triggered by the trial event, otherwise a next_sequence event is triggered. If no conditional expression is specified, corresponding event will always be triggered. Optionally, a delay can be specified, which value is default referenced relatively against the events timepoint time that triggers it. If it should be referenced against actual moment of execution of the event, instead specify for the delay: 0,'now'. The datasource is only relevant if corresponding triggered event defines data (it has a DATA timepoint) in order to collect the correct data epochs. For example useful if a single marker triggers periodic data collection or a limited number of data epochs as determined by logic incorporated in the conditional expression.
 
Line: 93 to 93
 

Preventing conflicts with imported tables

Changed:
<
<
BrainStream supports the use of imported tables. Alternatively, it is possible to build your own imported table.

When BrainStream is started, all experiment definition tables that are used in the experiment - including the imported tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.

>
>
BrainStream supports the use of imported tables. When BrainStream is started, all experiment definition tables that are used in the experiment - including the imported tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
 

Revision 3217 Nov 2014 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 12 to 12
 

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 where each table is put in a different sheet. 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, four different tables are needed: the Actions table, the DataSelection table, the Dictionary table, and Trigger 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 where each table is put in a different sheet. In the following, the experiment definition tables will be discussed in more detail.
 

Actions table

Line: 40 to 40
  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).
Added:
>
>

Trigger table

While actions give meaning to the events, the Trigger table implements the logic of the experiment program flow. It defines how each event possibly triggers the execution of other events. Conditional expressions implement runtime dependent triggered events, made possible by allowing global variables to be used in these expressions. An example would be to either trigger the next_trial event or next_sequence event based on the current state of the num_acquired_trials variable. Table 3 demonstrates corresponding Trigger table.

marker time fire datasource delay condition
trial EVENT next_trial eeg 0 num_acquired_trials <= 10
trial EVENT next_sequence eeg 0 num_acquired_trials > 10

Table 4: Trigger table

As long as the number of acquired trials doesn't exceed 10, a next_trial event is triggered by the trial event, otherwise a next_sequence event is triggered. If no conditional expression is specified, corresponding event will always be triggered. Optionally, a delay can be specified, which value is default referenced relatively against the events timepoint time that triggers it. If it should be referenced against actual moment of execution of the event, instead specify for the delay: 0,'now'. The datasource is only relevant if corresponding triggered event defines data (it has a DATA timepoint) in order to collect the correct data epochs. For example useful if a single marker triggers periodic data collection or a limited number of data epochs as determined by logic incorporated in the conditional expression.

 

DataSelection table

Line: 53 to 65
 
mrk2 0.5 mrk3+1  
mrk4 0 mrk4, mrk5, 3  
Changed:
<
<
Table 3: DataSelection table
>
>
Table 4: DataSelection table
  The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end one second after marker mrk3 arrives. Marker mrk4 will start data selection immediately and this will end when a new marker mrk4 arrives. In other words, after the first occurrence of marker mrk4, every new marker mrk4 will both end the previous period of data selection and start a new period. This sequence ends when marker mrk5 arrives or when no markers come in for 3 seconds. Note that if ending markers do not set the end of data selection and no timeout is specified, corresponding actions (with timepoint DATA) will never be executed.
Line: 81 to 93
 

Preventing conflicts with imported tables

Changed:
<
<
BrainStream supports the use of imported tables. An example of an imported table is the import-table for bad channel detection. Alternatively, it is possible to build your own imported table.
>
>
BrainStream supports the use of imported tables. Alternatively, it is possible to build your own imported table.
  When BrainStream is started, all experiment definition tables that are used in the experiment - including the imported tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.

Revision 3114 Nov 2014 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 24 to 24
 
  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 Import-tables).
  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: 79 to 79
 
Changed:
<
<

Preventing conflicts with plug-in tables

>
>

Preventing conflicts with imported tables

 
Changed:
<
<
BrainStream supports the use of plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table.
>
>
BrainStream supports the use of imported tables. An example of an imported table is the import-table for bad channel detection. Alternatively, it is possible to build your own imported table.
 
Changed:
<
<
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
>
>
When BrainStream is started, all experiment definition tables that are used in the experiment - including the imported tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
 

Revision 3011 Nov 2014 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 12 to 12
 

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 where each table is put in a different sheet. In the following, the experiment definition tables will be discussed in more detail.
 

Actions table

Line: 68 to 68
  The first three columns of the Dictionary table are fixed. In the marker column the marker names are specified. The second column specifies the marker type. The marker can for example be a stimulus or a response marker. The value column specifies the number with which the marker is represented outside BrainStream.
Changed:
<
<
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.
>
>
The datasource column is optional. 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
tone stimulus 10    
voice stimulus 11    
button response 128    
>
>
marker type value datasource
tone stimulus 10  
voice stimulus 11  
button response 128  
  Table 4: Dictionary table
Line: 83 to 83
  BrainStream supports the use of plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table.
Changed:
<
<
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
>
>
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables should not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
 

Revision 2915 Jun 2012 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 51 to 51
 
marker begintime endtime datasource
mrk1 -0.5 2  
mrk2 0.5 mrk3+1  
Changed:
<
<
mrk4 0 mrk4, mrk5, timeout(3)  
>
>
mrk4 0 mrk4, mrk5, 3  
  Table 3: DataSelection table
Line: 162 to 162
  In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
Changed:
<
<
In the blocksettings definitions, also direct assignments to sub fields are possible:
>
>
In the blocksettings definitions, also direct assignments to sub fields are possible:
 
[preproc]
pp.downsample.targetFs    = 256
pp.bcd.doplot      = 1;

Revision 2815 May 2012 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 191 to 191
 

Referencing to other block files

Changed:
<
<
It is possible to incorporate blocksettings defined in one block file in another. For example, in one block file (block1.blk) you may have specified certain stimulus settings under topic StimulusSettings:
[StimulusSettings]
>
>
It is possible to incorporate blocksettings defined in one block file in another. For example, in one block file (block1.blk) you may have specified certain stimulus settings under topic CommonStimulusSettings:
[CommonStimulusSettings]
 numstim = 20; %present 20 stimuli soa = 300; %stimulus onset asynchrony is 300 ms duration = 50; %stimulus duration is 50 ms

If you want to incorporate the same settings in another block file, you can do this with the @ symbol followed by the name of the block file and the topic you want to include. For example:

[StimulusSettings]
Changed:
<
<
@block1.blk StimulusSettings?
>
>
@block1.blk CommonStimulusSettings?
 
Changed:
<
<
All keys defined under topic StimulusSettings in block file block1.blk will be added to the block file in which the reference is specified.
>
>
All keys defined under topic CommonStimulusSettings in block file block1.blk will be added to the StimulusSettings topic.
  Note that the block file to which you refer must be in the same folder as where the current processed blockfile is located or on the Matlab search path.

Revision 2709 May 2012 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 162 to 162
  In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
Changed:
<
<
If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. The structure of a common block file is the same as other block files, but settings specified in a common block file will be applied to all blocks. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.
>
>
In the blocksettings definitions, also direct assignments to sub fields are possible:
[preproc]
pp.downsample.targetFs    = 256
pp.bcd.doplot      = 1;

This is especially convenient for grouped settings that need to be processed together. For instance, when calling functions from the FieldTrip toolbox, parameters are passed the functions through a Matlab structure (in general it is named cfg). In the blocksettings define:

[freqanalysis]
cfg.method      = 'mtmfft'; 
cfg.output      = 'fourier';
cfg.foilim      = [60 60];
cfg.taper       = 'dpss'; 
cfg.tapsmofrq   = 20; 
cfg.keeptrials  = 'yes';
cfg.keeptapers  = 'yes';  
then in your BrainStream function:
.. ..
cfg = bs_get_blockvalue(‘freqanalysis’,’cfg’);
freq = ft_freqanalysis(cfg, event.data.raw);
.. ..

This provides direct access to cfg parameters and different topics with configuration settings can be defined for each type of required FieldTrip analyses. Since Matlab syntax is allowed in the blocksettings assignments, FieldTrip configuration settings for BrainStream are defined in a similar way.


If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. The structure of a common block file is the same as other block files, but settings specified in a common block file will be applied to all blocks. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.

 

Referencing to other block files

Line: 191 to 215
  'my_BCI/feedback.blk'} [CommonBlocks] Files = {'lab1.blk'}
Changed:
<
<
Try to prevent using absolute path names and specify them relatively to the folder where the BrainStream project file is located (eg. '../myclassifiers/classifier.blk'). When entire folder structures are copied/moved around, corresponding block files will still be found.
>
>
Try to prevent using absolute path names and specify them relatively to the folder where the BrainStream project file is located (eg. '../myclassifiers/classifier.blk'). When entire folder structures are copied/moved around, corresponding block files will still be found.
 
<---End1--->

Revision 2617 Apr 2012 - Main.PhilipVanDenBroek

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

Building Experiments

Line: 179 to 179
  All keys defined under topic StimulusSettings in block file block1.blk will be added to the block file in which the reference is specified.
Changed:
<
<
Note that the block file to which you refer must be on the Matlab search path.
>
>
Note that the block file to which you refer must be in the same folder as where the current processed blockfile is located or on the Matlab search path.
 

BrainStream project files

References to all block files and common block files can be put together in a single seperate 'BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:

[Blocks]
Changed:
<
<
Files = {'/Volumes/my_experiments/my_BCI/train.blk', ... '/Volumes/my_experiments/my_BCI/classifier.blk', ... '/Volumes/my_experiments/my_BCI/feedback.blk'}
>
>
Files = {'train.blk', ... 'classifier.blk', ... 'my_BCI/feedback.blk'}
 [CommonBlocks]
Changed:
<
<
Files = {'lab1.blk'}
>
>
Files = {'lab1.blk'} Try to prevent using absolute path names and specify them relatively to the folder where the BrainStream project file is located (eg. '../myclassifiers/classifier.blk'). When entire folder structures are copied/moved around, corresponding block files will still be found.
 
<---End1--->

Revision 2522 Mar 2012 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 57 to 57
  The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end one second after marker mrk3 arrives. Marker mrk4 will start data selection immediately and this will end when a new marker mrk4 arrives. In other words, after the first occurrence of marker mrk4, every new marker mrk4 will both end the previous period of data selection and start a new period. This sequence ends when marker mrk5 arrives or when no markers come in for 3 seconds. Note that if ending markers do not set the end of data selection and no timeout is specified, corresponding actions (with timepoint DATA) will never be executed.
Changed:
<
<
Timing offsets can also be specified in number of samples. In that case, the number should be followed by a '#' symbol (for example, 1024#). Of course, time points that are specified in seconds will also be rounded off to the nearest sample number by BrainStream's internal processing.
>
>
Timing offsets can also be specified in number of samples. In that case, the number should be followed by a '#' symbol (for example, 1024#). Of course, time points that are specified in seconds will also be rounded off to the nearest sample number by BrainStream's internal processing. Importantly, the sample corresponding to 'begintime' is not included in the data selection, whereas the sample corresponding to 'endtime' is included. For some examples related to this issue, click here? .
  The datasource column is optional. If multiple data sources are used in the experiment, the datasource column specifies from which source the data should be collected. If only one data source is involved, BrainStream will automatically collect data from this single source only.

Revision 2421 Feb 2012 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 163 to 163
 In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.

If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. The structure of a common block file is the same as other block files, but settings specified in a common block file will be applied to all blocks. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.

Added:
>
>
 

Referencing to other block files

It is possible to incorporate blocksettings defined in one block file in another. For example, in one block file (block1.blk) you may have specified certain stimulus settings under topic StimulusSettings:

Revision 2306 Jan 2012 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 36 to 36
  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 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 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 can contain special functions that will be put into a loop by BrainStream. The client column can be used to direct execution of functions to another remote Matlab session (see 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: 132 to 132
 
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.

Added:
>
>

Functions in the 'looptick' column

Looptick functions are a specific type of loop function that can be used when BrainStream is running in parallel mode. More information on these functions can be found in the advanced topic Looptick Functions.

 

Block files and common block files

Revision 2215 Nov 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 169 to 169
 duration = 50; %stimulus duration is 50 ms

If you want to incorporate the same settings in another block file, you can do this with the @ symbol followed by the name of the block file and the topic you want to include. For example:

Changed:
<
<
@block1.blk StimulusSettings
>
>
[StimulusSettings]
@block1.blk StimulusSettings
  All keys defined under topic StimulusSettings in block file block1.blk will be added to the block file in which the reference is specified.

Revision 2115 Nov 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 112 to 112
 

Functions in the 'feval' column

Changed:
<
<
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:
>
>
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
Line: 157 to 157
  Additional possible topics with their keys are listed here.
Changed:
<
<
In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
>
>
In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
  If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. The structure of a common block file is the same as other block files, but settings specified in a common block file will be applied to all blocks. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.
Added:
>
>

Referencing to other block files

It is possible to incorporate blocksettings defined in one block file in another. For example, in one block file (block1.blk) you may have specified certain stimulus settings under topic StimulusSettings:

[StimulusSettings]
numstim  = 20;  %present 20 stimuli
soa      = 300; %stimulus onset asynchrony is 300 ms
duration = 50;  %stimulus duration is 50 ms

If you want to incorporate the same settings in another block file, you can do this with the @ symbol followed by the name of the block file and the topic you want to include. For example:

@block1.blk StimulusSettings

All keys defined under topic StimulusSettings in block file block1.blk will be added to the block file in which the reference is specified.

Note that the block file to which you refer must be on the Matlab search path.

 

BrainStream project files

Revision 2014 Nov 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
Changed:
<
<
META TOPICPARENT name="BrainStream.BrainStreamDocs"
>
>
META TOPICPARENT name="WebHome"
 
<---Start1--->

Building Experiments

Line: 7 to 7
 
Changed:
<
<
An experiment in BrainStream consists of experiment definition tables, block files and common block files. The experiment may also need user defined functions. The entire experiment is summarized in the BrainStream.BrainStream Project file. In the following, each of these components will be discussed.
>
>
An experiment in BrainStream consists of experiment definition tables, block files and common block files. The experiment may also need user defined functions. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.
 

Experiment definition tables

Line: 34 to 34
  Table 2: Specifying time of action execution
Changed:
<
<
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.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.
>
>
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 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.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 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: 44 to 44
 

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. 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.
>
>
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.
Line: 104 to 104
 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.
 
Line: 155 to 155
 Block = 'subjective_rhythm'
Changed:
<
<
Additional possible topics with their keys are listed here? .
>
>
Additional possible topics with their keys are listed here.
 
Changed:
<
<
In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
>
>
In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
  If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. The structure of a common block file is the same as other block files, but settings specified in a common block file will be applied to all blocks. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.

BrainStream project files

Changed:
<
<
References to all block files and common block files can be put together in a single seperate 'BrainStream.BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:
>
>
References to all block files and common block files can be put together in a single seperate 'BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:
 
[Blocks]
Files = {'/Volumes/my_experiments/my_BCI/train.blk', ...
         '/Volumes/my_experiments/my_BCI/classifier.blk', ...

Revision 1914 Nov 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Changed:
<
<
Generate current PDF
>
>
Generate current PDF
 
Changed:
<
<
An experiment in BrainStream consists of experiment definition tables, block files and common block files. The experiment may also need user defined functions. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.
>
>
An experiment in BrainStream consists of experiment definition tables, block files and common block files. The experiment may also need user defined functions. The entire experiment is summarized in the BrainStream.BrainStream Project file. In the following, each of these components will be discussed.
 

Experiment definition tables

Line: 34 to 34
  Table 2: Specifying time of action execution
Changed:
<
<
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.
>
>
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.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 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).
>
>
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.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: 117 to 117
 
mrk1 EVENT   tic
    my_fnc1 toc
Changed:
<
<
According to the fixed order in which BrainStreams executes actions, 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.
>
>
According to the fixed order in which BrainStream executes actions, 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
Line: 164 to 164
 

BrainStream project files

Changed:
<
<
References to all block files and common block files can be put together in a single seperate 'BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:
>
>
References to all block files and common block files can be put together in a single seperate 'BrainStream.BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:
 
[Blocks]
Files = {'/Volumes/my_experiments/my_BCI/train.blk', ...
         '/Volumes/my_experiments/my_BCI/classifier.blk', ...
Line: 178 to 178
 
  • Access control
    • Set DENYTOPICVIEW =
--> \ No newline at end of file
Added:
>
>
META TOPICMOVED by="MarjoleinVanDerWaal" date="1321263999" from="BrainStream.DocsSectionsBuildingExperiments" to="BrainStreamDocs.DocsSectionsBuildingExperiments"

Revision 1809 Nov 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 17 to 17
 

Actions table

Changed:
<
<
Table 1 is an example of an Actions table:
>
>
The Actions table specifies the actions that should be executed for each marker. Table 1 is an example of an Actions table:
 
marker time function feval looptick client
mrk1 EVENT fnc1,fnc2      

Revision 1717 Oct 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Revision 1612 Oct 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 112 to 112
 

Functions in the 'feval' column

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

Revision 1510 Oct 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 117 to 117
 
mrk1 EVENT   tic
    my_fnc1 toc
Changed:
<
<
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.
>
>
According to the fixed order in which BrainStreams executes actions, 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

Revision 1410 Oct 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Added:
>
>
Generate current PDF
 

An experiment in BrainStream consists of experiment definition tables, block files and common block files. The experiment may also need user defined functions. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.

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

Revision 1204 Oct 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Revision 1130 Sep 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 53 to 53
  Table 3: DataSelection table
Changed:
<
<
The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end one second after marker mrk3 arrives. Marker mrk4 will start data selection immediately and this will end when a new marker mrk4 arrives (in other words, after the first occurrence of marker mrk4, every new marker mrk4 will both end the previous period of data selection and start a new period). This sequence ends when marker mrk5 arrives or when no markers come in for 3 seconds. Note that if ending markers do not set the end of data selection and no timeout is specified, corresponding processing steps (with timepoint DATA) will never execute.
>
>
The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end one second after marker mrk3 arrives. Marker mrk4 will start data selection immediately and this will end when a new marker mrk4 arrives. In other words, after the first occurrence of marker mrk4, every new marker mrk4 will both end the previous period of data selection and start a new period. This sequence ends when marker mrk5 arrives or when no markers come in for 3 seconds. Note that if ending markers do not set the end of data selection and no timeout is specified, corresponding actions (with timepoint DATA) will never be executed.
  Timing offsets can also be specified in number of samples. In that case, the number should be followed by a '#' symbol (for example, 1024#). Of course, time points that are specified in seconds will also be rounded off to the nearest sample number by BrainStream's internal processing.
Line: 66 to 66
  The first three columns of the Dictionary table are fixed. In the marker column the marker names are specified. The second column specifies the marker type. The marker can for example be a stimulus or a response marker. The value column specifies the number with which the marker is represented outside BrainStream.
Changed:
<
<
The substitute and datasource columns are optional. More information about the substitute column can be found in the Plug-in? section. 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.
>
>
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.
 
marker type value substitute datasource
tone stimulus 10    
Line: 79 to 79
 

Preventing conflicts with plug-in tables

Changed:
<
<
BrainStream supports the use of plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table. Any plug-in itself consists of an Action, DataSelection and Dictionary table.
>
>
BrainStream supports the use of plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table.
 
Changed:
<
<
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
>
>
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
 
Line: 92 to 92
 
marker time function feval looptick client var1 ........ varN
mrk1 EVENT my_fnc1       get ........  
Changed:
<
<
mrk2 2 my_fnc2         ........ get,put
>
>
mrk2 2 my_fnc2(c1)         ........ get,put

Table 5: Example Actions table

  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 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.
>
>
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.
  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.
Line: 140 to 142
  '/Volumes/my_experiments/my_BCI/classifier.blk', ... '/Volumes/my_experiments/my_BCI/feedback.blk'} [CommonBlocks]
Changed:
<
<
Files = {'lab1.blk'}
<---End1--->
>
>
Files = {'lab1.blk'}

<---End1--->

<-- 
  • Access control
    • Set DENYTOPICVIEW =
-->

Revision 1028 Sep 2011 - Main.MarjoleinVanDerWaal

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

Building Experiments

Line: 139 to 140
  '/Volumes/my_experiments/my_BCI/classifier.blk', ... '/Volumes/my_experiments/my_BCI/feedback.blk'} [CommonBlocks]
Changed:
<
<
Files = {'lab1.blk'}
>
>
Files = {'lab1.blk'}
<---End1--->

Revision 927 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

Building Experiments

Line: 21 to 21
 
  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: 65 to 65
  The first three columns of the Dictionary table are fixed. In the marker column the marker names are specified. The second column specifies the marker type. The marker can for example be a stimulus or a response marker. The value column specifies the number with which the marker is represented outside BrainStream.
Changed:
<
<
The substitute and datasource columns are optional. More information about the substitute column can be found in the Plug-in section. 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.
>
>
The substitute and datasource columns are optional. More information about the substitute column can be found in the Plug-in? section. 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.
 
marker type value substitute datasource
tone stimulus 10    
Line: 78 to 78
 

Preventing conflicts with plug-in tables

Changed:
<
<
BrainStream supports the use of Plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table. Any plug-in itself consists of an Action, DataSelection and Dictionary table.
>
>
BrainStream supports the use of plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table. Any plug-in itself consists of an Action, DataSelection and Dictionary table.
 
Changed:
<
<
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers.
>
>
When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers in the Dictionary tables.
 

Revision 827 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

Building Experiments

Revision 726 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

Building Experiments

Line: 43 to 43
  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.
Changed:
<
<
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 again be before or after the onset of the marker specified in the marker column, or you can use a new incoming marker by entering the name of the new marker (with or without extra timing). If multiple endtimes, seperated by a comma, are specified, the one that happens first will end the data selection.
>
>
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.
 
marker begintime endtime datasource
mrk1 -0.5 2  
Changed:
<
<
mrk2 0.5 mrk3  
mrk3 0 mrk3, mrk4  
>
>
mrk2 0.5 mrk3+1  
mrk4 0 mrk4, mrk5, timeout(3)  
  Table 3: DataSelection table
Changed:
<
<
The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end when the new marker mrk3 arrives. mrk3 will start data selection immediately and this will end when a new marker mrk3 or the marker mrk4 arrives. For more examples of this data selection timing see Data-carrying events in the Architecture section.
>
>
The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end one second after marker mrk3 arrives. Marker mrk4 will start data selection immediately and this will end when a new marker mrk4 arrives (in other words, after the first occurrence of marker mrk4, every new marker mrk4 will both end the previous period of data selection and start a new period). This sequence ends when marker mrk5 arrives or when no markers come in for 3 seconds. Note that if ending markers do not set the end of data selection and no timeout is specified, corresponding processing steps (with timepoint DATA) will never execute.

Timing offsets can also be specified in number of samples. In that case, the number should be followed by a '#' symbol (for example, 1024#). Of course, time points that are specified in seconds will also be rounded off to the nearest sample number by BrainStream's internal processing.

  The datasource column is optional. If multiple data sources are used in the experiment, the datasource column specifies from which source the data should be collected. If only one data source is involved, BrainStream will automatically collect data from this single source only.

Revision 623 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"
Changed:
<
<

Building Experiments

>
>

Building Experiments

 
Changed:
<
<
An experiment in BrainStream consists of experiment definition tables, which in some instances might contain user defined functions, block files and common block files. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.
>
>
 
Changed:
<
<
>
>
An experiment in BrainStream consists of experiment definition tables, block files and common block files. The experiment may also need user defined functions. The entire experiment is summarized in the BrainStream Project file. 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 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.

Line: 14 to 16
  Table 1 is an example of an Actions table:
Changed:
<
<
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 defined variables (stored internally in BrainStream's user state, i.e. the global variables).

>
>
marker time function feval looptick client
mrk1 EVENT fnc1,fnc2      
  1 fnc3      
mrk2,mrk3 EVENT fnc4      
 
Changed:
<
<
The first column of the Actions table, 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.
>
>
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).
 
Changed:
<
<
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 some actions are executed at the onset of marker mrk1 whereas other actions take place two seconds after marker mrk2.
>
>
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: 32 to 31
  Table 2: Specifying time of action execution
Changed:
<
<
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 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 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.
>
>
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).
 
Changed:
<
<
All subsequent columns are free to use for an arbitrary number of user defined variables (more on this 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 defined variables (more on this later).
 

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 collection 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. The DataSelection table indicates which markers call for data selection and also 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 again be before or after the onset of the marker specified in the marker column, or you can use a new incoming marker by entering the name of the new marker (with or without extra timing). If multiple endtimes, seperated by a comma, are specified, the one that happens first will end the data selection.
Line: 55 to 54
  The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end when the new marker mrk3 arrives. mrk3 will start data selection immediately and this will end when a new marker mrk3 or the marker mrk4 arrives. For more examples of this data selection timing see Data-carrying events in the Architecture section.
Changed:
<
<
The datasource column is optional. If multiple data sources are used in the experiment, the datasource column specifies from which source the data should be collected. If only one data source is involved, BrainStream will automatically collect data from this single source only.
>
>
The datasource column is optional. If multiple data sources are used in the experiment, the datasource column specifies from which source the data should be collected. If only one data source is involved, BrainStream will automatically collect data from this single source only.
 

Dictionary table

Markers are represented as numbers in for example the acquisition hardware or stimulus presentation modules, whereas in BrainStream they are represented as names (strings). The Dictionary table is required to translate incoming markers to their associated names.

Changed:
<
<
The first three columns of the Dictionary table are fixed. In the marker column the marker names are specified. The second column (type) column specifies the marker type. The marker can for example be a stimulus or a response marker. The value column specifies the number with which the marker is represented outside BrainStream.
>
>
The first three columns of the Dictionary table are fixed. In the marker column the marker names are specified. The second column specifies the marker type. The marker can for example be a stimulus or a response marker. The value column specifies the number with which the marker is represented outside BrainStream.
  The substitute and datasource columns are optional. More information about the substitute column can be found in the Plug-in section. 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.
Line: 73 to 72
  Table 4: Dictionary table
Changed:
<
<
>
>
 
Changed:
<
<

Plug-in tables

>
>

Preventing conflicts with plug-in tables

 
Changed:
<
<
BrainStream supports the use of Plug-in tables. An example of a plug-in table is the plug-in for [BrainStreamDocs.DocsSectionsApplications#SeqBadChan][bad channel detection]]. Alternatively, it is possible to build your own plug-in table. Any plug-in itself consists of an Action, DataSelection and Dictionary table.
>
>
BrainStream supports the use of Plug-in tables. An example of a plug-in table is the plug-in for bad channel detection. Alternatively, it is possible to build your own plug-in table. Any plug-in itself consists of an Action, DataSelection and Dictionary table.
  When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers.
Changed:
<
<
>
>
 

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 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.
Line: 97 to 96
 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.
>
>
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). For more information about loading, modifying and saving user defined variables, see Modifying variables.
Changed:
<
<
>
>
 

Block files and common block files

Changed:
<
<
To initiate your experiment in BrainStream, you need to compose an initialization run file(s), also called a block file (.blk). Every block has a separate file, which contains or refers to all information needed to initiate the particular block. For example, BrainStream needs to know to which data acquisition source it is connected, where to store output and where the experiment definition tables are located. All this information can be summarized in a text file with file name extension .blk. The format of the file is according to the Windows .ini file style with topics enclosed in brackets and subsequent lines to define keys that belong to this topic. If another bracketed line is encountered, a new topic is started and additional lines will add keys to this new topic. The notation of the topics and keys is in Matlab style, which means that every valid Matlab statement is possible here. For example, Matlabs comment character (%) can be utilized. An example of a block file is shown below. In this example, all minimally required topics with their keys are shown.
>
>
To initiate your experiment in BrainStream, you need to compose one or more initialization run files, also called block files (.blk). Each block file contains or refers to all information needed to initiate the particular block of the experiment. For example, BrainStream needs to know to which data acquisition source it is connected, where to store output and where the experiment definition tables are located. The format of the block files is according to the Windows .ini file style with topics enclosed in brackets and subsequent lines to define keys that belong to this topic. If another bracketed line is encountered, a new topic is started and additional lines will add keys to this new topic. The notation of the topics and keys is in Matlab style, which means that every valid Matlab statement is possible here. For example, Matlabs comment character (%) can be utilized. An example of a block file is shown below. In this example, all minimally required topics with their keys are shown.
 
[DataSources]
eeg = 'buffer://localhost:1972:biosemi_active2'
Line: 125 to 124
  Additional possible topics with their keys are listed here? .
Changed:
<
<
In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
>
>
In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.
 
Changed:
<
<
If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.
>
>
If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. The structure of a common block file is the same as other block files, but settings specified in a common block file will be applied to all blocks. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.
 
Changed:
<
<
>
>
 

BrainStream project files

References to all block files and common block files can be put together in a single seperate 'BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:

Revision 522 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

Building Experiments

Changed:
<
<
An experiment in BrainStream consists of experiment definition tables, block files and common block files, and, in some instances, user defined functions. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.
>
>
An experiment in BrainStream consists of experiment definition tables, which in some instances might contain user defined functions, block files and common block files. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.
 

Experiment definition tables

Line: 20 to 20
  Table 1: Actions table
Changed:
<
<
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 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 defined variables (stored internally in BrainStream's user state, i.e. the global variables).
 
Changed:
<
<
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 first column of the Actions table, 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.
 
Changed:
<
<
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.
>
>
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 some actions are executed at the onset of marker mrk1 whereas other actions take place two seconds after marker mrk2.
 

Line: 36 to 36
  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.
Changed:
<
<
All subsequent columns are free to use for an arbitrary number of user specified variables (more on this later).
>
>
All subsequent columns are free to use for an arbitrary number of user defined variables (more on this later).
 

Revision 421 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

Building Experiments

Changed:
<
<
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.
>
>
An experiment in BrainStream consists of experiment definition tables, block files and common block files, and, in some instances, user defined functions. The entire experiment is summarized in the BrainStream Project file. In the following, each of these components will be discussed.
 
Added:
>
>
 

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

Line: 19 to 20
  Table 1: Actions table
Changed:
<
<
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 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.
Line: 29 to 30
 
EVENT
DATA
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
Changed:
<
<
Table 2: specifying time of action execution
>
>
Table 2: Specifying time of action execution
 
Changed:
<
<
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 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).

Added:
>
>
 

DataSelection table

Added:
>
>
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 collection 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 again be before or after the onset of the marker specified in the marker column, or you can use a new incoming marker by entering the name of the new marker (with or without extra timing). If multiple endtimes, seperated by a comma, are specified, the one that happens first will end the data selection.

marker begintime endtime datasource
mrk1 -0.5 2  
mrk2 0.5 mrk3  
mrk3 0 mrk3, mrk4  

Table 3: DataSelection table

The table above shows an example of a data selection table. The data selection of mrk1 will start half a second before onset of the marker and end 2 seconds after the onset.The data selection of mrk2 will start half a second after the onset of mrk2 and will end when the new marker mrk3 arrives. mrk3 will start data selection immediately and this will end when a new marker mrk3 or the marker mrk4 arrives. For more examples of this data selection timing see Data-carrying events in the Architecture section.

The datasource column is optional. If multiple data sources are used in the experiment, the datasource column specifies from which source the data should be collected. If only one data source is involved, BrainStream will automatically collect data from this single source only.

 

Dictionary table

Added:
>
>
Markers are represented as numbers in for example the acquisition hardware or stimulus presentation modules, whereas in BrainStream they are represented as names (strings). The Dictionary table is required to translate incoming markers to their associated names.

The first three columns of the Dictionary table are fixed. In the marker column the marker names are specified. The second column (type) column specifies the marker type. The marker can for example be a stimulus or a response marker. The value column specifies the number with which the marker is represented outside BrainStream.

The substitute and datasource columns are optional. More information about the substitute column can be found in the Plug-in section. 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.

marker type value substitute datasource
tone stimulus 10    
voice stimulus 11    
button response 128    

Table 4: Dictionary table

Plug-in tables

BrainStream supports the use of Plug-in tables. An example of a plug-in table is the plug-in for [BrainStreamDocs.DocsSectionsApplications#SeqBadChan][bad channel detection]]. Alternatively, it is possible to build your own plug-in table. Any plug-in itself consists of an Action, DataSelection and Dictionary table.

When BrainStream is started, all experiment definition tables that are used in the experiment - including the plug-in tables - are combined in a process called table expansion. This means that all Action tables will be integrated into a single Action table, and the same is true for the DataSelection and Dictionary tables. Importantly, the information in the individual tables shoud not conflict. For example, you should prevent double definitions of marker names or numbers.

 

User defined functions and variables

Changed:
<
<
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.
>
>
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:
 
marker time function feval looptick client var1 ........ varN
mrk1 EVENT my_fnc1       get ........  
Line: 52 to 94
  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.
Changed:
<
<
User defined functions) need to be written in the following format:
>
>
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 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). For more information about loading, modifying and saving user defined variables, see Modifying variables.

Block files and common block files

To initiate your experiment in BrainStream, you need to compose an initialization run file(s), also called a block file (.blk). Every block has a separate file, which contains or refers to all information needed to initiate the particular block. For example, BrainStream needs to know to which data acquisition source it is connected, where to store output and where the experiment definition tables are located. All this information can be summarized in a text file with file name extension .blk. The format of the file is according to the Windows .ini file style with topics enclosed in brackets and subsequent lines to define keys that belong to this topic. If another bracketed line is encountered, a new topic is started and additional lines will add keys to this new topic. The notation of the topics and keys is in Matlab style, which means that every valid Matlab statement is possible here. For example, Matlabs comment character (%) can be utilized. An example of a block file is shown below. In this example, all minimally required topics with their keys are shown.

[DataSources]
eeg = 'buffer://localhost:1972:biosemi_active2'

[eeg]
% keys specific to the eeg data source 

[biosemi_active2] 
sendMarkerFunction = 'sndMidiMarker'

[Files]
ExperimentDefinitionFile = '/Volumes/Data/ExpDefs/SubRhythm/SubjectiveRhythm.xls'
OutFolder = '/Volumes/Data/Experiment/'

[Experiment]
Block = 'subjective_rhythm'

Additional possible topics with their keys are listed here? .

In addition to the listed topics and keys you can add your own topics and keys, as long as they are not used by BrainStream itself. The advantage is that these items are readily accessible for your own written user defined functions throughout the whole experiment. Information in the block files can be accessed using the bs_get_blockvalue function.

 
Changed:
<
<
The additional input arguments (c1, c2, ...) are optional. You can enter constants there, if your function needs them.
>
>
If an experiment consists of several blocks, the topic and key combinations which are the same for all blocks can be put in a common block file. For example, information that is specific to the lab in which the experiment takes place could be put in a common block file. The advantage is that you do not have to specify the same information more than once and if you change the setting in the common block file it will be applied to all blocks.
 
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).
>
>

BrainStream project files

 
Changed:
<
<
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.
>
>
References to all block files and common block files can be put together in a single seperate 'BrainStream Project' (.bsp, or .exp for older versions) file with topics Blocks and CommonBlocks. Both topics define the Files key, in which a cell array of block file names defines which block files take part in the experiment. This single file then defines your whole BCI experiment. For example, if your experiment is defined by three functional blocks, namely train.blk, classifier.blk and feedback.blk, and one common block file lab1.blk, the following project file would be sufficient to include them all at once when starting BrainStream:
[Blocks]
Files = {'/Volumes/my_experiments/my_BCI/train.blk', ...
         '/Volumes/my_experiments/my_BCI/classifier.blk', ...
         '/Volumes/my_experiments/my_BCI/feedback.blk'}
[CommonBlocks]
Files = {'lab1.blk'}  

Revision 321 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

Building Experiments

Line: 19 to 19
  Table 1: Actions table
Changed:
<
<
The first three columns in an Actions table are reserved to specify marker, time, and function. The three following columns feval, client, and looptick 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 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).
 
Changed:
<
<
The first column of the Actions table is the marker column. The marker column contains 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 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.
 
Changed:
<
<
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 (EVENT), when a certain amount of data becomes available (DATA), 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.
>
>
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.
 

Line: 31 to 31
  Table 2: specifying time of action execution
Changed:
<
<
The third column (function) can contain one or more functions that will be executed after the specified marker and at the specified time. In table 1, fnc1 and fnc2 will be executed (in that order) as soon as marker mrk1 arrives. Two seconds after the onset of marker mrk2, fnc3 is 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 below.
>
>
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.

Revision 221 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
 
META TOPICPARENT name="BrainStreamDocs"

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

\ No newline at end of file
Added:
>
>
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, client, and looptick 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 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 (EVENT), when a certain amount of data becomes available (DATA), 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.

EVENT
DATA
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 after the specified marker and at the specified time. In table 1, fnc1 and fnc2 will be executed (in that order) as soon as marker mrk1 arrives. Two seconds after the onset of marker mrk2, fnc3 is 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 below.

Revision 121 Sep 2011 - Main.MarjoleinVanDerWaal

Line: 1 to 1
Added:
>
>
META TOPICPARENT name="BrainStreamDocs"

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

 
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