User Reference:Validating the Event Logging Mechanism - Revision history

Mellinger: /* Data recorded with g.USBamp source module */

2026-07-30T12:35:48Z

Data recorded with g.USBamp source module

← Older revision		Revision as of 12:35, 30 July 2026
Line 66:		Line 66:
	[[file:Event_vs_SourceTime_gUSBamp.png]]		[[file:Event_vs_SourceTime_gUSBamp.png]]

	Similarly to the ~~SignalSource~~ example above, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms (standard deviation).		Similarly to the SignalGenerator example above, the Event mechanism is working close to perfectly with the g.UBSamp amplifier, with a jitter of +/-0.4 ms (standard deviation).

	[[file:Event_vs_sample_time_gUSBamp.png]]		[[file:Event_vs_sample_time_gUSBamp.png]]

Mellinger: /* Synopsis */

2026-07-29T15:40:40Z

Synopsis

← Older revision		Revision as of 15:40, 29 July 2026
Line 1:		Line 1:
	==Synopsis==		==Synopsis==
	BCI2000 is able to record asynchronous data, so called [[Programming_Reference:Events\|Events]], that occur during a recording. These events are logged into [[Technical Reference:State Definition\|BCI2000 states]], which provide a universal way to store information associated with brain signal sample data.		BCI2000 is able to record asynchronous data, so-called [[Programming_Reference:Events\|Events]], that occur during a recording. These events are logged into [[Technical Reference:State Definition\|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.		This page provides an overview over the general concept and implementation of events.

Mellinger: /* Matlab Analysis Script */

2026-07-29T15:35:20Z

Matlab Analysis Script

← Older revision		Revision as of 15:35, 29 July 2026
Line 79:		Line 79:

	filename = 'RefLogger_gUSBampS001R01.dat';		filename = 'RefLogger_gUSBampS001R01.dat';
	%
	[signal, states, parameters] = load_bcidat(filename);		[signal, states, parameters] = load_bcidat(filename);
	SampleBlockSize = parameters.SampleBlockSize.NumericValue;		SampleBlockSize = parameters.SampleBlockSize.NumericValue;
	SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});		SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
	SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;		SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
	%
	% prepare SourceTime state by first reducing to a single value per block,		% prepare SourceTime state by first reducing to a single value per block,
	% then interpolating across block		% then interpolating across block
Line 94:		Line 94:
	% by a sample block duration		% by a sample block duration
	SourceTime3 = SourceTime3 - SampleBlockDurationMs;		SourceTime3 = SourceTime3 - SampleBlockDurationMs;
	%
	% prepare a vector of equally spaced sample times (SourceTime may be		% prepare a vector of equally spaced sample times (SourceTime may be
	% jittered)		% jittered)
	sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';		sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
	%
	% prepare RefTime state		% prepare RefTime state
	RefTime = double(states.RefTime);		RefTime = double(states.RefTime);
Line 107:		Line 107:
	RefTime2 = RefTime(valid_idx);		RefTime2 = RefTime(valid_idx);
	RefTime2 = extend_timestamp(RefTime2);		RefTime2 = extend_timestamp(RefTime2);
	%
	% determine difference between RefTime values, and interpolated SourceTime		% determine difference between RefTime values, and interpolated SourceTime
	% values		% values
	delta1 = RefTime2 - SourceTime3(valid_idx);		delta1 = RefTime2 - SourceTime3(valid_idx);
	%
	figure;		figure;
	hist(delta1, 40);		hist(delta1, 40);
Line 117:		Line 117:
	subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));		subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
	xlabel('offset in ms');		xlabel('offset in ms');
	%
	% determine difference between RefTime values, and interpolated sample time		% determine difference between RefTime values, and interpolated sample time
	% values		% values
	delta2 = RefTime2 - sample_time(valid_idx);		delta2 = RefTime2 - sample_time(valid_idx);
	%
	figure;		figure;
	hist(delta2, 40);		hist(delta2, 40);
Line 127:		Line 127:
	subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));		subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
	xlabel('offset in ms');		xlabel('offset in ms');
	%
	% determine difference between interpolated SourceTime, and interpolated sample time		% determine difference between interpolated SourceTime, and interpolated sample time
	% values		% values
	delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);		delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
	%
	figure;		figure;
	hist(delta3, 40);		hist(delta3, 40);
Line 137:		Line 137:
	subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));		subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
	xlabel('offset in ms');		xlabel('offset in ms');
	%
	%
	function result = extend_timestamp(input)		function result = extend_timestamp(input)
	% extend timestamp from the 0..65535 to full range		% extend timestamp from the 0..65535 to full range
Line 150:		Line 150:
	end		end
	end		end
	%
	function result = parse_sampling_rate(input)		function result = parse_sampling_rate(input)
	[token, remain] = strtok(input, 'Hk');		[token, remain] = strtok(input, 'Hk');

Mellinger: /* Data recorded with g.USBamp source module */

2026-07-29T15:33:37Z

Data recorded with g.USBamp source module

← Older revision		Revision as of 15:33, 29 July 2026
Line 71:		Line 71:

	When comparing event time stamps to sample time for data recorded with the g.USBamp amplifer, we have a nearly perfect distribution of differences, with an event timing jitter of +/-0.4 ms (standard deviation).		When comparing event time stamps to sample time for data recorded with the g.USBamp amplifer, we have a nearly perfect distribution of differences, with an event timing jitter of +/-0.4 ms (standard deviation).

			Note that time stamps are rounded to full milliseconds, so an event timing jitter in the order of half a millisecond is to be expected.

	===Matlab Analysis Script===		===Matlab Analysis Script===

Mellinger: /* Data recorded with g.USBamp source module */

2026-07-29T15:30:33Z

Data recorded with g.USBamp source module

← Older revision		Revision as of 15:30, 29 July 2026
Line 70:		Line 70:
	[[file:Event_vs_sample_time_gUSBamp.png]]		[[file:Event_vs_sample_time_gUSBamp.png]]

	When comparing event time stamps to sample time, we have a nearly perfect distribution of differences ~~with the g.USBamp amplifier~~, with an event timing jitter of +/-0.4 ms (standard deviation).		When comparing event time stamps to sample time for data recorded with the g.USBamp amplifer, we have a nearly perfect distribution of differences, with an event timing jitter of +/-0.4 ms (standard deviation).

	===Matlab Analysis Script===		===Matlab Analysis Script===

Mellinger: /* Data recorded with SignalGenerator source module */

2026-07-29T15:28:56Z

Data recorded with SignalGenerator source module

← Older revision		Revision as of 15:28, 29 July 2026
Line 61:		Line 61:

	This graph shows that there is quite some disagreement between sample time, and event time.		This graph shows that there is quite some disagreement between sample time, and event time.
	This is due to the fact that SignalGenerator is not a true data source, and uses the imprecise Windows <tt>Sleep()</tt> function to simulate ~~one~~.		This is due to the fact that SignalGenerator is not a true data source, and uses the imprecise Windows <tt>Sleep()</tt> function to simulate regular arrival of sample blocks.

	====Data recorded with g.USBamp source module====		====Data recorded with g.USBamp source module====

Mellinger: /* Analyzing RefLogger Data */

2026-07-29T15:27:09Z

Analyzing RefLogger Data

← Older revision		Revision as of 15:27, 29 July 2026
Line 41:		Line 41:
	''RefLogger'' data analysis follows two distinct purposes:		''RefLogger'' data analysis follows two distinct purposes:

	# Assessing whether the Event software mechanism works as designed,		# Assessing whether the Event logging software mechanism works as designed,
	# Assessing how precise and useful Event information is for a certain experiment.		# Assessing how precise and useful Event information is for a certain experiment.

Mellinger: /* Using the RefLogger */

2026-07-29T15:26:23Z

Using the RefLogger

← Older revision		Revision as of 15:26, 29 July 2026
Line 36:		Line 36:
	To enable it, add a command line option to the source module’s <tt>START EXECUTABLE</tt> command as in the following example:		To enable it, add a command line option to the source module’s <tt>START EXECUTABLE</tt> command as in the following example:
	Start Executable SignalGenerator --RefLoggerFrequency=100Hz --local		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.		You may specify any value for ''RefLoggerFrequency'' but notice that BCI2000 time stamps are limited to millisecond resolution, so producing ''RefLogger'' events at a frequency higher 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===		===Analyzing RefLogger Data===

Mellinger: /* Sources of Imprecision */

2026-07-29T15:25:00Z

Sources of Imprecision

← Older revision		Revision as of 15:25, 29 July 2026
Line 24:		Line 24:
	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.		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 using the BCI2000 [[User Reference:Timing\|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.		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 -- acquisition delay is the time delay between digitizing a block’s last sample, and seeing that block in the computer’s memory. ''Regularity'' of data blocks may be assessed using the BCI2000 [[User Reference:Timing\|timing window]]; there, data block duration should form a straight line. Acquisition ''delay'', in contrast, is more difficult to measure, and requires an amplifier with a digital (or analog) output that may be connected to an amplifier input, producing an input signal whenever a new block has entered the computer's memory.

	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.		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.

Mellinger: /* Associating Time-stamped Events with Samples */

2026-07-29T15:20:22Z

Associating Time-stamped Events with Samples

← Older revision		Revision as of 15:20, 29 July 2026
Line 19:		Line 19:
	===Associating Time-stamped Events with Samples===		===Associating Time-stamped Events with Samples===
	For the following, it is crucial to understand that events happen while a data block is being digitized by the amplifier's hardware, and may then be associated with the samples of that block once it arrives at the computer.		For the following, it is crucial to understand that events happen while a data block is being digitized by the amplifier's hardware, and may then be associated with the samples of that block once it arrives at the computer.
	As soon as that block enters the computer’s memory, events are taken from the event queue in temporal order, and applied to the state variables ~~inside~~ the block.		As soon as that block enters the computer’s memory, events are taken from the event queue in temporal order, and applied to the state variables associated with the block.

	===Sources of Imprecision===		===Sources of Imprecision===