Difference: DocsSectionsTroubleshooting (1 vs. 19)

Revision 1914 Nov 2011 - Main.MarjoleinVanDerWaal

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

Troubleshooting and FAQ

Changed:
<
<
Generate current PDF
>
>
Generate current PDF
 

6.1. Options for debugging

Revision 1814 Nov 2011 - Main.MarjoleinVanDerWaal

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

6 TROUBLESHOOTING AND FAQ

>
>

Troubleshooting and FAQ

  Generate current PDF
Line: 10 to 10
  There are different ways to debug your BCI application:

1) Use a recorded file
Changed:
<
<
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see BlockFile? ), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.
>
>
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see DocsSectionsBlockFile), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.
 
2) Use dummy data
The second possibility is to use the InsertMarker GUI to execute your experiment step by step by inserting markers manually. To use this functionality, RunMode.DataSource has to be set to empty.
Line: 108 to 108
  This happens if no data selection was specified for corresponding marker. Check if the 'DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
Changed:
<
<
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if RunMode.SampleRateAfterDecimation is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection begintimes can be set to t=0 s.
>
>
If you insert a marker? with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if RunMode.SampleRateAfterDecimation is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection begintimes can be set to t=0 s.
 
I defined actions for a marker, however nothing seems to execute?
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)
Line: 120 to 120
  The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.

I included a reference to another table, however, its content was not included during the table expansion.
Changed:
<
<
The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
>
>
The table can not be found in the Matlab path? or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
 
Instead of specifying data epochs in time units, I would like to use samples; is that possible?
Line: 161 to 161
 
  • Access control
    • Set DENYTOPICVIEW =
--> \ No newline at end of file
Added:
>
>
META TOPICMOVED by="MarjoleinVanDerWaal" date="1321266848" from="BrainStream.DocsSectionsTroubleshooting" to="BrainStreamDocs.DocsSectionsTroubleshooting"

Revision 1710 Oct 2011 - Main.MarjoleinVanDerWaal

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

6 TROUBLESHOOTING AND FAQ

Added:
>
>
Generate current PDF
 

6.1. Options for debugging

Revision 1619 Nov 2009 - Main.PhilipVanDenBroek

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

6 TROUBLESHOOTING AND FAQ

Line: 85 to 85
  One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.

How can I get access to constants defined in my block initialization file?
Changed:
<
<
Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue(RunMode','Subject','no_subject');.
>
>
Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue(event,'RunMode','Subject','no_subject');.
 
Does it make a difference which column I choose in the table for the markers, time or functions?
As long as they are in one of the first three columns, and before starting defining the columns with user variables, BrainStream will reorder the columns automatically.
Line: 100 to 100
  No, it is also possible to define your experiment in tab-delimited text files. Although the functionality is already integrated in BrainStream, it is not yet extensively tested. Also, the column-wise presentation of information in excel files really helps to get a good overview of the actions defined per marker. This is much more cumbersome in text files. Since excel files can hold more than one sheet per file, the same functionality for text files is implemented by putting the files in the same folder.

My function updates content for a variable, but it seems to get lost. What could go wrong?
Changed:
<
<
BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
>
>
BrainStream manages an internal user workspace (the global variables) which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
 
I defined actions at t=DATA, however nothing seems to execute?
Changed:
<
<
This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.
>
>
This happens if no data selection was specified for corresponding marker. Check if the 'DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.
 
I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if RunMode.SampleRateAfterDecimation is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection begintimes can be set to t=0 s.
Line: 121 to 121
  The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.

Instead of specifying data epochs in time units, I would like to use samples; is that possible?
Added:
>
>
  Yes, if a # symbol is placed right after the number, it will be treated as the number of samples instead of seconds. Thus 3 means three second, whereas 3# means 3 samples. The latter should be used with care since a changed sample rate will result in same length epochs (measured in samples), but different epoch lengths (measured in time). Note that for absolute time points (when actions should be executed) the same rules apply.
Added:
>
>
I inserted a marker with some time delay, however, the delay time doesn't seem to be recognized correctly.

Verify the delay time specified in the table. If this value is correct, be sure the inserted marker is not an action defined at a DATA timepoint. This will make execution time dependent of the amount of data specified if data end time exceeds the specified delay time.

 

6.3.4 Programming

Can I only use Matlab functions?
Line: 131 to 135
  Yes, this is supported. Before the actual modifier expressions are executed, a copy of current content of involved user variables is preserved. This content will be used for the user variables that might pop-up in the modifier expressions.

How does Brainstream deliver the data?
Changed:
<
<
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).
>
>
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).
 
Does BrainStream provide any standard data processing solutions?
The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).

Revision 1511 Nov 2009 - Main.MarianneSeverens

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

6 TROUBLESHOOTING AND FAQ

Line: 106 to 106
  This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
Changed:
<
<
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if RunMode.SampleRateAfterDecimation is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
>
>
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if RunMode.SampleRateAfterDecimation is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection begintimes can be set to t=0 s.
 
I defined actions for a marker, however nothing seems to execute?
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)

Revision 1410 Nov 2009 - Main.MarianneSeverens

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

6 TROUBLESHOOTING AND FAQ

Line: 106 to 106
  This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
Changed:
<
<
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
>
>
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if RunMode.SampleRateAfterDecimation is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
 
I defined actions for a marker, however nothing seems to execute?
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)

Revision 1310 Nov 2009 - Main.MarianneSeverens

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

6 TROUBLESHOOTING AND FAQ

6.1. Options for debugging

Changed:
<
<
There are different ways to debug your BCI application:
>
>
There are different ways to debug your BCI application:
 
1) Use a recorded file
Changed:
<
<
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see BlockFile? ), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.
>
>
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see BlockFile? ), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.
 
2) Use dummy data
Changed:
<
<
The second possibility is to use the InsertMarker GUI to execute your experiment step by step by inserting markers manually. To use this functionality, RunMode.DataSource has to be set to empty.
>
>
The second possibility is to use the InsertMarker GUI to execute your experiment step by step by inserting markers manually. To use this functionality, RunMode.DataSource has to be set to empty.
 
3) Read the log-file
Check if the log-file displays an error message or informs about something unusual.

4) Print information in the log-file
Changed:
<
<
If you want to print specific information in the log-file, use the functions bs_warn or bs_msg. See the Function Index for more information about these functions.
>
>
If you want to print specific information in the log-file, use the functions bs_warn or bs_msg. See the Function Index for more information about these functions.
 
5) Trace variables
Changed:
<
<
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. You can add or remove variables to a list of traced variables using function bs_trace. This list is stored in the variable trace_vars, which is reserved by BrainStream. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Every time content of the traced variable is requested or updated (via a modifying action, a get/load or a put/save), its content will be printed in the log-file. Note that for large-sized variables only the size will be outputted in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.
>
>
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. You can add or remove variables to a list of traced variables using function bs_trace. This list is stored in the variable trace_vars, which is reserved by BrainStream. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Every time content of the traced variable is requested or updated (via a modifying action, a get/load or a put/save), its content will be printed in the log-file. Note that for large-sized variables only the size will be outputted in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.
 
6) Screen level output
Changed:
<
<
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the experiment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile at key RunMode.screenoutputlevel.
>
>
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the experiment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile at key RunMode.screenoutputlevel.
  Options are:
  • 'ERROR': Only displays error messages. Warning messages and info messages are suppressed.
Line: 36 to 36
 All error messages BrainStream can generate are explained below:

'Missing get for ....' and BrainStream issues an error
Changed:
<
<
BrainStream warns for missing 'get' statements in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment 'get' keywords are often missing. For example, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable involved in this modification. At the moment BrainStream needs to execute actions for corresponding marker, it fails due to a missing field in the event structure (i.e. the missing user state variable) that is required in one (or more) of the user functions.
>
>
BrainStream warns for missing 'get' statements in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment 'get' keywords are often missing. For example, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable involved in this modification. At the moment BrainStream needs to execute actions for corresponding marker, it fails due to a missing field in the event structure (i.e. the missing user state variable) that is required in one (or more) of the user functions.
 
'Missing get for ....', though the experiment runs without any errors
Changed:
<
<
A missing 'get' statement will not necessarily issue an error. BrainStream verifies if all the detected event structure fields in a function have 'get' keyword specified. If not, BrainStream generates this error message. However, it only issues an error if a user-defined function uses a variable in the event structure for which the 'get' keyword is forgotten. For example, if a variable only needs to be initialized, no error will be issued.
>
>
A missing 'get' statement will not necessarily issue an error. BrainStream verifies if all the detected event structure fields in a function have 'get' keyword specified. If not, BrainStream generates this error message. However, it only issues an error if a user-defined function uses a variable in the event structure for which the 'get' keyword is forgotten. For example, if a variable only needs to be initialized, no error will be issued.
 
Blockfile defined in .exp file cannot be found

Time is specified but no actions are defined (file: filename and sheet Sheetname)
Changed:
<
<
Somewhere in the experiment definition file a time point is set, e.g. EVENT or DATA, but no actions have been given. This is not allowed, either add actions to the specific time point, or remove the time point from the experiment definition file. Note that this can also occur when one refers to a table with a list of markers, but no associated actions.
>
>
Somewhere in the experiment definition file a time point is set, e.g. EVENT or DATA, but no actions have been given. This is not allowed, either add actions to the specific time point, or remove the time point from the experiment definition file. Note that this can also occur when one refers to a table with a list of markers, but no associated actions.
 

6.3. Frequently Asked Questions

Line: 58 to 58
 

6.3.2 Installation

What do I need to use BrainStream?
Changed:
<
<
A Matlab license, BrainStream is tested with versions from 2007a and higher, possibly older versions would work too. At the moment, BrainStream assumes the availabilty of Matlabs' Signal Processing Toolbox.
>
>
A Matlab license, BrainStream is tested with versions from 2007a and higher, possibly older versions would work too. At the moment, BrainStream assumes the availabilty of Matlabs' Signal Processing Toolbox.
 

What is the minimal required technical setup?

Changed:
<
<
For BrainStream itself, there is no minimal technical requirement. This is almost fully determined by the type of the Brain-Computer Interface (BCI), (i.e., resources needed for the corresponding analyses) you are trying to execute. The acquisition source BrainStream is connecting to will have its effects on timing regarding incoming data and markers. This is mainly due to technical layers between the data source and BrainStream. The resources BrainStream requires for managing a correct execution of user defined actions are minimal.
>
>
For BrainStream itself, there is no minimal technical requirement. This is almost fully determined by the type of the Brain-Computer Interface (BCI), (i.e., resources needed for the corresponding analyses) you are trying to execute. The acquisition source BrainStream is connecting to will have its effects on timing regarding incoming data and markers. This is mainly due to technical layers between the data source and BrainStream. The resources BrainStream requires for managing a correct execution of user defined actions are minimal.
 
What kind of signals are supported?
In principal there are no limits to the type of signals BrainStream is connecting to. BrainStream itself is managing and executing the actions the user has defined in the experiment definition tables. In fact it is 'blind' for the content, although off course the hardware of the data source must be supported by BrainStream. Any solution can be made to work with BrainStream if it obeys to the API described here: xxxxx. Contact the BrainStream developers in order to get it standard integrated into BrainStream.

Which equipment is supported?
Changed:
<
<
Currently the following hardware devices are supported:
Biosemi, Active2, Actiview
!BrainProducts, BrainAmp, Brain Vision Recorder via Fieldtrip FileIO buffer (incoming markers under construction)
Any device supported by:
BCI2000, ......, via Fieldtrip FileIO buffer (filtered marker channel needs to be resolved)
>
>
Currently the following hardware devices are supported:
Biosemi, Active2, Actiview
!BrainProducts, BrainAmp, Brain Vision Recorder via Fieldtrip FileIO buffer (incoming markers under construction)
Any device supported by:
BCI2000, ......, via Fieldtrip FileIO buffer (filtered marker channel needs to be resolved)
  Supported data file formats for offline use:
Biosemi, biosemi data format (extended edf format)
All files supported by Fieldtrips FileIO module, see .......

Does BrainStream really need markers?
Changed:
<
<
BrainStreams' concept fully relies on incoming markers. Without them nothing will be executed.
>
>
BrainStreams' concept fully relies on incoming markers. Without them nothing will be executed.
 
How does BrainStream handle multiple marker sources?
Changed:
<
<
Currently marker information originating from one hardware data source is supported. Future developments will try to integrate a solution for multiple marker sources. Synchronization issues between the different sources then need to be resolved first.
>
>
Currently marker information originating from one hardware data source is supported. Future developments will try to integrate a solution for multiple marker sources. Synchronization issues between the different sources then need to be resolved first.
 
What is the timing based on?
The BrainStream API for connected data sources instructs to return information about the number of data samples gathered after each request for new events. It is crucial to BrainStream internal processing that proper timing information is available. Therefore, interfaces between hardware and BrainStream need to prevent large buffering of information in order to keep timing accurate.

6.3.3 Experiment definition

Why does BrainStream explicitly want users to define when they need access to their own variables?
Changed:
<
<
One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.
>
>
One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.
 
How can I get access to constants defined in my block initialization file?
Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue(RunMode','Subject','no_subject');.
Line: 100 to 100
  No, it is also possible to define your experiment in tab-delimited text files. Although the functionality is already integrated in BrainStream, it is not yet extensively tested. Also, the column-wise presentation of information in excel files really helps to get a good overview of the actions defined per marker. This is much more cumbersome in text files. Since excel files can hold more than one sheet per file, the same functionality for text files is implemented by putting the files in the same folder.

My function updates content for a variable, but it seems to get lost. What could go wrong?
Changed:
<
<
BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
>
>
BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
 
I defined actions at t=DATA, however nothing seems to execute?
Changed:
<
<
This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.
>
>
This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.
 
I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
Changed:
<
<
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
>
>
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
 
I defined actions for a marker, however nothing seems to execute?
Changed:
<
<
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)
>
>
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)
 
The order in which the actions are executed seems to be wrong?
Changed:
<
<
Check the expanded table that is outputted in the log file and command window. If the ordering here is also wrong, check the way the experiment definition table will be expanded. Such error typically is caused by a wrong ordering in action definitions. For example, the main table references another table that defines user functions fnc1, fnc2, and fnc3 for marker 'analyse'. The next row in this table defines user function fnc4 for marker analyse'. The execution order will then be: fnc1, fnc2, fnc3, fnc4. However, if the definition for fnc4 is put before the reference to the other table, the execution order will be: fnc4, fnc1, fnc2, fnc3.
>
>
Check the expanded table that is outputted in the log file and command window. If the ordering here is also wrong, check the way the experiment definition table will be expanded. Such error typically is caused by a wrong ordering in action definitions. For example, the main table references another table that defines user functions fnc1, fnc2, and fnc3 for marker 'analyse'. The next row in this table defines user function fnc4 for marker analyse'. The execution order will then be: fnc1, fnc2, fnc3, fnc4. However, if the definition for fnc4 is put before the reference to the other table, the execution order will be: fnc4, fnc1, fnc2, fnc3.
 
I use a variable to count the number of collected data epochs, however the numbers are not right, what could go wrong?
Changed:
<
<
The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.
>
>
The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.
 
I included a reference to another table, however, its content was not included during the table expansion.
Changed:
<
<
The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
>
>
The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
 
Instead of specifying data epochs in time units, I would like to use samples; is that possible?
Yes, if a # symbol is placed right after the number, it will be treated as the number of samples instead of seconds. Thus 3 means three second, whereas 3# means 3 samples. The latter should be used with care since a changed sample rate will result in same length epochs (measured in samples), but different epoch lengths (measured in time). Note that for absolute time points (when actions should be executed) the same rules apply.

6.3.4 Programming

Can I only use Matlab functions?
Changed:
<
<
No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.
>
>
No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.
 
Can I use other user variables in expressions modifying user variables?
Yes, this is supported. Before the actual modifier expressions are executed, a copy of current content of involved user variables is preserved. This content will be used for the user variables that might pop-up in the modifier expressions.

How does Brainstream deliver the data?
Changed:
<
<
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).
>
>
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).
 
Does BrainStream provide any standard data processing solutions?
Changed:
<
<
The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).
>
>
The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).
 

6.3.5 Block files

Line: 150 to 150
 

6.3.9 Slicing

<---End1--->
Added:
>
>
<-- 
  • Access control
    • Set DENYTOPICVIEW =
-->
 \ No newline at end of file

Revision 1202 Nov 2009 - Main.JoernHorschig

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

6 TROUBLESHOOTING AND FAQ

Line: 8 to 8
  There are different ways to debug your BCI application:

1) Use a recorded file
Changed:
<
<
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see BlockFile? ), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.
>
>
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see BlockFile? ), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.
 
2) Use dummy data
Changed:
<
<
The second possibility is to use the InsertMarker GUI to execute your experiment step by step by inserting markers manually. To use this functionality, RunMode.DataSource has to be set to empty.
>
>
The second possibility is to use the InsertMarker GUI to execute your experiment step by step by inserting markers manually. To use this functionality, RunMode.DataSource has to be set to empty.
 
3) Read the log-file
Check if the log-file displays an error message or informs about something unusual.
Line: 20 to 20
  If you want to print specific information in the log-file, use the functions bs_warn or bs_msg. See the Function Index for more information about these functions.

5) Trace variables
Changed:
<
<
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. You can add or remove variables to a list of traced variables using function bs_trace. This list is stored in the variable trace_vars, which is reserved by BrainStream. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Every time content of the traced variable is requested or updated (via a modifying action, a get/load or a put/save), its content will be printed in the log-file. Note that for large-sized variables only the size will be outputted in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.
>
>
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. You can add or remove variables to a list of traced variables using function bs_trace. This list is stored in the variable trace_vars, which is reserved by BrainStream. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Every time content of the traced variable is requested or updated (via a modifying action, a get/load or a put/save), its content will be printed in the log-file. Note that for large-sized variables only the size will be outputted in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.
 
6) Screen level output
Changed:
<
<
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the experiment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile at key RunMode.screenoutputlevel.
>
>
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the experiment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile at key RunMode.screenoutputlevel.
  Options are:
  • 'ERROR': Only displays error messages. Warning messages and info messages are suppressed.
Line: 36 to 36
 All error messages BrainStream can generate are explained below:

'Missing get for ....' and BrainStream issues an error
Changed:
<
<
BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment 'get' keywords are often missing. For example, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable involved in this modification. At the moment BrainStream needs to execute actions for corresponding marker, it fails due to a missing field in the event structure (i.e. the missing user state variable) that is required in one (or more) of the user functions.
>
>
BrainStream warns for missing 'get' statements in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment 'get' keywords are often missing. For example, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable involved in this modification. At the moment BrainStream needs to execute actions for corresponding marker, it fails due to a missing field in the event structure (i.e. the missing user state variable) that is required in one (or more) of the user functions.
 
'Missing get for ....', though the experiment runs without any errors
Changed:
<
<
A missing 'get' keyword will not necessarily issue an error. BrainStream verifies if all the detected event structure fields in a function have 'get' keyword specified. If not, BrainStream generates this error message. However, it only issues an error if a user-defined function uses a variable in the event structure for which the 'get' keyword is forgotten. For example, if a variable only needs to be initialized, no error will be issued.
>
>
A missing 'get' statement will not necessarily issue an error. BrainStream verifies if all the detected event structure fields in a function have 'get' keyword specified. If not, BrainStream generates this error message. However, it only issues an error if a user-defined function uses a variable in the event structure for which the 'get' keyword is forgotten. For example, if a variable only needs to be initialized, no error will be issued.
 
Blockfile defined in .exp file cannot be found

Time is specified but no actions are defined (file: filename and sheet Sheetname)
Changed:
<
<
Somewhere in the experiment definition file a time point is set, e.g. EVENT or DATA, but no actions have been given. This is not allowed, either add actions to the specific time point, or remove the time point from the experiment definition file. Note that this can also occur when one refers to a table with a list of markers, but no associated actions.
>
>
Somewhere in the experiment definition file a time point is set, e.g. EVENT or DATA, but no actions have been given. This is not allowed, either add actions to the specific time point, or remove the time point from the experiment definition file. Note that this can also occur when one refers to a table with a list of markers, but no associated actions.
 

6.3. Frequently Asked Questions

Line: 58 to 58
 

6.3.2 Installation

What do I need to use BrainStream?
Changed:
<
<
A Matlab license, BrainStream is tested with versions from 2007a and higher, possibly older versions would work too. At the moment, BrainStream assumes the availabilty of Matlabs' Signal Processing Toolbox.
>
>
A Matlab license, BrainStream is tested with versions from 2007a and higher, possibly older versions would work too. At the moment, BrainStream assumes the availabilty of Matlabs' Signal Processing Toolbox.
 

What is the minimal required technical setup?

Changed:
<
<
For BrainStream itself, there is no minimal technical requirement. This is almost fully determined by the type of BCI, (i.e., resources needed for the corresponding analyses) you are trying to execute. The acquisition source BrainStream is connecting to will have its effects on timing regarding incoming data and markers. This is mainly due to technical layers between the data source and BrainStream. The resources BrainStream requires for managing a correct execution of user defined actions are minimal.
>
>
For BrainStream itself, there is no minimal technical requirement. This is almost fully determined by the type of the Brain-Computer Interface (BCI), (i.e., resources needed for the corresponding analyses) you are trying to execute. The acquisition source BrainStream is connecting to will have its effects on timing regarding incoming data and markers. This is mainly due to technical layers between the data source and BrainStream. The resources BrainStream requires for managing a correct execution of user defined actions are minimal.
 
What kind of signals are supported?
In principal there are no limits to the type of signals BrainStream is connecting to. BrainStream itself is managing and executing the actions the user has defined in the experiment definition tables. In fact it is 'blind' for the content, although off course the hardware of the data source must be supported by BrainStream. Any solution can be made to work with BrainStream if it obeys to the API described here: xxxxx. Contact the BrainStream developers in order to get it standard integrated into BrainStream.

Which equipment is supported?
Changed:
<
<
Currently the following hardware devices are supported:
Biosemi, Active2, Actiview
!BrainProducts, BrainAmp, Brain Vision Recorder via Fieldtrip FileIO buffer (incoming markers under construction)
Any device supported by:
BCI2000, ......, via Fieldtrip FileIO buffer (filtered marker channel needs to be resolved)
>
>
Currently the following hardware devices are supported:
Biosemi, Active2, Actiview
!BrainProducts, BrainAmp, Brain Vision Recorder via Fieldtrip FileIO buffer (incoming markers under construction)
Any device supported by:
BCI2000, ......, via Fieldtrip FileIO buffer (filtered marker channel needs to be resolved)
  Supported data file formats for offline use:
Biosemi, biosemi data format (extended edf format)
All files supported by Fieldtrips FileIO module, see .......

Does BrainStream really need markers?
Changed:
<
<
BrainStreams' concept fully relies on incoming markers. Without them nothing will be executed.
>
>
BrainStreams' concept fully relies on incoming markers. Without them nothing will be executed.
 
How does BrainStream handle multiple marker sources?
Changed:
<
<
Currently marker information originating from one hardware data source is supported. Future developments will try to integrate a solution for multiple marker sources. Synchronization issues between the different sources then need to be resolved first.
>
>
Currently marker information originating from one hardware data source is supported. Future developments will try to integrate a solution for multiple marker sources. Synchronization issues between the different sources then need to be resolved first.
 
What is the timing based on?
The BrainStream API for connected data sources instructs to return information about the number of data samples gathered after each request for new events. It is crucial to BrainStream internal processing that proper timing information is available. Therefore, interfaces between hardware and BrainStream need to prevent large buffering of information in order to keep timing accurate.

6.3.3 Experiment definition

Why does BrainStream explicitly want users to define when they need access to their own variables?
Changed:
<
<
One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.
>
>
One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.
 
How can I get access to constants defined in my block initialization file?
Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue(RunMode','Subject','no_subject');.
Line: 100 to 100
  No, it is also possible to define your experiment in tab-delimited text files. Although the functionality is already integrated in BrainStream, it is not yet extensively tested. Also, the column-wise presentation of information in excel files really helps to get a good overview of the actions defined per marker. This is much more cumbersome in text files. Since excel files can hold more than one sheet per file, the same functionality for text files is implemented by putting the files in the same folder.

My function updates content for a variable, but it seems to get lost. What could go wrong?
Changed:
<
<
BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
>
>
BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
 
I defined actions at t=DATA, however nothing seems to execute?
Changed:
<
<
This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error)
>
>
This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error. For more information click here.
 
I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
Changed:
<
<
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
>
>
If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
 
I defined actions for a marker, however nothing seems to execute?
Changed:
<
<
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)
>
>
Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)
 
The order in which the actions are executed seems to be wrong?
Changed:
<
<
Check the expanded table that is outputted in the log file and command window. If the ordering here is also wrong, check the way the experiment definition table will be expanded. Such error typically is caused by a wrong ordering in action definitions. For example, the main table references another table that defines user functions fnc1, fnc2, and fnc3 for marker 'analyse'. The next row in this table defines user function fnc4 for marker analyse'. The execution order will then be: fnc1, fnc2, fnc3, fnc4. However, if the definition for fnc4 is put before the reference to the other table, the execution order will be: fnc4, fnc1, fnc2, fnc3.
>
>
Check the expanded table that is outputted in the log file and command window. If the ordering here is also wrong, check the way the experiment definition table will be expanded. Such error typically is caused by a wrong ordering in action definitions. For example, the main table references another table that defines user functions fnc1, fnc2, and fnc3 for marker 'analyse'. The next row in this table defines user function fnc4 for marker analyse'. The execution order will then be: fnc1, fnc2, fnc3, fnc4. However, if the definition for fnc4 is put before the reference to the other table, the execution order will be: fnc4, fnc1, fnc2, fnc3.
 
I use a variable to count the number of collected data epochs, however the numbers are not right, what could go wrong?
Changed:
<
<
The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.
>
>
The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.
 
I included a reference to another table, however, its content was not included during the table expansion.
Changed:
<
<
The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
>
>
The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
 
Instead of specifying data epochs in time units, I would like to use samples; is that possible?
Yes, if a # symbol is placed right after the number, it will be treated as the number of samples instead of seconds. Thus 3 means three second, whereas 3# means 3 samples. The latter should be used with care since a changed sample rate will result in same length epochs (measured in samples), but different epoch lengths (measured in time). Note that for absolute time points (when actions should be executed) the same rules apply.

6.3.4 Programming

Can I only use Matlab functions?
Changed:
<
<
No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.
>
>
No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.
 
Can I use other user variables in expressions modifying user variables?
Yes, this is supported. Before the actual modifier expressions are executed, a copy of current content of involved user variables is preserved. This content will be used for the user variables that might pop-up in the modifier expressions.

How does Brainstream deliver the data?
Changed:
<
<
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).
>
>
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).
 
Does BrainStream provide any standard data processing solutions?
Changed:
<
<
The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).
>
>
The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).
 

6.3.5 Block files

Revision 1129 Oct 2009 - Main.JeroenGeuze

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

6 TROUBLESHOOTING AND FAQ

Line: 43 to 43
 
Blockfile defined in .exp file cannot be found
Added:
>
>
Time is specified but no actions are defined (file: filename and sheet Sheetname)
Somewhere in the experiment definition file a time point is set, e.g. EVENT or DATA, but no actions have been given. This is not allowed, either add actions to the specific time point, or remove the time point from the experiment definition file. Note that this can also occur when one refers to a table with a list of markers, but no associated actions.
 

6.3. Frequently Asked Questions

Line: 141 to 144
 

6.3.8 Parallel Processing

Added:
>
>
Why is the connect_brainstream_client function not connecting?
A number of actions can be taken to solve this problem. First, check the addresses or ip-addresses used. If you are trying to connect a brainstream client, it must be identified in the blockfile under the [Clients] section. Make sure it is there, and if it is, make sure the dns-name or ip-address in the blockfile matches that of the computer you are running connect_brainstream_client on. Also make sure the dns-name or ip-address you are using in the connect_brainstream_client call matches that of the machine where brainstream is running on. Second, check if there is a firewall active on the machine that is running brainstream. If there is a firewall active, make sure that ports 5001 till 5020 are open, so the client can actually connect to brainstream. You could also try to only start connecting the brainstream client after Brainstream indicates that it is listening for incoming connections.
 

6.3.9 Slicing

<---End1--->

Revision 1029 Oct 2009 - Main.MoniekLijster

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

6 TROUBLESHOOTING AND FAQ

Line: 20 to 20
 If you want to print specific information in the log-file, use the functions bs_warn or bs_msg. See the Function Index for more information about these functions.

5) Trace variables
Changed:
<
<
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Futhermore, the Matlab function in which you want a variable to be traced should contain the function bs_trace_var. your experiment definition table should contain the variableUse the function bs_trace to use this functionality. In addition, in your experiment table Every time content of the traced variable is requested or updated, its content will be printed in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.
>
>
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. You can add or remove variables to a list of traced variables using function bs_trace. This list is stored in the variable trace_vars, which is reserved by BrainStream. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Every time content of the traced variable is requested or updated (via a modifying action, a get/load or a put/save), its content will be printed in the log-file. Note that for large-sized variables only the size will be outputted in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.
 
6) Screen level output
Changed:
<
<
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the epxeriment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile
  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)
>
>
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the experiment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile at key RunMode.screenoutputlevel.
 
Changed:
<
<
Options are:
’ERROR’, Only display error messages, output of warning and info messages are suppressed.
’WARNING’, Besides error messages, also dislay warning messages. Output of info messages is suppressed.
’INFO’, Display all outputted information in Matlab command window
’DEBUG’, Compared to ’INFO’, if running with the GUI, show information in its logwindow. Also, additional information is provided about which actions are being executed.
>
>
Options are:
  • 'ERROR': Only displays error messages. Warning messages and info messages are suppressed.
  • 'WARNING': Error messages and warning messages are displayed. Info messages are suppressed.
  • 'INFO': Displays all outputted information in the Matlab command window.
  • 'DEBUG': Displays all outputted information in the Matlab command window. Compared to INFO, however, all information is also shown in the log-window of the GUI. In addition, information is provided about which actions are being executed.
 
Changed:
<
<
  • Variables can be traced during runtime using the function bs trace var. The content will be outputted in the log-file (large sized items will only display its size) at every time corresponding variable will be requested via a modifying action, a get/load or put/save.
bs_trace_var
see: http://www.nici.ru.nl/brainstream/twiki/bin/view/BrainStream/DocsSectionsProgrmmersGuide#10_2_Functions_for_debugging
>
>

6.2. Error messages

 
Changed:
<
<
>
>
All error messages BrainStream can generate are explained below:
 
Changed:
<
<

Debugging

>
>
'Missing get for ....' and BrainStream issues an error
BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment 'get' keywords are often missing. For example, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable involved in this modification. At the moment BrainStream needs to execute actions for corresponding marker, it fails due to a missing field in the event structure (i.e. the missing user state variable) that is required in one (or more) of the user functions.
 
Changed:
<
<

What options do I have for debugging?

There are different ways to debug your BCI application.
>
>
'Missing get for ....', though the experiment runs without any errors
A missing 'get' keyword will not necessarily issue an error. BrainStream verifies if all the detected event structure fields in a function have 'get' keyword specified. If not, BrainStream generates this error message. However, it only issues an error if a user-defined function uses a variable in the event structure for which the 'get' keyword is forgotten. For example, if a variable only needs to be initialized, no error will be issued.
 
Changed:
<
<

6.2. Error messages.

'Missing get for ....', the experiment executes a while and then issues an error.

BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment often 'get' keywords are missing. For instance, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable utilized in this modification. Only at the moment BrainStream needs to execute actions for corresponding marker, it will fail because of a missing field, that is a missing user state variable, that is required in one (or more) of the user functions.

'Missing get for ....', though the experiment then executes entirely without any errors.

BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. However, a missing 'get' will not necessarily issue an error, for example if a variable only needs to be initialized. BrainStream has no means of understanding the specified user actions, it just verifies if for all the detected event structure fields in a function a 'get' keyword is specified.
>
>
Blockfile defined in .exp file cannot be found
 
Added:
>
>
 

6.3. Frequently Asked Questions

Changed:
<
<

General

What is BrainStream?

>
>

6.3.1 General

What is BrainStream?
  BrainStream is a Matlab-based toolbox that allows you to run and analyse EEG experiments in a modular way. For a more elaborate description see the introduction of the documentation.
Changed:
<
<

Who is BrainStream meant for?

>
>
Who is BrainStream meant for?
  BrainStream offers users without programming experience the opportunity to put together their experiment in easily editable tables, in MS Excel or in simple textfiles. Alternatively, people who do have programming experience can freely use any function they want within the BrainStream framework. BrainStream is entirely Matlab based and can therefore be used on different operating systems (it is tested on
Changed:
<
<

Hardware

What do I need to use BrainStream?

>
>

6.3.2 Installation

What do I need to use BrainStream?
  A Matlab license, BrainStream is tested with versions from 2007a and higher, possibly older versions would work too. At the moment, BrainStream assumes the availabilty of Matlabs' Signal Processing Toolbox.

What is the minimal required technical setup?

For BrainStream itself, there is no minimal technical requirement. This is almost fully determined by the type of BCI, (i.e., resources needed for the corresponding analyses) you are trying to execute. The acquisition source BrainStream is connecting to will have its effects on timing regarding incoming data and markers. This is mainly due to technical layers between the data source and BrainStream. The resources BrainStream requires for managing a correct execution of user defined actions are minimal.
Changed:
<
<

What kind of signals are supported?

>
>
What kind of signals are supported?
  In principal there are no limits to the type of signals BrainStream is connecting to. BrainStream itself is managing and executing the actions the user has defined in the experiment definition tables. In fact it is 'blind' for the content, although off course the hardware of the data source must be supported by BrainStream. Any solution can be made to work with BrainStream if it obeys to the API described here: xxxxx. Contact the BrainStream developers in order to get it standard integrated into BrainStream.
Changed:
<
<

Which equipment is supported?

>
>
Which equipment is supported?
  Currently the following hardware devices are supported:
Biosemi, Active2, Actiview
!BrainProducts, BrainAmp, Brain Vision Recorder via Fieldtrip FileIO buffer (incoming markers under construction)
Any device supported by:
BCI2000, ......, via Fieldtrip FileIO buffer (filtered marker channel needs to be resolved)

Supported data file formats for offline use:
Biosemi, biosemi data format (extended edf format)
All files supported by Fieldtrips FileIO module, see .......

Changed:
<
<

Does BrainStream really need markers?

>
>
Does BrainStream really need markers?
  BrainStreams' concept fully relies on incoming markers. Without them nothing will be executed.
Changed:
<
<

How does BrainStream handle multiple marker sources?

>
>
How does BrainStream handle multiple marker sources?
  Currently marker information originating from one hardware data source is supported. Future developments will try to integrate a solution for multiple marker sources. Synchronization issues between the different sources then need to be resolved first.
Changed:
<
<

What is the timing based on?

>
>
What is the timing based on?
  The BrainStream API for connected data sources instructs to return information about the number of data samples gathered after each request for new events. It is crucial to BrainStream internal processing that proper timing information is available. Therefore, interfaces between hardware and BrainStream need to prevent large buffering of information in order to keep timing accurate.
Changed:
<
<

Programming

Can I only use Matlab functions?

No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.

Can I use other user variables in expressions modifying user variables?

Yes, this is supported. Before the actual modifier expressions are executed, a copy of current content of involved user variables is preserved. This content will be used for the user variables that might pop-up in the modifier expressions.

How does Brainstream deliver the data?

Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).

Does BrainStream provide any standard data processing solutions?

The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).

Experiment definition

Why does BrainStream explicitly want users to define when they need access to their own variables?

>
>

6.3.3 Experiment definition

Why does BrainStream explicitly want users to define when they need access to their own variables?
  One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.
Changed:
<
<

How can I get access to constants defined in my block initialization file?

Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue('!RunMode','Subject','no_subject');.
>
>
How can I get access to constants defined in my block initialization file?
Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue(RunMode','Subject','no_subject');.
 
Changed:
<
<

Does it make a difference which column I choose in the table for the markers, time or functions?

>
>
Does it make a difference which column I choose in the table for the markers, time or functions?
  As long as they are in one of the first three columns, and before starting defining the columns with user variables, BrainStream will reorder the columns automatically.
Changed:
<
<

Can I use functions to modify content of variables directly?

>
>
Can I use functions to modify content of variables directly?
  Yes, this is possible as long as it returns one output argument; this will then become the new content of the variable.
Changed:
<
<

What does $self mean?

>
>
What does $self mean?
  This is a placeholder for the actual variable it is modifying. If the name of the variable would change, you do not need to check the column for other copies of the name to be changed too.
Changed:
<
<

Must I use excel to define my experiment?

>
>
Must I use excel to define my experiment?
  No, it is also possible to define your experiment in tab-delimited text files. Although the functionality is already integrated in BrainStream, it is not yet extensively tested. Also, the column-wise presentation of information in excel files really helps to get a good overview of the actions defined per marker. This is much more cumbersome in text files. Since excel files can hold more than one sheet per file, the same functionality for text files is implemented by putting the files in the same folder.
Changed:
<
<

My function updates content for a variable, but it seems to get lost. What could go wrong?

>
>
My function updates content for a variable, but it seems to get lost. What could go wrong?
  BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.
Changed:
<
<

I defined actions at t=DATA, however nothing seems to execute?

>
>
I defined actions at t=DATA, however nothing seems to execute?
 This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error)
Deleted:
<
<

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.

 
Added:
>
>
I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.
 If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
Changed:
<
<

I defined actions for a marker, however nothing seems to execute?

>
>
I defined actions for a marker, however nothing seems to execute?
  Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)
Changed:
<
<

The order in which the actions are executed seems to be wrong?

>
>
The order in which the actions are executed seems to be wrong?
  Check the expanded table that is outputted in the log file and command window. If the ordering here is also wrong, check the way the experiment definition table will be expanded. Such error typically is caused by a wrong ordering in action definitions. For example, the main table references another table that defines user functions fnc1, fnc2, and fnc3 for marker 'analyse'. The next row in this table defines user function fnc4 for marker analyse'. The execution order will then be: fnc1, fnc2, fnc3, fnc4. However, if the definition for fnc4 is put before the reference to the other table, the execution order will be: fnc4, fnc1, fnc2, fnc3.
Changed:
<
<

I use a variable to count the number of collected data epochs, however the numbers are not right, what could go wrong?

>
>
I use a variable to count the number of collected data epochs, however the numbers are not right, what could go wrong?
 The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.
Deleted:
<
<

I included a reference to another table, however, its content was not included during the table expansion.

 
Added:
>
>
I included a reference to another table, however, its content was not included during the table expansion.
 The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.
Deleted:
<
<

Instead of specifying data epochs in time units, I would like to use samples; is that possible?

 
Added:
>
>
Instead of specifying data epochs in time units, I would like to use samples; is that possible?
 Yes, if a # symbol is placed right after the number, it will be treated as the number of samples instead of seconds. Thus 3 means three second, whereas 3# means 3 samples. The latter should be used with care since a changed sample rate will result in same length epochs (measured in samples), but different epoch lengths (measured in time). Note that for absolute time points (when actions should be executed) the same rules apply.
Added:
>
>

6.3.4 Programming

Can I only use Matlab functions?
No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.

Can I use other user variables in expressions modifying user variables?
Yes, this is supported. Before the actual modifier expressions are executed, a copy of current content of involved user variables is preserved. This content will be used for the user variables that might pop-up in the modifier expressions.

How does Brainstream deliver the data?
Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).

Does BrainStream provide any standard data processing solutions?
The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).

6.3.5 Block files

6.3.6 BrainStream startup

6.3.7 Plug-ins

6.3.8 Parallel Processing

6.3.9 Slicing

 
<---End1--->

Revision 928 Oct 2009 - Main.MoniekLijster

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

6 TROUBLESHOOTING AND FAQ

Changed:
<
<

6.1. Options for debugging.

>
>

6.1. Options for debugging

There are different ways to debug your BCI application:

1) Use a recorded file
The experiment is 're-played' using data and markers present in a previously recorded data file. The recorded data file has to be structured equal to the data you will acquire during a real BCI experiment. If you enter this file in your blockfile at key RunMode.DataSource (see BlockFile? ), you can execute BrainStream using this file as data source. Running through your experiment in this way enables to debug your experiment by using Matlab debugging (i.e. placing break point in the code). For example, when Matlab encounters a break point, the experiment will stop running waiting for you to check the code. Time is now in your hand and you can easily debug your experiment.

2) Use dummy data
The second possibility is to use the InsertMarker GUI to execute your experiment step by step by inserting markers manually. To use this functionality, RunMode.DataSource has to be set to empty.

3) Read the log-file
Check if the log-file displays an error message or informs about something unusual.

4) Print information in the log-file
If you want to print specific information in the log-file, use the functions bs_warn or bs_msg. See the Function Index for more information about these functions.

5) Trace variables
Another functionality is tracing the content of the user-specific variables you use in your experiment definition file and/or user-defined functions. To be able to use this functionality, you have to enter the variable trace_vars in your experiment definition table. Futhermore, the Matlab function in which you want a variable to be traced should contain the function bs_trace_var. your experiment definition table should contain the variableUse the function bs_trace to use this functionality. In addition, in your experiment table Every time content of the traced variable is requested or updated, its content will be printed in the log-file. For more information this functionality of tracing the content of variables, see the Function Index.

6) Screen level output
You can choose how many information is shown to you on the screen during the experiment or during the 're-play' of the epxeriment. The level of screen output can be set in two different ways: 1) In the field 'Screen output level' of the GUI or 2) In your blockfile
 
  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)
Line: 15 to 35
 
Added:
>
>

Debugging

What options do I have for debugging?

There are different ways to debug your BCI application.
 

6.2. Error messages.

'Missing get for ....', the experiment executes a while and then issues an error.

Line: 97 to 122
 

I defined actions at t=DATA, however nothing seems to execute?

This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error)

Changed:
<
<

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.

>
>

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.

  If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.
Line: 117 to 142
  Yes, if a # symbol is placed right after the number, it will be treated as the number of samples instead of seconds. Thus 3 means three second, whereas 3# means 3 samples. The latter should be used with care since a changed sample rate will result in same length epochs (measured in samples), but different epoch lengths (measured in time). Note that for absolute time points (when actions should be executed) the same rules apply.
Deleted:
<
<

Debugging

What options do I have for debugging?

There are different ways to debug your BCI application.
1) use a recorded file
Acquire data with a structure that is equal to that acquired during a real BCI experiment and save it to file. Use this file as data source and execute BrainStream. This enables you to place Matlab break points in the code wherever you want it. Time is now in your hand and you can easily debug your experiment.
2) use dummy data
Set data source to empty and use the InsertMarker GUI to execute your experiment step by step by inserting markers manually.
3) trace vars
Use trace_vars functionality to trace content of variables. Every time content of the traced variable is requested or updated, its content will be printed in the log-file.
4) print
Print user specific information into the log-file by using the function bs_warn or bs_msg.
5) logfile
Check if the logfile informs about something unusual or displays an error message.
 
<---End1--->

Revision 828 Oct 2009 - Main.JeroenGeuze

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

6 TROUBLESHOOTING AND FAQ

Changed:
<
<
>
>
 

6.1. Options for debugging.

  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)

Revision 723 Oct 2009 - Main.MarianneSeverens

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

6 TROUBLESHOOTING AND FAQ

6.1. Options for debugging.

Line: 130 to 131
  Print user specific information into the log-file by using the function bs_warn or bs_msg.
5) logfile
Check if the logfile informs about something unusual or displays an error message. \ No newline at end of file
Added:
>
>
<---End1--->
 \ No newline at end of file

Revision 621 Oct 2009 - Main.PhilipVanDenBroek

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

6 TROUBLESHOOTING AND FAQ

Line: 29 to 29
  BrainStream is a Matlab-based toolbox that allows you to run and analyse EEG experiments in a modular way. For a more elaborate description see the introduction of the documentation.

Who is BrainStream meant for?

Changed:
<
<
BrainStream offers users without programming experience the opportunity to put together their experiment in easily editable tables, in MS Excel or in simple textfiles. Alternatively, people who do have programming experience can freely use any function they want within the BrainStream framework.
>
>
BrainStream offers users without programming experience the opportunity to put together their experiment in easily editable tables, in MS Excel or in simple textfiles. Alternatively, people who do have programming experience can freely use any function they want within the BrainStream framework. BrainStream is entirely Matlab based and can therefore be used on different operating systems (it is tested on
 

Hardware

What do I need to use BrainStream?

Line: 94 to 94
  BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.

I defined actions at t=DATA, however nothing seems to execute?

Added:
>
>
  This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error)
Added:
>
>

I get an error 'can not read data before t=0', however dataselections begintime was set to t=0 s.

If you insert a marker with zero time-delay at the BS_INIT marker, this inserted markers timestamp will also be set to t=0. Data selection definition is interpreted relative to this timestamp. Although DataSelection? begintime t=0 was specified, the extra samples required for the decimation filtering moves the start position towards values < 0. This risc exists for every marker which absolute DataSelection? begintime effectual becomes a value smaller than 0.1s. Thus, inserted markers timestamp plus begintime should be larger than 0.1s, but only if data is being decimated. Data will be decimated if SampleRateAfterDecimation? is not equal to the original sample rate (either from data source or file). In case no decimation is applied, effectual DataSelection? begintimes can be set to t=0 s.

 

I defined actions for a marker, however nothing seems to execute?

Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)

Revision 514 Oct 2009 - Main.MarianneSeverens

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

6 TROUBLESHOOTING AND FAQ

Line: 16 to 16
 

6.2. Error messages.

Changed:
<
<

I get a message: 'Missing get for ....', the experiment executes a while and then issues an error. Why?

>
>

'Missing get for ....', the experiment executes a while and then issues an error.

  BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment often 'get' keywords are missing. For instance, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable utilized in this modification. Only at the moment BrainStream needs to execute actions for corresponding marker, it will fail because of a missing field, that is a missing user state variable, that is required in one (or more) of the user functions.
Changed:
<
<

I get a message: 'Missing get for ....', though the experiment then executes entirely without any errors. Why does BrainStream give this message?

>
>

'Missing get for ....', though the experiment then executes entirely without any errors.

  BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. However, a missing 'get' will not necessarily issue an error, for example if a variable only needs to be initialized. BrainStream has no means of understanding the specified user actions, it just verifies if for all the detected event structure fields in a function a 'get' keyword is specified.

6.3. Frequently Asked Questions

Revision 412 Oct 2009 - Main.MarianneSeverens

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

6 TROUBLESHOOTING

>
>

6 TROUBLESHOOTING AND FAQ

 

6.1. Options for debugging.

  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)
Line: 15 to 15
 

6.2. Error messages.

Added:
>
>

I get a message: 'Missing get for ....', the experiment executes a while and then issues an error. Why?

BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. Especially during the initial setup of an experiment often 'get' keywords are missing. For instance, a user function was modified and it was forgotten to update the experiment definition table with a 'get' keyword for the user state variable utilized in this modification. Only at the moment BrainStream needs to execute actions for corresponding marker, it will fail because of a missing field, that is a missing user state variable, that is required in one (or more) of the user functions.

I get a message: 'Missing get for ....', though the experiment then executes entirely without any errors. Why does BrainStream give this message?

BrainStream warns for missing 'get' keywords in the experiment definition table in order to help you debugging your experiment. However, a missing 'get' will not necessarily issue an error, for example if a variable only needs to be initialized. BrainStream has no means of understanding the specified user actions, it just verifies if for all the detected event structure fields in a function a 'get' keyword is specified.

6.3. Frequently Asked Questions

General

What is BrainStream?

BrainStream is a Matlab-based toolbox that allows you to run and analyse EEG experiments in a modular way. For a more elaborate description see the introduction of the documentation.

Who is BrainStream meant for?

BrainStream offers users without programming experience the opportunity to put together their experiment in easily editable tables, in MS Excel or in simple textfiles. Alternatively, people who do have programming experience can freely use any function they want within the BrainStream framework.

Hardware

What do I need to use BrainStream?

A Matlab license, BrainStream is tested with versions from 2007a and higher, possibly older versions would work too. At the moment, BrainStream assumes the availabilty of Matlabs' Signal Processing Toolbox.

What is the minimal required technical setup?

For BrainStream itself, there is no minimal technical requirement. This is almost fully determined by the type of BCI, (i.e., resources needed for the corresponding analyses) you are trying to execute. The acquisition source BrainStream is connecting to will have its effects on timing regarding incoming data and markers. This is mainly due to technical layers between the data source and BrainStream. The resources BrainStream requires for managing a correct execution of user defined actions are minimal.

What kind of signals are supported?

In principal there are no limits to the type of signals BrainStream is connecting to. BrainStream itself is managing and executing the actions the user has defined in the experiment definition tables. In fact it is 'blind' for the content, although off course the hardware of the data source must be supported by BrainStream. Any solution can be made to work with BrainStream if it obeys to the API described here: xxxxx. Contact the BrainStream developers in order to get it standard integrated into BrainStream.

Which equipment is supported?

Currently the following hardware devices are supported:
Biosemi, Active2, Actiview
!BrainProducts, BrainAmp, Brain Vision Recorder via Fieldtrip FileIO buffer (incoming markers under construction)
Any device supported by:
BCI2000, ......, via Fieldtrip FileIO buffer (filtered marker channel needs to be resolved)

Supported data file formats for offline use:
Biosemi, biosemi data format (extended edf format)
All files supported by Fieldtrips FileIO module, see .......

Does BrainStream really need markers?

BrainStreams' concept fully relies on incoming markers. Without them nothing will be executed.

How does BrainStream handle multiple marker sources?

Currently marker information originating from one hardware data source is supported. Future developments will try to integrate a solution for multiple marker sources. Synchronization issues between the different sources then need to be resolved first.

What is the timing based on?

The BrainStream API for connected data sources instructs to return information about the number of data samples gathered after each request for new events. It is crucial to BrainStream internal processing that proper timing information is available. Therefore, interfaces between hardware and BrainStream need to prevent large buffering of information in order to keep timing accurate.

Programming

Can I only use Matlab functions?

No, the functions listed in the experiment definition tables should all be Matlab functions according to the BrainStream format. Starting from these functions, the user is free to call any other Matlab functions (not restricted to BrainStream format; event=function(event)), functions implemented via mex files, java functions or any other solution standard supported by Matlab.

Can I use other user variables in expressions modifying user variables?

Yes, this is supported. Before the actual modifier expressions are executed, a copy of current content of involved user variables is preserved. This content will be used for the user variables that might pop-up in the modifier expressions.

How does Brainstream deliver the data?

Only when a marker is associated with data (see xxx) and a timepoint t=DATA, it will get the data along with the event structure, that is: event.data.raw (channels x data).

Does BrainStream provide any standard data processing solutions?

The only supported data processing option available is decimation of the data. In the block file it can be specified which decimation factor should apply to the data (topic: RunMode, key: SampleRateAfterDecimation). In fact it is specified what the sample rate should be after decimation. BrainStream verifies if the data acquisitions' sample rate allows for decimation of the data (decimation factor should be a power of 2).

Experiment definition

Why does BrainStream explicitly want users to define when they need access to their own variables?

One reason is that BrainStreams internal processing variable space needs to be separated from the users variable space (user state). Users should not be able to 'see' BrainStreams internal code processing. Another reason is that by explicitly asking for such actions, BrainStream is able to decide on which parts of the processing can be executed parallel-wise (this is an option; standard turned off). if users would like to use this feature, they are relieved from this difficult task of writing debug-free-executing parallel code.

How can I get access to constants defined in my block initialization file?

Use the value = bs_get_blockvalue(,,) to retrieve defined constants. For example: subject = bs_get_blockvalue('!RunMode','Subject','no_subject');.

Does it make a difference which column I choose in the table for the markers, time or functions?

As long as they are in one of the first three columns, and before starting defining the columns with user variables, BrainStream will reorder the columns automatically.

Can I use functions to modify content of variables directly?

Yes, this is possible as long as it returns one output argument; this will then become the new content of the variable.

What does $self mean?

This is a placeholder for the actual variable it is modifying. If the name of the variable would change, you do not need to check the column for other copies of the name to be changed too.

Must I use excel to define my experiment?

No, it is also possible to define your experiment in tab-delimited text files. Although the functionality is already integrated in BrainStream, it is not yet extensively tested. Also, the column-wise presentation of information in excel files really helps to get a good overview of the actions defined per marker. This is much more cumbersome in text files. Since excel files can hold more than one sheet per file, the same functionality for text files is implemented by putting the files in the same folder.

My function updates content for a variable, but it seems to get lost. What could go wrong?

BrainStream manages an internal user workspace which stores all user variables content. If the user specifies a 'get' keyword in the experiment definition table, it will instruct BrainStream to add the content of the variable as a field to the event structure. This way, users get access to their own user variables. The other way around, if the user wants to update changed content to this user workspace, it needs to explicitly ask for this by issuing a 'put' keyword for this variable. A missing 'put' is most probably the reason why modifications are not preserved.

I defined actions at t=DATA, however nothing seems to execute?

This happens if no data selection was specified for corresponding marker. Check if the '!DataSelection' table defines data for this marker. (future versions will check the table for such failure and issue an error)

I defined actions for a marker, however nothing seems to execute?

Check if the marker did pop up in the data stream. If so, check if the time point for these actions was specified in the table. (BrainStream should warn for missing time point information)

The order in which the actions are executed seems to be wrong?

Check the expanded table that is outputted in the log file and command window. If the ordering here is also wrong, check the way the experiment definition table will be expanded. Such error typically is caused by a wrong ordering in action definitions. For example, the main table references another table that defines user functions fnc1, fnc2, and fnc3 for marker 'analyse'. The next row in this table defines user function fnc4 for marker analyse'. The execution order will then be: fnc1, fnc2, fnc3, fnc4. However, if the definition for fnc4 is put before the reference to the other table, the execution order will be: fnc4, fnc1, fnc2, fnc3.

I use a variable to count the number of collected data epochs, however the numbers are not right, what could go wrong?

The variable responsible for counting should be modified (i.e., by a $self+1 action) and retrieved (i.e., by a 'get' keyword) both at the same time point for corresponding marker that collects the data (best practice is to do this at time point t=EVENT). It will go wrong at the moment a second marker arrives in the data stream while the first one didn't yet obtain its data, i.e., with overlapping data epochs. If the counting is done at t=EVENT and the content of the counting variable is retrieved at t=DATA, the second marker would already have increased the counting variable before the first one retrieved its content.Instead of a value equal to one it will retrieve a value equal to two.

I included a reference to another table, however, its content was not included during the table expansion.

The table can not be found in the Matlab path or the file doesn't exist (perhaps a spelling error). References to external tables (i.e., not sheets included in the excel file) must include the extension of the file name. This tells BrainStream to search for another file instead of a local included sheet. Tables do not necessarily have to be found in the Matlab path. A full path can be included for the reference in order to directly point to its storage location; @mytable.xls (file can be found in Matlab path), or @/volumes/all_tables/mytable.xls.

Instead of specifying data epochs in time units, I would like to use samples; is that possible?

Yes, if a # symbol is placed right after the number, it will be treated as the number of samples instead of seconds. Thus 3 means three second, whereas 3# means 3 samples. The latter should be used with care since a changed sample rate will result in same length epochs (measured in samples), but different epoch lengths (measured in time). Note that for absolute time points (when actions should be executed) the same rules apply.

Debugging

What options do I have for debugging?

There are different ways to debug your BCI application.
1) use a recorded file
Acquire data with a structure that is equal to that acquired during a real BCI experiment and save it to file. Use this file as data source and execute BrainStream. This enables you to place Matlab break points in the code wherever you want it. Time is now in your hand and you can easily debug your experiment.
2) use dummy data
Set data source to empty and use the InsertMarker GUI to execute your experiment step by step by inserting markers manually.
3) trace vars
Use trace_vars functionality to trace content of variables. Every time content of the traced variable is requested or updated, its content will be printed in the log-file.
4) print
Print user specific information into the log-file by using the function bs_warn or bs_msg.
5) logfile
Check if the logfile informs about something unusual or displays an error message.

Revision 301 Sep 2009 - Main.PhilipVanDenBroek

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

6 TROUBLESHOOTING

6.1. Options for debugging.

Changed:
<
<
  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)
>
>
  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)
 
Changed:
<
<
Options are: ’ERROR’, Only display error messages, output of warning and info messages are suppressed. ’WARNING’, Besides error messages, also dislay warning messages. Output of info messages is suppressed. ’INFO’, Display all outputted information in Matlab command window ’DEBUG’, Compared to ’INFO’, if running with the GUI, show information in its logwindow. Also, additional information is provided about which actions are being executed.
>
>
Options are:
’ERROR’, Only display error messages, output of warning and info messages are suppressed.
’WARNING’, Besides error messages, also dislay warning messages. Output of info messages is suppressed.
’INFO’, Display all outputted information in Matlab command window
’DEBUG’, Compared to ’INFO’, if running with the GUI, show information in its logwindow. Also, additional information is provided about which actions are being executed.
 
Changed:
<
<
  • Variables can be traced during runtime using the function bs trace var. The content will be outputted in the log-file (large sized items will only display its size) at every time corresponding variable will be requested via a modifying action, a get/load or put/save.
>
>
  • Variables can be traced during runtime using the function bs trace var. The content will be outputted in the log-file (large sized items will only display its size) at every time corresponding variable will be requested via a modifying action, a get/load or put/save.
bs_trace_var
see: http://www.nici.ru.nl/brainstream/twiki/bin/view/BrainStream/DocsSectionsProgrmmersGuide#10_2_Functions_for_debugging

 
Deleted:
<
<
bs_trace_var(’myvar.field’,’add’) % add variable to the trace list bs_trace_var(’myvar ’,’add’) % add variables structure field to trace list bs_trace_var(’myvar.field’,’remove’) % remove form trace list bs_trace_var % get string cell-array of variables currently being traced bs_trace_var(’clear ’) % empty the trace list
 

6.2. Error messages.

\ No newline at end of file

Revision 218 Feb 2009 - Main.RebeccaSchaefer

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

6 TROUBLESHOOTING

>
>

6 TROUBLESHOOTING

 

6.1. Options for debugging.

  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)

Revision 116 Feb 2009 - Main.RebeccaSchaefer

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

6 TROUBLESHOOTING

6.1. Options for debugging.

  • screenoutputlevel ([RunMode], screenoutputlevel = ’ERROR’ // blocksettings.RunMode.screenoutputlevel=’ERROR’)

Options are: ’ERROR’, Only display error messages, output of warning and info messages are suppressed. ’WARNING’, Besides error messages, also dislay warning messages. Output of info messages is suppressed. ’INFO’, Display all outputted information in Matlab command window ’DEBUG’, Compared to ’INFO’, if running with the GUI, show information in its logwindow. Also, additional information is provided about which actions are being executed.

  • Variables can be traced during runtime using the function bs trace var. The content will be outputted in the log-file (large sized items will only display its size) at every time corresponding variable will be requested via a modifying action, a get/load or put/save.

bs_trace_var(’myvar.field’,’add’) % add variable to the trace list bs_trace_var(’myvar ’,’add’) % add variables structure field to trace list bs_trace_var(’myvar.field’,’remove’) % remove form trace list bs_trace_var % get string cell-array of variables currently being traced bs_trace_var(’clear ’) % empty the trace list

6.2. Error messages.

 
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