8 EXAMPLES

Getting started

Connect to specific hardware setups

Biosemi Active2 EEG amplifier

To use BrainStream? with the BioSemi Active2 EEG amplifier, the block file should contain the following.

[RunMode]
BrainStream.DataSource = 'BioSemiAcq' 
[Biosemi_Active2]
BrainStream.ConfigureFunction = 'configureBiosemiAcq'
BrainStream.ActiviewConfigFile = 'Actiview.cfg'
Host = 'hostname' % 
Port = '5050'

In Biosemi's acquisition software (Actiview) it should be specified which channels and at which sample rate EEG data is sent to a remote client. The tricky part is to inform BrainStream? about what will be received from Actiview. A safer solution is to reverse the approach and change Activiews configuration file before starting Actiview. BrainStream? gives the opportunity to specify a user function ( !ConfigureFunction) that could handle this before BrainStream? is making the connection to Actiview. The !ActiviewConfigFile is an Actiview configuration file that can be saved from the Actiview software environment. The user function then only needs to copy this file to the folder from where Actiview loads its configuration files and rename it to default.cfg. At startup, Actiview will then load this configuration file with your required settings. Make sure your custom user function waits for a button press to confirm Actiview is ready to send data on to the network. Then, BrainStream? will read the same configuration file for the header information and make the connection to Actiview starting receiving and buffering incoming data from Actiview. Host and port settings should specify the name of the computer running Actiview. The port setting should match the port setting in the Actiview software.

Currently, the Active2 status channel is interpreted as follows: lowest byte will produce markers of type 'stimulus' and value according to its 8-bits numerical byte presentation (##). The next 8 bits (the middle one of the 3 bytes sized data) will produce 'response' markers with value according to its corresponding numerical byte presentation (##).

marker type value
stimmrk1 stimulus ##
respmrk1 response ##

The highest byte represents status information and will produce the following markers:

marker type value
battery_ok Battery_ok -64
cmsense_fail CM_out_of_range -16
new_epoch Epoch -1
end-epoch Epoch_end 1
cmsense_ok CM_in_range 16
battery_low Battery_low 64
loose_triggerport loose_Triggerport 255

These tables are examples of dictionaries that associates incoming marker information ( type and value) with marker names. It is the users responsibility to define meaningful actions for these markers. Current interpretation of the status channel implies that maximal 255 'stimulus' markers and 255 'response' markers can be defined since value can have values in the range 1 to 255. The highest byte of the status channel can not be modified (trigger input is limited to the lower 16 bits or 2 bytes) and those markers are determined by Actiview.

Dependent on how the amplifiers trigger input port is being used, the dictionaries should connect names with incoming markers as is shown in the tables. Every possible marker from the Active2 amplifier should be connected with a marker name using the dictionary tables. Connecting actions to these markers enables you to define your experiment. Read the Getting Started section to learn more about defining experiments with BrainStream? in general.

CTF MEG system

This example assumes a specific setup as described here, using the fieldtrip realtime buffer. BrainStream? will receive data and events from this buffer. As a starting point the following block file and experiment definition file demonstrate how BrainStream? can be used to define your own experiment for the MEG setup.

Block file (my_meg_experiment.blk):

[RunMode]
BrainStream.DataSource = 'buffer://hostname:1972';
[Files]
BrainStream.ExperimentDefinitionFile = 'my_meg_experiment.xls'
BrainStream.OutFolder = [tempdir 'output'] % change to custom output folder
[Experiment]
Block = 'my_meg_experiment'
BrainStream.MatlabPathAdd = {'/volumes/pathtomyfunctions/'}

The experiment definition (my_meg_experiment.xls) involves data processing being triggered by the process_data marker. Associated actions will process the data and corresponding results are maintained in the myvar variable.

marker time function hdr myvar
BS_INIT EVENT get,put []
process_data DATA func1, func2 get get, put

This example assumes marker process_data to be associated with a certain event from the fieldtrip buffer. In the Dictionary table this will look like:

marker type value
process_data stimulus xx

Appropriate content for type and value should be provided in the dictionary dependent of the way the fieldtrip buffer sends marker information through the buffer to BrainStream. BrainStream? filters incoming events based on the markers defined in an experiment, in other words, unknown typed events will never get into BrainStream? since they wouldn't be recognized anyway (there are no actions associated with such events).

Requested data for this event can be defined in the DataSelection table:

marker begintime endtime
process_data 0 1

Read the Getting Started section in order to learn how to define entire experiments using BrainStream. In the plugins folder of the demo distribution of BrainStream, an example will be included which demonstrates how to view data coming from the CTF system.

Architecture

Answer at end of sequence propagates into all corresponding trial events

In this example the answer_1 marker initializes the CorrectAnswer to one. After a certain time given to answer, the end_of_waiting marker initiates the modification of the variables CorrectAnswered, NumCorrect and NumWrong based on the content of CorrectAnswer and Answer, which were already modified by actions coupled to markers answer_1 and button_x. Based on CorrectAnswered feedback is then given to the subject. The content of these variables are handed over to the end_of_waiting marker because of the specified ‘get’ keywords. The function bs_cond would be something like:

          function result = bs_cond(condition,val_true,val_false)
          if condition
               result = val_true;
          else
               result = val_false;
          end

slice_module_answer_1.gif Table 2a: main table; an example of an experiment with tone-stimulus triggered data processing and question/answer solution with or without correction and annotation.

    • slice_module_answer_2.gif
    • Table 2b: referred table; all markers in this table will inherit all the actions defined in the main table for @AllTones. This is ueful to prevent retyping large amounts of equal information for groups of markers.

    • slice_module_answer_3.gif
    • Table 2c: referred table; a definition of the required actions for the question/answer solution. Referring to this table will add all required actions to your own table.

      • slice_module_answer_4.gif
      • Table 2d: referred table; replicate actions for all these markers and add individual ones for CorrectAnswer each marker in this table separately.

      • slice_module_answer_5.gif
      • Table 2e: referred table; same mechanism as in table 2d, but then for other markers and Answer.

Table 2: Example of experiment definition features.

Table 2 demonstrates many features of the mechanisms that play a role in the composition of tables. It refers to other tables in order to benefit from the modular approach. The modular approach encourages exchange of BCI-solutions between groups (within or between institutes), enhances possibilities for maintenance of common modules that are shared. Changes to modules will then automatically propagate into other applications that refer to this module. Also, a better overview of the defined application is achieved by modularizing the table. The example in this table defines an experiment in where a sequence of stimuli is applied to the subject after which he/she is asked to answer a question. Often, the post-processing of the data requires information about whether the subject answered the question right or wrong. The approach shown here 'links' this information to each stimulus event structure immediately after the given time period to answer has ended ( end_of_waiting marker). It also includes information about the sequence number and stimulus (here a tone) index number in this sequence, together with the number of correct and wrong answered questions. This information is very useful if analyses need to distinguish certain parts of the stimuli based on these criteria (i.e., odd and even numbered stimuli etc.). Even switching between subjects being allowed to correct their answer or not is done by initializing the allow_correction variable to 1 or 0.

In the example, in time order the following actions are performed:

1) Annotation
The base_line marker resets ToneCount to 0, and increments SeqCount. During processing, actions connected to marker answer_X sets the CorrectAnswer variable to X. A button press will then insert a marker button_X in the data stream which are associated with an action to set Answer to X. After some time - defined by the moment the marker end_of_waiting pops up in the data stream, the response of the subject will be evaluated. Actions connected to this end_of_waiting marker will then compare the expected answer with the actual answer and set variable CorrectAnswered according to the outcome of this comparison. All tone markers with their associated data, which occurred before that all, wait for marker ‘end_of_waiting’ before getting the values of CorrectAnswered, NumWrong etc. In this way, the outcome of the comparison (correct answered or not) will then be included as an additional field to all event structures of all individual tones. Marker end_of_waiting also inserts another marker slice_now, which will trigger the moment for all tone markers to save data and annotation (event structure with fields) to disk (slice() function).

2) Referencing tables
By referencing another table it is possible to copy default actions to all the markers of the referred table. If no defaults are specified, a reference to another table will include all the actions of corresponding markers to the table where it is referred from. If a default action (for a specific marker and timepoint) is also defined in the referred table, the default action will be ignored. This is useful if a large number of markers define the same actions with only a few exceptions. These exceptions can then be specified in the referenced table and will overwrite the defaults. In table 2b, it is shown how copying actions is useful for a set of tone markers. Athough not included in table 2b, it would normally include actions that are specific to the individual tone markers. For example, tones can have different frequencies which difference could be expressed in an extra variable frequency. For @AllTones, default actions are specified for timepoints EVENT, DATA, and slice_now. The latter is a timepoint which execution moment will be determined by the moment the slice-now marker pops-up. For every marker out of the set: tone1 .. tone10 these actions will be executed at corresponding timepoints. By the same principle, table 2a refers to table 2c (Buttons.xls ProcessAnswer) to automatically include a mechanism for annotating events. Table 2c in turn refers to tables 2d and 2e to copy actions for button_X and answer_X markers.

3) Flexibility
Incoming markers initiate an unlimited sequence of actions at unlimited number of logical timepoints. This mechanism together with scheduled and (by means of user functions) insertable markers allows for many options to choose from in order to achieve desired processing.

For marker tone1 In Table 2, expansion of the recursive structure would lead to:

tone1
EVENT

ToneCount = ToneCount + 1
Get content of ToneCount
Get content of SeqCount

DATA

Execute functions:
SplitData()
Rereference()

slice_now

Get content of CorrectAnswer
Get content of Answer
Get content of CorrectAnswered
Get content of NumCorrect
Get content of NumWrong
Execute function:
slice()

Data selection (not shown in Table 2)

Begintime = 0
Endtime = 1


 

Environment

 

Applications

 

Troubleshooting

 

StimCat

 

Topic revision: r1 - 10 Nov 2009 - 10:51:40 - MarianneSeverens
 
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