BrainStreamMarkerHandling

Inserting Markers

Introduction

Markers fulfil two roles, synchronising stimuli and triggering events. The synchronisation role is required to match moments of presented stimuli with at that time acquired data. While markers translate into rich events, an event itself can also directly trigger execution of other events in order to implement required program flow. Inserting markers as described in this paragraph is solely meant to achieve the synchronisation role. Triggering other events from events should be specified in a separate Trigger table, explained in more detail here.

Inserting markers in the data stream

Data is recorded by a hardware device. BrainStream does not connect to this hardware device directly, but via a [FieldTrip buffer].

Figure 1: BrainStream is connected to the hardware via a FieldTrip buffer.

The data is recorded by the hardware and streamed to the FieldTrip buffer in small packages of a fixed number of samples. BrainStream reads the data from the buffer. Markers can be inserted in the data either via the hardware device or via the FieldTrip buffer. Markers can be inserted by BrainStream itself or any of its clients. The figure below shows a schematic representation of the two marker routes:

Figure 2: Markers can be inserted via the hardware or via the FieldTrip buffer.

Each marker route has its advantages and disadvantages, so which route is the best depends on the inserted marker's function. Markers inserted via the hardware have more accurate synchronization with the data, but markers inserted via the FieldTrip buffer can be processed faster. In addition, only markers that are inserted via the hardware are saved in the raw data file. This means that markers that are required for offline processing must always be inserted via the hardware.

We will now describe each of the marker routes in more detail.

Inserting markers via the hardware

The most accurate synchronization between markers and data is obtained when a marker is sent via the hardware. It is recommended to insert markers via the hardware when good synchronization between the markers and the data is important, for example when the markers represent the onset of stimuli in an ERP-based BCI.

Function: bs_send_hardware_marker

In order to insert a marker via the hardware, you must use the following function:

bs_send_hardware_marker(event, marker, datasource)

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)

The bs_send_hardware_marker function does not send the markers to the hardware itself. Instead, it will look in the blocksettings for a sndMarker function which actually sends the markers to the hardware device. If you have not specified a sndMarker function in the block file, BrainStream will insert the markers via the FieldTrip buffer instead. If this happens, you will see the following message in the Matlab command window and the log file:

No 'send-marker-function' defined: marker (<marker name>) sent to BrainStream directly 

Timing accuracy and processing speed

When the bs_send_hardware_marker function is executed, BrainStream will send the marker to the hardware device. Together with the data, markers that are inserted like this return to BrainStream via the FieldTrip buffer.

Figure 3: Schematic timeline of marker insertion via the hardware.

The marker will be inserted in the data at a certain sample number, represented as a white block in figure 3. Thus, the timing accuracy of markers inserted via the hardware corresponds to one sample. For example, at a sampling frequency of 2 kHz the timing accuracy is 0.5 ms.

The data is sent from the hardware to the FieldTrip buffer in packages of a fixed number of samples, represented in the figure as light and dark blocks. The inserted marker will be sent to the FieldTrip buffer together with the corresponding data package. The time this may take depends on the number of samples per package and the sampling rate of the device. For example, if the package size is 16 samples and the sampling rate of the hardware is 2 kHz, data and markers will be sent to the FieldTrip buffer every 8 ms. Thus, in this case it may take up to 8 ms before the marker is received by BrainStream and can be processed.

Testing without hardware

It is possible to test your experiment on your own machine, without any hardware connected. If the bs_send_hardware_marker function is called when no hardware is connected, BrainStream will automatically send the marker via the FieldTrip buffer instead. When this happens, the following message will appear in the Matlab command window and the log file:
marker <marker name> (type <marker type>) sent to fieldtrip buffer directly

If for some reason the insertion of markers via the hardware fails while hardware is connected (i.e. during a 'real' experiment), BrainStream will give an error message and end the experiment.

Additional issues

Markers that are inserted via the hardware must always be defined in the Dictionary table. An error occurs if the marker is not found in the Dictionary.

Only markers that are inserted via the hardware are stored in the raw data (e.g. .bdf or .gdf) file. Markers that you need after your experiment has finished, for example for offline processing, should therefore always be inserted via the hardware.

Inserting markers via the FieldTrip buffer

Markers inserted via the FieldTrip buffer can be processed faster than markers inserted via the hardware. However, the synchronization between these markers and the data is less accurate.

Function: bs_send_buffer_marker

In order to insert markers via the FieldTrip buffer, you must use the following function:

bs_send_buffer_marker(event, marker, datasource, delay, reference)

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, or
		          'marker' (default): delay is specified relative to the onset of the event during which bs_send_buffer_marker is executed

In contrast to insertion via the hardware, a delay can be specified for marker insertion via the FieldTrip buffer. A short example shows the difference between the two possible 'reference' specifications:

Actions table
marker	time	function
mrk1	EVENT	fnc1, fnc2, bs_send_buffer_marker('mrkA','eeg',2,'now')

Actions table
marker	time	function
mrk1	EVENT	fnc1, fnc2, bs_send_buffer_marker('mrkA','eeg',2,'marker')

This example shows that the 'now' option specifies the delay relative to the onset of the bs_send_buffer_marker function, whereas the 'marker' option specifies the delay relative to the onset of the event during which bs_send_buffer_marker is executed. In the latter case, if processing of the event takes longer than the specified delay, the marker cannot be inserted at the scheduled time. Instead, the marker will be inserted as soon as the execution of all functions prior to the bs_send_buffer_marker is completed.

Timing accuracy and processing speed

When the bs_send_buffer_marker function is executed, BrainStream sends the marker to the FieldTrip buffer, where it will be approximately synchronized with the data:

Figure 4: Schematic timeline of marker insertion via the FieldTrip buffer.

The actual insertion time of the marker relative to the data is represented as a white block in figure 3. However, in the FieldTrip buffer, the marker will be treated as if it arrived together with the most recent data package. As described above, with a data package size of 16 samples and a hardware sampling rate of 2 kHz, the marker can appear to have been inserted up to 8 ms earlier than it actually was. Thus, the timing accuracy of markers inserted via the FieldTrip buffer (8 ms) is less accurate than that of markers inserted via the hardware (0.5 ms). However, markers that are sent to the FieldTrip buffer can immediately be processed by BrainStream without having to wait for a data package update.

Additional issues

If markers that are sent via the FieldTrip buffer are not defined in the Dictionary table, BrainStream will internally assign a type and value for these markers. Markers that are inserted via the FieldTrip buffer are not stored in the raw data file. Therefore, markers that you need for offline processing (i.e., to sync moments of stimuli with the data) should be inserted via the hardware instead and must be defined in the Dictionary table.