Changes

Jump to: navigation, search

BrainStreamExampleSentences

28 bytes removed, 12:21, 26 September 2018
no edit summary
== Building the experiment ==
As described in the [.DocsSectionsBuildingExperiments [BrainStreamBuildingExperiments Building |Experiments]] section, a number of files are needed to define an experiment. In the following, we will show how to create each of these files. If you want to have a look at the final result before reading this tutorial, the experiment file (.exp) for this example can be found in <tt>/brainstream_mds/examples/blocks/sentences/sentences.exp</tt>.
<div id="BrainStream.[[DocsSectionsBlockFile]]"></div>
=== Creating the block file ===
This experiment consists of only one block (sentences.blk). A number of settings are specified in the [.DocsSectionsBuildingExperiments[BrainStreamBuildingExperiments#SecBlock |block file]]:
<pre>[DataSources]
eeg = 'simulate:biosemi_active2';
[Files]
[[ExperimentDefinitionFile|Experiment Definition File]] = 'sentences.edt';[[OutFolder|Out Folder]] = '../output/sentences/';
[Experiment]
Block = 'sentences';
[[MatlabPathFnc|Matlab Path Fnc]] = [];[[MatlabPathAdd|Matlab Path Add]] = {fullfile(bs_folder('BLOCK'),'..','common_functions'),bs_folder('BLOCK')};
</pre>
You can look up the meaning of the topic and key combinations [.DocsSectionsBlockFile [BrainStreamBlockFile|here]].
Note that for the keys that specify folders, such as OutFolder and MatlabPathAdd, relative path names are specified. For more information about relative path names, click [.DocsSectionsPathsFolders[BrainStreamPathsFolders#RelativePath |here]].
In addition to the standard topics and keys, we can specify our own settings in the block file. In this example, it would be useful to specify in the block file which sentences we want to show. We could for example define a key StimSequence under topic Experiment:
<pre>[Experiment][[StimSequence|Stim Sequence]] = {'Making BCIs','is really fun!'};
</pre>
The information specified in the block file can be retrieved during the experiment using the [.DocsSectionsProgrmmersGuide[BrainStreamProgrmmersGuide#GetBlockVal |bs_get_blockvalue]] function. In the next section we will show exactly how this works. The advantage of specifying the sentences in the block file is that we can use the same Actions table for displaying any sentence.
=== Creating the Actions Table ===
# before each sequence, decide whether to start a new sequence or end the experiment
# before each epoch, decide whether to start a new epoch or end the sequence
We will write [.DocsSectionsBuildingExperiments[BrainStreamBuildingExperiments#SecUserFun |user defined functions]] for making these decisions.
In order to be able to make each decision, we also need to:
# within each sequence, keep track of how many epochs we have shown so far
We will make use of [.DocsSectionsBuildingExperiments[BrainStreamBuildingExperiments#SecUserFun |user defined variables]] for these tasks.
The [.DocsSectionsBuildingExperiments[BrainStreamBuildingExperiments#SecActions |Actions table]] has three standard columns ''marker, time'' and ''function''. In addition, we will add three columns for our user defined variables. The first user variable, ''stimsequence'', will contain the sequences that we want to show. The second user variable,<em> sequence_count</em>, will keep track of the number of sequences that have been shown already. The third user variable, ''epoch_count'', will keep track how many epochs of a sequence have been shown already. These are the columns of the Actions table:{| borderclass="1wikitable"
|-
| '''marker''' || '''time''' || '''function''' || '''stimsequence''' || '''sequence_count''' || '''epoch_count'''
|-
| || | || | ||
 
|}
|-
| BS_INIT || EVENT || | [] || 0 || []
 
|}
Information specified in the block file can be retrieved during the experiment using the [.DocsSectionsProgrmmersGuide[BrainStreamProgrmmersGuide#GetBlockVal |bs_get_blockvalue]] function. At the BS_INIT marker, we will insert the marker init_sequence. As this marker does not need to be accurately synchronized with the data, we insert this marker [.DocsSectionsMarkerHandling[BrainStreamMarkerHandling#BufferMarker |via the !FieldTrip buffer]]. When the init_sequence marker arrives, we will execute a user defined function <tt>initSequence</tt> to retrieve the content of ''stimsequence'' from the block file and place it in the [.DocsSectionsImportantConcepts[BrainStreamImportantConcepts#SecVariables |global variables]].{| borderclass="1wikitable"
|-
| '''<strong>marker</strong>''' || '''<strong>time</strong>''' || '''<strong>function</strong>''' || '''<strong>stimsequence</strong>''' || '''<strong>sequence_count</strong>''' || '''<strong>epoch_count</strong>'''
|-
| <strong>init_sequence <br /></strong> || <strong>EVENT <br /></strong> || <strong>initSequence <br /></strong> || <strong>put </strong> || |
 
|}
Now we can proceed to the next step in the flowchart, the point where we need to decide whether to start a new sequence. Using the bs_send_buffer_marker function, we will insert a marker next_sequence to begin this next stage of the experiment. When this marker comes in, first the sequence counter must be increased by 1:
{| borderclass="1wikitable"
|-
| '''<strong>marker</strong>''' || '''<strong>time</strong>''' || '''<strong>function</strong>''' || '''<strong>stimsequence</strong>''' || '''<strong>sequence_count</strong>''' || '''<strong>epoch_count</strong>'''
| BS_INIT || EVENT || bs_send_buffer_marker('init_sequence','eeg',0,'now') || [] || 0 || []
|-
| init_sequence || EVENT || initSequence || put ||| |
|-
| | || | <strong>bs_send_buffer_marker('next_sequence','eeg',0,'now')</strong> ||| | ||
|-
| <strong>next_sequence</strong> || <strong>EVENT</strong> ||| | || <strong>$self+1</strong> ||
|}
Subsequently, we need to write a function that uses the content of ''stimsequence'' and the current value of ''sequence_count'' to decide whether to start a new sequence. We will call this function <tt>nextSequence</tt>. Because the function needs the content of two of our variables as input, we must specify get statements for these variables.
{| borderclass="1wikitable"
|-
| '''<strong>marker</strong>''' || '''<strong>time</strong>''' || '''<strong>function</strong>''' || '''<strong>stimsequence</strong>''' || '''<strong>sequence_count</strong>''' || '''<strong>epoch_count</strong>'''
| BS_INIT || EVENT || bs_send_buffer_marker('init_sequence','eeg',0,'now') || [] || 0 || []
|-
| init_sequence || EVENT || initSequence || put ||| |
|-
| | || | bs_send_buffer_marker('next_sequence','eeg',0,'now') ||| | ||
|-
| next_sequence || EVENT || <strong>nextSequence</strong> || <strong>get</strong> || $self+1, <strong>get</strong> ||
| init_sequence || EVENT || initSequence || put || |
|-
| | || | bs_send_buffer_marker('next_sequence','eeg',0,'now') ||| | ||
|-
| next_sequence || EVENT || nextSequence || get || $self+1, get ||
| <strong>start_sequence</strong> || <strong>button_1</strong> || <strong>displayString('')</strong> || <strong>get</strong> || <strong>get</strong> || <strong>0</strong>
|-
| | || | <strong>bs_send_buffer_marker('next_epoch','eeg',0,'now')</strong> ||| | ||
|}
| init_sequence || EVENT || initSequence || put || |
|-
| | || | bs_send_buffer_marker('next_sequence','eeg',0,'now') ||| | ||
|-
| next_sequence || EVENT || nextSequence || get || $self+1, get ||
| start_sequence || button_1 || displayString('') || get || get || 0
|-
| | || | bs_send_buffer_marker('next_epoch','eeg',0,'now') || | ||
|-
| <strong>next_epoch</strong> || <strong>EVENT</strong> || <strong>nextEpoch</strong> || <strong>get</strong> || <strong>get</strong> || <strong>$self+1, get</strong>
event = bs_send_buffer_marker(event,'end_sequence','eeg',0,'now'); % end the sequence
end
</pre>If the outcome of the decision is that another character should be displayed, the marker proc_epoch will be inserted. As we want to use this marker for data selection (see [.DocsSectionsExampleSentences[BrainStreamExampleSentences#DataSelection |next section]), accurate synchronization between marker and data is required. Therefore, we will insert this marker [.DocsSectionsMarkerHandling[BrainStreamMarkerHandling#HardwareMarker |via the hardware]. When this marker arrives, the displayString function will be used to show the current character. After this has been done, we insert the next_epoch marker and thereby return to the question whether to start another epoch. The next_epoch marker is inserted 0.25 seconds after the bs_send_buffer_marker function is called. As a result, there is a pause of approximately 0.25 seconds between the appearance of each character on the screen.
{| border="1"
| init_sequence || EVENT || initSequence || put || |
|-
| | || | bs_send_buffer_marker('next_sequence','eeg',0,'now') ||| | ||
|-
| next_sequence || EVENT || nextSequence || get || $self+1, get ||
| start_sequence || button_1 || displayString('') || get || get || 0
|-
| | || | bs_send_buffer_marker('next_epoch','eeg',0,'now') ||| | ||
|-
| next_epoch || EVENT || nextEpoch || get || get || $self+1, get
|-
| <strong>proc_epoch</strong> || <strong>EVENT</strong> || <strong>displayString()</strong> ||| | ||
|-
| | || | <strong>bs_send_buffer_marker('next_epoch','eeg',0.25,'now')</strong> ||| | ||
|}

Navigation menu