BrainStreamProgrmmersGuide

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