Include test

2 Getting Started Guide

This Getting Started Guide explains the minimal steps required for the definition of an experiment managed by BrainStream. After BrainStream is installed, several files need to be composed before being able to run an experiment. The experiment definition table (section 2.2? ) is the core of your experiment. It specifies what actions need to be executed at a certain time point and which data need to be processed during the experiment. In addition, markers? are added to the data stream making it possible to know the exact timepoints during the experiment at which certain actions? occur. The actions can either be directly set in the table or you can add Matlab functions to your table which define the actions. There are some pre-defined plug-ins; for example, bad channel rejection, classification, etc. (see Plug-ins). If you need other functions than those, you have the possibility to write new functions yourself (section 2.3? ). After you defined your experiment, you need to compose a file(s) to initiate your experiment in BrainStream (section 2.4? ). Every block has a separate file, which contains or refers to all information needed to initiate the particular block. The Examples? section of this documentation gives examples of the full set of definition tables and initialization files for several experiments. After finishing all these files, you are now ready to do your experiment! Section 2.5? explains how you have to start running BrainStream.

NB. This text is still under revision. If parts are unclear or missing, you can edit the text yourself or notifty someone else?

2.1 Start-up checklist

  1. Make sure BrainStream is installed correctly (see InstallationGuide? )
  2. Compose a definition file for your experiment (section 2.2? )
  3. Compose your own functions (section 2.3? )
  4. Define file(s) to initialize your experiment (= block files? ) (section 2.4? )
  5. Start BrainStream to run your experiment (section 2.5? )

2.2 Compose an experiment definition file

The experiment definition file? is the core of your BCI experiment? . Here you can specify what actions need to be executed at what time. For this markers? are used to ‘mark’ the timing of for example stimulus information or button responses of your participant.
The experiment definition file? consists of several tables, which will be discussed below. 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. Below, BrainStreams? internal editor will be used for explanation.

2.2.1 Tables

Actions table

BrainStream? tables contain one or more sheets, just like excel tables. A basic sheet consists of a marker, time, function and client column and can additionally contain an arbitrary number of variable columns. The first row of the table is the header and contains in the first four cells the words ‘marker’, ‘time’, ‘function’ and 'client' and in the remaining cells the variable names for the corresponding variable columns. The marker column tells Brainstream at what marker it has to execute an action? . In the time column, the exact timing of the execution of the action can be specified in several ways. You can let an action be executed directly at marker onset, some time after the marker, when the data comes available or when another marker arrives. See table 1 for more information. The next column is the function column. Here you can specify a Matlab? function that will be executed at the earlier specified time. See section 2.3? for more information on these user defined functions. The fourth 'client' column is optional, for more information see: Running BrainStream in parallel mode?

Table 1.

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

The subsequent columns can be used for user defined variables? , i.e., variables that you need in user defined functions. If a function needs such a variable, you first need to get it from the global variables? (with a ‘get’ statement in the corresponding cell). Then the function has access to it, and can for example change it. Saving the updated variable information to the global variables? will only be executed if a ‘put’ statement is included in the corresponding cell. These 'get'? and 'put'? statements specify when data exchange with the global variables is necessary, or in other words for communication between event? processing steps. To exchange information between the different sub-parts (blocks? ) of an experiment, user variables can be stored to disk using the 'save'? and retrieved from disk using the 'load'? statements. Click here? for more information.Furthermore, the value of the variable can be updated with Matlab style assignments, which can even use it’s own value by using the '$self' statement or other user defined variables. (see Architecture? ; Modifying variables for more information)

An example of a user variable? that will be used very often is a variable that contains the header information from the acquisition data file. It informs the user about the number of measured channels, their labels, and acquisition related information like the sample rate. The exact information delivered to the user can be found here? .

The order of actions per incoming marker is fixed. First content of user defined variables is modified, then content of user defined variables is retrieved (for use in functions) after which the functions are executed, and finally the new variable content is stored. Below a simple example of an actions table is given. The first row (the header) defines two user variables; var1 and var2. When Brainstream receives the BS_INIT marker (time = EVENT; moment of incoming marker), first these variables are set to empty with the [] statement. Then the content of these variables becomes available via the get statement. Subsequently the init_all function is executed, which can for example change var1 and var2. This changed content is then saved via the put statement. When the marker stimulus arrives, Brainstream will execute actions at two different timepoints. First when the marker arrives (time = EVENT) it adds ‘1’ to the current value (specified with $self) of var1 and gets it. Then, when the data that is associated with the marker stimulus becomes available (see dataselection sheet below), also the content of var2 is retrieved (var1 was already made available at the EVENT processing step) and the functions preproc, and classify are executed in this order. Then the updated content of only var2 is saved wtih the put statement. You can see in the example that it is not necessary to copy the name of the marker (stimulus in this case) if more than one processing steps (time column) are necessary for the actions associated with that marker. Note also that the BrainStream is case-sensitive. Upper-case variables are reserved markers (see section 2.2.1? ).

Table 2.

marker time function var1 var2
BS_INIT EVENT init_all [],get,put [],get,put
stimulus EVENT   $self+1, get  
  DATA preproc,classify   get,put

It is recommended to only 'get' and 'put' variables when content is indeed required for that event. This assures fast and efficient processing of your experiment.


In the Actions table you can also refer to a different table by putting the name of the sheet or complete path to a different table (.edt) in the marker column preceded by a @. Brainstream will expand your first action sheet with all referred tables into one big table. If you just put a reference in the marker column without any further actions defined, all processing steps of the referenced table will be added tot the current table. Actions defined for a references table will be treated as default actions to all markers mentioned in the referenced table. This can be useful if you want to execute the same actions for a lot of different markers. Here you can find examples of referencing. Another reason to make such a reference is the possibility to use a plug-in? that is used by many experiments, for example a bad channel detection Plug-in. This referred plug-in itself can also refer to other tables and in the end all corresponding definitions could have been spread out over many different tables. See the Plug-in section for more information about the available plug-ins and examples how to use them.

Table 2.3


The next important part of the experiment definition file is the dictionary? . Since markers can potentially arrive from different sources in different formats (eg. numbers), they will first be converted into names. For this purpose a dictionary or lookup-table maps incoming marker information to the proper marker name. The first row of the dictionary table is the header and defines the marker, type, value and optional substitute and datasource column. In the marker column the marker name is specified. The type column specifies the marker type. The marker can be for example a stimulus or response marker. In the value column, the value of the marker is specified. The substitute column can be used to make a substitute for corresponding marker. Its purpose is to merge actions of other markers before or after corresponding marker, see Plug-in. Below a short example of such a dictionary table is given. If definitions involve usage of multiple data sources, the datasource column specifies for which data source the dictionary information is meant.If only one datasource is involved, it can be left out and BrainStream? will assume definitions are meant for the single data source used.

Table 4.

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

The type and value information is delivered by the interface (between acquisition hardware, or a stimulus presentation module and Brainstream), and will translate into the marker names specified in the first marker column. Any table that is encountered - during expansion of the experiment definition table - that contains a sheet named 'Dictionary' will be added to the dictionary information that Brainstream uses to translate incoming markers into marker names (see Architecture? for more information. In case only .txt files are used the same is true for any folder containing the file 'Dictionary.txt'. Off course information inside these tables should not conflict (for example, double definitions of marker names or numbers).


Each marker can specify a segment of data? that should come along with the event. This can be specified in a separate table called 'DataSelection'. This table consists of a marker column, a begindata column, and an enddata column. Data selection may start before or after onset of the marker, inicated 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). By specifying multiple endtimes (seperated by a comma) the one that happens first will end the dataselection. As is the case for the dictionary, all tables named 'DataSelection' encountered during the expansion, will define data for the markers specified. Also here, information inside the different tables should not conflict. As is the case for Dictionary tables, a datasource column serves to specify for which datasource data selection is meant. In case only one data source is involved, it can be left out and BrainStream? will assume definitions are meant for this single data source.

Table 5.

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

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

More information about the tables can be found here: Architecture? .
Examples of a plug-in is given here: Plug-ins.

More information about editing tables in the BrainStream Editor can be found here: BrainStream Editor? .

2.2.2 Reserved markers

BrainStream defines a couple of reserved marker names that have special meaning and will be inserted by BrainStream in certain situations. Users can define their own actions for these markers:
BS_INIT : at startup, this marker is inserted by BrainStream and will always be the first processed marker. Use this marker to initialize your experiment (variables or acquisition related matter).
BS_EXIT : at shutdown, this marker is inserted by BrainStream and will always be the last processed marker. Use this marker to finalize your experiment.
BS_QUIT : marker triggers alternative shutdown, for example useful to discard certain actions defined for BS_EXIT, but still guarantee a normal closing of acquisition related items. For example, you would like to skip saving output to file and disk after quitting, but all acquisition related items should be normally closed.
BS_ABORT : marker triggers immediate shutdown. Do not define user actions for this marker.
BS_ACQFAILURE : marker triggers restart of acquisition (after possible failure) (WARNING: under construction)

2.2.3 Reserved variables

Users can define their own variables, as many as they like. The names must obey the Matlab variable naming convention rules (the first character isn't a number and symbols like !@#$%^&*(){}[]:;|\/?><~` are forbidden) and must not be equal to one of the reserved names in use by BrainStream. These reserved variables are listed below:

Table 6.

markermight get confused with marker column in exp.def.table
might get confused with marker column in exp.def.table
might get confused with marker column in exp.def.table
might get confused with marker column in exp.def.table
might get confused with marker column in exp.def.table
name of marker (and assoicated event)
time of execution referred to number of acquired samples
hdracquisition/file header info
trialinformation about selected data
datarequested raw data, trial information, samplerate
BRAINSTREAMused by BrainStream? internally
Acqinformation required for acquiring data (read-only)
trace_varsKeeps a list of traced variables (output in logfile)
brainstreamversionthe version of BrainStream? that you used to run your experiment

testlink naar getting started

Topic revision: r2 - 09 Nov 2009 - 16:50:33 - MarianneSeverens
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