User Reference:Validating the Event Logging Mechanism

Synopsis

BCI2000 is able to record asynchronous data, so called Events, that occur during a recording. These events are logged into BCI2000 states, which provide a universal way to store information associated with brain signal sample data.

This page provides an overview over the general concept and implementation of events.

Also, it describes the RefLogger, which allows to quantify how reliable event recording is, and shows a simple Matlab script to analyze RefLogger data, together with results from a reference system.

The Event Logging Mechanism

Time-stamping Brain Signal Data

As described elsewhere, BCI2000 processes brain signal data in blocks of fixed size and duration. Whenever a block of data has been acquired from the main brain signal source, a time stamp is taken from the computer's clock. Note that this time stamp is taken after the data block has been sampled and transmitted from the hardware. Assuming a negligible time delay between sampling of the block's last sample, and transmission into the computer, we can say that this time stamp represents the time of sampling for the first sample of the following block. Knowing this time stamp, and the sampling rate of the brain signal source, we can thus associate each of the block's samples with a sample time.

Time-stamping Events

In the BCI2000 software, a function exists that takes the name of an event, and a value. Whenever this function is called, it takes a time stamp from the computer’s clock and stores the event’s name, value, and time stamp into a queue of events. This queue is organized according to time stamps such that oldest entries will be retrieved first (priority queue).

Associating Time-stamped Events with Samples

For the following, it is crucial to understand that events that happen while a data block is being digitized should be associated with the samples of that block. As soon as that block enters the computer’s memory, events are then taken from the event queue in order, and applied to the state variables inside the block.

Sources of Imprecision

The event logging mechanism depends on precision of the BCI2000 time stamp. As this is derived from a high-precision clock available in all modern computers, this is in general not an issue.

More of interest is another source of imprecision: Acquisition irregularities. Ideally, BCI2000 block duration is constant, and data blocks arrive regularly with little to no acquisition delay (time from sampling a block’s last sample, and seeing that block in the computer’s memory). Regularity of data blocks may be assessed by using the BCI2000 timing window; there, data block duration should form a straight line. Acquisition delay is more difficult to measure, and requires an amplifier with a digital (or analog) output that may be connected to an amplifier input.

Imprecise block duration will result in differences between measured block durations, and ideal block durations. If this happens, time stamps may appear older than the oldest sample in the current block. If this is the case, the affected events will be associated with the block’s first sample, as the previous block is no longer available for storing events. This will result in events that are shifted slightly into the future, so they may appear to precede the actual time of the physical event that produced them.

The RefLogger Component

The ‘’RefLogger’’ is a simple BCI2000 component that logs a special event, called ‘’’RefTime’’’, in regular intervals. What is special about that event is that it does not hold simple values like “1” or “2” but time stamps derived from the computer’s clock, just as the time stamps used to align events with brain signal samples. In data analysis, this allows to compare the sample position of an event to its time stamp value, and to assess how well the two match.

Using the RefLogger

The ‘’RefLogger’’ is available in all BCI2000 modules, but not active by default. To enable it, add a command line option to the source module’s START EXECUTABLE command as in the following example:

Start Executable SignalGenerator --RefLoggerFrequency=100Hz —local

You may specify any value for ‘’RefLoggerFrequency’’ but notice that BCI2000 time stamps are limited to millisecond resolution, so producing RefLogger events at a higher frequency than 1000Hz is not useful. Also, if the ‘’SamplingRate’’ parameter is set to a value lower than ‘’RefLoggerFrequency’’, no useful results may be expected.

Analyzing RefLogger Data

‘’RefLogger’’ data analysis follows two purposes: 1. Assessing whether the Event software mechanism works as designed, 2. Assessing how precise and useful Event information is for a certain experiment. In terms of data, the two questions are quite similar, but differ in the time base used to compare ‘’’RefTime’’’ timestamps against. For question (1), the time base is taken from each data block’s ‘’SourceTime’’ timestamp, and extrapolated into the past before determining the difference to the ‘’’RefTime’’’ entries. For question (2), a sample-based time base is constructed by taking the recording’s duration as measured in terms of time stamps, and evenly distributing that across all samples in the recording, taking into consideration the first time stamp as a offset. Then, the time stamp differences give an impression of how the event mechanism performs with regard to physical time.

Ideally, the results of (1) and (2) would agree. Differences are due to the sources of imprecision discussed above.