Difference: DocsSectionsProgrmmersGuide (1 vs. 30)

Revision 3016 May 2012 - Main.PhilipVanDenBroek

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

Function Index

Line: 24 to 24
 Output
value content of requested key or default value if specified, otherwise an error is generated. Blocksettings structure if first argument is a filename
Changed:
<
<
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 both topic and key are empty, like as follows
result=bs_get_blockvalue(event,[],[])
the complete block settings structure is returned.
>
>
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.
Line: 83 to 83
 

bs_start_viewer

bs_start_viewer display any data supported by fieldtrip fileio module
Changed:
<
<
Use as
event = bs_start_viewer(file)
>
>
Use as
event = bs_start_viewer(url)
  Input
Changed:
<
<
file string with name of the datafile
>
>
url string with name of the datafile or fieldtrip buffer url (i.e., something like: 'buffer://localhost:1972')
 

2. Functions for debugging

bs_trace

Line: 166 to 166
 
'PLUGINSFOLDER' folder with plugin tables
'FIELDTRIPFOLDER' fieldtrip toolbox folder
'EXAMPLES' folder with examples
Changed:
<
<
'TOOLBOXES' folder with internal toolboxes
>
>
'TOOLBOXES' folder with internally included toolboxes
  See also:

bs_disp

Changed:
<
<
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
>
>
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 feval column.
  Use as
bs_disp(event,text)

Revision 2915 May 2012 - Main.PhilipVanDenBroek

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

Function Index

Line: 159 to 159
 
'SUBJECTFOLDER' folder with subject related content
'EXPERIMENTFOLDER' folder with experiment related content
'REFERENCEFOLDER' folder with currently executed blockfile
Changed:
<
<
'BRAINSTREAMFOLDER' folder where brainstream is installed
>
>
'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
Added:
>
>
'EXAMPLES' folder with examples
'TOOLBOXES' folder with internal toolboxes
  See also:

bs_disp

Revision 2804 Jan 2012 - Main.MarjoleinVanDerWaal

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

Function Index

Line: 241 to 241
 
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
Changed:
<
<
'marker': 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
  For more information about inserting markers via the FieldTrip buffer, see Inserting Markers.

Revision 2714 Nov 2011 - Main.MarjoleinVanDerWaal

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

Function Index

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

1. General purpose functions

Revision 2614 Nov 2011 - Main.MarjoleinVanDerWaal

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

10. FUNCTION INDEX

>
>

Function Index

  Generate current PDF
Changed:
<
<

10.1 General purpose functions

>
>

1. General purpose functions

 

bs_get_blockvalue

Line: 88 to 88
 Input
file string with name of the datafile
Changed:
<
<

10.2 Functions for debugging

>
>

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.

Line: 105 to 105
  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.
Changed:
<
<

10.3 Functions for directing BrainStream output to user defined locations

>
>

3. Functions for directing BrainStream output to user defined locations

 

bs_custom_out

Customizes BrainStreams output. Users can customize locations where BrainStream stores output

Line: 177 to 177
  See also: bs_cond
Changed:
<
<

10.4 Functions for warnings and messages

>
>

4. Functions for warnings and messages

 
Line: 209 to 209
  See also: bs_msg, bs_custom_out, bs_get_custom_out
Changed:
<
<

10.5 Functions for manipulating runtime event processing

>
>

5. Functions for manipulating runtime event processing

 

bs_send_hardware_marker

Line: 298 to 298
 
  • Access control
    • Set DENYTOPICVIEW =
-->
Added:
>
>
META TOPICMOVED by="MarjoleinVanDerWaal" date="1321267216" from="BrainStream.DocsSectionsProgrmmersGuide" to="BrainStreamDocs.DocsSectionsProgrmmersGuide"

Revision 2509 Nov 2011 - Main.MarjoleinVanDerWaal

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

10. FUNCTION INDEX

Line: 209 to 210
 See also: bs_msg, bs_custom_out, bs_get_custom_out

10.5 Functions for manipulating runtime event processing

Deleted:
<
<

bs_insert_marker

 
Changed:
<
<
Insert marker(s) with specific time delay (t>=0)
>
>

bs_send_hardware_marker

 
Changed:
<
<
Use as
event = bs_insert_marker(event,name,delaytime,priority)
>
>
Insert marker in the data stream via the hardware.
 
Changed:
<
<
Input
event BrainStream event structure
name name(s) of the marker (use cell array for multiple markers)
delaytime time of insertion in seconds relative to actions own execution time (>=0), for multiple inserted markers, specify an array
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
>
>
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)
 
Changed:
<
<
See also: bs_change_processing, bs_insert_multiple_markers
>
>
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': 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

Revision 2421 Oct 2011 - Main.MarjoleinVanDerWaal

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

10. FUNCTION INDEX

Line: 145 to 145
 See also: bs_custom_out

bs_folder

Changed:
<
<
Retrieve information about the different folders used by BrainStream
>
>
Retrieve information about the different folders used by BrainStream
  Use as
value = bs_folder(event,text), or
value = bs_folder(text)
Line: 153 to 153
 
event BrainStream event structure (optional)
text string with requested folder reference
'RUNFOLDER' folder with system related content
Changed:
<
<
'BLOCKFOLDER' same as 'RUNFOLDER'
>
>
'BLOCK' folder with block file
 
'SESSIONFOLDER' folder with session related content
'SUBJECTFOLDER' folder with subject related content
'EXPERIMENTFOLDER' folder with experiment related content
Line: 161 to 161
 
'BRAINSTREAMFOLDER' folder where brainstream is installed
'RESOURCESFOLDER' folder with user resources
'LIBFOLDER' folder with library tables
Changed:
<
<
'PLUGINSFOLDER' folder with plugins tables
>
>
'PLUGINSFOLDER' folder with plugin tables
 
'FIELDTRIPFOLDER' fieldtrip toolbox folder

See also:

Revision 2310 Oct 2011 - Main.MarjoleinVanDerWaal

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

10. FUNCTION INDEX

Added:
>
>
Generate current PDF
 

10.1 General purpose functions

Revision 2221 Sep 2011 - Main.MarjoleinVanDerWaal

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

10. FUNCTION INDEX

10.1 General purpose functions

Added:
>
>
 

bs_get_blockvalue

Function to retrieve information from blocksettings file.

Revision 2121 Jul 2011 - Main.PhilipVanDenBroek

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

10. FUNCTION INDEX

Line: 58 to 58
 See also: bs_disp

bs_compose_expdef

Changed:
<
<
This function can be used to expand an experiment definition table. 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.
>
>
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.
 
Changed:
<
<
Use as
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,subfile,dataselection,fs)
>
>
Use as
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs)
  Input
Changed:
<
<
filename name of experiment definition table to be expanded
>
>
filename name of blockfile with defined experiment definition table to be expanded
 
fs data source sample rate (default 256Hz)
Deleted:
<
<
tablevars if table includes table variables, specify content (under construction)
  Output
markers all info BrainStream requires for its internal processing
definition of all actions for all markers
Line: 74 to 73
 
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)
Deleted:
<
<
For testing, in most cases [m,n,d,c,t] = bs_compose_expdef(filename) will be sufficient, all additional input arguments can be omitted.
 See also: bs_block2text, bs_get_blockvalue

bs_start_viewer

Line: 146 to 143
 

bs_folder

Retrieve information about the different folders used by BrainStream
Changed:
<
<
Use as
value = bs_folder(event,text)
>
>
Use as
value = bs_folder(event,text), or
value = bs_folder(text)
  Input
Added:
>
>
event BrainStream event structure (optional)
 
text string with requested folder reference
'RUNFOLDER' folder with system related content
'BLOCKFOLDER' same as 'RUNFOLDER'

Revision 2021 Jul 2011 - Main.PhilipVanDenBroek

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

10. FUNCTION INDEX

Line: 127 to 127
  See also: bs_get_custom_out
Deleted:
<
<
value = bs_get_custom_out(event,mod) Options for mod:
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
 

bs_get_custom_out

Gets information about BrainStreams output locations

Line: 140 to 137
 
event BrainStream event structure
mod specifies what information to retrieve, options are:
'LOGFILE' name of the logfile
Deleted:
<
<
'DISABLEOUTPUT' disabled (1) or enabled (0=default) output
'RUNFOLDER' folder with system related content
'BLOCKFOLDER' same as 'RUNFOLDER'
'SESSIONFOLDER' folder with session related content
'SUBJECTFOLDER' folder with subject related content
'EXPERIMENTFOLDER' folder with experiment related content
  Output
value requested info, dependent of mod
Line: 155 to 146
 

bs_folder

Retrieve information about the different folders used by BrainStream
Changed:
<
<
Use as
bs_folder(event,text)
>
>
Use as
value = bs_folder(event,text)
  Input
text string with requested folder reference
Deleted:
<
<
'LOGFILE' name of the logfile
'DISABLEOUTPUT' disabled (1) or enabled (0=default) output
 
'RUNFOLDER' folder with system related content
'BLOCKFOLDER' same as 'RUNFOLDER'
'SESSIONFOLDER' folder with session related content
'SUBJECTFOLDER' folder with subject related content
'EXPERIMENTFOLDER' folder with experiment related content
Added:
>
>
'REFERENCEFOLDER' folder with currently executed blockfile
'BRAINSTREAMFOLDER' folder where brainstream is installed
'RESOURCESFOLDER' folder with user resources
'LIBFOLDER' folder with library tables
'PLUGINSFOLDER' folder with plugins tables
'FIELDTRIPFOLDER' fieldtrip toolbox folder
  See also:
Deleted:
<
<
# switch fld case 'RUNFOLDER' case 'SESSIONFOLDER' case 'SUBJECTFOLDER' case 'EXPERIMENTFOLDER' case 'REFERENCEFOLDER' end else switch lower(fld) case {'run','runfolder'} case {'session','sessionfolder'} case {'subject','subjectfolder'} case {'experiment','experimentfolder'} case {'brainstream','bs','brainstreamfolder'} case {'resources', 'resource','resourcesfolder','resourcefolder'} case {'lib','library','libfolder','libraryfolder'} case {'plugin','plugins','plug-in','plug-ins','apps','app','pluginsfolder','pluginfolder'} case {'reference','referencefolder','block','blockfile','blocks','blockfolder','blocksfolder'} case {'fieldtrip','fieldtripfolder'} #
 

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

Revision 1921 Jul 2011 - Main.PhilipVanDenBroek

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

10. FUNCTION INDEX

Line: 128 to 128
 See also: bs_get_custom_out

value = bs_get_custom_out(event,mod) Options for mod:

Changed:
<
<
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
>
>
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
 

bs_get_custom_out

Line: 152 to 152
  See also: bs_custom_out
Added:
>
>

bs_folder

Retrieve information about the different folders used by BrainStream

Use as
bs_folder(event,text)

Input

text string with requested folder reference
'LOGFILE' name of the logfile
'DISABLEOUTPUT' disabled (1) or enabled (0=default) output
'RUNFOLDER' folder with system related content
'BLOCKFOLDER' same as 'RUNFOLDER'
'SESSIONFOLDER' folder with session related content
'SUBJECTFOLDER' folder with subject related content
'EXPERIMENTFOLDER' folder with experiment related content

See also:

# switch fld case 'RUNFOLDER' case 'SESSIONFOLDER' case 'SUBJECTFOLDER' case 'EXPERIMENTFOLDER' case 'REFERENCEFOLDER' end else switch lower(fld) case {'run','runfolder'} case {'session','sessionfolder'} case {'subject','subjectfolder'} case {'experiment','experimentfolder'} case {'brainstream','bs','brainstreamfolder'} case {'resources', 'resource','resourcesfolder','resourcefolder'} case {'lib','library','libfolder','libraryfolder'} case {'plugin','plugins','plug-in','plug-ins','apps','app','pluginsfolder','pluginfolder'} case {'reference','referencefolder','block','blockfile','blocks','blockfolder','blocksfolder'} case {'fieldtrip','fieldtripfolder'} #

 

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
Line: 199 to 239
  Insert marker(s) with specific time delay (t>=0)
Changed:
<
<
Use as
event = bs_insert_marker(event,name,delaytime,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).
>
>
Use as
event = bs_insert_marker(event,name,delaytime,priority)
  Input
event BrainStream event structure

Revision 1820 Nov 2009 - Main.LinseyRoijendijk

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

10. FUNCTION INDEX

Line: 128 to 128
 See also: bs_get_custom_out

value = bs_get_custom_out(event,mod) Options for mod:

Changed:
<
<
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
>
>
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
 

bs_get_custom_out

Line: 199 to 199
  Insert marker(s) with specific time delay (t>=0)
Changed:
<
<
Use as
event = bs_insert_marker(event,name,delaytime,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).
>
>
Use as
event = bs_insert_marker(event,name,delaytime,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
Line: 209 to 209
 
'low' (default) put behind all other actions with equal execution times
'high' put before all other actions with equal execution times
Changed:
<
<
See also: bs_change_processing
>
>
See also: bs_change_processing, bs_insert_multiple_markers
 
Added:
>
>

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.

Revision 1716 Nov 2009 - Main.PhilipVanDenBroek

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

10. FUNCTION INDEX

Line: 29 to 29
  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.
Changed:
<
<
Use as
lines = bs_block2text(input,toscreen)
>
>
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
Line: 46 to 44
 

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.
Changed:
<
<
Use as
bs_cond(expression, opttrue, optfalse)
>
>
Use as
bs_cond(expression, opttrue, optfalse)
  Input
expression some expression that either results in true or false
Line: 63 to 60
 

bs_compose_expdef

This function can be used to expand an experiment definition table. 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.
Changed:
<
<
Use as
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,subfile,dataselection,fs)
>
>
Use as
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,subfile,dataselection,fs)
  Input
filename name of experiment definition table to be expanded
Line: 85 to 81
 

bs_start_viewer

bs_start_viewer display any data supported by fieldtrip fileio module
Changed:
<
<
Use as
event = bs_start_viewer(file)
>
>
Use as
event = bs_start_viewer(file)
  Input
file string with name of the datafile
Line: 97 to 91
  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.
Changed:
<
<
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)
>
>
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
Line: 112 to 101
 
'remove' remove variable from the list
'clear' remove all variables from the list
Changed:
<
<
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.
>
>
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.
 

10.3 Functions for directing BrainStream output to user defined locations

bs_custom_out

Customizes BrainStreams output. Users can customize locations where BrainStream stores output

Changed:
<
<
Use as
event = bs_custom_out(event,mod,value)
>
>
Use as
event = bs_custom_out(event,mod,value)
  Input
event BrainStream event structure
mod specifies what to change, options are:
Changed:
<
<
'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)
>
>
'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)
 
Changed:
<
<
Output modifies event structure to inform BrainStream about what to change
>
>
Output modifies event structure to inform BrainStream about what to change
  See also: bs_get_custom_out
Line: 149 to 134
  Gets information about BrainStreams output locations
Changed:
<
<
Use as
value = bs_get_custom_out(event,mod)
>
>
Use as
value = bs_get_custom_out(event,mod)
  Input
event BrainStream event structure
Line: 172 to 155
 

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
Changed:
<
<
Use as
bs_disp(event,text)
>
>
Use as
bs_disp(event,text)
  Input
event BrainStream event structure
Line: 187 to 169
 

bs_msg

Ouputs user messages according to the BrainStream verbosity level. Messages will be added to the log-file.
Changed:
<
<
Use as
event = bs_msg(event,msg)
>
>
Use as
event = bs_msg(event,msg)
  Input
event BrainStream event structure
msg string with user message
Changed:
<
<
Output
user message in logfile and/or at console dependent of BrainStream verbosity level
>
>
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
Line: 203 to 183
  Ouputs warning messages according to the BrainStream verbosity level. Warning messages will be added to the log-file.
Changed:
<
<
Use as
event = bs_warn(event,msg) or,
event = bs_warn(event,id,msg)
>
>
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)
Changed:
<
<
Output
warning message in logfile and/or at console dependent of BrainStream verbosity level
>
>
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

10.5 Functions for manipulating runtime event processing

bs_insert_marker

Changed:
<
<
Insert marker(s) with specific time delay (t>=0)
>
>
Insert marker(s) with specific time delay (t>=0)
 
Changed:
<
<
Use as
event = bs_insert_marker(event,name,delaytime,priority)
>
>
Use as
event = bs_insert_marker(event,name,delaytime,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
Changed:
<
<
event BrainStream event structure
>
>
event BrainStream event structure
 
name name(s) of the marker (use cell array for multiple markers)
Changed:
<
<
delaytime time of insertion in seconds relative to actions own execution time (>=0), for multiple inserted markers, specify an array
>
>
delaytime time of insertion in seconds relative to actions own execution time (>=0), for multiple inserted markers, specify an array
 
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
Line: 239 to 215
  Provides several options to dynamically change BrainStreams processing.
Changed:
<
<
Use as
event = bs_change_processing(event,mod)
>
>
Use as
event = bs_change_processing(event,mod)
  Input
event BrainStream event structure
Line: 253 to 228
 
'FINISHEVENT' discard execution of any queued actions for this event
'ABORTAPPLICATION' immediately abort
Changed:
<
<
Output
modified event structure which informs BrainStream to change its processing
>
>
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

Revision 1610 Nov 2009 - Main.MarianneSeverens

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

10. FUNCTION INDEX

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

Input

Changed:
<
<
event BrainStream event structure
>
>
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
Line: 19 to 19
 Output
value content of requested key or default value if specified, otherwise an error is generated. Blocksettings structure if first argument is a filename
Changed:
<
<
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 both topic and key are empty, like as follows
result=bs_get_blockvalue(event,[],[])
the complete block settings structure is returned.
>
>
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 both topic and key are empty, like as follows
result=bs_get_blockvalue(event,[],[])
the complete block settings structure is returned.
 
Changed:
<
<
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.
>
>
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
Line: 72 to 72
 
tablevars if table includes table variables, specify content (under construction)

Output

Changed:
<
<
markers all info BrainStream requires for its internal processing
definition of all actions for all markers
>
>
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
Line: 95 to 95
 

10.2 Functions for debugging

bs_trace

Changed:
<
<
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.
>
>
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)
Line: 105 to 105
 event = bs_trace(event[,var],mod)

Input

Changed:
<
<
event BrainStream event structure
>
>
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
Line: 116 to 116
 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.
Changed:
<
<

10.3 Functions for directing BrainStream output to user defined locations

>
>

10.3 Functions for directing BrainStream output to user defined locations

 

bs_custom_out

Changed:
<
<
Customizes BrainStreams output. Users can customize locations where BrainStream stores output
>
>
Customizes BrainStreams output. Users can customize locations where BrainStream stores output
  Use as
event = bs_custom_out(event,mod,value)
Line: 143 to 143
 See also: bs_get_custom_out

value = bs_get_custom_out(event,mod) Options for mod:

Changed:
<
<
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
>
>
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
 

bs_get_custom_out

Changed:
<
<
Gets information about BrainStreams output locations
>
>
Gets information about BrainStreams output locations
  Use as
value = bs_get_custom_out(event,mod)
Line: 195 to 195
 
msg string with user message

Output

Changed:
<
<
user message in logfile and/or at console dependent of BrainStream verbosity level
>
>
user message in logfile and/or at console dependent of BrainStream verbosity level
  See also: bs_warn, bs_custom_out, bs_get_custom_out
Line: 254 to 254
 
'ABORTAPPLICATION' immediately abort

Output

Changed:
<
<
modified event structure which informs BrainStream to change its processing
>
>
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--->
Added:
>
>
<-- 
  • Access control
    • Set DENYTOPICVIEW =
-->

Revision 1505 Nov 2009 - Main.MarianneSeverens

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

10. FUNCTION INDEX

Revision 1403 Nov 2009 - Main.MarianneSeverens

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

10. FUNCTION INDEX

Line: 25 to 25
  See also: bs_block2text, bs_compose_expdef
Changed:
<
<

block2text

>
>

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.
Changed:
<
<
Use as lines = bs_block2text(input,toscreen) Input
>
>
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)
Changed:
<
<
<> use sprintf('%s',lines{:}) to print output again afterwards
>
>
use sprintf('%s',lines{:}) to print output again afterwards
  See also: bs_get_blockvalue, bs_compose_expdef
Deleted:
<
<
block2text(block,1)
 

bs_cond

Changed:
<
<
bs_cond(expression, opt_true, opt_false)
Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.
>
>
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

Changed:
<
<
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs,tablevars)
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
fs % acquisition sample rate.
tablevars % table variables (under construction)
>
>
This function can be used to expand an experiment definition table. 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,subfile,dataselection,fs)

Input

filename name of experiment definition table to be expanded
fs data source sample rate (default 256Hz)
tablevars if table includes table variables, specify content (under construction)

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)

For testing, in most cases [m,n,d,c,t] = bs_compose_expdef(filename) will be sufficient, all additional input arguments can be omitted.

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(file)

Input

file string with name of the datafile
 
Deleted:
<
<
Returns:
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the utilized cores (internal) and clients (another computer).
text % the expanded table in tab-delimited format. Copy to an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted. #TraceVars
 

10.2 Functions for debugging

bs_trace

Changed:
<
<
bs_trace([trace_vars,]variable,mod)
Purpose: Trace variables runtime content.
Use this function to add or remove variables to the list of traced variables, their content will be displayed in the logfile at the moment the variable is requested from BrainStream (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.
There are two ways to use this function:
>
>
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.
 
Changed:
<
<
1) bs_trace=($self,'variable','add') variable modifying-action applied to trace_vars
2) bs_trace('variable','add')) function-action
var: name of the variable, i.e., myvar or myvar.field
Options for mod:
'add', add variable to the list .
'remove', remove variable from the list.
'clear', remove all variables from the list.
>
>
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)
 
Changed:
<
<
Usage as modifying action in experiment definition table, ONLY applied to variable trace_vars !:
EXAMPLE1: bs_trace($self,'ToneCount','add')
EXAMPLE2: bs_trace($self,'hdr.channels','add')
EXAMPLE3: bs_trace($self,'clear') % clear all variables from trace_vars list
>
>
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
 
Changed:
<
<
Usage in a function list in experiment definition table
EXAMPLE1: bs_trace('ToneCount','add')
EXAMPLE2: bs_trace('hdr.channels','add')
EXAMPLE3: bs_trace('clear') % clear all variables from trace_vars 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.
 
Deleted:
<
<
Usage directly in some custom user function
EXAMPLE1: event=bs_trace(event,'ToneCount','add'), and possibly later:
EXAMPLE2: event=bs_trace(event,'ToneCount','remove')
EXAMPLE3: event=bs_trace(event,'hdr.channels','add')
EXAMPLE4: event=bs_trace(event,'clear') % clear all variables from trace_vars list
 

10.3 Functions for directing BrainStream output to user defined locations

bs_custom_out

Changed:
<
<
function event = bs_custom_out(event,mod,value)
Options for mod:
Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines 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
>
>
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

  value = bs_get_custom_out(event,mod) Options for mod:
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
Added:
>
>

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
'DISABLEOUTPUT' disabled (1) or enabled (0=default) output
'RUNFOLDER' folder with system related content
'BLOCKFOLDER' same as 'RUNFOLDER'
'SESSIONFOLDER' folder with session related content
'SUBJECTFOLDER' folder with subject related content
'EXPERIMENTFOLDER' folder with experiment related content

Output

value requested info, dependent of mod

See also: bs_custom_out

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

Use as
bs_disp(event,text)

Input

event BrainStream event structure
text string with text to output

See also: bs_cond

 

10.4 Functions for warnings and messages

bs_msg

Added:
>
>
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

 
Deleted:
<
<
event = bs_msg(event,txt) txt = message copied to logfile
 

bs_warn

Changed:
<
<
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output
>
>
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

 

10.5 Functions for manipulating runtime event processing

bs_insert_marker

Changed:
<
<
function event=bs_insert_marker(event,name,delaytime,priority)
Purpose: Insert any marker with specific time delay (t>=0)
event event structure
name name of the marker
delaytime execution delay in seconds relative to own time occurence
priority influences execution order; ’low’ (default) or set to ’high’ to force earlier execution than possible other markers' actions with equal execution time.
>
>
Insert marker(s) with specific time delay (t>=0)

Use as
event = bs_insert_marker(event,name,delaytime,priority)

Input

event BrainStream event structure
name name(s) of the marker (use cell array for multiple markers)
delaytime time of insertion in seconds relative to actions own execution time (>=0), for multiple inserted markers, specify an array
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_change_processing

Changed:
<
<
function event = bs_change_processing(event,mod)
Purpose: Change BrainStreams' internal scheduled marker processing.
event 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
>
>
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

 

Revision 1331 Oct 2009 - Main.PhilipVanDenBroek

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

10. FUNCTION INDEX

Line: 7 to 7
 

bs_get_blockvalue

Function to retrieve information from blocksettings file.
Changed:
<
<
Use as
1. value  =  bs_get_blockvalue(event, topic, key [,default]), or
2. value  =  bs_get_blockvalue(filename)
>
>
Use as
1. value = bs_get_blockvalue(event, topic, key [,default]), or
2. value = bs_get_blockvalue(filename)
 
Changed:
<
<
Input
>
>
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
Changed:
<
<
Output
>
>
Output
 
value content of requested key or default value if specified, otherwise an error is generated. Blocksettings structure if first argument is a filename
Changed:
<
<
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 both topic and key are empty, like as follows
result=bs_get_blockvalue(event,[],[])
the complete block settings structure is returned.
>
>
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 both topic and key are empty, like as follows
result=bs_get_blockvalue(event,[],[])
the complete block settings structure is returned.
 
Changed:
<
<
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.
>
>
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

block2text

Changed:
<
<
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.
>
>
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.
 
Changed:
<
<
Use as lines = bs_block2text(input,toscreen) Input
>
>
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)
Changed:
<
<
<> use sprintf('%s',lines{:}) to print output again afterwards
>
>
<> use sprintf('%s',lines{:}) to print output again afterwards
  See also: bs_get_blockvalue, bs_compose_expdef
Changed:
<
<
block2text(block,1)
>
>
block2text(block,1)
 

bs_cond

Changed:
<
<
bs_cond(expression, opt_true, opt_false)
Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.
>
>
bs_cond(expression, opt_true, opt_false)
Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.
 

bs_compose_expdef

Changed:
<
<
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs,tablevars)
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
fs % acquisition sample rate.
tablevars % table variables (under construction)
>
>
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs,tablevars)
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
fs % acquisition sample rate.
tablevars % table variables (under construction)
  Returns:
Changed:
<
<
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the utilized cores (internal) and clients (another computer).
text % the expanded table in tab-delimited format. Copy to an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted.
>
>
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the utilized cores (internal) and clients (another computer).
text % the expanded table in tab-delimited format. Copy to an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted. #TraceVars
 

10.2 Functions for debugging

Added:
>
>

bs_trace

 
Changed:
<
<
bs_trace([trace_vars,]variable,mod)
>
>
bs_trace([trace_vars,]variable,mod)
 
Purpose: Trace variables runtime content.
Use this function to add or remove variables to the list of traced variables, their content will be displayed in the logfile at the moment the variable is requested from BrainStream (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.
There are two ways to use this function:

1) bs_trace=($self,'variable','add') variable modifying-action applied to trace_vars
2) bs_trace('variable','add')) function-action

Line: 82 to 69
 
EXAMPLE1: event=bs_trace(event,'ToneCount','add'), and possibly later:
EXAMPLE2: event=bs_trace(event,'ToneCount','remove')
EXAMPLE3: event=bs_trace(event,'hdr.channels','add')
EXAMPLE4: event=bs_trace(event,'clear') % clear all variables from trace_vars list

10.3 Functions for directing BrainStream output to user defined locations

Changed:
<
<
function event = bs_custom_out(event,mod,value)
Options for mod:
Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines 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
>
>

bs_custom_out

function event = bs_custom_out(event,mod,value)
Options for mod:

Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines 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 = bs_get_custom_out(event,mod) Options for mod:
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
Line: 88 to 78
 
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.

10.4 Functions for warnings and messages

Added:
>
>
 
Changed:
<
<
event = bs_msg(event,txt) txt = message copied to logfile
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output
>
>

bs_msg

event = bs_msg(event,txt) txt = message copied to logfile

bs_warn

event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output

 

10.5 Functions for manipulating runtime event processing

Changed:
<
<
function event=bs_insert_marker(event,name,delaytime,priority)
Purpose: Insert any marker with specific time delay (t>=0)
event event structure
name name of the marker
delaytime execution delay in seconds relative to own time occurence
priority influences execution order; ’low’ (default) or set to ’high’ to force earlier execution than possible other markers' actions with equal execution time.
>
>

bs_insert_marker

function event=bs_insert_marker(event,name,delaytime,priority)

Purpose: Insert any marker with specific time delay (t>=0)
event event structure
name name of the marker
delaytime execution delay in seconds relative to own time occurence
priority influences execution order; ’low’ (default) or set to ’high’ to force earlier execution than possible other markers' actions with equal execution time.

bs_change_processing

 
Changed:
<
<
function event = bs_change_processing(event,mod)
>
>
function event = bs_change_processing(event,mod)
 
Purpose: Change BrainStreams' internal scheduled marker processing.
event 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

Revision 1228 Oct 2009 - Main.MoniekLijster

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

10. FUNCTION INDEX

Line: 63 to 63
  Returns:
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the utilized cores (internal) and clients (another computer).
text % the expanded table in tab-delimited format. Copy to an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted.
Changed:
<
<
>
>
 

10.2 Functions for debugging

bs_trace([trace_vars,]variable,mod)

Line: 88 to 88
 
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.

10.4 Functions for warnings and messages

Added:
>
>
  event = bs_msg(event,txt) txt = message copied to logfile
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output

10.5 Functions for manipulating runtime event processing

Revision 1127 Oct 2009 - Main.MarianneSeverens

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

10. PROGRAMMERS GUIDE

>
>

10. FUNCTION INDEX

 

10.1 General purpose functions

Changed:
<
<
bs_get_blockvalue
result = 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 both topic and key are empty, like as follows result=bs_get_blockvalue(event,[],[]) the complete block settings structure is returned.
>
>

bs_get_blockvalue

Function to retrieve information from blocksettings file.
 
Changed:
<
<
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.
>
>
Use as
1. value  =  bs_get_blockvalue(event, topic, key [,default]), or
2. value  =  bs_get_blockvalue(filename)
 
Changed:
<
<
block2text(block,1)
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.
>
>
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
 
Added:
>
>
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 both topic and key are empty, like as follows
result=bs_get_blockvalue(event,[],[])
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

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

block2text(block,1)

bs_cond

 bs_cond(expression, opt_true, opt_false)
Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.
Added:
>
>

bs_compose_expdef

 [markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs,tablevars)
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
fs % acquisition sample rate.
tablevars % table variables (under construction)

Revision 1023 Oct 2009 - Main.MarianneSeverens

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

10. PROGRAMMERS GUIDE

10.1 General purpose functions

Line: 53 to 54
 
Purpose: Change BrainStreams' internal scheduled marker processing.
event 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

\ No newline at end of file
Added:
>
>
<---End1--->
 \ No newline at end of file

Revision 919 Oct 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

Line: 9 to 9
 
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.

block2text(block,1)

Changed:
<
<
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.
>
>
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.
  bs_cond(expression, opt_true, opt_false)
Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.

Revision 819 Oct 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

Line: 14 to 14
 bs_cond(expression, opt_true, opt_false)
Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.
Changed:
<
<
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,subfile,dataselection,fs)
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
subfile % name of the starting sheet in case xls-file.
dataselection % name of the sheet defining markers with defined data epochs
fs % acquisition sample rate.
>
>
[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,fs,tablevars)
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
fs % acquisition sample rate.
tablevars % table variables (under construction)
  Returns:
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the utilized cores (internal) and clients (another computer).
text % the expanded table in tab-delimited format. Copy to an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted.
Line: 40 to 40
 

10.3 Functions for directing BrainStream output to user defined locations

function event = bs_custom_out(event,mod,value)
Options for mod:
Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines 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
Changed:
<
<
value = get_custom_out(event,mod) Options for mod:
>
>
value = bs_get_custom_out(event,mod) Options for mod:
 
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.

10.4 Functions for warnings and messages

Revision 716 Oct 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

Line: 38 to 38
 
EXAMPLE1: event=bs_trace(event,'ToneCount','add'), and possibly later:
EXAMPLE2: event=bs_trace(event,'ToneCount','remove')
EXAMPLE3: event=bs_trace(event,'hdr.channels','add')
EXAMPLE4: event=bs_trace(event,'clear') % clear all variables from trace_vars list

10.3 Functions for directing BrainStream output to user defined locations

Changed:
<
<
function event = bs_custom_out(event,mod,value)
Options for mod:
Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines name of the logfile
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
>
>
function event = bs_custom_out(event,mod,value)
Options for mod:
Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines 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
 
Changed:
<
<
value = get_custom_out(event,mod) Options for mod:
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
Retrieve abovementioned values.
>
>
value = get_custom_out(event,mod) Options for mod:
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
'LOGFILE', name of the logfile
'DATAFILE', name of the datafile (according to output folders, subject, session, and block information )
Retrieve abovementioned values.
 

10.4 Functions for warnings and messages

event = bs_msg(event,txt) txt = message copied to logfile
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output

Revision 615 Oct 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

Line: 38 to 38
 
EXAMPLE1: event=bs_trace(event,'ToneCount','add'), and possibly later:
EXAMPLE2: event=bs_trace(event,'ToneCount','remove')
EXAMPLE3: event=bs_trace(event,'hdr.channels','add')
EXAMPLE4: event=bs_trace(event,'clear') % clear all variables from trace_vars list

10.3 Functions for directing BrainStream output to user defined locations

Changed:
<
<
function event = bs_outfolder(event,mod,value)
Options for mod:
Purpose: Users can define where BrainStream stores output.
Different output storage levels can be defined, i.e. on the experiment, subject, session or run/block level. If nothing is specified, it will default to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings) for all these different output levels. ’RUNFOLDER’ user defines folder where platform can put system related content
’BLOCKFOLDER’ same as ’RUNFOLDER’
’SESSIONFOLDER’ user defines folder where platform can put session related content
’SUBJECTFOLDER’ user defines folder where platform can put subject related content
’EXPERIMENTFOLDER’ user defines folder where platform can put experiment related content
’LOGFILE’ user defines name of the logfile
’DISABLEOUTPUT’ user can disable any output by BrainStream
'MESSAGE' same as bs_msg()
'WARNING' same as bs_warn()
>
>
function event = bs_custom_out(event,mod,value)
Options for mod:
Purpose: Users can customize locations where BrainStream stores output.
’LOGFILE’ user defines name of the logfile
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 = get_custom_out(event,mod)
Changed:
<
<
Retrieve abovementioned values.
>
>
Options for mod:
Purpose: Users can retrieve information about where BrainStream stores output.
BrainStream uses different output storage levels, i.e. on the experiment, subject, session or run/block level. All folders will be created relative to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings).
’RUNFOLDER’, folder with system related content
’BLOCKFOLDER’, same as ’RUNFOLDER’
’SESSIONFOLDER’, folder with session related content
’SUBJECTFOLDER’, folder with subject related content
’EXPERIMENTFOLDER’, folder with experiment related content
Retrieve abovementioned values.
 

10.4 Functions for warnings and messages

event = bs_msg(event,txt) txt = message copied to logfile
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output
Line: 50 to 50
  function event=bs_insert_marker(event,name,delaytime,priority)
Purpose: Insert any marker with specific time delay (t>=0)
event event structure
name name of the marker
delaytime execution delay in seconds relative to own time occurence
priority influences execution order; ’low’ (default) or set to ’high’ to force earlier execution than possible other markers' actions with equal execution time.

function event = bs_change_processing(event,mod)

Changed:
<
<
Purpose: Change BrainStreams' internal scheduled marker processing.
event 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 (not recommended)
>
>
Purpose: Change BrainStreams' internal scheduled marker processing.
event 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
 

Revision 501 Sep 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

10.1 General purpose functions

Changed:
<
<
result = 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 both topic and key are empty, like as follows result=bs_get_blockvalue(event,[],[]), the complete block settings structure is returned.
>
>
bs_get_blockvalue
result = 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 both topic and key are empty, like as follows result=bs_get_blockvalue(event,[],[]) the complete block settings structure is returned.
  block = bs_get_blockvalue(block_file)
Changed:
<
<
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.
>
>
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.
  block2text(block,1)
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.
Line: 20 to 18
 
Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
subfile % name of the starting sheet in case xls-file.
dataselection % name of the sheet defining markers with defined data epochs
fs % acquisition sample rate.

Returns:

Changed:
<
<
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the number of required cores/clients.
text % the expanded table in tab-delimited format. Copy in an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted.
>
>
markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the utilized cores (internal) and clients (another computer).
text % the expanded table in tab-delimited format. Copy to an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted.
 

10.2 Functions for debugging

Changed:
<
<
bs_trace([trace_vars,]variable,mod)
>
>
bs_trace([trace_vars,]variable,mod)
 
Purpose: Trace variables runtime content.
Use this function to add or remove variables to the list of traced variables, their content will be displayed in the logfile at the moment the variable is requested from BrainStream (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.
There are two ways to use this function:

1) bs_trace=($self,'variable','add') variable modifying-action applied to trace_vars
2) bs_trace('variable','add')) function-action

Changed:
<
<
var: name of the variable, i.e., myvar or myvar.field Options for mod:
'add', add variable to the list .
'remove', remove variable from the list.
'clear', remove all variables from the list.
>
>
var: name of the variable, i.e., myvar or myvar.field
Options for mod:
'add', add variable to the list .
'remove', remove variable from the list.
'clear', remove all variables from the list.
  Usage as modifying action in experiment definition table, ONLY applied to variable trace_vars !:
EXAMPLE1: bs_trace($self,'ToneCount','add')
EXAMPLE2: bs_trace($self,'hdr.channels','add')
EXAMPLE3: bs_trace($self,'clear') % clear all variables from trace_vars list

Revision 431 Aug 2009 - Main.MoniekLijster

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

10. PROGRAMMERS GUIDE

10.1 General purpose functions

Changed:
<
<
>
>
 result = 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 both topic and key are empty, like as follows result=bs_get_blockvalue(event,[],[]), the complete block settings structure is returned.

Revision 323 Jun 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

Line: 24 to 24
 

10.2 Functions for debugging

Changed:
<
<
bs_trace([trace_vars,]variable,mod)
>
>
bs_trace([trace_vars,]variable,mod)
 
Purpose: Trace variables runtime content.
Use this function to add or remove variables to the list of traced variables, their content will be displayed in the logfile at the moment the variable is requested from BrainStream (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.
There are two ways to use this function:

1) bs_trace=($self,'variable','add') variable modifying-action applied to trace_vars
2) bs_trace('variable','add')) function-action

Line: 48 to 48
 

10.4 Functions for warnings and messages

event = bs_msg(event,txt) txt = message copied to logfile
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output
Changed:
<
<

10.3 Functions for manipulating runtime event processing

>
>

10.5 Functions for manipulating runtime event processing

  function event=bs_insert_marker(event,name,delaytime,priority)
Purpose: Insert any marker with specific time delay (t>=0)
event event structure
name name of the marker
delaytime execution delay in seconds relative to own time occurence
priority influences execution order; ’low’ (default) or set to ’high’ to force earlier execution than possible other markers' actions with equal execution time.

function event = bs_change_processing(event,mod)

Revision 219 Jun 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

Added:
>
>
 

10.1 General purpose functions

result = bs_get_blockvalue(event, topic, key, default)

Revision 119 Jun 2009 - Main.PhilipVanDenBroek

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

10. PROGRAMMERS GUIDE

10.1 General purpose functions

result = 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 both topic and key are empty, like as follows result=bs_get_blockvalue(event,[],[]), the complete block settings structure is returned.

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.

block2text(block,1)

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.

bs_cond(expression, opt_true, opt_false)

Purpose: use this function as a modifying action to set content of variables to one of two specified options ( opt_true or opt_false) dependent of whether expression is true or false.

[markers, names, dictionary, clients, text] = bs_compose_expdef(filename,subfile,dataselection,fs)

Purpose: use this function to test if your experiment definition table will be expanded correctly or to verify if all actions for all markers are correctly defined.
Input arguments:
filename % name of the experiment definition table to be expanded.
subfile % name of the starting sheet in case xls-file.
dataselection % name of the sheet defining markers with defined data epochs
fs % acquisition sample rate.

Returns:

markers % definition of all actions for all markers.
names % a list of all marker names defined.
dictionary % dictionary to translate marker type and value to marker name.
clients % in case parallel execution is required, it specifies the number of required cores/clients.
text % the expanded table in tab-delimited format. Copy in an empty xls-worksheet to get a complete overview of all markers' actions.
In most cases [m,n,d,c,t] = bs_compose(filename) will be sufficient, all additional input arguments can be omitted.

10.2 Functions for debugging

bs_trace([trace_vars,]variable,mod)

Purpose: Trace variables runtime content.
Use this function to add or remove variables to the list of traced variables, their content will be displayed in the logfile at the moment the variable is requested from BrainStream (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.
There are two ways to use this function:

1) bs_trace=($self,'variable','add') variable modifying-action applied to trace_vars
2) bs_trace('variable','add')) function-action

var: name of the variable, i.e., myvar or myvar.field Options for mod:
'add', add variable to the list .
'remove', remove variable from the list.
'clear', remove all variables from the list.

Usage as modifying action in experiment definition table, ONLY applied to variable trace_vars !:

EXAMPLE1: bs_trace($self,'ToneCount','add')
EXAMPLE2: bs_trace($self,'hdr.channels','add')
EXAMPLE3: bs_trace($self,'clear') % clear all variables from trace_vars list

Usage in a function list in experiment definition table

EXAMPLE1: bs_trace('ToneCount','add')
EXAMPLE2: bs_trace('hdr.channels','add')
EXAMPLE3: bs_trace('clear') % clear all variables from trace_vars list

Usage directly in some custom user function

EXAMPLE1: event=bs_trace(event,'ToneCount','add'), and possibly later:
EXAMPLE2: event=bs_trace(event,'ToneCount','remove')
EXAMPLE3: event=bs_trace(event,'hdr.channels','add')
EXAMPLE4: event=bs_trace(event,'clear') % clear all variables from trace_vars list

10.3 Functions for directing BrainStream output to user defined locations

function event = bs_outfolder(event,mod,value)
Options for mod:
Purpose: Users can define where BrainStream stores output.
Different output storage levels can be defined, i.e. on the experiment, subject, session or run/block level. If nothing is specified, it will default to the obligatory defined outfolder (topic 'Files', key 'OutFolder' in block settings) for all these different output levels. ’RUNFOLDER’ user defines folder where platform can put system related content
’BLOCKFOLDER’ same as ’RUNFOLDER’
’SESSIONFOLDER’ user defines folder where platform can put session related content
’SUBJECTFOLDER’ user defines folder where platform can put subject related content
’EXPERIMENTFOLDER’ user defines folder where platform can put experiment related content
’LOGFILE’ user defines name of the logfile
’DISABLEOUTPUT’ user can disable any output by BrainStream
'MESSAGE' same as bs_msg()
'WARNING' same as bs_warn()

value = get_custom_out(event,mod)

Retrieve abovementioned values.

10.4 Functions for warnings and messages

event = bs_msg(event,txt) txt = message copied to logfile
event = bs_warn(event,txt) txt = warning copied to logfile and optional standard output

10.3 Functions for manipulating runtime event processing

function event=bs_insert_marker(event,name,delaytime,priority)
Purpose: Insert any marker with specific time delay (t>=0)
event event structure
name name of the marker
delaytime execution delay in seconds relative to own time occurence
priority influences execution order; ’low’ (default) or set to ’high’ to force earlier execution than possible other markers' actions with equal execution time.

function event = bs_change_processing(event,mod)

Purpose: Change BrainStreams' internal scheduled marker processing.
event 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 (not recommended)

 
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