Difference between revisions of "BrainStreamProgrmmersGuide"

From TSG Doc
Jump to navigation Jump to search
 
(8 intermediate revisions by the same user not shown)
Line 13: Line 13:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| <tt>event</tt> || BrainStream event structure  
 
| <tt>event</tt> || BrainStream event structure  
Line 28: Line 28:
  
 
Output
 
Output
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| <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  
 
| <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  
Line 47: Line 47:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| <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>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  
Line 56: Line 56:
  
 
Output
 
Output
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| lines || cell array of lines (one per row)  
 
| lines || cell array of lines (one per row)  
Line 72: Line 72:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| expression || some expression that either results in true or false  
 
| expression || some expression that either results in true or false  
Line 83: Line 83:
  
 
Output
 
Output
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| opttrue || if expression is true  
 
| opttrue || if expression is true  
Line 99: Line 99:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| filename || name of blockfile with defined experiment definition table to be expanded  
 
| filename || name of blockfile with defined experiment definition table to be expanded  
Line 108: Line 108:
  
 
Output
 
Output
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| markers || all info BrainStream requires for its internal processing <br /> definition of all actions for all markers  
 
| markers || all info BrainStream requires for its internal processing <br /> definition of all actions for all markers  
Line 130: Line 130:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| url || string with name of the datafile or fieldtrip buffer url (i.e., something like: 'buffer://localhost:1972')  
 
| url || string with name of the datafile or fieldtrip buffer url (i.e., something like: 'buffer://localhost:1972')  
Line 177: Line 177:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
−
| event || BrainStream event structure || ||
+
| event || colspan=2|BrainStream event structure
 
|-
 
|-
−
| mod || specifies what to change, options are: || ||
+
| mod || colspan=2|specifies what to change, options are:
 
|-
 
|-
−
| ^ || 'LOGFILE' || specify name of the logfile (overwrites the one composed by BrainStream based on runfolder) |
+
| || 'LOGFILE' || specify name of the logfile (overwrites the one composed by BrainStream based on runfolder)
 
|-
 
|-
−
| ^ || ^ || value = name of the logfile (without path information) |
+
| || || value = name of the logfile (without path information)
 
|-
 
|-
−
| ^ || 'DISABLEOUTPUT' || user can disable any output by BrainStream |
+
| || 'DISABLEOUTPUT' || user can disable any output by BrainStream
 
|-
 
|-
−
| ^ || ^ || value = 0: normal output; 1: no output |
+
| || || value = 0: normal output; 1: no output
 
|-
 
|-
−
| ^ || 'MESSAGE' || same as bs_msg() |
+
| || 'MESSAGE' || same as bs_msg()
 
|-
 
|-
−
| ^ || ^ || value = a string with the message |
+
| || || value = a string with the message
 
|-
 
|-
−
| ^ || 'WARNING' || same as bs_warn() |
+
| || 'WARNING' || same as bs_warn()
 
|-
 
|-
−
| ^ || ^ || value = a string with the warning |
+
| || || value = a string with the warning
 
|-
 
|-
−
| value || content for what should be changed (see mod) || ||
+
| value ||colspan=2|content for what should be changed (see mod) ||
 
|}
 
|}
  
Line 213: Line 213:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
−
| event || BrainStream event structure |
+
| event || colspan=2|BrainStream event structure
 
|-
 
|-
−
| mod || specifies what information to retrieve, options are: |
+
| mod || colspan=2|specifies what information to retrieve, options are:
 
|-
 
|-
−
| ^ || 'LOGFILE' || name of the logfile  
+
| || 'LOGFILE' || name of the logfile  
 
|}
 
|}
  
 
Output
 
Output
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| value || requested info, dependent of mod  
 
| value || requested info, dependent of mod  
Line 236: Line 236:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
−
| event || BrainStream event structure (optional) |
+
| event ||colspan=2| BrainStream event structure (optional)  
 
|-
 
|-
−
| text || string with requested folder reference |
+
| text ||colspan=2| string with requested folder reference
 
|-
 
|-
−
| ^ || 'RUNFOLDER' || folder with system related content  
+
| || 'RUNFOLDER' || folder with system related content  
 
|-
 
|-
−
| ^ || 'BLOCK' || folder with block file  
+
| || 'BLOCK' || folder with block file  
 
|-
 
|-
−
| ^ || 'SESSIONFOLDER' || folder with session related content  
+
| || 'SESSIONFOLDER' || folder with session related content  
 
|-
 
|-
−
| ^ || 'SUBJECTFOLDER' || folder with subject related content  
+
| || 'SUBJECTFOLDER' || folder with subject related content  
 
|-
 
|-
−
| ^ || 'EXPERIMENTFOLDER' || folder with experiment related content  
+
| || 'EXPERIMENTFOLDER' || folder with experiment related content  
 
|-
 
|-
−
| ^ || 'REFERENCEFOLDER' || folder with currently executed blockfile  
+
| || 'REFERENCEFOLDER' || folder with currently executed blockfile  
 
|-
 
|-
−
| ^ || 'BRAINSTREAMFOLDER' || brainstream core folder  
+
| || 'BRAINSTREAMFOLDER' || brainstream core folder  
 
|-
 
|-
−
| ^ || 'ROOT' || brainstream root folder  
+
| || 'ROOT' || brainstream root folder  
 
|-
 
|-
−
| ^ || 'RESOURCESFOLDER' || folder with user resources  
+
| || 'RESOURCESFOLDER' || folder with user resources  
 
|-
 
|-
−
| ^ || 'LIBFOLDER' || folder with library tables  
+
| || 'LIBFOLDER' || folder with library tables  
 
|-
 
|-
−
| ^ || 'PLUGINSFOLDER' || folder with plugin tables  
+
| || 'PLUGINSFOLDER' || folder with plugin tables  
 
|-
 
|-
−
| ^ || 'FIELDTRIPFOLDER' || fieldtrip toolbox folder  
+
| || 'FIELDTRIPFOLDER' || fieldtrip toolbox folder  
 
|-
 
|-
−
| ^ || 'EXAMPLES' || folder with examples  
+
| || 'EXAMPLES' || folder with examples  
 
|-
 
|-
−
| ^ || 'TOOLBOXES' || folder with internally included toolboxes  
+
| || 'TOOLBOXES' || folder with internally included toolboxes  
 
|}
 
|}
  
 
See also:
 
See also:
 +
 
=== bs_disp ===
 
=== 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.
 
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.
Line 278: Line 279:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| event || BrainStream event structure  
 
| event || BrainStream event structure  
Line 298: Line 299:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| event || BrainStream event structure  
 
| event || BrainStream event structure  
Line 316: Line 317:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| event || BrainStream event structure  
 
| event || BrainStream event structure  
Line 339: Line 340:
 
<pre>bs_send_hardware_marker(event, marker, datasource)</pre>Input
 
<pre>bs_send_hardware_marker(event, marker, datasource)</pre>Input
  
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| event || event structure  
 
| event || event structure  
Line 360: Line 361:
 
<pre>bs_send_buffer_marker(event, marker, datasource, delay, reference)</pre>Input
 
<pre>bs_send_buffer_marker(event, marker, datasource, delay, reference)</pre>Input
  
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
 
| event || event structure  
 
| event || event structure  
Line 372: Line 373:
 
| reference || relative to which timepoint is the delay specified, either:  
 
| reference || relative to which timepoint is the delay specified, either:  
 
|-
 
|-
−
| ^ || 'now': delay is specified relative to timepoint of bs_send_buffer_marker execution  
+
| || '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  
+
| || 'marker' (default): delay is specified relative to the onset of the event during which bs_send_buffer_marker is executed  
 
|}
 
|}
  
Line 382: Line 383:
  
 
=== bs_insert_marker ===
 
=== bs_insert_marker ===
−
This function is deprecated, use bs_send_hardware_marker and bs_send_buffer_marker instead.
+
This function is deprecated, use bs_send_hardware_marker and bs_send_buffer_marker instead.
  
 
=== bs_insert_multiple_markers ===
 
=== bs_insert_multiple_markers ===
Line 391: Line 392:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
−
| event || BrainStream event structure |
+
| event || colspan="2"|BrainStream event structure  
 
|-
 
|-
−
| name || name of the marker |
+
| name || colspan="2"|name of the marker  
 
|-
 
|-
−
| delaytime || time of insertion in seconds relative to actions own execution time (&gt;=0)y |
+
| delaytime || colspan="2"|time of insertion in seconds relative to actions own execution time (&gt;=0)y  
 
|-
 
|-
−
| interval || time in seconds between insertions of markers |
+
| interval || colspan="2"|time in seconds between insertions of markers  
 
|-
 
|-
−
| number || number of times the marker has to be inserted |
+
| number || colspan="2"|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> |
+
| priority || colspan="2"|<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  
+
| || 'low' || (default) put behind all other actions with equal execution times  
 
|-
 
|-
−
| ^ || 'high' || put before all other actions with equal execution times  
+
| || 'high' || put before all other actions with equal execution times  
 
|}
 
|}
  
Line 419: Line 420:
  
 
Input
 
Input
−
{| border="1"
+
{| class="wikitable"
 
|-
 
|-
−
| event || BrainStream event structure |||
+
| event || colspan="3"|BrainStream event structure
 
|-
 
|-
−
| mod || modifier indicating what needs to change in the scheduled processing |||
+
| mod || colspan="3"|modifier indicating what needs to change in the scheduled processing
 
|-
 
|-
−
| ^ || options for mod: |||
+
| || colspan="3"|options for mod:  
 
|-
 
|-
−
| ^ || ^ || 'FINISHAPPLICATION' || finish application, normal shutdown via BS EXIT  
+
| || || 'FINISHAPPLICATION' || finish application, normal shutdown via BS EXIT  
 
|-
 
|-
−
| ^ || ^ || 'FINISHEXPERIMENT' || same as FINISHAPPLICATION  
+
| || || 'FINISHEXPERIMENT' || same as FINISHAPPLICATION  
 
|-
 
|-
−
| ^ || ^ || 'QUITAPPLICATION' || quit application, alternative shutdown via BS QUIT  
+
| || || 'QUITAPPLICATION' || quit application, alternative shutdown via BS QUIT  
 
|-
 
|-
−
| ^ || ^ || 'QUITEXPERIMENT' || same as QUITAPPLICATION  
+
| || || 'QUITEXPERIMENT' || same as QUITAPPLICATION  
 
|-
 
|-
−
| ^ || ^ || 'FINISHEVENT' || discard execution of any queued actions for this event  
+
| || || 'FINISHEVENT' || discard execution of any queued actions for this event  
 
|-
 
|-
−
| ^ || ^ || 'ABORTAPPLICATION' || immediately abort  
+
| || || 'ABORTAPPLICATION' || immediately abort  
 
|}
 
|}
  

Latest revision as of 09:04, 26 September 2018

Function Index

1. General purpose functions

bs_get_blockvalue

Function to retrieve information from blocksettings file.

Use as
1. value = bs_get_blockvalue(event, topic, key [,default]), or
2. value = bs_get_blockvalue(filename)

Input

event BrainStream event structure
topic string with topic section where to find key value (always within brackets)
key string with the specific key (or constant) to retrieve
default if key can not be found, value will be set to this default
filename string with name of the block settings file

Output

value content of requested key or default value if specified, otherwise an error is generated. Blocksettings structure if first argument is a filename

1. value = bs_get_blockvalue(event, topic, key, default)
Purpose: retrieve constants defined in your experiments' block file.
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:
class = bs_get_blockvalue(event,'MyClassNames','Class1','UnknownClass')
The content of variable class will be set to 'Class1' or to 'UnknownClass' 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
result=bs_get_blockvalue()
the complete block settings structure is returned.

2. block = bs_get_blockvalue(block_file)
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., start_brainstream_nogui.

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 block.
It prevents having to manually type each separate field in order to see its content. The output is in .blk style.

Use as
lines = bs_block2text(input,toscreen)

Input

input either blocksettings structure or the name of a blocksettings file, the latter option is useful to retrieveclean block file content without any comment lines
toscreen show output to screen (1) or not (0)

Output

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 ( opt_true or opt_false) dependent of whether expression is true or false.

Use as
bs_cond(expression, opttrue, optfalse)

Input

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

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
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs)

Input

filename name of blockfile with defined experiment definition table to be expanded
fs data source sample rate (default 256Hz)

Output

markers all info BrainStream requires for its internal processing
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
event = bs_start_viewer(url)

Input

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) trace_vars. If this feature is being used, trace_vars should be added to the list of user variables in the experiment definition table, like all other user variables.

Use as
1. as modifying action in experiment definition table, APPLIED to variable tarce_vars
bs_trace($self [,var], mod)
2. as a function in experiment definition table
bs_trace([var,] mod)
3. from within a user function
event = bs_trace(event[,var],mod)

Input

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
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
event = bs_custom_out(event,mod,value)

Input

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
value = bs_get_custom_out(event,mod)

Input

event BrainStream event structure
mod specifies what information to retrieve, options are:
'LOGFILE' name of the logfile

Output

value requested info, dependent of mod

See also: bs_custom_out

bs_folder

Retrieve information about the different folders used by BrainStream

Use as
value = bs_folder(event,text), or
value = bs_folder(text)

Input

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
bs_disp(event,text)

Input

event BrainStream event structure
text string with text to output

See also: bs_cond

4. Functions for warnings and messages

bs_msg

Ouputs user messages according to the BrainStream verbosity level. Messages will be added to the log-file.

Use as
event = bs_msg(event,msg)

Input

event BrainStream event structure
msg string with user message

Output
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
event = bs_warn(event,msg) or,
event = bs_warn(event,id,msg)

Input

event BrainStream event structure
msg string with warning message
id warning message identifier (optional)

Output
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

bs_send_hardware_marker

Insert marker in the data stream via the hardware.

Use as: 

bs_send_hardware_marker(event, marker, datasource)

Input

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

See also: bs_send_buffer_marker

bs_send_buffer_marker

Insert marker in the data stream via the FieldTrip buffer.

Use as: 

bs_send_buffer_marker(event, marker, datasource, delay, reference)

Input

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 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
event = bs_insert_multiple_markers(event,name,delaytime, interval, number, priority)

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

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

option to change execution order in case multiple actions have equal execution times

'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
event = bs_change_processing(event,mod)

Input

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
modified event structure which informs BrainStream to change its processing

See also: bs_finish_experiment, bs_quit_experiment, bs_finish_event, bs_abort_experiment



Retrieved from "http://tsgdoc.socsci.ru.nl/index.php?title=BrainStreamProgrmmersGuide&oldid=4562"