BrainStreamRunningExperiments - Revision history

Wiki-admin at 13:29, 21 September 2018

2018-09-21T13:29:25Z

Wiki-admin: Created page with " =Running Experiments = TOC When you have created all the [.DocsSectionsBuildingExperiments necessary files] for your experiment, you can run your experime..."

2018-09-21T10:47:57Z

Created page with " =Running Experiments = __TOC__ When you have created all the [.DocsSectionsBuildingExperiments necessary files] for your experiment, you can run your experime..."

New page

=Running Experiments =
__TOC__

When you have created all the [.DocsSectionsBuildingExperiments necessary files] for your experiment, you can run your experiment via BrainStream's [.DocsSectionsGlossary#SecG Grapical User Interface (GUI)].
== Startup of the BrainStream GUI ==

The BrainStream GUI can be opened from Matlab with the command <tt>start_brainstream</tt>. If the startup function is used without any input arguments, a popup window will appear containing a list of recently opened experiment files. You can select an experiment from this list or press cancel and select another experiment file via the GUI.

Alternatively, the startup function can be used with one or more input arguments. The settings that can be specified by means of these input arguments can also be selected in the GUI after startup. The following input arguments have to be entered as type [.DocsSectionsGlossary#SecS 'string'].

<pre>start_brainstream(block_file [,path_fnc, bfiles_path, com_bfiles_path]) </pre>

<tt>block_file</tt>: filename of a [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk) or [.DocsSectionsBuildingExperiments#SecProjectFile BrainStream Project file] (.bsp or .exp). Include (relative) path name or make sure it can be found on the Matlab path.<br /> <tt>path_fnc</tt> (optional): function that handles setting Matlab path. In general, it is recommended to specify this function in the block file (see [.DocsSectionsBlockFile#TopicExperiment here]) rather than via this input argument.<br /> <tt>bfiles_path</tt> (optional): starting folder for browsing block files<br /> <tt>com_bfiles_path</tt> (optional): starting folder for browsing common block files

<div id="BrainStreamGUI"></div>
== Using the BrainStream GUI ==

If no block or experiment file is specified during startup of the GUI, the GUI will be empty:

[[File:DocsSectionsRunningExperiments_GUI_screenshot1.png|452px|503x]]

''Figure 1: GUI before experiment specification''

You can load your experiment files by clicking on the 'Browse exp.def.files' button and selecting your experiment file (.bsp or .exp). All block files and common block files included in this experiment will be loaded. Alternatively, you can add block files and common block files manually (block files via 'Browse exp.def.files' and common block files via 'Browse common block files').

Based on information in the (common) block files, other fields of the GUI will be filled in automatically:

[[File:DocsSectionsRunningExperiments_GUI_screenshot2_numbered.png|447px|500x]]

''Figure 2: GUI after experiment specification''

1. All block files and common block files included in the experiment are listed in the top right part of the GUI. You can select one of the block files by clicking on it. The information in other fields of the GUI shows the settings specified in the currently selected block file.

2. In the Experiment section of the GUI, the datasource, the name of the block, the sample rate and the location of the [.DocsSectionsBuildingExperiments#SecExpDef experiment definition table] are obtained from the block files. A subject's name must be entered manually.

3. Information in the Files section is also automatically obtained from the block files, but can be changed manually by clicking on the buttons on the right. The Out folder is the folder where the recorded data will be saved.

4. The block settings of the selected block file are shown in the bottom part of the GUI, where the can be changed. Note that the changed settings will be used when the experiment is started. In this part of the GUI, you can also view Log info, which shows the Log file of the experiment, and Warning info, which shows a list of warning messages.

5. You can start the experiment by clicking on the Start button at the bottom. You can end the experiment with either the Quit or Exit button. Clicking the Quit button is equivalent to inserting the BS_QUIT marker and clicking the Exit button is equivalent to inserting the BS_EXIT marker (for more information about these markers, click [[DocsSectionsReservedNames#ResMarkers|here]]). In the bottom right corner of the GUI, you can specify the amount of output that is displayed on the screen during the experiment. You can also specify this amount in the block file under topic RunMode and key screenoutputlevel. For more information about the different levels of screen output, click [.DocsSectionsBlockFile#KeyScreenOutput here].

<div id="NoGui"></div>
== Command window startup (no GUI) ==

It is also possible to use BrainStream without the GUI. BrainStream can be started from the Matlab command window using the following function:

<tt>start_brainstream_nogui(block_file [,subject,user_folders])</tt>

<tt>block_file:</tt> filename of a [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk). Include ([.DocsSectionsPathsFolders#RelativePath relative]) path name or make sure it can be found on the [.DocsSectionsPathsFolders#AddFolders Matlab path]. If more than one (common) block file is required, specify a cell array of block files in order of relevance (settings of block files that appear earlier in this list will overwrite the same settings specified in subsequently listed block files).<br /> <tt>subject (optional):</tt> name of the subject (default = 'test')<br /> <tt>user_folders (optional):</tt> cell array with [.DocsSectionsPathsFolders paths] you need for the experiment. If you need several folders on your Matlab path, you can enter them as a cell array.

The following example shows the command for starting the block bci_example1 for a subject called 'subject'. In addition, folders containing code for cap montage and artefact detection are added to the Matlab path:<br /> <tt>start_brainstream_nogui('bci_example1.blk','subject',{/Volumes/MyCode/CapMontage,/Volumes/MyCode/EpochArtifacts})</tt>.

BrainStream can also be started without the GUI with the function

<tt>brainstream_block(blocksettings)</tt>.

The argument 'blocksettings' needs to be available as a Matlab type structure variable. Topics from the block file become fields of this structure and keys become subfields of these fields. You can obtain the blocksettings in two ways:
# Translate an existing block file into the blocksettings structure using the function <tt>blocksettings = bs_get_blockvalue(blockfile)</tt>, where blockfile is the name of your [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk).
# Manually generate a blocksettings structure. The following example contains the minimally required items to start BrainStream without the GUI:
<pre>
blocksettings.DataSources.eeg = 'buffer://localhost:1972:my_device';
blocksettings.RunMode.Subject = 'a_subjects_name';
blocksettings.Files.ReferenceFolder = '/Volumes/exps/defs/my_project/';
blocksettings.Files.ExperimentDefinitionFile = '/Volumes/exps/defs/my_project/my_block.edt';
blocksettings.Files.OutFolder = '/Volumes/data/my_project/';
blocksettings.Experiment.Block = 'my_block';
</pre>

The block settings <tt>RunMode.Subject</tt> and <tt>Files.Referencefolder</tt> are only required when BrainStream is started without the GUI. If the GUI is used, these settings are automatically included.

<div id="InsertMarkers"></div>
== Manually inserting markers during the experiment ==

You have the option to manually insert markers while your experiment is running. This can be useful in the design and test stages of your experiment, as it allows you to for example trigger or skip the execution of certain functions.

During your experiment, a window will appear containing a list with the names of all markers that are used in your experiment:

[[File:DocsSectionsRunningExperiments_InsertMarkers_screenshot.png|437px|347x]]

''Figure 3: Insert markers menu''

You can insert a marker simply by selecting it and clicking the 'Insert selected markers' button.

@@ Line 3: / Line 3: @@
 __TOC__
-When you have created all the [.DocsSectionsBuildingExperiments necessary files] for your experiment, you can run your experiment via BrainStream's [.DocsSectionsGlossary#SecG Grapical User Interface (GUI)].
+When you have created all the [[BrainStreamBuildingExperiments|necessary files]] for your experiment, you can run your experiment via BrainStream's [[BrainStreamGlossary#SecG|Grapical User Interface (GUI)]].
 == Startup of the BrainStream GUI ==
 The BrainStream GUI can be opened from Matlab with the command <tt>start_brainstream</tt>. If the startup function is used without any input arguments, a popup window will appear containing a list of recently opened experiment files. You can select an experiment from this list or press cancel and select another experiment file via the GUI.
-Alternatively, the startup function can be used with one or more input arguments. The settings that can be specified by means of these input arguments can also be selected in the GUI after startup. The following input arguments have to be entered as type [.DocsSectionsGlossary#SecS 'string'].
+Alternatively, the startup function can be used with one or more input arguments. The settings that can be specified by means of these input arguments can also be selected in the GUI after startup. The following input arguments have to be entered as type [[BrainStreamGlossary#SecS|'string']].
 <pre>start_brainstream(block_file [,path_fnc, bfiles_path, com_bfiles_path]) </pre>
-<tt>block_file</tt>: filename of a [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk) or [.DocsSectionsBuildingExperiments#SecProjectFile BrainStream Project file] (.bsp or .exp). Include (relative) path name or make sure it can be found on the Matlab path.<br /> <tt>path_fnc</tt> (optional): function that handles setting Matlab path. In general, it is recommended to specify this function in the block file (see [.DocsSectionsBlockFile#TopicExperiment here]) rather than via this input argument.<br /> <tt>bfiles_path</tt> (optional): starting folder for browsing block files<br /> <tt>com_bfiles_path</tt> (optional): starting folder for browsing common block files
+<tt>block_file</tt>: filename of a [[BrainStreamBuildingExperiments#SecBlock|block file]] (.blk) or [[BrainStreamBuildingExperiments#SecProjectFile|BrainStream Project file]] (.bsp or .exp). Include (relative) path name or make sure it can be found on the Matlab path.<br /> <tt>path_fnc</tt> (optional): function that handles setting Matlab path. In general, it is recommended to specify this function in the block file (see [[BlockFile#TopicExperiment|here]]) rather than via this input argument.<br /> <tt>bfiles_path</tt> (optional): starting folder for browsing block files<br /> <tt>com_bfiles_path</tt> (optional): starting folder for browsing common block files
 <div id="BrainStreamGUI"></div>
@@ Line 33: / Line 33: @@
 . All block files and common block files included in the experiment are listed in the top right part of the GUI. You can select one of the block files by clicking on it. The information in other fields of the GUI shows the settings specified in the currently selected block file.
-. In the Experiment section of the GUI, the datasource, the name of the block, the sample rate and the location of the [.DocsSectionsBuildingExperiments#SecExpDef experiment definition table] are obtained from the block files. A subject's name must be entered manually.
+. In the Experiment section of the GUI, the datasource, the name of the block, the sample rate and the location of the [[BrainStreamBuildingExperiments#SecExpDef|experiment definition table] are obtained from the block files. A subject's name must be entered manually.
 . Information in the Files section is also automatically obtained from the block files, but can be changed manually by clicking on the buttons on the right. The Out folder is the folder where the recorded data will be saved.
@@ Line 39: / Line 39: @@
 . The block settings of the selected block file are shown in the bottom part of the GUI, where the can be changed. Note that the changed settings will be used when the experiment is started. In this part of the GUI, you can also view Log info, which shows the Log file of the experiment, and Warning info, which shows a list of warning messages.
-. You can start the experiment by clicking on the Start button at the bottom. You can end the experiment with either the Quit or Exit button. Clicking the Quit button is equivalent to inserting the BS_QUIT marker and clicking the Exit button is equivalent to inserting the BS_EXIT marker (for more information about these markers, click [[DocsSectionsReservedNames#ResMarkers|here]]). In the bottom right corner of the GUI, you can specify the amount of output that is displayed on the screen during the experiment. You can also specify this amount in the block file under topic RunMode and key screenoutputlevel. For more information about the different levels of screen output, click [.DocsSectionsBlockFile#KeyScreenOutput here].
+. You can start the experiment by clicking on the Start button at the bottom. You can end the experiment with either the Quit or Exit button. Clicking the Quit button is equivalent to inserting the BS_QUIT marker and clicking the Exit button is equivalent to inserting the BS_EXIT marker (for more information about these markers, click [[DocsSectionsReservedNames#ResMarkers|here]]). In the bottom right corner of the GUI, you can specify the amount of output that is displayed on the screen during the experiment. You can also specify this amount in the block file under topic RunMode and key screenoutputlevel. For more information about the different levels of screen output, click [[BrainStreamBlockFile#KeyScreenOutput|here]].
 <div id="NoGui"></div>
@@ Line 48: / Line 48: @@
 <tt>start_brainstream_nogui(block_file [,subject,user_folders])</tt>
-<tt>block_file:</tt> filename of a [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk). Include ([.DocsSectionsPathsFolders#RelativePath relative]) path name or make sure it can be found on the [.DocsSectionsPathsFolders#AddFolders Matlab path]. If more than one (common) block file is required, specify a cell array of block files in order of relevance (settings of block files that appear earlier in this list will overwrite the same settings specified in subsequently listed block files).<br /> <tt>subject (optional):</tt> name of the subject (default = 'test')<br /> <tt>user_folders (optional):</tt> cell array with [.DocsSectionsPathsFolders paths] you need for the experiment. If you need several folders on your Matlab path, you can enter them as a cell array.
+<tt>block_file:</tt> filename of a [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk). Include ([[BrainStreamPathsFolders#RelativePath|relative]]) path name or make sure it can be found on the [[BrainStreamPathsFolders#AddFolders|Matlab path]]. If more than one (common) block file is required, specify a cell array of block files in order of relevance (settings of block files that appear earlier in this list will overwrite the same settings specified in subsequently listed block files).<br /> <tt>subject (optional):</tt> name of the subject (default = 'test')<br /> <tt>user_folders (optional):</tt> cell array with [[BrainStreamPathsFolders|paths]] you need for the experiment. If you need several folders on your Matlab path, you can enter them as a cell array.
 The following example shows the command for starting the block bci_example1 for a subject called 'subject'. In addition, folders containing code for cap montage and artefact detection are added to the Matlab path:<br /> <tt>start_brainstream_nogui('bci_example1.blk','subject',{/Volumes/MyCode/CapMontage,/Volumes/MyCode/EpochArtifacts})</tt>.
@@ Line 57: / Line 57: @@
 The argument 'blocksettings' needs to be available as a Matlab type structure variable. Topics from the block file become fields of this structure and keys become subfields of these fields. You can obtain the blocksettings in two ways:
-# Translate an existing block file into the blocksettings structure using the function <tt>blocksettings = bs_get_blockvalue(blockfile)</tt>, where blockfile is the name of your [.DocsSectionsBuildingExperiments#SecBlock block file] (.blk).
+# Translate an existing block file into the blocksettings structure using the function <tt>blocksettings = bs_get_blockvalue(blockfile)</tt>, where blockfile is the name of your [[BrainStreamBuildingExperiments#SecBlock|block file]] (.blk).
 # Manually generate a blocksettings structure. The following example contains the minimally required items to start BrainStream without the GUI:
 <pre>

BrainStreamRunningExperiments - Revision history

Wiki-admin at 13:29, 21 September 2018

Wiki-admin: Created page with " =Running Experiments = __TOC__ When you have created all the [.DocsSectionsBuildingExperiments necessary files] for your experiment, you can run your experime..."

Wiki-admin: Created page with " =Running Experiments = TOC When you have created all the [.DocsSectionsBuildingExperiments necessary files] for your experiment, you can run your experime..."