1,658
edits
Changes
Jump to navigation
Jump to search
BrainStreamProgrmmersGuide (view source)
Revision as of 09:15, 26 September 2018
, 09:15, 26 September 2018Created page with "<!---Start1---> = Function Index = __TOC__ == 1. General purpose functions == <div id="GetBlockVal"></div> === bs_get_blockvalue === Function to retrieve information from b..."
<!---Start1--->
= Function Index =
__TOC__
== 1. General purpose functions ==
<div id="GetBlockVal"></div>
=== bs_get_blockvalue ===
Function to retrieve information from blocksettings file.
Use as <br /> 1. <tt>value = bs_get_blockvalue(event, topic, key [,default])</tt>, or <br /> 2. <tt>value = bs_get_blockvalue(filename)</tt>
Input
{| border="1"
|-
| <tt>event</tt> || BrainStream event structure
|-
| <tt>topic</tt> || string with topic section where to find key value (always within brackets)
|-
| <tt>key</tt> || string with the specific key (or constant) to retrieve
|-
| <tt>default</tt> || if key can not be found, value will be set to this default
|-
| <tt>filename</tt> || string with name of the block settings file
|}
Output
{| border="1"
|-
| <tt>value</tt> || content of requested key or default value if specified, otherwise an error is generated. Blocksettings structure if first argument is a filename
|}
1. <tt>value = bs_get_blockvalue(event, topic, key, default)</tt> <br /> Purpose: retrieve constants defined in your experiments' block file. <br /> Returns ''key'' for the specified ''topic'' from the block settings current used by BrainStream. If the ''topic/key'' combination doesn't exist, the default is returned. Users can define as many constants as they need in their functions by just adding keys to their own defined topics in the block file. For example if you defined the topic 'MyClassNames' with key 'Class1', you would retrieve this information in your own user function by the following statement:<br /> <tt>class = bs_get_blockvalue(event,'MyClassNames','Class1','UnknownClass')</tt> <br /> The content of variable <tt>class</tt> will be set to <tt>'Class1'</tt> or to <tt>'UnknownClass'</tt> if the constant wasn't found. An error is generated if the key can not be found and no default is specified. If no input arguments are specified, like as follows <br /> <tt>result=bs_get_blockvalue()</tt> <br /> the complete block settings structure is returned.
2. <tt>block = bs_get_blockvalue(block_file)</tt> <br /> Purpose: Use this function outside BrainStream to import structure settings from an existing block-file. This can be useful if BrainStream is used without the GUI. If settings for a number of blocks are almost the same, a common .blk file can be used to define these constants. Then, use this function to import these constants in a structure and add or adapt the fields at need for each specific block. This structure can be used as input argument for the function to start brain_stream, i.e., <tt>start_brainstream_nogui</tt>.
See also: bs_block2text, bs_compose_expdef
=== bs_block2text ===
bs_block2text() converts a blocksettings structure back to text Purpose: Get a quick overview of all fields defines in block settings structure <tt>block</tt>. <br /> It prevents having to manually type each separate field in order to see its content. The output is in .blk style.
Use as <br /> <tt>lines = bs_block2text(input,toscreen)</tt>
Input
{| border="1"
|-
| <tt>input</tt> || either blocksettings structure or the name of a blocksettings file, the latter option is useful to retrieveclean block file content without any comment lines
|-
| <tt>toscreen</tt> || show output to screen (1) or not (0)
|}
Output
{| border="1"
|-
| lines || cell array of lines (one per row)
|-
| ^ || use sprintf('%s',lines{:}) to print output again afterwards
|}
See also: bs_get_blockvalue, bs_compose_expdef
=== bs_cond ===
bs_cond() produces output dependent of some arbitrary conditional expression, useful for modifying expressions in the experiment definition table. It can set content of variables to one of two specified options ( <tt>opt_true</tt> or <tt>opt_false</tt>) dependent of whether <tt>expression</tt> is true or false.
Use as <br /> <tt>bs_cond(expression, opttrue, optfalse)</tt>
Input
{| border="1"
|-
| expression || some expression that either results in true or false
|-
| opttrue || content for user variable in case expression is true
|-
| optfalse || content for user variable in case expression is false
|}
Output
{| border="1"
|-
| opttrue || if expression is true
|-
| optfalse || if expression is false
|}
See also: bs_disp
=== bs_compose_expdef ===
This function can be used to expand an experiment definition table, which is defined in a blockfile. All separate tables will be combined in a single one to get a nice overview of actions defined. It can be used to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Use as <br /> <tt>[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs)</tt>
Input
{| border="1"
|-
| filename || name of blockfile with defined experiment definition table to be expanded
|-
| fs || data source sample rate (default 256Hz)
|}
Output
{| border="1"
|-
| markers || all info BrainStream requires for its internal processing <br /> definition of all actions for all markers
|-
| names || all names of the markers involved in the experiment
|-
| dictionary || translates 'type' and 'value' combinations to marker names
|-
| clients || a list of parallel cores (internal) and clients (other computers) assigned for parallel processing (only if parallel execution is required
|-
| text || the complete table in tab-delimited text format (copy to an empty excel-sheet for a nice overview of all actions)
|}
See also: bs_block2text, bs_get_blockvalue
=== bs_start_viewer ===
bs_start_viewer display any data supported by fieldtrip fileio module
Use as <br /> <tt>event = bs_start_viewer(url)</tt>
Input
{| border="1"
|-
| url || string with name of the datafile or fieldtrip buffer url (i.e., something like: 'buffer://localhost:1972')
|}
== 2. Functions for debugging ==
=== bs_trace ===
bs_trace() adds or removes variables to the list of debugged variables. Their content will be displayed in the logfile at the moment the variable is retrieved or updated (by ''get'' or ''put''). The list itself is stored in a user variable (but reserved for this purpose by BrainStream) <tt>trace_vars</tt>. If this feature is being used, <tt>trace_vars</tt> should be added to the list of user variables in the experiment definition table, like all other user variables.
Use as <br />1. as modifying action in experiment definition table, APPLIED to variable tarce_vars <br /> <tt>bs_trace($self [,var], mod)</tt> <br /> 2. as a function in experiment definition table <br /> <tt>bs_trace([var,] mod)</tt> <br /> 3. from within a user function <br /> <tt>event = bs_trace(event[,var],mod)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure |
|-
| var || name of the user variable, notation according to the name specified in the experiment definition file, i.e., myvar or myvar.field |
|-
| mod || options for mod are: |
|-
| ^ || 'add' || add variable to the list
|-
| ^ || 'remove' || remove variable from the list
|-
| ^ || 'clear' || remove all variables from the list
|}
Output <br /> Content of listed debugged user variables in logfile if retrieved or updated to global variables. From large sized variables, instead of the content the actual size is displayed.
== 3. Functions for directing BrainStream output to user defined locations ==
=== bs_custom_out ===
Customizes BrainStreams output. Users can customize locations where BrainStream stores output
Use as <br /> <tt>event = bs_custom_out(event,mod,value)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure || ||
|-
| mod || specifies what to change, options are: || ||
|-
| ^ || 'LOGFILE' || specify name of the logfile (overwrites the one composed by BrainStream based on runfolder) |
|-
| ^ || ^ || value = name of the logfile (without path information) |
|-
| ^ || 'DISABLEOUTPUT' || user can disable any output by BrainStream |
|-
| ^ || ^ || value = 0: normal output; 1: no output |
|-
| ^ || 'MESSAGE' || same as bs_msg() |
|-
| ^ || ^ || value = a string with the message |
|-
| ^ || 'WARNING' || same as bs_warn() |
|-
| ^ || ^ || value = a string with the warning |
|-
| value || content for what should be changed (see mod) || ||
|}
Output modifies event structure to inform BrainStream about what to change
See also: bs_get_custom_out
=== bs_get_custom_out ===
Gets information about BrainStreams output locations
Use as <br /> <tt>value = bs_get_custom_out(event,mod)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure |
|-
| mod || specifies what information to retrieve, options are: |
|-
| ^ || 'LOGFILE' || name of the logfile
|}
Output
{| border="1"
|-
| value || requested info, dependent of mod
|}
See also: bs_custom_out
=== bs_folder ===
Retrieve information about the different folders used by BrainStream
Use as <br /> value = bs_folder(event,text), or<br />value = bs_folder(text)
Input
{| border="1"
|-
| event || BrainStream event structure (optional) |
|-
| text || string with requested folder reference |
|-
| ^ || 'RUNFOLDER' || folder with system related content
|-
| ^ || 'BLOCK' || folder with block file
|-
| ^ || 'SESSIONFOLDER' || folder with session related content
|-
| ^ || 'SUBJECTFOLDER' || folder with subject related content
|-
| ^ || 'EXPERIMENTFOLDER' || folder with experiment related content
|-
| ^ || 'REFERENCEFOLDER' || folder with currently executed blockfile
|-
| ^ || 'BRAINSTREAMFOLDER' || brainstream core folder
|-
| ^ || 'ROOT' || brainstream root folder
|-
| ^ || 'RESOURCESFOLDER' || folder with user resources
|-
| ^ || 'LIBFOLDER' || folder with library tables
|-
| ^ || 'PLUGINSFOLDER' || folder with plugin tables
|-
| ^ || 'FIELDTRIPFOLDER' || fieldtrip toolbox folder
|-
| ^ || 'EXAMPLES' || folder with examples
|-
| ^ || 'TOOLBOXES' || folder with internally included toolboxes
|}
See also:
=== bs_disp ===
bs_disp() outputs text to console (or screen). It is a wrapper function around Matlab disp function, intended to be used as function in the experiment definition table for displaying output to screen. Instead, you could also directly define the disp() function in the special [.DocsSectionsBuildingExperiments#SecFeval feval] column.
Use as <br /> <tt>bs_disp(event,text)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure
|-
| text || string with text to output
|}
See also: bs_cond
== 4. Functions for warnings and messages ==
<div id="InfoFuncs"></div>
=== bs_msg ===
Ouputs user messages according to the BrainStream verbosity level. Messages will be added to the log-file.
Use as <br /> <tt>event = bs_msg(event,msg)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure
|-
| msg || string with user message
|}
Output <br /> user message in logfile and/or at console dependent of BrainStream verbosity level
See also: bs_warn, bs_custom_out, bs_get_custom_out
=== bs_warn ===
Ouputs warning messages according to the BrainStream verbosity level. Warning messages will be added to the log-file.
Use as <br /> <tt>event = bs_warn(event,msg)</tt> or, <br /> <tt>event = bs_warn(event,id,msg)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure
|-
| msg || string with warning message
|-
| id || warning message identifier (optional)
|}
Output <br /> warning message in logfile and/or at console dependent of BrainStream verbosity level
See also: bs_msg, bs_custom_out, bs_get_custom_out
== 5. Functions for manipulating runtime event processing ==
<div id="SendHardwareMarker"></div>
=== bs_send_hardware_marker ===
Insert marker in the data stream via the hardware.
Use as:
<pre>bs_send_hardware_marker(event, marker, datasource)</pre>Input
{| border="1"
|-
| event || event structure
|-
| marker || marker name
|-
| datasource || in which data source should the marker be inserted (you may leave this argument empty if only one data source is used)
|}
For more information about inserting markers via the hardware, see [[BrainStreamMarkerHandling#HardwareMarker|Inserting Markers]].
See also: bs_send_buffer_marker
<div id="SendBufferMarker"></div>
=== bs_send_buffer_marker ===
Insert marker in the data stream via the FieldTrip buffer.
Use as:
<pre>bs_send_buffer_marker(event, marker, datasource, delay, reference)</pre>Input
{| border="1"
|-
| event || event structure
|-
| marker || marker name
|-
| datasource || in which data source should the marker be inserted (you may leave this argument empty of only one data source is used)
|-
| delay || time in seconds before marker is inserted
|-
| reference || relative to which timepoint is the delay specified, either:
|-
| ^ || 'now': delay is specified relative to timepoint of bs_send_buffer_marker execution
|-
| ^ || 'marker' (default): delay is specified relative to the onset of the event during which bs_send_buffer_marker is executed
|}
For more information about inserting markers via the FieldTrip buffer, see [[BrainStreamMarkerHandling#BufferMarker|Inserting Markers]].
See also: bs_send_hardware_marker
=== bs_insert_marker ===
This function is deprecated, use bs_send_hardware_marker and bs_send_buffer_marker instead.
=== bs_insert_multiple_markers ===
Inserts a marker multiple times with a specific time delay (t>=0) and a specific time interval between the markers.
Use as <br />event = bs_insert_multiple_markers(event,name,delaytime, interval, number, priority)<br /><br />WARNING: correct processing of markers is NOT guaranteed if markers are inserted when running in parallel mode. In this case you should be convinced that in your experiment design corresponding actions of the inserted marker will never involve global variables that t the same time could be used in other parallel executed actions (functions).
Input
{| border="1"
|-
| event || BrainStream event structure |
|-
| name || name of the marker |
|-
| delaytime || time of insertion in seconds relative to actions own execution time (>=0)y |
|-
| interval || time in seconds between insertions of markers |
|-
| number || number of times the marker has to be inserted |
|-
| priority || <p>option to change execution order in case multiple actions have equal execution times</p> |
|-
| ^ || 'low' || (default) put behind all other actions with equal execution times
|-
| ^ || 'high' || put before all other actions with equal execution times
|}
See also: bs_change_processing, bs_insert_marker
=== bs_change_processing ===
Provides several options to dynamically change BrainStreams processing.
Use as <br /> <tt>event = bs_change_processing(event,mod)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure |||
|-
| mod || modifier indicating what needs to change in the scheduled processing |||
|-
| ^ || options for mod: |||
|-
| ^ || ^ || 'FINISHAPPLICATION' || finish application, normal shutdown via BS EXIT
|-
| ^ || ^ || 'FINISHEXPERIMENT' || same as FINISHAPPLICATION
|-
| ^ || ^ || 'QUITAPPLICATION' || quit application, alternative shutdown via BS QUIT
|-
| ^ || ^ || 'QUITEXPERIMENT' || same as QUITAPPLICATION
|-
| ^ || ^ || 'FINISHEVENT' || discard execution of any queued actions for this event
|-
| ^ || ^ || 'ABORTAPPLICATION' || immediately abort
|}
Output <br /> modified event structure which informs BrainStream to change its processing
See also: bs_finish_experiment, bs_quit_experiment, bs_finish_event, bs_abort_experiment
<!---End1--->
<!--
* Access control
-->
= Function Index =
__TOC__
== 1. General purpose functions ==
<div id="GetBlockVal"></div>
=== bs_get_blockvalue ===
Function to retrieve information from blocksettings file.
Use as <br /> 1. <tt>value = bs_get_blockvalue(event, topic, key [,default])</tt>, or <br /> 2. <tt>value = bs_get_blockvalue(filename)</tt>
Input
{| border="1"
|-
| <tt>event</tt> || BrainStream event structure
|-
| <tt>topic</tt> || string with topic section where to find key value (always within brackets)
|-
| <tt>key</tt> || string with the specific key (or constant) to retrieve
|-
| <tt>default</tt> || if key can not be found, value will be set to this default
|-
| <tt>filename</tt> || string with name of the block settings file
|}
Output
{| border="1"
|-
| <tt>value</tt> || content of requested key or default value if specified, otherwise an error is generated. Blocksettings structure if first argument is a filename
|}
1. <tt>value = bs_get_blockvalue(event, topic, key, default)</tt> <br /> Purpose: retrieve constants defined in your experiments' block file. <br /> Returns ''key'' for the specified ''topic'' from the block settings current used by BrainStream. If the ''topic/key'' combination doesn't exist, the default is returned. Users can define as many constants as they need in their functions by just adding keys to their own defined topics in the block file. For example if you defined the topic 'MyClassNames' with key 'Class1', you would retrieve this information in your own user function by the following statement:<br /> <tt>class = bs_get_blockvalue(event,'MyClassNames','Class1','UnknownClass')</tt> <br /> The content of variable <tt>class</tt> will be set to <tt>'Class1'</tt> or to <tt>'UnknownClass'</tt> if the constant wasn't found. An error is generated if the key can not be found and no default is specified. If no input arguments are specified, like as follows <br /> <tt>result=bs_get_blockvalue()</tt> <br /> the complete block settings structure is returned.
2. <tt>block = bs_get_blockvalue(block_file)</tt> <br /> Purpose: Use this function outside BrainStream to import structure settings from an existing block-file. This can be useful if BrainStream is used without the GUI. If settings for a number of blocks are almost the same, a common .blk file can be used to define these constants. Then, use this function to import these constants in a structure and add or adapt the fields at need for each specific block. This structure can be used as input argument for the function to start brain_stream, i.e., <tt>start_brainstream_nogui</tt>.
See also: bs_block2text, bs_compose_expdef
=== bs_block2text ===
bs_block2text() converts a blocksettings structure back to text Purpose: Get a quick overview of all fields defines in block settings structure <tt>block</tt>. <br /> It prevents having to manually type each separate field in order to see its content. The output is in .blk style.
Use as <br /> <tt>lines = bs_block2text(input,toscreen)</tt>
Input
{| border="1"
|-
| <tt>input</tt> || either blocksettings structure or the name of a blocksettings file, the latter option is useful to retrieveclean block file content without any comment lines
|-
| <tt>toscreen</tt> || show output to screen (1) or not (0)
|}
Output
{| border="1"
|-
| lines || cell array of lines (one per row)
|-
| ^ || use sprintf('%s',lines{:}) to print output again afterwards
|}
See also: bs_get_blockvalue, bs_compose_expdef
=== bs_cond ===
bs_cond() produces output dependent of some arbitrary conditional expression, useful for modifying expressions in the experiment definition table. It can set content of variables to one of two specified options ( <tt>opt_true</tt> or <tt>opt_false</tt>) dependent of whether <tt>expression</tt> is true or false.
Use as <br /> <tt>bs_cond(expression, opttrue, optfalse)</tt>
Input
{| border="1"
|-
| expression || some expression that either results in true or false
|-
| opttrue || content for user variable in case expression is true
|-
| optfalse || content for user variable in case expression is false
|}
Output
{| border="1"
|-
| opttrue || if expression is true
|-
| optfalse || if expression is false
|}
See also: bs_disp
=== bs_compose_expdef ===
This function can be used to expand an experiment definition table, which is defined in a blockfile. All separate tables will be combined in a single one to get a nice overview of actions defined. It can be used to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Use as <br /> <tt>[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs)</tt>
Input
{| border="1"
|-
| filename || name of blockfile with defined experiment definition table to be expanded
|-
| fs || data source sample rate (default 256Hz)
|}
Output
{| border="1"
|-
| markers || all info BrainStream requires for its internal processing <br /> definition of all actions for all markers
|-
| names || all names of the markers involved in the experiment
|-
| dictionary || translates 'type' and 'value' combinations to marker names
|-
| clients || a list of parallel cores (internal) and clients (other computers) assigned for parallel processing (only if parallel execution is required
|-
| text || the complete table in tab-delimited text format (copy to an empty excel-sheet for a nice overview of all actions)
|}
See also: bs_block2text, bs_get_blockvalue
=== bs_start_viewer ===
bs_start_viewer display any data supported by fieldtrip fileio module
Use as <br /> <tt>event = bs_start_viewer(url)</tt>
Input
{| border="1"
|-
| url || string with name of the datafile or fieldtrip buffer url (i.e., something like: 'buffer://localhost:1972')
|}
== 2. Functions for debugging ==
=== bs_trace ===
bs_trace() adds or removes variables to the list of debugged variables. Their content will be displayed in the logfile at the moment the variable is retrieved or updated (by ''get'' or ''put''). The list itself is stored in a user variable (but reserved for this purpose by BrainStream) <tt>trace_vars</tt>. If this feature is being used, <tt>trace_vars</tt> should be added to the list of user variables in the experiment definition table, like all other user variables.
Use as <br />1. as modifying action in experiment definition table, APPLIED to variable tarce_vars <br /> <tt>bs_trace($self [,var], mod)</tt> <br /> 2. as a function in experiment definition table <br /> <tt>bs_trace([var,] mod)</tt> <br /> 3. from within a user function <br /> <tt>event = bs_trace(event[,var],mod)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure |
|-
| var || name of the user variable, notation according to the name specified in the experiment definition file, i.e., myvar or myvar.field |
|-
| mod || options for mod are: |
|-
| ^ || 'add' || add variable to the list
|-
| ^ || 'remove' || remove variable from the list
|-
| ^ || 'clear' || remove all variables from the list
|}
Output <br /> Content of listed debugged user variables in logfile if retrieved or updated to global variables. From large sized variables, instead of the content the actual size is displayed.
== 3. Functions for directing BrainStream output to user defined locations ==
=== bs_custom_out ===
Customizes BrainStreams output. Users can customize locations where BrainStream stores output
Use as <br /> <tt>event = bs_custom_out(event,mod,value)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure || ||
|-
| mod || specifies what to change, options are: || ||
|-
| ^ || 'LOGFILE' || specify name of the logfile (overwrites the one composed by BrainStream based on runfolder) |
|-
| ^ || ^ || value = name of the logfile (without path information) |
|-
| ^ || 'DISABLEOUTPUT' || user can disable any output by BrainStream |
|-
| ^ || ^ || value = 0: normal output; 1: no output |
|-
| ^ || 'MESSAGE' || same as bs_msg() |
|-
| ^ || ^ || value = a string with the message |
|-
| ^ || 'WARNING' || same as bs_warn() |
|-
| ^ || ^ || value = a string with the warning |
|-
| value || content for what should be changed (see mod) || ||
|}
Output modifies event structure to inform BrainStream about what to change
See also: bs_get_custom_out
=== bs_get_custom_out ===
Gets information about BrainStreams output locations
Use as <br /> <tt>value = bs_get_custom_out(event,mod)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure |
|-
| mod || specifies what information to retrieve, options are: |
|-
| ^ || 'LOGFILE' || name of the logfile
|}
Output
{| border="1"
|-
| value || requested info, dependent of mod
|}
See also: bs_custom_out
=== bs_folder ===
Retrieve information about the different folders used by BrainStream
Use as <br /> value = bs_folder(event,text), or<br />value = bs_folder(text)
Input
{| border="1"
|-
| event || BrainStream event structure (optional) |
|-
| text || string with requested folder reference |
|-
| ^ || 'RUNFOLDER' || folder with system related content
|-
| ^ || 'BLOCK' || folder with block file
|-
| ^ || 'SESSIONFOLDER' || folder with session related content
|-
| ^ || 'SUBJECTFOLDER' || folder with subject related content
|-
| ^ || 'EXPERIMENTFOLDER' || folder with experiment related content
|-
| ^ || 'REFERENCEFOLDER' || folder with currently executed blockfile
|-
| ^ || 'BRAINSTREAMFOLDER' || brainstream core folder
|-
| ^ || 'ROOT' || brainstream root folder
|-
| ^ || 'RESOURCESFOLDER' || folder with user resources
|-
| ^ || 'LIBFOLDER' || folder with library tables
|-
| ^ || 'PLUGINSFOLDER' || folder with plugin tables
|-
| ^ || 'FIELDTRIPFOLDER' || fieldtrip toolbox folder
|-
| ^ || 'EXAMPLES' || folder with examples
|-
| ^ || 'TOOLBOXES' || folder with internally included toolboxes
|}
See also:
=== bs_disp ===
bs_disp() outputs text to console (or screen). It is a wrapper function around Matlab disp function, intended to be used as function in the experiment definition table for displaying output to screen. Instead, you could also directly define the disp() function in the special [.DocsSectionsBuildingExperiments#SecFeval feval] column.
Use as <br /> <tt>bs_disp(event,text)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure
|-
| text || string with text to output
|}
See also: bs_cond
== 4. Functions for warnings and messages ==
<div id="InfoFuncs"></div>
=== bs_msg ===
Ouputs user messages according to the BrainStream verbosity level. Messages will be added to the log-file.
Use as <br /> <tt>event = bs_msg(event,msg)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure
|-
| msg || string with user message
|}
Output <br /> user message in logfile and/or at console dependent of BrainStream verbosity level
See also: bs_warn, bs_custom_out, bs_get_custom_out
=== bs_warn ===
Ouputs warning messages according to the BrainStream verbosity level. Warning messages will be added to the log-file.
Use as <br /> <tt>event = bs_warn(event,msg)</tt> or, <br /> <tt>event = bs_warn(event,id,msg)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure
|-
| msg || string with warning message
|-
| id || warning message identifier (optional)
|}
Output <br /> warning message in logfile and/or at console dependent of BrainStream verbosity level
See also: bs_msg, bs_custom_out, bs_get_custom_out
== 5. Functions for manipulating runtime event processing ==
<div id="SendHardwareMarker"></div>
=== bs_send_hardware_marker ===
Insert marker in the data stream via the hardware.
Use as:
<pre>bs_send_hardware_marker(event, marker, datasource)</pre>Input
{| border="1"
|-
| event || event structure
|-
| marker || marker name
|-
| datasource || in which data source should the marker be inserted (you may leave this argument empty if only one data source is used)
|}
For more information about inserting markers via the hardware, see [[BrainStreamMarkerHandling#HardwareMarker|Inserting Markers]].
See also: bs_send_buffer_marker
<div id="SendBufferMarker"></div>
=== bs_send_buffer_marker ===
Insert marker in the data stream via the FieldTrip buffer.
Use as:
<pre>bs_send_buffer_marker(event, marker, datasource, delay, reference)</pre>Input
{| border="1"
|-
| event || event structure
|-
| marker || marker name
|-
| datasource || in which data source should the marker be inserted (you may leave this argument empty of only one data source is used)
|-
| delay || time in seconds before marker is inserted
|-
| reference || relative to which timepoint is the delay specified, either:
|-
| ^ || 'now': delay is specified relative to timepoint of bs_send_buffer_marker execution
|-
| ^ || 'marker' (default): delay is specified relative to the onset of the event during which bs_send_buffer_marker is executed
|}
For more information about inserting markers via the FieldTrip buffer, see [[BrainStreamMarkerHandling#BufferMarker|Inserting Markers]].
See also: bs_send_hardware_marker
=== bs_insert_marker ===
This function is deprecated, use bs_send_hardware_marker and bs_send_buffer_marker instead.
=== bs_insert_multiple_markers ===
Inserts a marker multiple times with a specific time delay (t>=0) and a specific time interval between the markers.
Use as <br />event = bs_insert_multiple_markers(event,name,delaytime, interval, number, priority)<br /><br />WARNING: correct processing of markers is NOT guaranteed if markers are inserted when running in parallel mode. In this case you should be convinced that in your experiment design corresponding actions of the inserted marker will never involve global variables that t the same time could be used in other parallel executed actions (functions).
Input
{| border="1"
|-
| event || BrainStream event structure |
|-
| name || name of the marker |
|-
| delaytime || time of insertion in seconds relative to actions own execution time (>=0)y |
|-
| interval || time in seconds between insertions of markers |
|-
| number || number of times the marker has to be inserted |
|-
| priority || <p>option to change execution order in case multiple actions have equal execution times</p> |
|-
| ^ || 'low' || (default) put behind all other actions with equal execution times
|-
| ^ || 'high' || put before all other actions with equal execution times
|}
See also: bs_change_processing, bs_insert_marker
=== bs_change_processing ===
Provides several options to dynamically change BrainStreams processing.
Use as <br /> <tt>event = bs_change_processing(event,mod)</tt>
Input
{| border="1"
|-
| event || BrainStream event structure |||
|-
| mod || modifier indicating what needs to change in the scheduled processing |||
|-
| ^ || options for mod: |||
|-
| ^ || ^ || 'FINISHAPPLICATION' || finish application, normal shutdown via BS EXIT
|-
| ^ || ^ || 'FINISHEXPERIMENT' || same as FINISHAPPLICATION
|-
| ^ || ^ || 'QUITAPPLICATION' || quit application, alternative shutdown via BS QUIT
|-
| ^ || ^ || 'QUITEXPERIMENT' || same as QUITAPPLICATION
|-
| ^ || ^ || 'FINISHEVENT' || discard execution of any queued actions for this event
|-
| ^ || ^ || 'ABORTAPPLICATION' || immediately abort
|}
Output <br /> modified event structure which informs BrainStream to change its processing
See also: bs_finish_experiment, bs_quit_experiment, bs_finish_event, bs_abort_experiment
<!---End1--->
<!--
* Access control
-->