BCI2000 Wiki - User contributions [en]

Technical Reference:Operator Library

2026-08-12T14:34:44Z

Mellinger: /* BCI_OnQuitRequest( void* refdata, const char** pMsg ) */

The Operator Library is a shared library that encapsulates the Operator Module's core functionality into an interface that allows to embed Operator functionality into one's own application. This way, is is possible to write your own Operator module, or to control BCI2000 from your own application, without having to deal with details of the BCI2000 protocol. The BCI2000 Operator library can be used from any programming language that allows using a shared library (DLL). Although the Operator library is written in C++, its DLL interface is plain C, and can be used with compiled languages such as C, C++, C#, Pascal, but also with interpreted languages that can call functions in a DLL, such as Python, Matlab, VisualBasic, etc. Interfacing with Java requires a JNI (Java Native Interface) wrapper, which is currently not provided by BCI2000.

For a C++ example that uses the Operator Library to implement a simple Operator Module, see [http://www.bci2000.org/tracproj/browser/trunk/src/contrib/OperatorLibApplications/OperatorLibDemo/main.cpp the OperatorLibDemo] program.

==System State (State of Operation)==
BCI2000 system state may be queried using <tt>BCI_GetStateOfOperation()</tt>, and modified using the <tt>BCI_SetConfig()</tt>, <tt>BCI_StartRun()</tt>, and <tt>BCI_StopRun()</tt> functions. These functions manipulate system state in a way that is analogous to the main buttons in the standard [[User Reference:Operator Module|Operator module]].

System state is one of the following:
===BCI_StateUnavailable===
The system is not available for changes to system state.

===BCI_StateIdle===
The system is initialized, but not started up, ie., not waiting for connections.

===BCI_StateStartup===
The Operator module is waiting for core modules to connect.
===BCI_StateInitialization===
Core modules are connected, the system is waiting to be parameterized via <tt>SetConfig()</tt>.
===BCI_StateResting===
The system has been parameterized and is waiting for a <tt>StartRun()</tt> command.
===BCI_StateSuspended===
The system has been suspended via <tt>StopRun()</tt>, or from one of the modules setting the "Running" state variable to 0.
===BCI_StateParamsModified===
The system has been suspended, and parameters have been modified from one or more of the core modules.
===BCI_StateRunning===
The system is running.
===BCI_StateBusy===
The system is currently busy, and not in one of the above states. It is not available for changes to system state.

System state may be '''manipulated''' calling one of the following functions:

===int BCI_GetStateOfOperation()===
Determines the externally visible state of the state machine, i.e.
the state of operation of the BCI2000 system.
===int BCI_SetConfig()===
Asynchronously applies current parameter settings to the BCI2000 system, i.e. initiates the parameterization process, and returns immediately, indicating whether parameterization has been initiated.
;returns: 1 if successful, 0 otherwise.

===int BCI_StartRun()===
Asynchronously starts a new run.
;returns: 1 if successful, 0 otherwise.

===int BCI_StopRun()===
Asynchronously stops the current run.
;returns: 1 if successful, 0 otherwise.

==Parameterization==
Parameterization functions allow to populate and modify of the Operator Library's internal parameter list, state list, event list, and visproperty list. When calling <tt>SetConfig()</tt>, parameter values are applied to the BCI2000 system.

===int BCI_PutParameter( const char* parameterLine )===
Parses a BCI2000 parameter definition line, and adds the resulting parameter object to the internal parameter list, or changes the value of a parameter if it exists.
;arguments: Pointer to a null-terminated parameter line string.
;returns: 1 if successful, 0 otherwise.

===const char* BCI_GetParameter( long index )===
Returns the parameter with the given index from the operator's internal parameter list, or NULL when the index is out of range.
;arguments: Parameter index.
;returns: Pointer to a null-terminated string containing a parameter line, or NULL. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===int BCI_PutState( const char* stateLine )===
Parses a BCI2000 state definition line, and adds the resulting state to the operator library's state list.
;arguments: Pointer to a null-terminated state line string.
;returns: 1 if successful, 0 otherwise.

===const char* BCI_GetState( long index )===
Returns the state with the given index from the DLL's internal state list. , or NULL when the index is out of range.
;arguments: State index.
;returns: Pointer to a null-terminated string containing a state line, or NULL. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===int BCI_PutEvent( const char* eventLine )===
Parses a BCI2000 event definition line, and adds the resulting event to the operator library's event list.
;arguments: Pointer to a null-terminated event line string.
;returns: 1 if successful, 0 otherwise.

===const char* BCI_GetEvent( long index )===
Returns the event with the given index from the DLL's internal event list. , or NULL when the index is out of range.
;arguments: Event index.
;returns: Pointer to a null-terminated string containing an event line, or NULL. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===int BCI_PutVisProperty( const char* visID, int cfgID, const char* value )===
Sets the a property to the given value, or adds the property to the property list if it is not present. A list of visualization properties is available at [[Technical Reference:Visualization Properties]].
;arguments: Pointer to a null-terminated vis ID string, numeric config ID, and a pointer to a null-terminated value string.
;returns: 1 if successful, 0 otherwise.

===const char* BCI_GetVisProperty( const char* visID, int cfgID )===
Returns the property with the given cfgID from the DLL's internal property list. A list of visualization properties is available at [[Technical Reference:Visualization Properties]].
;arguments: Pointer to a null-terminated vis ID string, numeric config ID.
;returns: Pointer to a null-terminated string containing a property line, or NULL. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

==Online Information==
These functions allow to access information processed when the system is running. Modifying states and setting events will affect what is recorded in the data file.

===int BCI_SetStateValue( const char* stateName, long value )===
Sets the value of a state to a given value. Setting a state via <tt>BCI_SetStateValue()</tt> may result in a change to BCI2000 system state.
;arguments: Pointer to a null-terminated state name string; new state value.
;returns: 1 if successful, 0 otherwise.

===long BCI_GetStateValue( const char* stateName )===
Returns the value of a state. '''NOTE:''' During operation, state values will only be updated when sent by the last module in the chain of core modules. This is governed by the <tt>OperatorBackLink</tt> parameter on the <tt>System</tt> tab, which must be set to 1.
;arguments: Pointer to a null-terminated state name string.
;returns: State value, or 0 if the state does not exist.

===int BCI_SetEvent( const char* eventName, long value )===
Asynchronously sets the value of an event. In the data file, the point in time where SetEvent() was called will be associated with a single sample.
;arguments: Pointer to a null-terminated event name string; new event value.
;returns: 1 if successful, 0 otherwise.

===int BCI_GetSignalChannels()===
Returns the number of channels in the control signal.
===int BCI_GetSignalElements()===
Returns the number of elements in the control signal.

===float BCI_GetSignal( int channel, int element )===
Returns a value from the control signal. '''NOTE:''' During operation, control signal values will only be updated when sent by the last module in the chain of core modules. This is governed by the <tt>OperatorBackLink</tt> parameter on the <tt>System</tt> tab, which must be set to 1.
;arguments: Channel index, element index (zero-based).
;returns: Signal value.

==Watches==
Watches are expressions that are tied to ''callback events'' (see below). Whenever the expression's value changes, the associated callback event is triggered. Use <tt>BCI_AddWatch</tt> to create a watch a receive a unique callback event ID, followed with <tt>BCI_SetCallback()</tt> or <tt>BCI_SetExternalCallback()</tt> to register a callback function with the watch's event.
Whenever the watch is triggered, your callback function will be called with the expression's current value in string format.

===long BCI_AddWatch( const char* expressions )===
Create a watch consisting of one or more expressions. An event is triggered whenever
one of the expressions changes its value. Expressions are evaluated as described for
the EVALUATE EXPRESSION scripting command.
You may associate a callback with the created watch by specifying its watch ID as an
event ID to any of the callback registration functions. To the callback function, an
additional argument of type const char* will be provided, which contains a string
representation of all current expression values, separated by tab characters, and terminated
with a Windows newline sequence (CRLF).
The argument is a string containing a list of expressions, separated by tab characters.
The function returns a watch ID if successful, BCI_None otherwise. The function will fail if the list of expressions
contains an invalid expression.

===int BCI_SetWatchDecimation( long watchID, int decimation )===
Set decimation for a watch. By default, decimation is 1, and expressions will be evaluated
for each sample in a data block. For higher values of decimation, every n-th sample will be evaluated.
The function returns 1 if successful, 0 if no watch was registered with the given ID.

===int BCI_RemoveWatch( long watchID )===
Removes a watch that was created using BCI_AddWatch(), and unregisters its associated callback function.
The Watch ID argument is a watch ID as returned by BCI_AddWatch.
Returns 1 if successful, 0 if no watch was registered with the given ID.

==Callbacks==
Whenever the Operator Library receives data, or its state is modified, a ''callback event'' is triggered. In response to this event, a callback function is called. Callback functions are registered with <tt>BCI_SetCallback()</tt> or <tt>BCI_SetExternalCallback()</tt>. The difference between the two registration functions is that the first registers a callback function to be called within the context of an internal thread of the Operator Library, while the second registers a callback function to be executed in a thread owned by the application that uses the Operator library, i.e. a thread that is "external" to the Operator library. That "external" thread needs to call <tt>BCI_CheckPendingCallback()</tt> regularly in order to execute callback functions. Typically, <tt>BCI_CheckPendingCallback()</tt> would be called from a GUI application's main thread within its message handling loop.

Callback events are listed with their event names, and their handlers' arguments. A callback function has at least one argument, which is a void* named refdata. The refdata pointer is supplied by user code when registering the callback function, and provided to the callback function unchanged. Typically, it would be used to store an object pointer in C++, or to an application specific data structure in C.

In Windows, callbacks must follow the ''stdcall'' calling convention. In the Operator Library's header file, a macro STDCALL is provided that should be inserted after a callback function's return type in the function declaration. This macro allows setting the calling convention without confusing compilers when compiling for non-Windows systems.

When programming in C++, callback functions must be either global functions, or functions declared "static" within class scope. They may not be ordinary member functions of a class. In object oriented programming however, you will typically want an ordinary member function to be called as a callback. This is possible using the "refdata" pointer to store an object pointer, and then call a member function on that object from the callback function as in the following example:
<pre>
class MyOperator
{
public:
MyOperator()
{
BCI_SetCallback( BCI_OnSystemStateChange, BCI_Function( &OnSystemStateChangeCallback ), this );
}
~MyOperator()
{
BCI_SetCallback( BCI_OnSystemStateChange, NULL, NULL );
}
private:
void OnSystemStateChange()
{
... // ordinary member function that gets executed when system state changes
}
static void STDCALL OnSystemStateChangeCallback( void* refdata )
{
MyOperator* pObject = reinterpret_cast<MyOperator*>( refdata );
pObject->OnSystemStateChange();
}
};
</pre>

In the following, callbacks are listed as if they were ordinary functions. However, you will not use them this way. Rather, the "function name" is the name of the callback that is supplied as the first argument to <tt>BCI_SetCallback()</tt> or <tt>BCI_SetExternalCallback()</tt>. Your own callback function will have a different name, must return "void" or "int" as indicated, and must take the arguments listed as arguments to the callback. A pointer to your own callback function will then be specified as the second argument to <tt>BCI_SetCallback()</tt>, casted to the <tt>BCI_Function</tt> type (see the example above).

===Callback Constants===
;BCI_Handled
:Return this constant to indicate that your callback handled the event. Only used with callback functions listed with an "int" return type.
;BCI_NotHandled
:Return this constant to indicate that your callback did not handle the event in question. Only used with callback functions listed with an "int" return type.

=== BCI_OnSystemStateChange( void* refdata )===
Occurs on any change to BCI2000 system state.
===BCI_OnCoreInput( void* refdata )===
Occurs on input from any of the BCI2000 core modules.
===BCI_OnConnect( void* refdata )===
Occurs when core modules have connected to the Operator Library.
===BCI_OnSetConfig( void* refdata )===
Triggered when <tt>SetConfig()</tt> has been called.
===BCI_OnStart( void* refdata )===
Triggered when <tt>StartRun()</tt> has been called.
===BCI_OnSuspend( void* refdata )===
Triggered when BCI2000 goes into suspended state.
===BCI_OnResume( void* refdata )===
Triggered when BCI2000 enters the running state again.
===BCI_OnShutdown( void* refdata )===
Triggered when <tt>BCI_Shutdown()</tt> is called.

===BCI_OnQuitRequest( void* refdata, const char** pMsg )===
Triggered when a script executes the QUIT command. The application may choose to ignore the quit request, and should set the "message" pointer to a constant or static C string in this case. That string should provide information why the quit request was ignored.

===BCI_OnLogMessage( void* refdata, const char* msg )===
Triggered for each log message arriving from one of the modules, including the Operator module itself.
===BCI_OnWarningMessage( void* refdata, const char* msg )===
Triggered for warning messages. Note that also a <tt>BCI_OnLogMessage</tt> event is triggered for warning messages.
===BCI_OnErrorMessage( void* refdata, const char* msg )===
Triggered for error messages. Note that also a <tt>BCI_OnLogMessage</tt> event is triggered for error messages.
===BCI_OnDebugMessage( void* refdata, const char* msg )===
Triggered for each [[Programming_Reference:Debug_Output|debug message]] received by the Operator module.

===BCI_OnParameter( void* refdata, const char* parameterline )===
Triggered whenever a parameter message arrives at the Operator module.
===BCI_OnState( void* refdata, const char* stateline )===
Triggered whenever a state message arrives at the Operator module.
===BCI_OnVisPropertyMessage( void* refdata, const char* visID, int cfgID, const char* value )===
Triggered whenever a visproperty message arrives at the Operator module. For a list of available visualization properties, see [[Technical Reference:Visualization Properties]]. Constants for the cfgID parameter are defined in the <tt>src/shared/types/CfgID.h</tt> header file.

===BCI_OnVisProperty( void* refdata, const char* visID, int cfgID, const char* value )===
Triggered when a visualization property is modified from a script. For a list of available visualization properties, see [[Technical Reference:Visualization Properties]]. Constants for the cfgID parameter are defined in the <tt>src/shared/types/CfgID.h</tt> header file. The "value" parameter may be NULL to indicate that the property should be reset to default (e.g., by removing it from the property store).

===BCI_OnInitializeVis( void* refdata, const char* visID, const char* kind )===
Triggered when the first data message for a visualization window arrives. The <tt>kind</tt> argument contains a string describing the kind of visualization required for; it is one of "Graph", "Memo", "Bitmap", or "VideoFrame".

===BCI_OnVisMemo( void* refdata, const char* visID, const char* msg )===
Triggered for each memo data message to a visualization window. The <tt>visID</tt> argument specifies the window's visualization ID, the <tt>msg</tt> argument specifies the memo data.
===BCI_OnVisSignal( void* refdata, const char* visID, int channels, int elements, float* data )===
Triggered for each signal data message to a visualization window. Data are given such that the pair of indices <tt>(ch,el)</tt> corresponds to the single index <tt>ch*elements+el</tt>. Note that this is different from the layout of bitmap data.

===BCI_OnVisSignalHandle( void* refdata, const char* visID, void* signalHandle )===
Triggered for each signal data message to a visualization window. Note that using this callback is more efficient than the previous ''BCI_OnVisSignal'' because it allows to access signal data received through shared memory without copying. To access signal data behind the opaque handle, use the ''BCI_HandleGetSignalData()'' function explained below.

===BCI_OnVisBitmap( void* refdata, const char* visID, int width, int height, signed short* data )===
Triggered for each bitmap data message to a visualization window. Data are given in ARGB 1444 format, where the 12 bits with lowest significance represent color, and the four most significant of these 12 bits represent the R component. When any of the 3 bits with higher significance is set, the pixel is assumed to be transparent.

In actual images, the most significant bit is never set but allows for transmission of difference images between frames. Difference frames are computed by subtracting pixel values as if they were signed 16 bit integers, i.e. without regard to their interpretation as ARGB colors.
In transmission, empty bitmaps (width and height set to 0) are sent to indicate that the next bitmap will be a reference frame; between reference frames, difference frames are sent.

When addressing pixels, the pair of indices <tt>(x,y)</tt> corresponds to the single index <tt>y*width+x</tt>. Note that this is different from the layout of signal messages.

===BCI_OnVisVideoFrame( void* refdata, const char* visID, int width, int height, unsigned int* data )===
Triggered for each video frame message sent to the Operator module. Data are given in ARGB 8888 format.

When addressing pixels, the pair of indices <tt>(x,y)</tt> corresponds to the single index <tt>y*width+x</tt>. Note that this is different from the layout of signal messages.

===int BCI_OnUnknownCommand( void* refdata, const char* command, const char** output, const char** error )===
Triggered when the [[User Reference:Operator Module Scripting|Operator Module Scripting]] engine meets an unknown command. The event handler can be used to extend the set of commands by handling those commands that are unknown to the scripting engine. To report that a command has been handled, return <tt>BCI_Handled</tt> from the callback function. Otherwise, return a value of <tt>BCI_NotHandled</tt>.

If your command produces any output, use <tt>BCI_AllocateString()</tt> to allocate a string, and assign the resulting <tt>const char*</tt> to <tt>*output</tt>.

If your command produces any error messages, use <tt>BCI_AllocateString()</tt> to allocate a string, and assign the resulting <tt>const char*</tt> to <tt>*error</tt>.

===BCI_OnScriptHelp( void* refdata, const char** pMsg )===
Triggered when the scripting engine's "Help" command is executed. Assign the address of a string constant to the memory location received in <tt>pMsg</tt>. The contents of the string will be printed last in the list of commands, preceded with "Application-defined commands: ".

===BCI_OnScriptError( void* refdata, const char* msg )===
Triggered when script execution results in an error condition. Note that unknown commands are reported through the <tt>BCI_OnUnknownCommand</tt> event handler to allow handling additional commands.

===BCI_OnQuitRequest( void* refdata, const char** pMsg )===
This callback is executed when a script executes the QUIT command. It is the responsibility of your client program to shutdown the BCI2000 Operator library, and terminate the application. If you choose not to terminate, you may abort the Quit command by returning a message through the pMsg pointer. Use the <tt>BCI_AllocateString()</tt> function to allocate such an error message.

===BCI_OnNextFilePart( void* refdata, int part )===
This callback is executed when the ''FilePart'' event state is incremented. It receives the number of the the new file part as an argument.

==Functions that manage callbacks==

===int BCI_SetCallback( long, BCI_Function, void* )===
Register a callback function. To clear a callback function, specify NULL as a function pointer.
;arguments: Event ID, callback function pointer, data pointer. The callback function pointer must be cast to the <tt>BCI_Function</tt> function pointer type. The data pointer may be any data that should be available to the callback function.
;returns: 1 if successful, 0 otherwise.

===int BCI_SetExternalCallback( long, BCI_Function, void* )===
Register a callback function to be executed in an external thread on execution of <tt>BCI_CheckPendingCallback()</tt>. To clear a callback function, specify NULL as a function pointer.
;arguments: Event ID, callback function pointer, data pointer. The callback function pointer must be cast to the <tt>BCI_Function</tt> function pointer type. The data pointer may point to any data that should be available to the callback function.
;returns: 1 if successful, 0 otherwise.

===int BCI_CheckPendingCallback()===
Call this function regularly from within an external thread you want external callbacks to run in. Typically, is is called from a GUI application's main event loop.
;arguments: None.
;returns: 1 if a callback was executed, 0 otherwise.

===BCI_Function BCI_GetCallbackFunction( long )===
Get a registered callback function pointer.
;arguments: Event ID.
;returns: Callback function pointer, or NULL if no callback function has been registered for the specified event.

===void* BCI_GetCallbackData( long )===
Get registered callback data. Callback data is the first argument to callback functions, and specified when calling <tt>SetCallback()</tt> or <tt>SetExternalCallback()</tt>.
;arguments: Event ID.
;returns: Callback data, or NULL if no callback data has been registered for the specified event.

===int BCI_GetCallbackIsExternal( long )===
Get information how callback was registered.
;arguments: Event ID.
;returns: 1 if the function was registered with <tt>BCI_SetExternalCallback()</tt>, and 0 if it was registered with <tt>BCI_SetCallback()</tt>, or when no callback was registered.

==Miscellaneous Functions==
===const char* BCI_GetInfo( void )===
Reports build and source version information.
;arguments: None.
;returns: Pointer to a null-terminated string holding the information requested. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===const char* BCI_GetConnectionInfo( int index )===
Obtains information about a [[Technical Reference:Core Modules|core module]] connection.
;argument: Zero-based index of core module connection.
;returns: Pointer to a null-terminated string containing connection information, or NULL for an invalid index. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===const char* BCI_GetCoreModuleStatus( int index )===
Obtains a [[Technical Reference:Core Modules|core module's]] current status message.
;argument: Zero-based index of core module connection.
;returns: Pointer to a null-terminated string containing status information, or NULL for an invalid index. The output buffer is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===int BCI_Startup( const char* arguments )===
Listens on core module connection ports.
;arguments: A string defining a local IP address (such as "localhost", or "134.2.123.151", or "*" to listen on all local addresses), and [[Technical Reference:Core Modules|core module]] names and listening ports in the form "<name1>:<port1> <name2:port2> ... <nameN:portN>" If NULL or empty, a value of "Source:4000 SignalProcessing:4001 Application:4002" representing a standard BCI2000 configuration is used, and the Operator module listens on all addresses.
;returns: 1 if successful, 0 otherwise.

===int BCI_Shutdown( void )===
Close connections to core modules, and go into idle state.
;returns: 1 if successful, 0 otherwise.

=== int BCI_Initialize( void )===
Initialize the library. Must be called before any other library function is used. This function should be called from your application's main thread.
;returns: 1 if no error occurred, 0 otherwise.

=== int BCI_Dispose( void )===
Dispose of all resources allocated by the library. This function must be called from the thread that called BCI_Initialize().
;returns: 1 if no error occurred, 0 otherwise.

=== int BCI_SetPerThreadWD( const char* directory)===
Sets the per-thread working directory stored inside the operator library.
Expects a pointer to a null-terminated string defining the working directory, in UTF8-encoding.
Returns 1 if successful (i.e., the directory exists), and 0 otherwise.

===BCI_PipeListen(const char* name)===
Start a telnet server, listening at the given named pipe.
;arguments: Pipe name.
;returns: 1 if no error occurred, 0 otherwise.

===BCI_PipeCloseOne(const char* name)===
Stop a named pipe server, keeping connections open.
;arguments: Pipe name.
;returns: 1 if no error occurred, 0 otherwise.

===BCI_PipeClose()===
Stop all named pipe servers, keeping connections open.
;returns: 1 if no error occurred, 0 otherwise.

=== int BCI_TelnetListen( const char* address )===
Start a telnet server, listening at the given address. By opening a telnet connection, it is possible to execute [[User_Reference:Operator_Module_Scripting|scripting commands]] interactively.
Any number of telnet servers may be started listening on different addresses. If a telnet server is already running for a given
address, the request will be ignored, and 0 will be returned.
;arguments: Address as a string in <IP>:<port> format. May be NULL, in which case it defaults to "localhost:3999".
;returns: 1 if no error occurred, 0 otherwise.

=== int BCI_TelnetCloseOne( const char* address )===
Stop the telnet server that is listening at the given address.
If no telnet server is listening at the given address, 0 is returned.
;arguments: Address as a string in <IP>:<port> format.
;returns: 1 if a telnet server was listening at the given address, 0 otherwise.

=== int BCI_TelnetClose( void )===
Stop all telnet servers, while keeping open connections.
;returns: 1 if no error occurred, 0 otherwise.

=== int BCI_WebsocketListen( const char* address )===
Start a [https://en.wikipedia.org/wiki/WebSocket WebSocket] server, listening at the given address. By opening a WebSocket connection to ''ws://ip:port/'', it is possible to execute [[User_Reference:Operator_Module_Scripting|scripting commands]] and receive command results.
Any number of websocket servers may be started listening on different addresses. If a websocket server is already running for a given
address, the request will be ignored, and 0 will be returned.
;arguments: Address as a string in <IP>:<port> format. May be NULL, in which case it defaults to "localhost:3998".
;returns: 1 if no error occurred, 0 otherwise.

=== int BCI_WebsocketCloseOne( const char* address )===
Stop the websocket server that is listening at the given address.
If no websocket server is listening at the given address, 0 is returned.
;arguments: Address as a string in <IP>:<port> format.
;returns: 1 if a websocket server was listening at the given address, 0 otherwise.

=== int BCI_WebsocketClose( void )===
Stop all WebSocket servers, while keeping open connections.
;returns: 1 if no error occurred, 0 otherwise.

===int BCI_ExecuteScript( const char* script )===
Interprets and executes the specified script according to the [[User Reference:Operator Module Scripting|Operator scripting reference]].
;arguments: Null-terminated string specifying script commands.
;returns: 0 if a syntax error is present, 1 otherwise.

===const char* BCI_ExecuteScriptWithResult( const char* script )===
Interprets and executes the specified script according to the [[User Reference:Operator Module Scripting|Operator scripting reference]].
;arguments: Null-terminated string specifying script commands.
;returns: NULL if a syntax error is present, pointer to a null-terminated result string otherwise. The result string is allocated by the library, and should be released by the caller using BCI_ReleaseObject(). The result is always identical to the result of the last executed script command.

===void BCI_Log( int messageType, const char* message )===
Acts as if receiving the respective type of message from a module, i.e. typically calls the handler installed for that type of message.
;arguments: Type of message, which is one of BCI_LogMessage, BCI_Warning, BCI_Error, BCI_DebugMessage; null-terminated message string.

===int BCI_ReleaseObject( const char* )===
Indicate that an object that has been allocated by the library is no longer needed by the library's client.
;arguments: Object to be released, or NULL.
;returns: 1 if successful, 0 otherwise.

===const char* BCI_AllocateString( const char* )===
Allocate a copy of the given string on the Operator Library's heap.
;arguments: Pointer to a null-terminated string.
;returns: Pointer to a null-terminated copy of the argument string. The result is allocated by the library and should be released using <tt>BCI_ReleaseObject()</tt>.

===const char* BCI_GetPerThreadWD()===
Returns the current per-thread working directory stored inside the operator library, in UTF8-encoding.
The purpose of this command is to allow scripting commands implemented inside the library's caller to obtain the working directory that applies for the current script (see the <tt>BCI_OnUnknownCommand()</tt> callback).
;returns: Pointer to a null-terminated string containing the result. The result is allocated by the library, and should be released by the caller using <tt>BCI_ReleaseObject()</tt>.

===int BCI_SetPerThreadWD(const char*)===
Set the per-thread working directory stored inside the operator library.
The purpose of this command is to allow scripting commands implemented inside the library's caller to modify the working directory that applies for the current script (see the <tt>BCI_OnUnknownCommand()</tt> callback).
;arguments: Pointer to a null-terminated string defining the working directory, in UTF8-encoding.
;returns: 1 if successful, 0 otherwise.

===BCI_HandleAddRef(void* handle)===
Increments the use counter of the object referenced by a handle.
;arguments: A handle received from BCI_OperatorLib, e.g. as an argument to BCI_OnVisSignalHandle().

===BCI_HandleRelease(void* handle)===
Decrements the use counter of the object referenced by a handle, destroying the object when its use counter reaches zero.
;arguments: A handle received from BCI_OperatorLib, e.g. as an argument to BCI_OnVisSignalHandle().

===BCI_HandleGetSignalData(void* handle, int* channels, int* elements, double** pData)===
Gives access to data managed by a signal handle.
;arguments: A handle received from BCI_OperatorLib, e.g. as an argument to BCI_OnVisSignalHandle().
;returns: 1 if successful, 0 if not (e.g. the handle is invalid).

==See also==
[[User Reference:Operator Module Scripting]], [[Technical Reference:States of Operation]], [[Programming Reference:Debug Output]], [[Technical Reference:BCI2000Remote Library]]

[[Category:External Interfaces]]

User Reference:Operator Module Scripting

2026-08-09T16:04:41Z

Mellinger: /* START WEBSOCKET , STOP WEBSOCKET */

Operator scripts automate actions that the otherwise would be performed by the user, e.g. starting or suspending system operation.
Scripts may be contained in script files, or given immediately in the operator module's preferences dialog.
There is also an option to specify scripts from the [[User Reference:Module Command Line Options#Operator Module|command line]] when starting the operator module. When using the [[User_Reference:BCI2000Shell|BCI2000Shell]], or the [[Technical_Reference:Operator_Library|Operator Library]] from your own application, you may execute scripts at any time.

In addition, the operator scripting language may be used to control an operator module over a [[User_Reference:Module_Command_Line_Options#--Telnet|Telnet]] or [[User_Reference:Module_Command_Line_Options#--WebSocket|WebSocket]] connection.
===Syntax===
'''Command separation.''' Scripts consist of sequences of the commands listed below. A command must be terminated with either a newline, or a semicolon (;).
This allows to put multiple commands into one line, separated by semicolon characters.
Commands are case-insensitive, variables and values may be case-sensitive, depending on context.

'''Comments.''' Lines starting with a '#' character are ignored. Such lines may be used to hold comments. In addition, when any of the first two lines of a script contains "#!" (the Unix shell invocation sequence), it will be ignored. In conjunction with [[User Reference:BCI2000Shell|BCI2000Shell]], this may be used to write Operator scripts that may be treated as executables.

'''Escaping.''' In order to resolve ambiguity about command arguments that contain white space, they must be included in double quotes, or the white space must be encoded in URL-fashion, e.g. ''%20'' instead of a space character. Similarly, when an argument contains a semicolon (;), it must be included in double quotes, or the semicolon must be encoded in URL-fashion, i.e. as ''%3B''. Also, "$" characters indicate command substitution, so they should be encoded as ''%24'' if substitution is not desired.

'''Variable Substitution.''' When a command contains a dollar sign, alphanumeric characters following the dollar sign will be interpreted as the name of a variable: $NAME. The name will be matched against Expression variable names first, followed with Local variable names, and finally Environment variable names. When a match is found, $NAME will be replaced with the content of the matching variable. When no match is found, $NAME will be resolved to an empty string, without triggering an error.

'''Command Substitution.''' When part of a command is enclosed with ${...}, this subexpression will be substituted with the result of its execution as a command. E.g.,
LOG "Current system state is: ${GET SYSTEM STATE}"
LOG "The path environment variable is: ${PATH}"
Note that the last example uses the short form of the GET command, which will return the value of a PATH parameter or a PATH state if such exists. To make sure that only environment variables are matched, use the long form of the GET command:
LOG MESSAGE "The path environment variable is: ${GET VARIABLE PATH}"


'''Mathematical Expressions.''' A command may consist of a single [[User Reference:Expression Syntax|mathematical expression]]. This expression is then evaluated, and its result is returned as the command's result. As a special case, this allows the use of expression variables in ${...} substitutions. Consider for example
x:=0; WHILE x<10; LOG ${x:=x+1}; END
There, the first command creates and initializes the expression variable x. In the WHILE condition, an expression is allowed as well as any command. In the LOG command, an expression appears in ${...}, which executes the expression in braces, and substitutes the result of the expression as an argument into the LOG command, which adds an entry to the Operator log. This results in a sequence of 10 log entries, containing the numbers from 1 to 10.

===Commands===
====Control commands====
These commands allow conditional execution of parts of a script. When a condition is expected, any other scripting command may be given. Its result will be considered to represent a boolean value of "true" if it is empty, a nonzero number, or the string "true". It will be taken to represent a boolean value of "false" if it contains a numeric value of zero, or any string that does not evaluate to a nonzero number. Note that identification of an empty value with "true" differs from string handling in the EVALUATE CONDITION command. This is because most scripting commands return nothing on success, but an error message on failure.

The output of the SYSTEM and START EXECUTABLE commands is handled specially. There, the result code of the created child process is translated into a boolean value in the ordinary manner, treating a result code of zero as "true", and any other result code as "false". This allows to use external commands in the same way as in a native shell.

=====IF <condition>; <if commands>; [ ELSEIF <condition>; <elseif commands>;] ... [ ELSE; <else commands>;] END=====
Executes ''if commands'' if ''condition'' evaluates to "true". Otherwise, the ''elseif commands'' of the first matching ''elseif condition'' are executed. When none of the ''elseif conditions'' evaluates to "true", ''else commands'' are executed. ELSEIF and ELSE blocks may be omitted.

=====WHILE <condition>; <loop commands>; END=====
Executes ''loop commands'' while ''condition'' evaluates to ''true''.
=====DO; <loop commands>; UNTIL <condition>=====
Executes ''loop commands'' until ''condition'' evaluates to ''true''.

=====FOR <name> IN <item1> <item2> ... ; <loop commands>; END=====
Creates a local variable with the specified name. Then, sequentially assigns each ''item'' to that variable, and executes ''loop commands''. If an ''item'' contains newline characters, it is split up into multiple items, corresponding to the lines contained in the ''item''. E.g.,
FOR i IN top ${LIST FILES} bottom; LOG ${i}; END
will first write a log entry "top". Then, it will create a log entry for each file in the current directory, and finally, it will create a log entry "bottom".
=====RETURN [<value>]=====
Finishes execution of the current script, and optionally returns a value to the caller.

====Commands operating on Conditions====
=====EVALUATE CONDITION <left> [<op> [<right>]]=====
Evaluates a comparison between the ''left'' and ''right'' operands. As a comparison operator, the following may be specified: ==, !=, ~=, <, >, <=, >=. There, the != operator behaves identically to the ~= operator. When a test for equality is performed, the two operands are treated as strings, and compared in a case-insensitive manner. When any of the inequality tests is performed, the two operands are converted into floating-point numbers before comparison.

The ''right'' operand may be omitted, in which case it is treated as if an empty string were specified. Also, the ''op'' operator may be omitted, in which case the following rules apply regarding the remaining operand: If it is an empty string, or equal to the string "false" in case-insensitive comparison, the result is "false". If entirely consists of the text representation of a floating-point number, the result is "false" if the number is 0, and "true" if the number is not 0.

Inspired by the unix sh shells' <tt>test</tt> command, there exists a short form of the EVALUATE CONDITION command, where the arguments of EVALUATE CONDITION may appear within square brackets. This allows constructs such as
IF [ ${MyVar} == MyValue ]; LOG Is equal; ELSE; LOG Is different; END
Note that the arguments to EVALUATE CONDITION must always be separated by white space, no matter whether its long or short form is used.

Conditions may be combined logically using the operators && and ||. These go ''outside'' the square brackets. Note also that whitespace around the comparison operators is critical, otherwise the conditional will be treated as a single string (which will always evaluate to "true")

IF [ ${foo} == foo ] || [ ${bar} == bar ]; LOG got a match; END

====Commands operating on Local Variables====
Besides environment variables, there exist local variables in scripts. Local variables are inherited by sub-scripts executed with the EXECUTE SCRIPT command, but changes to the variable's values will not be propagated to the calling script.
=====SET VARIABLE <name> <value>=====
Sets the named variable to the specified value.
=====CLEAR VARIABLE <name>=====
Removes the named variable from memory.
=====GET VARIABLE <name>=====
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message generated.

====Commands operating on Environment Variables====
These scripting commands allow to read and modify environment variables. Changes to environment variables will be visible to child processes started with SYSTEM or START EXECUTABLE. Variable values are stored as strings. Variable names may not contain the equals sign.
=====SET ENVIRONMENT <name> <value>=====
Sets the named variable to the specified value.
=====CLEAR ENVIRONMENT <name>=====
Removes the named variable from memory.
=====GET ENVIRONMENT <name>=====
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.
=====WRITE ENVIRONMENT <fileName> <variableName1> <variableName2> ...=====
Writes a series of SET ENVIRONMENT statements to the specified file, overwriting any previous file contents. This saves the values of the named variables in such a way that you can later load them back by calling EXECUTE SCRIPT <filename>. The variable names may refer to either local or environment variables at the time of writing, but when you execute the script they will all be loaded as environment variables.
=====APPEND ENVIRONMENT <fileName> <variableName1> <variableName2> ...=====
This is the same as WRITE ENVIRONMENT, except that the SET ENVIRONMENT statements are appended to the named file without overwriting its previous contents.

====Commands operating on Scripts====
=====SET SCRIPT <handler names> <scripting commands>=====
Associates a sequence of scripting commands with the named handler. Handlers are specified by names as given [[#Handlers|below]]. Multiple handlers may be specified by concatenating their names with a pipe character, e.g. "OnStart|OnResume".

Scripting commands must be included in double quotes, unless they consist of a single word.
When specifying a sequence of scripting commands, they must be separated with a semicolon character: "SetConfig; Start". In order to use double quotes or semicolons within the commands themselves, encode these as you would in a URL, i.e. replace a double quote character with ''%22'', and a semicolon with ''%3B'': "Load Parameters %22my file%22".

To use a script file rather than a literal script, use the EXECUTE SCRIPT command:
SET SCRIPT OnConnect "EXECUTE SCRIPT myscript.txt"

=====GET SCRIPT <handler name>=====
Returns the script associated with the specified handler.

=====CLEAR SCRIPT <handler names>=====
Clears scripts for the given handlers. Equivalent to calling SET SCRIPT with an empty script.

=====EXECUTE SCRIPT <file or handler name> [<Arg1> <Arg2> ... <Arg9>]=====
Executes a script contained in a file, and optionally sets the script's local variables ''1'' to ''9'' to the specified values. To execute script commands already associated with a handler, provide a handler name rather than a file. When the script is executed successfully, the result of the last executed script command becomes the result of the EXECUTE SCRIPT command itself. Use "RETURN <value>" anywhere in a script in order to finish execution, and return a certain value.

When you run a script through EXECUTE SCRIPT, it will inherit copies of variables from its calling script/command line. Modifications of variables will be local to the script, and will be lost when script execution is complete.

The ''AbortOnError'' variable determines whether a script is aborted when any of its commands result in an error message. ''AbortOnError'' is not inherited but defaults to 1 in any script.

====Commands operating on Parameters====
=====LOAD PARAMETERFILE <file>, LOAD PARAMETERS <file>=====
Loads a parameter file specified by its path and name. Relative paths are interpreted relative to the operator module's working directory at startup. Usually, this matches the executable's location in the <tt>prog</tt> directory.
As the parameter file name must not contain white space, please use HTML-type encoding for white space characters, such as <tt>Documents%20and%20Settings</tt> when referring to a user's "Documents and Settings" folder.

NOTE: Only those parameters will be loaded that do exist at the time when this command is called. In idle state, no parameters exist other than created by ADD PARAMETER. After modules are connected and have published their parameters to the Operator module, a full set of parameters exists.

=====ADD PARAMETER <parameter definition>=====
Adds a parameter to the system. The parameter is specified as a [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.
=====EXISTS PARAMETER <name>=====
Returns "true" when the specified parameter exists in the system, and "false" otherwise.

=====ISEMPTY PARAMETER <name>=====
Returns "true" when the specified parameter exists and has no values, "false" if it exists and has values.

=====SET PARAMETER <name>[( idx1, idx2 )] <value>=====
Sets the named parameter to the specified value. Values that contain special characters, or whitespace must use the [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. Use parentheses to specify indices or labels. Omitted indices default to 1.

=====SET PARAMETER <parameter line>=====
Replace a parameter's value and definition with the information given in the [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. The parameter must exist in the system when this command is executed.

=====GET PARAMETER <name>[( idx1, idx2 )]=====
Prints the value of the named parameter. Use parentheses to specify indices or labels.

=====SET PARAMETERROWS <parameter name> <rows>=====
Sets the number of rows in the named parameter.

=====GET PARAMETERROWS <parameter name>=====
Prints the number of rows in the named parameter.

=====SET PARAMETERCOLS <parameter name>=====
Sets the number of columns in the named parameter.

=====GET PARAMETERCOLS <parameter name>=====
Prints the number of columns in the named parameter.

=====LIST PARAMETER <wildcard expression>, LIST PARAMETERS=====
Prints all parameters with names matching the wildcard expression, in form of parameter lines.
=====CLEAR PARAMETERS=====
Clears the list of parameters in the system. May only be executed in ''Idle'' and ''Publishing'' system states.

====Commands operating on States====
In BCI2000, there are three types of States that differ in their alignment to brain signal data (see [[Technical_Reference:State_Definition#Kinds_of_States|Kinds of States]]). This section applies to both Stream States, and normal States.
For Event States, see the next section.

=====ADD STATE <name> <bit width> <initial value>=====
Adds a state variable to the system. State variables are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.
=====EXISTS STATE <name>=====
Returns "true" when the specified state exists in the system, and "false" otherwise.

=====SET STATE <name> <value>, SET STATES <name1> <value1> <name2> <value2> ...=====
Sets the named state variable to the specified integer value by sending a state message to the source module.
Setting the ''Running'' state to 1 will start system operation, setting it to 0 will suspend the system.

<tt>SET STATES</tt> will atomically set the values of multiple states.

=====GET STATE[(<sample>)] <name>=====
Gets the value of the named state. Note that state values are not updated from the application module when the ''OperatorBackLink'' parameter is 0. In that case, GET STATE will return the state's initial value.

An optional one-based sample index may be given to indicate that the state value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.

By default, the state's value is retrieved for sample index 1.

=====LIST STATE <wildcard expression>, LIST STATES=====
Lists all states, or states with names matching the given wildcard expression, in form of state lines.
=====CLEAR STATES=====
Clears the list of states in the system. May only be executed in ''Idle'' and ''Publishing'' system states.

=====FREEZE STATES, THAW STATES=====
Freezes/thaws the values of all states in the state vector, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the state vector. For the duration of its existence, GET STATE calls will be diverted to the snapshot. This is useful for ensuring that multiple GET STATE commands actually retrieve mutually-consistent values from different state variables (i.e. values from the same sample-block).

=====GET STATEVECTOR SAMPLES=====
Returns the number of samples in the state vector per block of data. In the system's "Running" state, this matches the number of samples per block in the source data. Prior to the "Running" state, this command returns 1 because the state vector has not yet been updated from the application module.

====Commands operating on Events====
Events are a special type of state, which are recorded asynchronously, at single-sample resolution. Events may only be added while the system is in "idle" state. This kind of events is not related to [[#Handlers|Operator Events]] as defined below.
=====ADD EVENT <name> <bit width> <initial value>=====
Adds an event to the system. Like state variables, events are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after the system has started up, so it is typically executed in a batch file before ''STARTUP'' has been called.

=====EXISTS EVENT <name>=====
Returns "true" when the specified event exists in the system, and "false" otherwise.

=====SET EVENT <name> <value>=====
Asynchronously sets an event to the given value. Recording events requires the EventLink logger component to be present in the source module.

'''NOTE:''' In versions prior to BCI2000 3.06, this command behaved as described for PULSE EVENT below, rather than as advertised. If you used SET EVENT in your scripts, it is recommended to replace it with PULSE EVENT in order to retain original behavior.

=====PULSE EVENT <name> <value>=====
Asynchronously sets an event to the given value for a single sample duration. Recording events requires the EventLink logger component to be present in the source module.

=====SET EVENTS [<name> <value>] [<name2> <value2>] ... =====
Asynchronously sets given events to their specified values. Using this command, rather than multiple SET EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.

=====PULSE EVENTS [<name> <value>] [<name2> <value2>] ... =====
Asynchronously sets given events to their specified values for a single sample duration. Using this command, rather than multiple PULSE EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.

=====GET EVENT[(<sample>)] <name>=====
Gets the value of the named event. Note that evemt values are not updated from the application module when the ''OperatorBackLink'' parameter is 0.

An optional one-based sample index may be given to indicate that the event's value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.

By default, the event's value is retrieved for sample index 1.

=====LIST EVENT <wildcard expression>, LIST EVENTS=====
Lists all events, or events with names matching the given wildcard expression, in form of state lines.
=====CLEAR EVENTS=====
Clears the list of events in the system. May only be executed in ''Idle'' state.

====Commands operating on VisProperties====
=====SET VISPROPERTY <visID>.<name> <value>=====
Sets the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID to the given value. If the visualization ID contains a dot character, it must be encoded in [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. E.g., setting the window width for the visualization ID "2.D1" would be written <code>SET VISPROPERTY 2%2ED1.Width 200</code>.

=====RESET VISPROPERTY <visID>.<name>=====
Removes the named visualization property with the specified visualization ID from the property store, effectively resetting its value to its default.

=====GET VISPROPERTY <visID>.<name>=====
Prints the value of the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID.

=====SET VISPROPERTIES <property set ID>=====
Applies a set of visualization property values as given in the [[#VisPropertySets|VisPropertySets]] parameter. In that matrix-valued parameter, row labels specify visualization properties such as "SRCD.Left", and columns represent sets of property values. Column labels are IDs of the corresponding property sets.

====Commands operating on the Control Signal====
=====GET SIGNAL( <channel index>, <element index> )=====
Prints the value of the control signal at the given indices. Indices are 1-based.
=====GET SIGNAL CHANNELS=====
Prints the number of channels in the control signal.
=====GET SIGNAL ELEMENTS=====
Prints the number of elements (samples) in the control signal.
=====FREEZE SIGNAL, THAW SIGNAL=====
Freezes/thaws the contents of the control signal, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the control signal. For the duration of its existence, GET SIGNAL calls will be diverted to the snapshot. This is useful for ensuring that multiple GET SIGNAL commands actually retrieve mutually-consistent values from different elements in the control signal (i.e. values from the same sample-block).

====Commands operating on Expressions====
=====EVALUATE EXPRESSION <expression>=====
This command treats the remainder of the command as a literal mathematical expression (for a description, see [[User Reference:Expression Syntax]]). An expression may contain assignments to variables; such variables may then be used in later expressions. Note that expression variables are different from local and environment variables that may be accessed by GET/SET VARIABLE/ENVIRONMENT. Expression variables hold numerical values, while local and environment variables hold string values. Also, environment variables are accessible to child processes started with SYSTEM or START EXECUTABLE, while expression variables are accessible only to scripts. When a script is executed using the EXECUTE SCRIPT command, it will inherit a copy of all expression variables present. Changes to these variables from the executed script will not be visible in the parent script.

=====CLEAR EXPRESSION VARIABLE <name>=====
Clears the named expression variable from storage.

====Commands operating on Watches====
A "Watch" is an object that consists of a set of expressions, and an action. Whenever the value of any of the expressions changes, the watch is "triggered", and the action is executed. Watches allow client applications to respond to BCI2000 state changes in a reliable manner. Rather than polling information from BCI2000, a client may create a watch to be notified about changes of interest. This avoids the problem of missing short-lived changes, which is inherent in the polling approach.

For watches created through operator scripting, the action consists of dumping values of all the expressions to a UDP port.

The intended use of a watch from a client application is to create a separate thread that reads from the watch's UDP port in a blocking mode, and calls an appropriate handler function whenever it receives data.
The data sent will consist of a single UDP packet with a single line in ASCII format, terminated with a CRLF sequence. The line consists of tab-separated data fields, which contain the current values of the expressions specified when creating the watch. In addition, the first field contains a time stamp in milliseconds. This time stamp represents the point in time where the expression value changed, with an accuracy of a single sample.

=====ADD WATCH [decimate <n>] <expression1> <expression2> ... [AT <ip:port>]=====
Adds a watch for the listed expressions. Each expression's value will be reported in a separate field. When an address is specified in <tt>ip:port</tt> format, the watch tries to open that port for output, and creation fails if that port is taken. When no address is specified, a free port is chosen automatically. In both cases, successful creation of the watch is indicated by returning the output address in ASCII format. The address is also used to uniquely identify a watch in the context of a connection.

When a ''decimate <n>'' clause is present, the watch will be created with decimation, i.e. it will only be evaluated for every ''n''th
sample of the state vector.

If a watch is created through a remote connection, it will use the remote host's external IP address for automatically chosen addresses. Otherwise, the output port will be associated with the machine's <tt>localhost</tt> address.

Watches may be created even if the system is currently running. In this case, the watch is triggered immediately at creation, and sends its current expression values to its output port.

=====ADD WATCH SYSTEM STATE [AT <address>]=====
Similar to the first variant of ADD WATCH, but will watch the system's state as reported by GET SYSTEM STATE.

=====CLEAR WATCH <address>, CLEAR WATCHES [<wildcard-expression>]=====
Removes the watches specified by address, or those with their addresses matching a wildcard expression. If CLEAR WATCHES is called without argument, all watches will be deleted.

=====TRIGGER WATCH <address>, TRIGGER WATCHES [<wildcard-expression>]=====
Forces dumping of the watches' current expression values to their output ports. Mostly useful for testing purposes.

=====LIST WATCHES [<wildcard-expression>]=====
Displays a list of existing watches, and their addresses.

=====COUNT WATCHES [<wildcard-expression>]=====
Returns the number of existing watches, or the number of watches whose addresses match the optional wildcard expression.

====Commands operating on Files, Directories, and Paths====
=====EXTRACT DIRECTORY <path>, EXTRACT FILE <path>, EXTRACT FILE BASE <path>=====
Extracts the directory or file portion of a given path. When the path specifies a non-existing directory, the directory name must be followed with a separator ("/") in order to be recognized as a directory. The EXTRACT DIRECTORY command always returns its result with a trailing separator. The EXTRACT FILE BASE command returns the file portion without extension.

=====IS DIRECTORY <path>, IS FILE <path>, IS PATH <path>=====
Determines whether the specified path points to an existing directory, file, or any of the two. The result is returned as one of the strings "true" or "false".
=====PARENT DIRECTORY <path>=====
Returns the parent directory of the specified path, independently of whether the path points to a directory, or to a file.
=====CURRENT DIRECTORY=====
Returns the current working directory. Note that working directories are per-script, i.e. multiple scripts running in parallel may have different working directories.

=====CHANGE DIRECTORY <path>=====
Changes the script's working directory. Note that working directories are per-script, i.e. multiple scripts running in parallel may have different working directories. Also, this command will only affect the default directory of scripting commands, not the application-global working directory as seen by the OS.

=====MAKE DIRECTORY <path>=====
Creates a new directory with the given path. The directory's parent must exist for the command to succeed.
=====LIST DIRECTORY [<path> or <wildcard expression>]=====
Returns a listing of the specified directory, or the current working directory if no path is specified. The listing is in long form. You may use wildcard expressions in order to restrict the output.
=====LIST FILE <wildcard expression>=====
Returns a list of file names matching ''wildcard expression'' in the current directory.
=====LIST FILES [<directory> [<wildcard expression>]]=====
Returns a list of file names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all files are listed. When ''directory'' is missing, files in the current directory are listed.
=====LIST DIRECTORIES [<directory> [<wildcard expression>]]=====
Returns a list of directory names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all directories are listed. When ''directory'' is missing, directories in the current directory are listed.

=====RENAME FILE <current path> <new path>, RENAME DIRECTORY <current path> <new name>=====
Renames a file resp. a directory. For files, a different path may be given in the second argument, resulting in that the file is moved to the location specified by the new path. For directories, the path up to the directory's name must stay the same.
=====REMOVE FILE <path>, REMOVE DIRECTORY <path>=====
Removes the specified file or directory. This command cannot be undone. The directory must be empty for the command to succeed.
=====FORCEREMOVE DIRECTORY <path>=====
Removes the specified directory and its contents. Symbolic links are treated as ordinary files, i.e. they are not followed. This command cannot be undone.
=====NORMALIZED PATH <path>=====
Returns <path>, with the following transformations applied:
*Removes relative elements (<tt>..</tt> <tt>.</tt>) as far as possible. For absolute paths, the result will not contain any relative elements; for relative paths, double-dots may appear at the beginning of the result if necessary.
If a relative path simplifies to the empty string, <tt>./</tt> is returned. Thus, the result of NORMALIZED PATH is never empty, unless its input was empty.
*Replaces backward slashes with forward slashes to achieve uniformity across platforms.
*On case-insensitive file systems, replaces the spelling of names with the one stored in the file system.
*On Win32, replaces short (8.3) names with long ones.

=====CANONICAL PATH <path>=====
If <path> points to an existing file or directory, CANONICAL PATH returns a valid absolute file path, suitable as an unambiguous representation for the object pointed to. Especially, two non-empty canonical path strings will compare equal if and only if they refer to the same file system object.

If <path> does not point to an existing file system object, construction of a canonical path is not possible due to lack of information about the named object, and CANONICAL PATH will return an empty string.

'''NOTES:''' The need for an unambiguous, or canonical, representation arises due to ambiguities in the string representation of paths, and in file systems themselves.
*Paths may contain relative elements: <tt>/mydir/../myfile</tt> points to the same object as <tt>/myfile</tt>.
*A path that involves symbolic links will point to the same object as a path containing one or more of those links in resolved form.
*File systems may be case-insensitive, or may even provide multiple distinct names for individual directory entries (Win32 short vs. long names).

On '''Win32,''' CANONICAL PATH returns the short (8.3) representation of a path, using uppercase spelling, and backslashes as directory separators. Apart from efficiency considerations, this aesthetically unpleasing representation has been chosen to discourage its use for anything except comparing file system objects.

On '''other systems,''' CANONICAL PATH will return the result of the POSIX <tt>realpath()</tt> function.

In both cases, a CANONICAL PATH will end with a native directory separator if, and only if, the object pointed to is a directory.

=====REAL PATH <path>=====
On this command provides a work-alike for the POSIX <tt>realpath()</tt> function.
If <path> is empty, or if <path> points to a non-existing object, the result will be empty. Otherwise, an absolute path will be returned, with symbolic links resolved, using forward slashes as directory separators, and with spelling normalized as described for NORMALIZED PATH. A forward slash will be appended if the path points to a directory.

'''NOTE:''' In principle, the path returned by REAL PATH should be just as unambiguous as the result of CANONICAL PATH. However, there are a few caveats:
* On case-insensitive file systems, two independently obtained results of REAL PATH might differ in case spelling even if referring to the same file system object. This should not be the case for CANONICAL PATH.
* Determining the result of CANONICAL PATH is a fast operation. In contrast, REAL PATH may be expensive to determine, as for each directory on the path a listing needs to be obtained, and a canonical path needs to be formed, and compared, for half of the listed directory entries on average.
* On Win32, quite some amount of complexity arises from backward compatibility layers, forbidden file names, multiple filesystem roots, etc. Internally calling <tt>GetShortPathName()</tt>, CANONICAL PATH does not need to handle that complexity, and may be considered more reliable for identifying file system objects than REAL PATH.

=====READ FILE <filename>=====
Returns the text content of the file indicated by <filename>.

=====WRITE FILE <filename> <line>, OVERWRITE FILE <filename> <line>, APPEND TO FILE <filename> <line>=====
These commands write the specified <line> of text to the file indicated by <filename>. They behave like the <tt>echo</tt> command of a typical shell, in the sense that a line-ending will be automatically added to the <line> if it does not already end with one. To suppress the automatic line-ending, you can say WRITE FILE <filename> <content> WITHOUT LINE ENDING (or equivalently, for short, you can say WITHOUT LF or WITHOUT CRLF). Any previous content in <file> will be lost if you use WRITE or OVERWRITE (they are the same, just synonyms for each other) whereas APPEND preserves previous content and adds the new <line> to the end.

====Commands operating on executables====
=====START EXECUTABLE <command line>=====
Behaves identically to CREATE PROCESS, except that it does not report a process id for the new process. For details, see CREATE PROCESS.

=====CATEGORIZE EXECUTABLE <name or path>=====
BCI2000 keeps a list of executables/modules that have been built, and sorts them into categories. The CATEGORIZE EXECUTABLE command provides a way to retrieve that information. Given the name or path of an executable, it outputs one of the following categories:
* SignalSource,
* SignalProcessing,
* Application,
* Operator,
* Tool,
* Helper,
* Unknown.

====Commands operating on Lines of input/output====
=====WRITE LINE <line>=====
Writes a line of output. Destination depends on the context in which a script is executed. If the context is an Operator Handler, output is written as a log entry. If the context is a telnet session, output is written to the telnet connection. If the context is a [[User Reference:BCI2000Shell|BCI2000Shell]], output is written to the shell's stdout.

=====READ LINE=====
Reads a line of input from the current execution context's input. If the command is executed within an Operator Handler, it will fail. If executed within a telnet session, the other side of the connection is prompted for input. If executed from within a [[User Reference:BCI2000Shell|BCI2000Shell]], input is read from the shell's stdin.

====Commands operating on Processes in the Operating System====
=====CREATE PROCESS <command line>=====
Starts the specified executable with options. This command returns after the started program has finished initialization, i.e. it will detect load time failures such as missing DLLs on Windows. If the process is still running when CREATE PROCESS returns, its result will be an operating system process id (pid). If the process has terminated, CREATE PROCESS will report its exit code marked with an <tt>ExitCode</tt> tag to allow distinction between a pid and an exit code.
Please note that CREATE PROCESS requires quoting of arguments differently from other scripting commands. For details, see the SYSTEM command.

=====TERMINATE PROCESS <pid>=====
Tries to terminate the process with the given operating system pid, waiting for the process to terminate before returning. Will return <tt>false</tt> to indicate that a suitable process existed but could not be terminated.

=====WAIT FOR PROCESS <pid> [<timeout seconds> = infinite]=====
Waits for the process with the given operating system pid to terminate, or the timeout to expire. Returns <tt>false</tt> to indicate that the process is still executing.

=====SHOW PROCESS <pid>=====
Makes all windows visible which are associated with the process referred to by pid.
In addition, brings one of the process' top level (desktop level) windows to the front for user interaction.

=====HIDE PROCESS <pid>=====
Makes all windows invisible which are associated with the process referred to by pid.

====Global commands====
=====HELP [<type>]=====
When called with a type argument, lists commands that exist for the specified type (e.g., SYSTEM, or FILE). When called without argument, lists all commands in their main form. HELP ALL will list all commands, including synonyms.

=====SET <name> <value>, GET <name>, <name>=====
Allows to set or retrieve the value of local and environment variables. The name is matched against local and environment variables. When no variable with the given name is found, SET will create a local variable, while GET will result in an error. GET may be further abbreviated to only consist of a name.

GET further allows evaluation of [[User_Reference:Expression_Syntax|mathematical expressions]]. When the expression is invalid, or contains an unknown variable, an error is triggered.

=====GET SYSTEM STATE=====
Prints the current system state. This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy (for details, see the WAIT FOR command below).

=====GET CURRENT RUN FILE=====
Prints the full path to the current run file, or an empty string, if called outside Running state.

=====WAIT FOR <system state> [<timeout seconds>]=====
Waits until the system is in the specified state. This may be one of Idle, Startup, Connected, Resting, Suspended, ParamsModified, Running, Busy, or a combination of these, separated with a pipe character: "Resting|Suspended". When no timeout is given, this command waits indefinitely. If the wait is successful, i.e. system state matches one of the specified states, WAIT FOR will return a value of "true". If timeout occurred, WAIT FOR will return "false".

If the BCI2000 system is shut down while a script is executing a WAIT FOR command, the script will be terminated with a "wait aborted" error message.

In more detail, user visible states are:
* Idle: System is shut down and does not do other processing than executing scripts.
* Startup: System has started up and is listening for incoming connections.
* Connected: All core modules have connected to the system.
* Resting: The system has been initialized but is not running.
* Suspended: The system has ended running and is behaving like in Resting.
* ParamsModified: In Suspended mode, parameter changes have been published and will be applied at Resume.
* Running: The system is running, processing brain signals, and displaying stimuli.
* Busy: The system is performing a transition from one state to another.

As a synonym for "Connected," "Initialization" is valid as well since it is compatible with the nomenclature in StateMachine.h. Still, it should be avoided because it is easily confused with, but very distinct from, the actions performed in the Initialize() phase.

=====SLEEP <time in seconds>=====
Waits (sleeps) for the given amount of time. Timing resolution is 50ms. Tends to sleep a little longer than specified, with the error growing with duration.

=====GET SYSTEM VERSION=====
Prints BCI2000 version information.
=====SETCONFIG, SET CONFIG=====
Applies current parameters to the system. Corresponds to the ''SetConfig'' button in the GUI version of the Operator module.

=====START=====
Starts or resumes system operation, corresponding to the ''Start/Resume'' button in the GUI version of the Operator module.
=====STOP=====
Stops system operation. Corresponds to the ''Stop'' button in the GUI version of the Operator.
=====STARTUP SYSTEM=====
When in idle state, starts up the system to wait for incoming connections from core modules. Additionally, the following arguments may be given: 1) an IP address on which to listen (default is to listen on all addresses), and 2) a list of generic core module names with ports. The default configuration corresponds to these arguments:
STARTUP SYSTEM * SignalSource:4000 SignalProcessing:4001 Application:4002

A system log file may optionally be specified on this line, by inserting the <code>--SystemLogFile</code> flag between the IP address and the module specifiers. For example:

STARTUP SYSTEM * --SystemLogFile=SOME_FILE.TXT SignalSource:4000 SignalProcessing:4001 Application:4002

The system log file will record all operator log window messages for the current launch, until the system shuts down. It may be helpful to use the variables <code>$YYYYMMDD</code> and <code>$HHMMSS</code> to specify the filename. Note that file name and path cannot contain spaces.

=====SHUTDOWN SYSTEM=====
Shuts down core modules, and enters idle system state.
=====RESET SYSTEM=====
Shuts down the system, and clears all parameter, state, and event information.

=====QUIT, EXIT [<result>]=====
Quits the operator module after terminating all BCI2000 modules. The optional ''result'' argument determines the result of the executed script.

=====CLOSE CONNECTION, TERMINATE CONNECTION=====
In the context of a telnet or websocket connection, this command will terminate the connection.
In other contexts, such as event handlers, it will be ignored.

=====SYSTEM <command line>=====
Executes a shell command, redirecting any console output into the command's script result. E.g., to obtain a directory listing, under Windows, you would enter
SYSTEM DIR
'''NOTE:''' Arguments to the SYSTEM command are executed by the operating system's shell, and thus may require quoting different from the other scripting commands. E.g., writing
SET mydir ${PARENT DIRECTORY $BCI2000LAUNCHDIR}; ECHO ${LIST FILES $mydir}
will list files in the BCI2000 main directory, independently of whether the path to that directory contains space characters or not. However, to obtain a directory listing through the SYSTEM command, you would need to write
ECHO ${SYSTEM DIR "$mydir"}
to make sure the content of the variable ''mydir'' is interpreted as a single argument, independently of whether it contains space characters.

=====LOG <message>=====
Append the specified message to the system log.
=====WARN <message>=====
Append the specified message to the system log, formatted as a warning.
=====ERROR <message>=====
Append the specified message to the system log, formatted as an error message.

=====CAPTURE MESSAGES <message types>=====
Captures system log messages into a background buffer. When no message type is given, all messages are captured. When "None" is given as a message type, message capturing is disabled. Otherwise, the message type must be one of "Errors", "Warnings", "Debug", "Log". Multiple message types may be specified in a single command. When "None" appears within a single command, all preceding message types are ignored. Multiple CAPTURE MESSAGES commands are cumulative, except when "None" is specified as a message type.

=====FLUSH MESSAGES=====
Clears the background message buffer, and returns its previous content. Use CAPTURE MESSAGES to capture messages into the background message buffer.

====Operator-module defined Commands====
=====HIDE WINDOW [<name>], SHOW WINDOW [<name>]=====
Hides or shows the specified window. When called without a window name, the Operator module's main window is hidden or shown. The window name may be one of Main, Configuration, Log, Watches, and Visualizations. When "Watches" is given, the window state refers to visibility of the Watches area in the Visualizations window.

=====MOVE WINDOW <name> <x> <y>, RESIZE WINDOW <name> <width> <height>=====
Moves resp. resizes the specified window with one of the above names.
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height.

=====ARRANGE WINDOW <name> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====
Arranges the named window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.

Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column.
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.
Likewise, a ''colspan'' of 0 will result in the window's minimum width.

If multiple screens are present, windows are arranged on the screen that contains the Operator window.

=====SET TITLE <title>=====
Sets the title of the main Operator window.
=====SET BUTTON <idx> <label> <commands>=====
Configures the function button with 1-based index ''idx'' such that it is labelled ''label'' and executes ''commands''.

=====VISUALIZE WATCH [decimate <n>] [range <min> <max>] <expression1> ...=====
Adds a watch for the given expressions to the operator module's Watches window, and makes the Watches window visible if it is hidden. If the ''decimate'' clause is present, the command will create a watch which will be evaluated only for every ''n''th sample in the state vector. If the ''range'' clause is present, display minimum and maximum will not be adjusted automatically but will be fixed to the values given.

By default, ''decimate'' has a value of "auto"; this means that there is no decimation of evaluation (i.e., all samples are evaluated) but changes that occur within 1ms will be shortened into their maximum and minimum, and thus reported as only two values.
This has proven to be efficient for avoiding sluggishness from flooding the application with events.

=====MOVE VISUALIZATON <visID> <x> <y>, RESIZE VISUALIZATION <visID> <width> <height>=====
Moves resp. resizes the specified visualization window.
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height. If unknown, visualization IDs may be obtained from the Operator's ''Window->Visualizations'' menu.

=====ARRANGE VISUALIZATION <visID> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====
Arranges the named visualization window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.

Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column.
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.
Likewise, a ''colspan'' of 0 will result in the window's minimum width.

If multiple screens are present, windows are arranged on the screen that contains the Operator window.

=====RECORD VISUALIZATION <visID> [on|off]=====
Registers the named visualization for recording. The visualization name must be the short name as displayed in the ''View->Visualizations'' menu. Switching a visualization recording to "on" is only possible in idle state (because an event for recording frame numbers must be registered in the system). When a visualization is registered for recording, its frames are stored immediately as they arrive at the operator module. Currently, only bitmap visualizations may be recorded.

Example: Recording the application window
RECORD VISUALIZATION ApplicationWindow on
...
# after parameters have been loaded
Set parameter VisualizeApplicationWindow 1
...

=====PUT NOTE <note>=====
Adds the given text to the [[User_Reference:Operator_Notes#Taking_Notes_during_recording_in_Operator|notes window]].
If the system is in ''Running'' state, the text will also be added to the current notes file as described under
[[User_Reference:Operator_Notes#Note_storage_and_file_format|"notes file"]].

=====START TELNET [<address>], STOP TELNET [<address>]=====
Starts or stops a telnet server listening at the given address. The address is in <IP>:<port> format. The default address is 127.0.0.1:3999.

'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed. Only use addresses in the local network, such as 10.x.x.x, 172.x.x.x, or 192.168.x.x.

=====START WEBSOCKET [<address>], STOP WEBSOCKET [<address>]=====
Starts or stops a websocket server listening at the given address. The address is in <IP>:<port> format. The default address is 127.0.0.1:3998.

'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed. Only use addresses in the local network, such as 10.x.x.x, 172.x.x.x, or 192.168.x.x.

====Operator-module Commands for Soliciting Input from the User====

=====CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====
Via the Qt graphical user interface, prompt the user to select an existing file (or multiple files, if the keyword FILES is used). Print the resulting file path(s).
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

=====CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====
Via the Qt graphical user interface, prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

=====CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]=====
Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

=====CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ... =====
Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

===Predefined Variables===
The following variables exist when an Operator script is executed.
Some of these variables are marked with ''local''. This means that they are not environment variables, i.e. they are invisible to child processes that are launched using the SYSTEM or START EXECUTABLE commands, and their values may be different between script invocations. In script code, they are accessed like ordinary variables.
====BCI2000LAUNCHDIR====
The full absolute path to the directory where the Operator module resides. This is also prepended to the PATH environment variable, such that executables from the current BCI2000 installation will have precedence over any other executable with the same name.

On macOS, this is the path where the Operator module's application bundle resides. In the default configuration, this is the BCI2000 prog directory, both on macOS and on other platforms.

====BCI2000BINARY====
The full absolute path to the Operator module.
====LogLevel (local)====
Determines the amount of log information written to the Operator log. This variable only affects log messages originating from the current script. May be 2 (display all log messages), 1 (display fewer log messages), or 0 (suppress all log messages). Set to 1 by default. Changes to this local variable are not propagated to any sub-scripts called. ''NOTE:'' Only log messages are controlled by this variable. Error messages originating from a script with 'LogLevel 0' will still be displayed in the Operator log. When 'AbortOnError' is set to 0, you may set 'LogLevel' to -1 in order to display error messages. When 'AbortOnError' is 1 (the default), error messages will always be displayed to indicate the reason for failure.

====AbortOnError (local)====
Determines if a script is aborted when an error happens, or whether the error is silently ignored. Set to 1 by default (script is aborted on error). Changes to this local variable are not propagated to any sub-scripts called.

====Result (local)====
The result of the last executed scripting command. When a script is executed by calling EXECUTE SCRIPT, the script's last executed command determines the result of the EXECUTE SCRIPT command itself.

====0, 1, ... 9 (local)====
When a script file is being executed, these variables contain the arguments of the EXECUTE SCRIPT command.
''$0'' resolves to the full absolute path to the current script file. Within scripts, all of the ''0-9'' variables are defined, and those that do not have a matching argument are empty.

====YYYYMMDD (local)====
Local time at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.

====HHMMSS (local)====
Local time at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.

===Abbreviated commands and synonyms===
To minimize the need of consulting documentation, as well as for backward compatibility, a number of '''synonymous commands''' are provided. E.g., states may be added by INSERT STATE as well as ADD STATE, and the existence of a file may be queried by IS FILE as well as EXISTS FILE. For an overview over all allowed forms of commands, use the HELP ALL command.

To simplify operation in interactive sessions, '''abbreviated commands''' exist. Currently, these are:
:'''cd''' for CHANGE DIRECTORY,
:'''pwd''' and '''cd''' without argument for CURRENT DIRECTORY,
:'''ls''' and '''dir''' for LIST DIRECTORY,
:'''mkdir''' for MAKE DIRECTORY,
:'''echo''' for WRITE LINE,
:'''realpath''' for REAL PATH,
:'''dirname''' for EXTRACT DIRECTORY,
:'''basename''' for EXTRACT FILE BASE.

===Handlers===
In the Operator GUI, script execution is bound to a number of Operator Events (not to be confused with Event states, above) that occur during various [[Technical Reference:States of Operation|stages of BCI2000 system operation]]:
====OnConnect====
This handler runs at startup, as soon as all modules are connected to the operator module.
====OnSetConfig====
This handler runs each time a set of parameters is applied to the system. This happens when the user clicks the ''SetConfig'' button. Execution of the ''SETCONFIG'' command also runs this handler.

====OnStart, OnResume====
These handlers are triggered by the ''Start''/''Resume'' button. One of these handlers is also triggered when the ''Running'' state variable is set to 1 from a script. Whether ''OnStart'' or ''OnResume'' is triggered depends on whether the system has been running before with the current set of parameters.

====OnStartRun====
Similarly to OnStart and OnResume, this handler is triggered by the ''Start''/''Resume'' button. Unlike other event handlers, OnStartRun has an argument, which is the current run file.

OnStart or OnResume are triggered immediately after ''Start''/''Resume'' has been pressed, whereas OnStartRun is deferred until modules have confirmed to be in Running state. This makes sure that the OnStartRun event handler receives a valid run file name.

====OnNextFilePart====
This handler is triggered during a run, whenever the ''FilePart'' event state is incremented. It allows scripts to know when a new
partial file has begun. For further information, see the [[User_Reference:BCI2000FileWriter#FileSplittingCondition|FileSplittingCondition]] parameter.

====OnSuspend/OnStopRun====
Triggered when the system goes from running into suspended mode. This happens whenever the ''Running'' state variable changes from 1 to 0. This may happen when the user clicks ''Suspend'', when the application module switches the system into suspended mode, or when a script sets the ''Running'' state variable to 0.

====OnShutdown====
Triggered when the operator module shuts down connections, and switches into idle state.

====OnExit====
Triggered when the operator module exits. Execution of the QUIT command also triggers this handler. This handler is not available to the SET SCRIPT and CLEAR SCRIPT commands. Also, when both an OnShutdown and an OnExit script are defined, the OnExit script may be executed before the OnShutdown script.

====Associating Scripts with Operator Events====
In the operator module's preferences dialog, script commands may be entered for each of the handlers listed above.
Scripts may be specified as paths to script files, or as immediate one-line scripts.
Entries that start with a minus sign (-) are treated as one-line scripts, which may contain multiple commands separated with semicolons.

Scripts may also be specified from the command line used to start up the operator module. There, handler names are followed with the content of the respective preference entry, enclosed in double quotes ("...").

Finally, scripts may be specified using the SET SCRIPT command of the scripting language itself.

===Examples===
====Making use of the Operator module's Function Buttons====
To add a state variable called "Artifact", and to set it using the operator's function buttons, do this:
*Enter the following line under "After All Modules Connected" in the operator's preferences dialog (note the minus sign):
-ADD STATE Artifact 1 0
*Under "Function Buttons", enter "Set Artifact" as the name of button 1, and as its command, enter (note there is no minus sign):
SET STATE Artifact 1
*Enter "Clear Artifact" as the name of button 2, and as its command, enter
SET STATE Artifact 0

====A fully automated BCI2000 session====
<pre>
Echo Please enter a subject ID:
Set SubjectID ${Read line}

Startup system
Start executable SignalGenerator
Start executable SpectralSignalProcessing
Start executable CursorTask
Wait for Connected
Load parameterfile "../parms/examples/CursorTask_SignalGenerator.prm"
For i in 1 2 3
Load parameterfile "../parms/MyExperiment/Session$i.prm"
Set parameter SubjectName $SubjectID
Set parameter SubjectSession $i
Set config
Wait for Resting
Start
Wait for Suspended 1000
End
</pre>

====Automating BCI2000 by Operator command line arguments====
The following example shows how to specify script commands from the command line.
It fully automates BCI2000 operation by loading a parameter file, applying parameters, starting the system once the parameters are applied, and quitting the system once the run is over. For better readability, the example is broken across lines, using the ^ DOS line continuation character.

operator.exe --OnConnect "-LOAD PARAMETERFILE ../parms/examples/CursorTask_SignalGenerator.prm; SETCONFIG" ^
--OnSetConfig "-SET STATE Running 1" ^
--OnSuspend "-QUIT"

====Automatically arranging windows in a 4x2 grid====
The following example arranges Source and Roundtrip visualizations on the left side of the screen.
On the right side, a large area is dedicated to the Operator's log window, and the Operator's main window sits at the bottom right.

Arrange Visualization SRCD 4 2 1 1 2 1
Arrange Visualization RNDT 4 2 3 1
Arrange Window Main 4 2 4 2
Arrange Window Log 4 2 1 2 3 1

[[File:Operator_Arrangement.PNG|center|640px|border]]

==See also==
[[User Reference:Module Command Line Options]], [[User Reference:Operator Module]], [[User Reference:BCI2000Shell]], [[Technical Reference:States of Operation]]

[[Category:User Interface]]

User Reference:Operator Module Scripting

2026-08-09T16:03:33Z

Mellinger: /* START TELNET , STOP TELNET */

Operator scripts automate actions that the otherwise would be performed by the user, e.g. starting or suspending system operation.
Scripts may be contained in script files, or given immediately in the operator module's preferences dialog.
There is also an option to specify scripts from the [[User Reference:Module Command Line Options#Operator Module|command line]] when starting the operator module. When using the [[User_Reference:BCI2000Shell|BCI2000Shell]], or the [[Technical_Reference:Operator_Library|Operator Library]] from your own application, you may execute scripts at any time.

In addition, the operator scripting language may be used to control an operator module over a [[User_Reference:Module_Command_Line_Options#--Telnet|Telnet]] or [[User_Reference:Module_Command_Line_Options#--WebSocket|WebSocket]] connection.
===Syntax===
'''Command separation.''' Scripts consist of sequences of the commands listed below. A command must be terminated with either a newline, or a semicolon (;).
This allows to put multiple commands into one line, separated by semicolon characters.
Commands are case-insensitive, variables and values may be case-sensitive, depending on context.

'''Comments.''' Lines starting with a '#' character are ignored. Such lines may be used to hold comments. In addition, when any of the first two lines of a script contains "#!" (the Unix shell invocation sequence), it will be ignored. In conjunction with [[User Reference:BCI2000Shell|BCI2000Shell]], this may be used to write Operator scripts that may be treated as executables.

'''Escaping.''' In order to resolve ambiguity about command arguments that contain white space, they must be included in double quotes, or the white space must be encoded in URL-fashion, e.g. ''%20'' instead of a space character. Similarly, when an argument contains a semicolon (;), it must be included in double quotes, or the semicolon must be encoded in URL-fashion, i.e. as ''%3B''. Also, "$" characters indicate command substitution, so they should be encoded as ''%24'' if substitution is not desired.

'''Variable Substitution.''' When a command contains a dollar sign, alphanumeric characters following the dollar sign will be interpreted as the name of a variable: $NAME. The name will be matched against Expression variable names first, followed with Local variable names, and finally Environment variable names. When a match is found, $NAME will be replaced with the content of the matching variable. When no match is found, $NAME will be resolved to an empty string, without triggering an error.

'''Command Substitution.''' When part of a command is enclosed with ${...}, this subexpression will be substituted with the result of its execution as a command. E.g.,
LOG "Current system state is: ${GET SYSTEM STATE}"
LOG "The path environment variable is: ${PATH}"
Note that the last example uses the short form of the GET command, which will return the value of a PATH parameter or a PATH state if such exists. To make sure that only environment variables are matched, use the long form of the GET command:
LOG MESSAGE "The path environment variable is: ${GET VARIABLE PATH}"


'''Mathematical Expressions.''' A command may consist of a single [[User Reference:Expression Syntax|mathematical expression]]. This expression is then evaluated, and its result is returned as the command's result. As a special case, this allows the use of expression variables in ${...} substitutions. Consider for example
x:=0; WHILE x<10; LOG ${x:=x+1}; END
There, the first command creates and initializes the expression variable x. In the WHILE condition, an expression is allowed as well as any command. In the LOG command, an expression appears in ${...}, which executes the expression in braces, and substitutes the result of the expression as an argument into the LOG command, which adds an entry to the Operator log. This results in a sequence of 10 log entries, containing the numbers from 1 to 10.

===Commands===
====Control commands====
These commands allow conditional execution of parts of a script. When a condition is expected, any other scripting command may be given. Its result will be considered to represent a boolean value of "true" if it is empty, a nonzero number, or the string "true". It will be taken to represent a boolean value of "false" if it contains a numeric value of zero, or any string that does not evaluate to a nonzero number. Note that identification of an empty value with "true" differs from string handling in the EVALUATE CONDITION command. This is because most scripting commands return nothing on success, but an error message on failure.

The output of the SYSTEM and START EXECUTABLE commands is handled specially. There, the result code of the created child process is translated into a boolean value in the ordinary manner, treating a result code of zero as "true", and any other result code as "false". This allows to use external commands in the same way as in a native shell.

=====IF <condition>; <if commands>; [ ELSEIF <condition>; <elseif commands>;] ... [ ELSE; <else commands>;] END=====
Executes ''if commands'' if ''condition'' evaluates to "true". Otherwise, the ''elseif commands'' of the first matching ''elseif condition'' are executed. When none of the ''elseif conditions'' evaluates to "true", ''else commands'' are executed. ELSEIF and ELSE blocks may be omitted.

=====WHILE <condition>; <loop commands>; END=====
Executes ''loop commands'' while ''condition'' evaluates to ''true''.
=====DO; <loop commands>; UNTIL <condition>=====
Executes ''loop commands'' until ''condition'' evaluates to ''true''.

=====FOR <name> IN <item1> <item2> ... ; <loop commands>; END=====
Creates a local variable with the specified name. Then, sequentially assigns each ''item'' to that variable, and executes ''loop commands''. If an ''item'' contains newline characters, it is split up into multiple items, corresponding to the lines contained in the ''item''. E.g.,
FOR i IN top ${LIST FILES} bottom; LOG ${i}; END
will first write a log entry "top". Then, it will create a log entry for each file in the current directory, and finally, it will create a log entry "bottom".
=====RETURN [<value>]=====
Finishes execution of the current script, and optionally returns a value to the caller.

====Commands operating on Conditions====
=====EVALUATE CONDITION <left> [<op> [<right>]]=====
Evaluates a comparison between the ''left'' and ''right'' operands. As a comparison operator, the following may be specified: ==, !=, ~=, <, >, <=, >=. There, the != operator behaves identically to the ~= operator. When a test for equality is performed, the two operands are treated as strings, and compared in a case-insensitive manner. When any of the inequality tests is performed, the two operands are converted into floating-point numbers before comparison.

The ''right'' operand may be omitted, in which case it is treated as if an empty string were specified. Also, the ''op'' operator may be omitted, in which case the following rules apply regarding the remaining operand: If it is an empty string, or equal to the string "false" in case-insensitive comparison, the result is "false". If entirely consists of the text representation of a floating-point number, the result is "false" if the number is 0, and "true" if the number is not 0.

Inspired by the unix sh shells' <tt>test</tt> command, there exists a short form of the EVALUATE CONDITION command, where the arguments of EVALUATE CONDITION may appear within square brackets. This allows constructs such as
IF [ ${MyVar} == MyValue ]; LOG Is equal; ELSE; LOG Is different; END
Note that the arguments to EVALUATE CONDITION must always be separated by white space, no matter whether its long or short form is used.

Conditions may be combined logically using the operators && and ||. These go ''outside'' the square brackets. Note also that whitespace around the comparison operators is critical, otherwise the conditional will be treated as a single string (which will always evaluate to "true")

IF [ ${foo} == foo ] || [ ${bar} == bar ]; LOG got a match; END

====Commands operating on Local Variables====
Besides environment variables, there exist local variables in scripts. Local variables are inherited by sub-scripts executed with the EXECUTE SCRIPT command, but changes to the variable's values will not be propagated to the calling script.
=====SET VARIABLE <name> <value>=====
Sets the named variable to the specified value.
=====CLEAR VARIABLE <name>=====
Removes the named variable from memory.
=====GET VARIABLE <name>=====
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message generated.

====Commands operating on Environment Variables====
These scripting commands allow to read and modify environment variables. Changes to environment variables will be visible to child processes started with SYSTEM or START EXECUTABLE. Variable values are stored as strings. Variable names may not contain the equals sign.
=====SET ENVIRONMENT <name> <value>=====
Sets the named variable to the specified value.
=====CLEAR ENVIRONMENT <name>=====
Removes the named variable from memory.
=====GET ENVIRONMENT <name>=====
Returns the variable's current value. When the variable does not exist, an empty value is returned rather than an error message.
=====WRITE ENVIRONMENT <fileName> <variableName1> <variableName2> ...=====
Writes a series of SET ENVIRONMENT statements to the specified file, overwriting any previous file contents. This saves the values of the named variables in such a way that you can later load them back by calling EXECUTE SCRIPT <filename>. The variable names may refer to either local or environment variables at the time of writing, but when you execute the script they will all be loaded as environment variables.
=====APPEND ENVIRONMENT <fileName> <variableName1> <variableName2> ...=====
This is the same as WRITE ENVIRONMENT, except that the SET ENVIRONMENT statements are appended to the named file without overwriting its previous contents.

====Commands operating on Scripts====
=====SET SCRIPT <handler names> <scripting commands>=====
Associates a sequence of scripting commands with the named handler. Handlers are specified by names as given [[#Handlers|below]]. Multiple handlers may be specified by concatenating their names with a pipe character, e.g. "OnStart|OnResume".

Scripting commands must be included in double quotes, unless they consist of a single word.
When specifying a sequence of scripting commands, they must be separated with a semicolon character: "SetConfig; Start". In order to use double quotes or semicolons within the commands themselves, encode these as you would in a URL, i.e. replace a double quote character with ''%22'', and a semicolon with ''%3B'': "Load Parameters %22my file%22".

To use a script file rather than a literal script, use the EXECUTE SCRIPT command:
SET SCRIPT OnConnect "EXECUTE SCRIPT myscript.txt"

=====GET SCRIPT <handler name>=====
Returns the script associated with the specified handler.

=====CLEAR SCRIPT <handler names>=====
Clears scripts for the given handlers. Equivalent to calling SET SCRIPT with an empty script.

=====EXECUTE SCRIPT <file or handler name> [<Arg1> <Arg2> ... <Arg9>]=====
Executes a script contained in a file, and optionally sets the script's local variables ''1'' to ''9'' to the specified values. To execute script commands already associated with a handler, provide a handler name rather than a file. When the script is executed successfully, the result of the last executed script command becomes the result of the EXECUTE SCRIPT command itself. Use "RETURN <value>" anywhere in a script in order to finish execution, and return a certain value.

When you run a script through EXECUTE SCRIPT, it will inherit copies of variables from its calling script/command line. Modifications of variables will be local to the script, and will be lost when script execution is complete.

The ''AbortOnError'' variable determines whether a script is aborted when any of its commands result in an error message. ''AbortOnError'' is not inherited but defaults to 1 in any script.

====Commands operating on Parameters====
=====LOAD PARAMETERFILE <file>, LOAD PARAMETERS <file>=====
Loads a parameter file specified by its path and name. Relative paths are interpreted relative to the operator module's working directory at startup. Usually, this matches the executable's location in the <tt>prog</tt> directory.
As the parameter file name must not contain white space, please use HTML-type encoding for white space characters, such as <tt>Documents%20and%20Settings</tt> when referring to a user's "Documents and Settings" folder.

NOTE: Only those parameters will be loaded that do exist at the time when this command is called. In idle state, no parameters exist other than created by ADD PARAMETER. After modules are connected and have published their parameters to the Operator module, a full set of parameters exists.

=====ADD PARAMETER <parameter definition>=====
Adds a parameter to the system. The parameter is specified as a [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.
=====EXISTS PARAMETER <name>=====
Returns "true" when the specified parameter exists in the system, and "false" otherwise.

=====ISEMPTY PARAMETER <name>=====
Returns "true" when the specified parameter exists and has no values, "false" if it exists and has values.

=====SET PARAMETER <name>[( idx1, idx2 )] <value>=====
Sets the named parameter to the specified value. Values that contain special characters, or whitespace must use the [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. Use parentheses to specify indices or labels. Omitted indices default to 1.

=====SET PARAMETER <parameter line>=====
Replace a parameter's value and definition with the information given in the [[Technical_Reference:Parameter_Definition#Parameter_Lines|parameter line]]. The parameter must exist in the system when this command is executed.

=====GET PARAMETER <name>[( idx1, idx2 )]=====
Prints the value of the named parameter. Use parentheses to specify indices or labels.

=====SET PARAMETERROWS <parameter name> <rows>=====
Sets the number of rows in the named parameter.

=====GET PARAMETERROWS <parameter name>=====
Prints the number of rows in the named parameter.

=====SET PARAMETERCOLS <parameter name>=====
Sets the number of columns in the named parameter.

=====GET PARAMETERCOLS <parameter name>=====
Prints the number of columns in the named parameter.

=====LIST PARAMETER <wildcard expression>, LIST PARAMETERS=====
Prints all parameters with names matching the wildcard expression, in form of parameter lines.
=====CLEAR PARAMETERS=====
Clears the list of parameters in the system. May only be executed in ''Idle'' and ''Publishing'' system states.

====Commands operating on States====
In BCI2000, there are three types of States that differ in their alignment to brain signal data (see [[Technical_Reference:State_Definition#Kinds_of_States|Kinds of States]]). This section applies to both Stream States, and normal States.
For Event States, see the next section.

=====ADD STATE <name> <bit width> <initial value>=====
Adds a state variable to the system. State variables are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after system initialization has completed, i.e. its use is restricted to the "Idle" and "Publishing" [[Technical_Reference:States_of_Operation#Publishing_Phase|phases of system operation]]. In terms of handlers, its use is restricted to the ''OnConnect'' handler.
=====EXISTS STATE <name>=====
Returns "true" when the specified state exists in the system, and "false" otherwise.

=====SET STATE <name> <value>, SET STATES <name1> <value1> <name2> <value2> ...=====
Sets the named state variable to the specified integer value by sending a state message to the source module.
Setting the ''Running'' state to 1 will start system operation, setting it to 0 will suspend the system.

<tt>SET STATES</tt> will atomically set the values of multiple states.

=====GET STATE[(<sample>)] <name>=====
Gets the value of the named state. Note that state values are not updated from the application module when the ''OperatorBackLink'' parameter is 0. In that case, GET STATE will return the state's initial value.

An optional one-based sample index may be given to indicate that the state value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.

By default, the state's value is retrieved for sample index 1.

=====LIST STATE <wildcard expression>, LIST STATES=====
Lists all states, or states with names matching the given wildcard expression, in form of state lines.
=====CLEAR STATES=====
Clears the list of states in the system. May only be executed in ''Idle'' and ''Publishing'' system states.

=====FREEZE STATES, THAW STATES=====
Freezes/thaws the values of all states in the state vector, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the state vector. For the duration of its existence, GET STATE calls will be diverted to the snapshot. This is useful for ensuring that multiple GET STATE commands actually retrieve mutually-consistent values from different state variables (i.e. values from the same sample-block).

=====GET STATEVECTOR SAMPLES=====
Returns the number of samples in the state vector per block of data. In the system's "Running" state, this matches the number of samples per block in the source data. Prior to the "Running" state, this command returns 1 because the state vector has not yet been updated from the application module.

====Commands operating on Events====
Events are a special type of state, which are recorded asynchronously, at single-sample resolution. Events may only be added while the system is in "idle" state. This kind of events is not related to [[#Handlers|Operator Events]] as defined below.
=====ADD EVENT <name> <bit width> <initial value>=====
Adds an event to the system. Like state variables, events are defined by name, bit width, and initial value (see [[Technical Reference:State Definition]]). This command may not be used after the system has started up, so it is typically executed in a batch file before ''STARTUP'' has been called.

=====EXISTS EVENT <name>=====
Returns "true" when the specified event exists in the system, and "false" otherwise.

=====SET EVENT <name> <value>=====
Asynchronously sets an event to the given value. Recording events requires the EventLink logger component to be present in the source module.

'''NOTE:''' In versions prior to BCI2000 3.06, this command behaved as described for PULSE EVENT below, rather than as advertised. If you used SET EVENT in your scripts, it is recommended to replace it with PULSE EVENT in order to retain original behavior.

=====PULSE EVENT <name> <value>=====
Asynchronously sets an event to the given value for a single sample duration. Recording events requires the EventLink logger component to be present in the source module.

=====SET EVENTS [<name> <value>] [<name2> <value2>] ... =====
Asynchronously sets given events to their specified values. Using this command, rather than multiple SET EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.

=====PULSE EVENTS [<name> <value>] [<name2> <value2>] ... =====
Asynchronously sets given events to their specified values for a single sample duration. Using this command, rather than multiple PULSE EVENT commands in a row, ensures that all event changes are recorded at exactly the same point in time. Recording events requires the EventLink logger component to be present in the source module.

=====GET EVENT[(<sample>)] <name>=====
Gets the value of the named event. Note that evemt values are not updated from the application module when the ''OperatorBackLink'' parameter is 0.

An optional one-based sample index may be given to indicate that the event's value should be retrieved at the given sample position. Sample positions range from 1 to the number of samples per block present in the state vector. The number of samples per block may be retrieved using GET STATEVECTOR SAMPLES.

By default, the event's value is retrieved for sample index 1.

=====LIST EVENT <wildcard expression>, LIST EVENTS=====
Lists all events, or events with names matching the given wildcard expression, in form of state lines.
=====CLEAR EVENTS=====
Clears the list of events in the system. May only be executed in ''Idle'' state.

====Commands operating on VisProperties====
=====SET VISPROPERTY <visID>.<name> <value>=====
Sets the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID to the given value. If the visualization ID contains a dot character, it must be encoded in [[Technical_Reference:Parameter_Definition#Special_Characters|parameter value encoding]]. E.g., setting the window width for the visualization ID "2.D1" would be written <code>SET VISPROPERTY 2%2ED1.Width 200</code>.

=====RESET VISPROPERTY <visID>.<name>=====
Removes the named visualization property with the specified visualization ID from the property store, effectively resetting its value to its default.

=====GET VISPROPERTY <visID>.<name>=====
Prints the value of the named [[Technical Reference:Visualization Properties|visualization property]] for the specified visualization ID.

=====SET VISPROPERTIES <property set ID>=====
Applies a set of visualization property values as given in the [[#VisPropertySets|VisPropertySets]] parameter. In that matrix-valued parameter, row labels specify visualization properties such as "SRCD.Left", and columns represent sets of property values. Column labels are IDs of the corresponding property sets.

====Commands operating on the Control Signal====
=====GET SIGNAL( <channel index>, <element index> )=====
Prints the value of the control signal at the given indices. Indices are 1-based.
=====GET SIGNAL CHANNELS=====
Prints the number of channels in the control signal.
=====GET SIGNAL ELEMENTS=====
Prints the number of elements (samples) in the control signal.
=====FREEZE SIGNAL, THAW SIGNAL=====
Freezes/thaws the contents of the control signal, without interfering with system operation. "Freezing" creates, and "thawing" discards, a frozen snapshot of the control signal. For the duration of its existence, GET SIGNAL calls will be diverted to the snapshot. This is useful for ensuring that multiple GET SIGNAL commands actually retrieve mutually-consistent values from different elements in the control signal (i.e. values from the same sample-block).

====Commands operating on Expressions====
=====EVALUATE EXPRESSION <expression>=====
This command treats the remainder of the command as a literal mathematical expression (for a description, see [[User Reference:Expression Syntax]]). An expression may contain assignments to variables; such variables may then be used in later expressions. Note that expression variables are different from local and environment variables that may be accessed by GET/SET VARIABLE/ENVIRONMENT. Expression variables hold numerical values, while local and environment variables hold string values. Also, environment variables are accessible to child processes started with SYSTEM or START EXECUTABLE, while expression variables are accessible only to scripts. When a script is executed using the EXECUTE SCRIPT command, it will inherit a copy of all expression variables present. Changes to these variables from the executed script will not be visible in the parent script.

=====CLEAR EXPRESSION VARIABLE <name>=====
Clears the named expression variable from storage.

====Commands operating on Watches====
A "Watch" is an object that consists of a set of expressions, and an action. Whenever the value of any of the expressions changes, the watch is "triggered", and the action is executed. Watches allow client applications to respond to BCI2000 state changes in a reliable manner. Rather than polling information from BCI2000, a client may create a watch to be notified about changes of interest. This avoids the problem of missing short-lived changes, which is inherent in the polling approach.

For watches created through operator scripting, the action consists of dumping values of all the expressions to a UDP port.

The intended use of a watch from a client application is to create a separate thread that reads from the watch's UDP port in a blocking mode, and calls an appropriate handler function whenever it receives data.
The data sent will consist of a single UDP packet with a single line in ASCII format, terminated with a CRLF sequence. The line consists of tab-separated data fields, which contain the current values of the expressions specified when creating the watch. In addition, the first field contains a time stamp in milliseconds. This time stamp represents the point in time where the expression value changed, with an accuracy of a single sample.

=====ADD WATCH [decimate <n>] <expression1> <expression2> ... [AT <ip:port>]=====
Adds a watch for the listed expressions. Each expression's value will be reported in a separate field. When an address is specified in <tt>ip:port</tt> format, the watch tries to open that port for output, and creation fails if that port is taken. When no address is specified, a free port is chosen automatically. In both cases, successful creation of the watch is indicated by returning the output address in ASCII format. The address is also used to uniquely identify a watch in the context of a connection.

When a ''decimate <n>'' clause is present, the watch will be created with decimation, i.e. it will only be evaluated for every ''n''th
sample of the state vector.

If a watch is created through a remote connection, it will use the remote host's external IP address for automatically chosen addresses. Otherwise, the output port will be associated with the machine's <tt>localhost</tt> address.

Watches may be created even if the system is currently running. In this case, the watch is triggered immediately at creation, and sends its current expression values to its output port.

=====ADD WATCH SYSTEM STATE [AT <address>]=====
Similar to the first variant of ADD WATCH, but will watch the system's state as reported by GET SYSTEM STATE.

=====CLEAR WATCH <address>, CLEAR WATCHES [<wildcard-expression>]=====
Removes the watches specified by address, or those with their addresses matching a wildcard expression. If CLEAR WATCHES is called without argument, all watches will be deleted.

=====TRIGGER WATCH <address>, TRIGGER WATCHES [<wildcard-expression>]=====
Forces dumping of the watches' current expression values to their output ports. Mostly useful for testing purposes.

=====LIST WATCHES [<wildcard-expression>]=====
Displays a list of existing watches, and their addresses.

=====COUNT WATCHES [<wildcard-expression>]=====
Returns the number of existing watches, or the number of watches whose addresses match the optional wildcard expression.

====Commands operating on Files, Directories, and Paths====
=====EXTRACT DIRECTORY <path>, EXTRACT FILE <path>, EXTRACT FILE BASE <path>=====
Extracts the directory or file portion of a given path. When the path specifies a non-existing directory, the directory name must be followed with a separator ("/") in order to be recognized as a directory. The EXTRACT DIRECTORY command always returns its result with a trailing separator. The EXTRACT FILE BASE command returns the file portion without extension.

=====IS DIRECTORY <path>, IS FILE <path>, IS PATH <path>=====
Determines whether the specified path points to an existing directory, file, or any of the two. The result is returned as one of the strings "true" or "false".
=====PARENT DIRECTORY <path>=====
Returns the parent directory of the specified path, independently of whether the path points to a directory, or to a file.
=====CURRENT DIRECTORY=====
Returns the current working directory. Note that working directories are per-script, i.e. multiple scripts running in parallel may have different working directories.

=====CHANGE DIRECTORY <path>=====
Changes the script's working directory. Note that working directories are per-script, i.e. multiple scripts running in parallel may have different working directories. Also, this command will only affect the default directory of scripting commands, not the application-global working directory as seen by the OS.

=====MAKE DIRECTORY <path>=====
Creates a new directory with the given path. The directory's parent must exist for the command to succeed.
=====LIST DIRECTORY [<path> or <wildcard expression>]=====
Returns a listing of the specified directory, or the current working directory if no path is specified. The listing is in long form. You may use wildcard expressions in order to restrict the output.
=====LIST FILE <wildcard expression>=====
Returns a list of file names matching ''wildcard expression'' in the current directory.
=====LIST FILES [<directory> [<wildcard expression>]]=====
Returns a list of file names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all files are listed. When ''directory'' is missing, files in the current directory are listed.
=====LIST DIRECTORIES [<directory> [<wildcard expression>]]=====
Returns a list of directory names from the specified directory, matching ''wildcard expression''. When ''wildcard expression'' is missing, all directories are listed. When ''directory'' is missing, directories in the current directory are listed.

=====RENAME FILE <current path> <new path>, RENAME DIRECTORY <current path> <new name>=====
Renames a file resp. a directory. For files, a different path may be given in the second argument, resulting in that the file is moved to the location specified by the new path. For directories, the path up to the directory's name must stay the same.
=====REMOVE FILE <path>, REMOVE DIRECTORY <path>=====
Removes the specified file or directory. This command cannot be undone. The directory must be empty for the command to succeed.
=====FORCEREMOVE DIRECTORY <path>=====
Removes the specified directory and its contents. Symbolic links are treated as ordinary files, i.e. they are not followed. This command cannot be undone.
=====NORMALIZED PATH <path>=====
Returns <path>, with the following transformations applied:
*Removes relative elements (<tt>..</tt> <tt>.</tt>) as far as possible. For absolute paths, the result will not contain any relative elements; for relative paths, double-dots may appear at the beginning of the result if necessary.
If a relative path simplifies to the empty string, <tt>./</tt> is returned. Thus, the result of NORMALIZED PATH is never empty, unless its input was empty.
*Replaces backward slashes with forward slashes to achieve uniformity across platforms.
*On case-insensitive file systems, replaces the spelling of names with the one stored in the file system.
*On Win32, replaces short (8.3) names with long ones.

=====CANONICAL PATH <path>=====
If <path> points to an existing file or directory, CANONICAL PATH returns a valid absolute file path, suitable as an unambiguous representation for the object pointed to. Especially, two non-empty canonical path strings will compare equal if and only if they refer to the same file system object.

If <path> does not point to an existing file system object, construction of a canonical path is not possible due to lack of information about the named object, and CANONICAL PATH will return an empty string.

'''NOTES:''' The need for an unambiguous, or canonical, representation arises due to ambiguities in the string representation of paths, and in file systems themselves.
*Paths may contain relative elements: <tt>/mydir/../myfile</tt> points to the same object as <tt>/myfile</tt>.
*A path that involves symbolic links will point to the same object as a path containing one or more of those links in resolved form.
*File systems may be case-insensitive, or may even provide multiple distinct names for individual directory entries (Win32 short vs. long names).

On '''Win32,''' CANONICAL PATH returns the short (8.3) representation of a path, using uppercase spelling, and backslashes as directory separators. Apart from efficiency considerations, this aesthetically unpleasing representation has been chosen to discourage its use for anything except comparing file system objects.

On '''other systems,''' CANONICAL PATH will return the result of the POSIX <tt>realpath()</tt> function.

In both cases, a CANONICAL PATH will end with a native directory separator if, and only if, the object pointed to is a directory.

=====REAL PATH <path>=====
On this command provides a work-alike for the POSIX <tt>realpath()</tt> function.
If <path> is empty, or if <path> points to a non-existing object, the result will be empty. Otherwise, an absolute path will be returned, with symbolic links resolved, using forward slashes as directory separators, and with spelling normalized as described for NORMALIZED PATH. A forward slash will be appended if the path points to a directory.

'''NOTE:''' In principle, the path returned by REAL PATH should be just as unambiguous as the result of CANONICAL PATH. However, there are a few caveats:
* On case-insensitive file systems, two independently obtained results of REAL PATH might differ in case spelling even if referring to the same file system object. This should not be the case for CANONICAL PATH.
* Determining the result of CANONICAL PATH is a fast operation. In contrast, REAL PATH may be expensive to determine, as for each directory on the path a listing needs to be obtained, and a canonical path needs to be formed, and compared, for half of the listed directory entries on average.
* On Win32, quite some amount of complexity arises from backward compatibility layers, forbidden file names, multiple filesystem roots, etc. Internally calling <tt>GetShortPathName()</tt>, CANONICAL PATH does not need to handle that complexity, and may be considered more reliable for identifying file system objects than REAL PATH.

=====READ FILE <filename>=====
Returns the text content of the file indicated by <filename>.

=====WRITE FILE <filename> <line>, OVERWRITE FILE <filename> <line>, APPEND TO FILE <filename> <line>=====
These commands write the specified <line> of text to the file indicated by <filename>. They behave like the <tt>echo</tt> command of a typical shell, in the sense that a line-ending will be automatically added to the <line> if it does not already end with one. To suppress the automatic line-ending, you can say WRITE FILE <filename> <content> WITHOUT LINE ENDING (or equivalently, for short, you can say WITHOUT LF or WITHOUT CRLF). Any previous content in <file> will be lost if you use WRITE or OVERWRITE (they are the same, just synonyms for each other) whereas APPEND preserves previous content and adds the new <line> to the end.

====Commands operating on executables====
=====START EXECUTABLE <command line>=====
Behaves identically to CREATE PROCESS, except that it does not report a process id for the new process. For details, see CREATE PROCESS.

=====CATEGORIZE EXECUTABLE <name or path>=====
BCI2000 keeps a list of executables/modules that have been built, and sorts them into categories. The CATEGORIZE EXECUTABLE command provides a way to retrieve that information. Given the name or path of an executable, it outputs one of the following categories:
* SignalSource,
* SignalProcessing,
* Application,
* Operator,
* Tool,
* Helper,
* Unknown.

====Commands operating on Lines of input/output====
=====WRITE LINE <line>=====
Writes a line of output. Destination depends on the context in which a script is executed. If the context is an Operator Handler, output is written as a log entry. If the context is a telnet session, output is written to the telnet connection. If the context is a [[User Reference:BCI2000Shell|BCI2000Shell]], output is written to the shell's stdout.

=====READ LINE=====
Reads a line of input from the current execution context's input. If the command is executed within an Operator Handler, it will fail. If executed within a telnet session, the other side of the connection is prompted for input. If executed from within a [[User Reference:BCI2000Shell|BCI2000Shell]], input is read from the shell's stdin.

====Commands operating on Processes in the Operating System====
=====CREATE PROCESS <command line>=====
Starts the specified executable with options. This command returns after the started program has finished initialization, i.e. it will detect load time failures such as missing DLLs on Windows. If the process is still running when CREATE PROCESS returns, its result will be an operating system process id (pid). If the process has terminated, CREATE PROCESS will report its exit code marked with an <tt>ExitCode</tt> tag to allow distinction between a pid and an exit code.
Please note that CREATE PROCESS requires quoting of arguments differently from other scripting commands. For details, see the SYSTEM command.

=====TERMINATE PROCESS <pid>=====
Tries to terminate the process with the given operating system pid, waiting for the process to terminate before returning. Will return <tt>false</tt> to indicate that a suitable process existed but could not be terminated.

=====WAIT FOR PROCESS <pid> [<timeout seconds> = infinite]=====
Waits for the process with the given operating system pid to terminate, or the timeout to expire. Returns <tt>false</tt> to indicate that the process is still executing.

=====SHOW PROCESS <pid>=====
Makes all windows visible which are associated with the process referred to by pid.
In addition, brings one of the process' top level (desktop level) windows to the front for user interaction.

=====HIDE PROCESS <pid>=====
Makes all windows invisible which are associated with the process referred to by pid.

====Global commands====
=====HELP [<type>]=====
When called with a type argument, lists commands that exist for the specified type (e.g., SYSTEM, or FILE). When called without argument, lists all commands in their main form. HELP ALL will list all commands, including synonyms.

=====SET <name> <value>, GET <name>, <name>=====
Allows to set or retrieve the value of local and environment variables. The name is matched against local and environment variables. When no variable with the given name is found, SET will create a local variable, while GET will result in an error. GET may be further abbreviated to only consist of a name.

GET further allows evaluation of [[User_Reference:Expression_Syntax|mathematical expressions]]. When the expression is invalid, or contains an unknown variable, an error is triggered.

=====GET SYSTEM STATE=====
Prints the current system state. This will be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy (for details, see the WAIT FOR command below).

=====GET CURRENT RUN FILE=====
Prints the full path to the current run file, or an empty string, if called outside Running state.

=====WAIT FOR <system state> [<timeout seconds>]=====
Waits until the system is in the specified state. This may be one of Idle, Startup, Connected, Resting, Suspended, ParamsModified, Running, Busy, or a combination of these, separated with a pipe character: "Resting|Suspended". When no timeout is given, this command waits indefinitely. If the wait is successful, i.e. system state matches one of the specified states, WAIT FOR will return a value of "true". If timeout occurred, WAIT FOR will return "false".

If the BCI2000 system is shut down while a script is executing a WAIT FOR command, the script will be terminated with a "wait aborted" error message.

In more detail, user visible states are:
* Idle: System is shut down and does not do other processing than executing scripts.
* Startup: System has started up and is listening for incoming connections.
* Connected: All core modules have connected to the system.
* Resting: The system has been initialized but is not running.
* Suspended: The system has ended running and is behaving like in Resting.
* ParamsModified: In Suspended mode, parameter changes have been published and will be applied at Resume.
* Running: The system is running, processing brain signals, and displaying stimuli.
* Busy: The system is performing a transition from one state to another.

As a synonym for "Connected," "Initialization" is valid as well since it is compatible with the nomenclature in StateMachine.h. Still, it should be avoided because it is easily confused with, but very distinct from, the actions performed in the Initialize() phase.

=====SLEEP <time in seconds>=====
Waits (sleeps) for the given amount of time. Timing resolution is 50ms. Tends to sleep a little longer than specified, with the error growing with duration.

=====GET SYSTEM VERSION=====
Prints BCI2000 version information.
=====SETCONFIG, SET CONFIG=====
Applies current parameters to the system. Corresponds to the ''SetConfig'' button in the GUI version of the Operator module.

=====START=====
Starts or resumes system operation, corresponding to the ''Start/Resume'' button in the GUI version of the Operator module.
=====STOP=====
Stops system operation. Corresponds to the ''Stop'' button in the GUI version of the Operator.
=====STARTUP SYSTEM=====
When in idle state, starts up the system to wait for incoming connections from core modules. Additionally, the following arguments may be given: 1) an IP address on which to listen (default is to listen on all addresses), and 2) a list of generic core module names with ports. The default configuration corresponds to these arguments:
STARTUP SYSTEM * SignalSource:4000 SignalProcessing:4001 Application:4002

A system log file may optionally be specified on this line, by inserting the <code>--SystemLogFile</code> flag between the IP address and the module specifiers. For example:

STARTUP SYSTEM * --SystemLogFile=SOME_FILE.TXT SignalSource:4000 SignalProcessing:4001 Application:4002

The system log file will record all operator log window messages for the current launch, until the system shuts down. It may be helpful to use the variables <code>$YYYYMMDD</code> and <code>$HHMMSS</code> to specify the filename. Note that file name and path cannot contain spaces.

=====SHUTDOWN SYSTEM=====
Shuts down core modules, and enters idle system state.
=====RESET SYSTEM=====
Shuts down the system, and clears all parameter, state, and event information.

=====QUIT, EXIT [<result>]=====
Quits the operator module after terminating all BCI2000 modules. The optional ''result'' argument determines the result of the executed script.

=====CLOSE CONNECTION, TERMINATE CONNECTION=====
In the context of a telnet or websocket connection, this command will terminate the connection.
In other contexts, such as event handlers, it will be ignored.

=====SYSTEM <command line>=====
Executes a shell command, redirecting any console output into the command's script result. E.g., to obtain a directory listing, under Windows, you would enter
SYSTEM DIR
'''NOTE:''' Arguments to the SYSTEM command are executed by the operating system's shell, and thus may require quoting different from the other scripting commands. E.g., writing
SET mydir ${PARENT DIRECTORY $BCI2000LAUNCHDIR}; ECHO ${LIST FILES $mydir}
will list files in the BCI2000 main directory, independently of whether the path to that directory contains space characters or not. However, to obtain a directory listing through the SYSTEM command, you would need to write
ECHO ${SYSTEM DIR "$mydir"}
to make sure the content of the variable ''mydir'' is interpreted as a single argument, independently of whether it contains space characters.

=====LOG <message>=====
Append the specified message to the system log.
=====WARN <message>=====
Append the specified message to the system log, formatted as a warning.
=====ERROR <message>=====
Append the specified message to the system log, formatted as an error message.

=====CAPTURE MESSAGES <message types>=====
Captures system log messages into a background buffer. When no message type is given, all messages are captured. When "None" is given as a message type, message capturing is disabled. Otherwise, the message type must be one of "Errors", "Warnings", "Debug", "Log". Multiple message types may be specified in a single command. When "None" appears within a single command, all preceding message types are ignored. Multiple CAPTURE MESSAGES commands are cumulative, except when "None" is specified as a message type.

=====FLUSH MESSAGES=====
Clears the background message buffer, and returns its previous content. Use CAPTURE MESSAGES to capture messages into the background message buffer.

====Operator-module defined Commands====
=====HIDE WINDOW [<name>], SHOW WINDOW [<name>]=====
Hides or shows the specified window. When called without a window name, the Operator module's main window is hidden or shown. The window name may be one of Main, Configuration, Log, Watches, and Visualizations. When "Watches" is given, the window state refers to visibility of the Watches area in the Visualizations window.

=====MOVE WINDOW <name> <x> <y>, RESIZE WINDOW <name> <width> <height>=====
Moves resp. resizes the specified window with one of the above names.
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height.

=====ARRANGE WINDOW <name> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====
Arranges the named window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.

Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column.
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.
Likewise, a ''colspan'' of 0 will result in the window's minimum width.

If multiple screens are present, windows are arranged on the screen that contains the Operator window.

=====SET TITLE <title>=====
Sets the title of the main Operator window.
=====SET BUTTON <idx> <label> <commands>=====
Configures the function button with 1-based index ''idx'' such that it is labelled ''label'' and executes ''commands''.

=====VISUALIZE WATCH [decimate <n>] [range <min> <max>] <expression1> ...=====
Adds a watch for the given expressions to the operator module's Watches window, and makes the Watches window visible if it is hidden. If the ''decimate'' clause is present, the command will create a watch which will be evaluated only for every ''n''th sample in the state vector. If the ''range'' clause is present, display minimum and maximum will not be adjusted automatically but will be fixed to the values given.

By default, ''decimate'' has a value of "auto"; this means that there is no decimation of evaluation (i.e., all samples are evaluated) but changes that occur within 1ms will be shortened into their maximum and minimum, and thus reported as only two values.
This has proven to be efficient for avoiding sluggishness from flooding the application with events.

=====MOVE VISUALIZATON <visID> <x> <y>, RESIZE VISUALIZATION <visID> <width> <height>=====
Moves resp. resizes the specified visualization window.
Window decorations (title bar, frame) are taken into consideration such that the total size of the window matches the given width and height. If unknown, visualization IDs may be obtained from the Operator's ''Window->Visualizations'' menu.

=====ARRANGE VISUALIZATION <visID> <rows> <cols> <row> <col> [<rowspan> <colspan>]=====
Arranges the named visualization window in a virtual ''rows'' x ''cols'' grid at grid position ''row, col''.

Optional ''rowspan'' and ''colspan'' arguments may be given to specify the extension of the window across more than one row or column.
Using a ''rowspan'' of 0 will result in the window assuming its minimum height.
Likewise, a ''colspan'' of 0 will result in the window's minimum width.

If multiple screens are present, windows are arranged on the screen that contains the Operator window.

=====RECORD VISUALIZATION <visID> [on|off]=====
Registers the named visualization for recording. The visualization name must be the short name as displayed in the ''View->Visualizations'' menu. Switching a visualization recording to "on" is only possible in idle state (because an event for recording frame numbers must be registered in the system). When a visualization is registered for recording, its frames are stored immediately as they arrive at the operator module. Currently, only bitmap visualizations may be recorded.

Example: Recording the application window
RECORD VISUALIZATION ApplicationWindow on
...
# after parameters have been loaded
Set parameter VisualizeApplicationWindow 1
...

=====PUT NOTE <note>=====
Adds the given text to the [[User_Reference:Operator_Notes#Taking_Notes_during_recording_in_Operator|notes window]].
If the system is in ''Running'' state, the text will also be added to the current notes file as described under
[[User_Reference:Operator_Notes#Note_storage_and_file_format|"notes file"]].

=====START TELNET [<address>], STOP TELNET [<address>]=====
Starts or stops a telnet server listening at the given address. The address is in <IP>:<port> format. The default address is 127.0.0.1:3999.

'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed. Only use addresses in the local network, such as 10.x.x.x, 172.x.x.x, or 192.168.x.x.

=====START WEBSOCKET <address>, STOP WEBSOCKET <address>=====
Starts or stops a websocket server listening at the given address. The address is in <IP>:<port> format.

'''IMPORTANT:''' You should not use this command on global internet addresses, as there is no authentication performed. Only use addresses in the local network, such as 10.x.x.x, 172.x.x.x, or 192.168.x.x.

====Operator-module Commands for Soliciting Input from the User====

=====CHOOSE [INPUT] FILE[S] [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====
Via the Qt graphical user interface, prompt the user to select an existing file (or multiple files, if the keyword FILES is used). Print the resulting file path(s).
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

=====CHOOSE [OUTPUT] FILE [OF TYPE <.ext1> [<.ext2> ...]] [STARTING AT <dir>] [WITH PROMPT <message>]=====
Via the Qt graphical user interface, prompt the user to specify a file into which data can be saved (with an overwrite confirmation dialog if it already exists). Print the resulting file path.
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

=====CHOOSE DIRECTORY [STARTING AT <dir>] [WITH PROMPT <message>]=====
Via the Qt graphical user interface, prompt the user to specify a directory. Print the resulting directory path.
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

=====CUSTOM DIALOG [MESSAGE <msg>] [VAR <varname> <label> {[<options>]} ] [BUTTONS {<buttons>}] ... =====
Via the Qt graphical user interface, prompt the user with a modal dialog that can be flexibly customized.
(See the [[User_Reference:Custom_GUI_Commands|Custom GUI Commands]] page for details and examples.)

===Predefined Variables===
The following variables exist when an Operator script is executed.
Some of these variables are marked with ''local''. This means that they are not environment variables, i.e. they are invisible to child processes that are launched using the SYSTEM or START EXECUTABLE commands, and their values may be different between script invocations. In script code, they are accessed like ordinary variables.
====BCI2000LAUNCHDIR====
The full absolute path to the directory where the Operator module resides. This is also prepended to the PATH environment variable, such that executables from the current BCI2000 installation will have precedence over any other executable with the same name.

On macOS, this is the path where the Operator module's application bundle resides. In the default configuration, this is the BCI2000 prog directory, both on macOS and on other platforms.

====BCI2000BINARY====
The full absolute path to the Operator module.
====LogLevel (local)====
Determines the amount of log information written to the Operator log. This variable only affects log messages originating from the current script. May be 2 (display all log messages), 1 (display fewer log messages), or 0 (suppress all log messages). Set to 1 by default. Changes to this local variable are not propagated to any sub-scripts called. ''NOTE:'' Only log messages are controlled by this variable. Error messages originating from a script with 'LogLevel 0' will still be displayed in the Operator log. When 'AbortOnError' is set to 0, you may set 'LogLevel' to -1 in order to display error messages. When 'AbortOnError' is 1 (the default), error messages will always be displayed to indicate the reason for failure.

====AbortOnError (local)====
Determines if a script is aborted when an error happens, or whether the error is silently ignored. Set to 1 by default (script is aborted on error). Changes to this local variable are not propagated to any sub-scripts called.

====Result (local)====
The result of the last executed scripting command. When a script is executed by calling EXECUTE SCRIPT, the script's last executed command determines the result of the EXECUTE SCRIPT command itself.

====0, 1, ... 9 (local)====
When a script file is being executed, these variables contain the arguments of the EXECUTE SCRIPT command.
''$0'' resolves to the full absolute path to the current script file. Within scripts, all of the ''0-9'' variables are defined, and those that do not have a matching argument are empty.

====YYYYMMDD (local)====
Local time at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.

====HHMMSS (local)====
Local time at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.

===Abbreviated commands and synonyms===
To minimize the need of consulting documentation, as well as for backward compatibility, a number of '''synonymous commands''' are provided. E.g., states may be added by INSERT STATE as well as ADD STATE, and the existence of a file may be queried by IS FILE as well as EXISTS FILE. For an overview over all allowed forms of commands, use the HELP ALL command.

To simplify operation in interactive sessions, '''abbreviated commands''' exist. Currently, these are:
:'''cd''' for CHANGE DIRECTORY,
:'''pwd''' and '''cd''' without argument for CURRENT DIRECTORY,
:'''ls''' and '''dir''' for LIST DIRECTORY,
:'''mkdir''' for MAKE DIRECTORY,
:'''echo''' for WRITE LINE,
:'''realpath''' for REAL PATH,
:'''dirname''' for EXTRACT DIRECTORY,
:'''basename''' for EXTRACT FILE BASE.

===Handlers===
In the Operator GUI, script execution is bound to a number of Operator Events (not to be confused with Event states, above) that occur during various [[Technical Reference:States of Operation|stages of BCI2000 system operation]]:
====OnConnect====
This handler runs at startup, as soon as all modules are connected to the operator module.
====OnSetConfig====
This handler runs each time a set of parameters is applied to the system. This happens when the user clicks the ''SetConfig'' button. Execution of the ''SETCONFIG'' command also runs this handler.

====OnStart, OnResume====
These handlers are triggered by the ''Start''/''Resume'' button. One of these handlers is also triggered when the ''Running'' state variable is set to 1 from a script. Whether ''OnStart'' or ''OnResume'' is triggered depends on whether the system has been running before with the current set of parameters.

====OnStartRun====
Similarly to OnStart and OnResume, this handler is triggered by the ''Start''/''Resume'' button. Unlike other event handlers, OnStartRun has an argument, which is the current run file.

OnStart or OnResume are triggered immediately after ''Start''/''Resume'' has been pressed, whereas OnStartRun is deferred until modules have confirmed to be in Running state. This makes sure that the OnStartRun event handler receives a valid run file name.

====OnNextFilePart====
This handler is triggered during a run, whenever the ''FilePart'' event state is incremented. It allows scripts to know when a new
partial file has begun. For further information, see the [[User_Reference:BCI2000FileWriter#FileSplittingCondition|FileSplittingCondition]] parameter.

====OnSuspend/OnStopRun====
Triggered when the system goes from running into suspended mode. This happens whenever the ''Running'' state variable changes from 1 to 0. This may happen when the user clicks ''Suspend'', when the application module switches the system into suspended mode, or when a script sets the ''Running'' state variable to 0.

====OnShutdown====
Triggered when the operator module shuts down connections, and switches into idle state.

====OnExit====
Triggered when the operator module exits. Execution of the QUIT command also triggers this handler. This handler is not available to the SET SCRIPT and CLEAR SCRIPT commands. Also, when both an OnShutdown and an OnExit script are defined, the OnExit script may be executed before the OnShutdown script.

====Associating Scripts with Operator Events====
In the operator module's preferences dialog, script commands may be entered for each of the handlers listed above.
Scripts may be specified as paths to script files, or as immediate one-line scripts.
Entries that start with a minus sign (-) are treated as one-line scripts, which may contain multiple commands separated with semicolons.

Scripts may also be specified from the command line used to start up the operator module. There, handler names are followed with the content of the respective preference entry, enclosed in double quotes ("...").

Finally, scripts may be specified using the SET SCRIPT command of the scripting language itself.

===Examples===
====Making use of the Operator module's Function Buttons====
To add a state variable called "Artifact", and to set it using the operator's function buttons, do this:
*Enter the following line under "After All Modules Connected" in the operator's preferences dialog (note the minus sign):
-ADD STATE Artifact 1 0
*Under "Function Buttons", enter "Set Artifact" as the name of button 1, and as its command, enter (note there is no minus sign):
SET STATE Artifact 1
*Enter "Clear Artifact" as the name of button 2, and as its command, enter
SET STATE Artifact 0

====A fully automated BCI2000 session====
<pre>
Echo Please enter a subject ID:
Set SubjectID ${Read line}

Startup system
Start executable SignalGenerator
Start executable SpectralSignalProcessing
Start executable CursorTask
Wait for Connected
Load parameterfile "../parms/examples/CursorTask_SignalGenerator.prm"
For i in 1 2 3
Load parameterfile "../parms/MyExperiment/Session$i.prm"
Set parameter SubjectName $SubjectID
Set parameter SubjectSession $i
Set config
Wait for Resting
Start
Wait for Suspended 1000
End
</pre>

====Automating BCI2000 by Operator command line arguments====
The following example shows how to specify script commands from the command line.
It fully automates BCI2000 operation by loading a parameter file, applying parameters, starting the system once the parameters are applied, and quitting the system once the run is over. For better readability, the example is broken across lines, using the ^ DOS line continuation character.

operator.exe --OnConnect "-LOAD PARAMETERFILE ../parms/examples/CursorTask_SignalGenerator.prm; SETCONFIG" ^
--OnSetConfig "-SET STATE Running 1" ^
--OnSuspend "-QUIT"

====Automatically arranging windows in a 4x2 grid====
The following example arranges Source and Roundtrip visualizations on the left side of the screen.
On the right side, a large area is dedicated to the Operator's log window, and the Operator's main window sits at the bottom right.

Arrange Visualization SRCD 4 2 1 1 2 1
Arrange Visualization RNDT 4 2 3 1
Arrange Window Main 4 2 4 2
Arrange Window Log 4 2 1 2 3 1

[[File:Operator_Arrangement.PNG|center|640px|border]]

==See also==
[[User Reference:Module Command Line Options]], [[User Reference:Operator Module]], [[User Reference:BCI2000Shell]], [[Technical Reference:States of Operation]]

[[Category:User Interface]]

File:Event vs sample time gUSBamp.png

2026-07-30T12:41:43Z

Mellinger: Mellinger uploaded a new version of File:Event vs sample time gUSBamp.png

User Reference:Validating the Event Logging Mechanism

2026-07-30T12:35:48Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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 regular arrival of sample blocks.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

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

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===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';

[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;

% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;

% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';

% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);

% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);

figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');

% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);

figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');

% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);

figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');

function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end

function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

Contributions:SecondaryBCI2000Controller

2026-07-30T12:32:12Z

Mellinger: /* Source Code Revisions */

==Synopsis==
An extension that controls one or more secondary BCI2000 instances from the GUI of a primary one.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/SecondaryBCI2000Controller

==Versioning==
===Author===
*Jürgen Mellinger (mellinger@neurotechcenter.org)
===Version History===

===Source Code Revisions===
*Initial development: 6819
*Tested under: 9500
*Known to compile under: 9500

===Known Issues===
*Log windows of primary and secondary BCI2000 instances will initially have the same location, hiding each other and possibly leading to confusion. The same applies to operator main windows if secondary instances are not hidden by calling "Hide Window" from the secondary batch file(s).

==Functional Description==
The extension will start up one or more secondary instances of BCI2000, and synchronize data file storage and operation state between the instances. This is useful to record from two or more different data sources at the same time, when online processing of secondary data sources is not required. In later analysis, data from the multiple sources may be aligned in time using BCI2000 time stamps found in the data files.

==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration. In your root build folder, run <tt>Configure.sh.cmd</tt> in order to bring up the CMake GUI; there, enable EXTENSIONS_SECONDARY_BCI2000_CONTROLLER.

Once the extension is built into the source module, enable it by starting the source module with the <code>--SecondaryBCI2000=1</code> command line argument.

==Usage==
When the SecondaryBCI2000Controller extension has been enabled in the system at compile time, you will find a <tt>BCI2000TwiceStartup.bat</tt> batch file in your BCI2000 batch folder. Double-click it to start BCI2000.

Startup configuration of secondary BCI2000 instances is done in the files <tt>BCI2000SecondaryStartup.bat</tt>, <tt>BCI2000Secondary2Startup.bat</tt>, etc.
You may load identical or different configuration parameter files in the startup batch files.

Data file location is synchronized between BCI2000 instances. Secondary instances use identical file names to the first one, with an appended <tt>_1</tt>, <tt>_2</tt>, ... before the file name extension.

==Parameters==
The SecondaryBCI2000Controller extension is configured in the ''Source'' tab within the "Secondary BCI2000" section. The configurable parameters are:

===SecondaryBCI2000===
Enables/Disables the SecondaryBCI2000Controller.

===SecondaryBCI2000Instances===
A matrix with one row per secondary instance.

The first column contains the telnet port that is used to control the secondary instance of BCI2000.

The second column contains the the script that is used to start up and configure the secondary instance of BCI2000. An example script is available as <tt>BCI2000SecondaryStartup.bat</tt> in your BCI2000 batch directory, and is called by the <tt>BCI2000TwiceStartup.bat</tt> batch file.

To tell the second instance that it should refer to the first one for file names, there is a command line parameter:

===IsSecondaryBCI2000===
This parameter must be set to 1 in the secondary instance's batch file: <tt>--IsSecondaryBCI2000=1</tt>

==See also==
[[Contributions:Extensions]], [[User Reference:Operator Module Scripting]]

[[Category:Contributions]][[Category:Extension]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:40:40Z

Mellinger: /* 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.

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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 regular arrival of sample blocks.

====Data recorded with g.USBamp source module====
[[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).

[[file:Event_vs_sample_time_gUSBamp.png]]

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===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';

[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;

% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;

% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';

% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);

% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);

figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');

% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);

figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');

% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);

figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');

function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end

function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:35:20Z

Mellinger: /* Matlab Analysis Script */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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 regular arrival of sample blocks.

====Data recorded with g.USBamp source module====
[[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).

[[file:Event_vs_sample_time_gUSBamp.png]]

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===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';

[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;

% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;

% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';

% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);

% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);

figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');

% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);

figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');

% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);

figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');

function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end

function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:33:37Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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 regular arrival of sample blocks.

====Data recorded with g.USBamp source module====
[[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).

[[file:Event_vs_sample_time_gUSBamp.png]]

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===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:30:33Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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 regular arrival of sample blocks.

====Data recorded with g.USBamp source module====
[[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).

[[file:Event_vs_sample_time_gUSBamp.png]]

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===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:28:56Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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 regular arrival of sample blocks.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:27:09Z

Mellinger: /* Analyzing RefLogger Data */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event logging software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:26:23Z

Mellinger: /* Using the RefLogger */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 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===
''RefLogger'' data analysis follows two distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:25:00Z

Mellinger: /* Sources of Imprecision */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

==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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:20:22Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-29T15:20:02Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Contents

2026-07-28T22:33:33Z

Mellinger:

User reference information helps you configure and perform experiments with BCI2000, using the executables that come with its [[BCI2000 Binaries|binary distribution]].
For information about how to modify existing filters, or develop your own from scratch, see the [[Programming Reference:Contents|Programming Reference]] section.

In the user reference section, information is available about the following topics:

==Using the Online System==
*[[User Reference:Operator Module]]:
**Parameter editing,
**saving and loading parameter files,
**starting and stopping BCI operation.
*[[User Reference:Operator Notes]]: Manually taking notes during recordings.
*[[User Reference:Operator.ini]]: Operator module settings file.
*[[User Reference:Operator Module Scripting]]: Automated execution of operator tasks.
*[[User Reference:Module Command Line Options]]: Modifying module behavior with command line options.
*[[User Reference:Data File Formats]]: File formats supported by BCI2000.
*[[User FAQ]]: Frequently asked questions about using BCI2000.

==Configuring the Online System==
*[[User Reference:Filters|BCI2000 Filters]]: Any BCI2000 configuration consists of different filters in the Data Acquisition, Signal Processing, and Application module. These filters determine what device BCI2000 acquires data from, what data format it uses for data storage, which feature extraction and translation algorithms it uses to translate brain signals into device commands, and which kind of user feedback is provided. This page gives an overview of all filters that are currently available in the BCI2000 distribution.
*[[User Reference:Parameters]] provides an index of configuration parameters present in BCI2000 components.
*[[User Reference:States]] provides an index of state variables present in BCI2000 components.

*[[User Reference:Parameter Changes for Version 2]] helps in migrating experiments from BCI2000 version 1 to version 2.

==Verifying the Online System==
*[[User Reference:Validating the Event Logging Mechanism]]: A description and validation instructions for BCI2000 events.
*[[User Reference:BCI2000Certification]]: Measure a BCI2000 system's timing performance.

==Using BCI2000 Tools==
*[[User Reference:BCI2000Launcher]]: Conveniently start up BCI2000 modules from a graphical interface.
*[[User Reference:BCI2000Watchdog]]: A tool to start up and monitor BCI2000 for long-term recordings.
*[[User Reference:BCI2000Viewer]]: View signals recorded with BCI2000.
*[[User Reference:BCI2000FileInfo]]: View and extract parameter information from BCI2000 data files.
*[[User Reference:BCI2000Export]]: Export BCI2000 data files into various formats.
*[[User Reference:BCI2000Analysis]]: Analyze data files offline, create and test filter chains, train classifiers for online recognition.
*[[User Reference:BCI2000 Offline Analysis]]: MATLAB-based tool to analyze data files offline in order to determine the best features for online recognition.
*[[User Reference:Eloc Helper]]: Matlab-based tool to create and modify montage files.
*[[User Reference:EEGLabImport]]: Read BCI2000 data into EEGLab.
*[[User Reference:Matlab Tools]]: Perform offline data analysis, and manage information in BCI2000 files, using Matlab functions.
*[[User Reference:Matlab MEX Files]]: Access BCI2000 data from within Matlab.
*[[User Reference:Command Line Processing]]: Compile BCI2000 filters into executables for offline processing.
*[[User Reference:StimulationConfigurationIntegrativeTool (SCIT)]]: Easily create and visualize BCI2000 parameter files for the Neuro Omega, CereStim, g.Estim, and Cortec Brain Interchange.

[[Category:Contents]]

User Reference:Contents

2026-07-28T22:31:53Z

Mellinger: /* Configuring the Online System */

User reference information helps you configure and perform experiments with BCI2000, using the executables that come with its [[BCI2000 Binaries|binary distribution]].
For information about how to modify existing filters, or develop your own from scratch, see the [[Programming Reference:Contents|Programming Reference]] section.

In the user reference section, information is available about the following topics:

==Using the Online System==
*[[User Reference:Operator Module]]:
**Parameter editing,
**saving and loading parameter files,
**starting and stopping BCI operation.
*[[User Reference:Operator Notes]]: Manually taking notes during recordings.
*[[User Reference:Operator.ini]]: Operator module settings file.
*[[User Reference:Operator Module Scripting]]: Automated execution of operator tasks.
*[[User Reference:Module Command Line Options]]: Modifying module behavior with command line options.
*[[User Reference:Data File Formats]]: File formats supported by BCI2000.
*[[User FAQ]]: Frequently asked questions about using BCI2000.

==Configuring the Online System==
*[[User Reference:Filters|BCI2000 Filters]]: Any BCI2000 configuration consists of different filters in the Data Acquisition, Signal Processing, and Application module. These filters determine what device BCI2000 acquires data from, what data format it uses for data storage, which feature extraction and translation algorithms it uses to translate brain signals into device commands, and which kind of user feedback is provided. This page gives an overview of all filters that are currently available in the BCI2000 distribution.
*[[User Reference:Parameters]] provides an index of configuration parameters present in BCI2000 components.
*[[User Reference:States]] provides an index of state variables present in BCI2000 components.

*[[User Reference:Parameter Changes for Version 2]] helps in migrating experiments from BCI2000 version 1 to version 2.

==Verifying the Online System==

==Using BCI2000 Tools==
*[[User Reference:BCI2000Certification]]: Measure a BCI2000 system's timing performance.
*[[User Reference:BCI2000Launcher]]: Conveniently start up BCI2000 modules from a graphical interface.
*[[User Reference:BCI2000Watchdog]]: A tool to start up and monitor BCI2000 for long-term recordings.
*[[User Reference:BCI2000Viewer]]: View signals recorded with BCI2000.
*[[User Reference:BCI2000FileInfo]]: View and extract parameter information from BCI2000 data files.
*[[User Reference:BCI2000Export]]: Export BCI2000 data files into various formats.
*[[User Reference:BCI2000Analysis]]: Analyze data files offline, create and test filter chains, train classifiers for online recognition.
*[[User Reference:BCI2000 Offline Analysis]]: MATLAB-based tool to analyze data files offline in order to determine the best features for online recognition.
*[[User Reference:Eloc Helper]]: Matlab-based tool to create and modify montage files.
*[[User Reference:EEGLabImport]]: Read BCI2000 data into EEGLab.
*[[User Reference:Matlab Tools]]: Perform offline data analysis, and manage information in BCI2000 files, using Matlab functions.
*[[User Reference:Matlab MEX Files]]: Access BCI2000 data from within Matlab.
*[[User Reference:Command Line Processing]]: Compile BCI2000 filters into executables for offline processing.
*[[User Reference:StimulationConfigurationIntegrativeTool (SCIT)]]: Easily create and visualize BCI2000 parameter files for the Neuro Omega, CereStim, g.Estim, and Cortec Brain Interchange.

[[Category:Contents]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:28:09Z

Mellinger: /* Matlab Analysis Script */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
The following script has been used to produce the above graphs.
Modify the filename variable to hold the name of the BCI2000 data file to analyze.

filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:26:41Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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).

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:25:47Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[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.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:24:22Z

Mellinger: /* Analyzing RefLogger Data */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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, using the first time stamp as an 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:22:46Z

Mellinger: /* Using the RefLogger */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:22:14Z

Mellinger: /* The RefLogger Component */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 these 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:20:51Z

Mellinger: /* Sources of Imprecision */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

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

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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:19:23Z

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

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (priority queue).

===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.
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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:17:46Z

Mellinger: /* Time-stamping Events */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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, even if they may not have arrived in temporal order (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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:16:10Z

Mellinger: /* Time-stamping Brain Signal Data */

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

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 may 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:15:20Z

Mellinger: /* 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.

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

Also, it describes the ''RefLogger'', a software component 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 systems.

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:15:02Z

Mellinger: /* 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.

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

Also, it describes the ''RefLogger'', a software component 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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:11:02Z

Mellinger:

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

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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:09:44Z

Mellinger:

==Synopsis==
BCI2000 is able to record asynchronous data, so called [[Programming_Reference:Events|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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

==See also==
[[Programming_Reference:Events]], [[Technical Reference:State Definition]], [[Programming Tutorial:Implementing an Input Logger]]

[[Category:Data Acquisition]] [[Category:Framework API]]

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:03:29Z

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

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.4 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:03:18Z

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

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.3 ms.

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

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

User Reference:Validating the Event Logging Mechanism

2026-07-28T22:02:45Z

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

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]

Also here, the Event mechanism is working close to perfectly, with a jitter of +/-0.3 ms.

[[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.3 ms.

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

User Reference:Validating the Event Logging Mechanism

2026-07-28T21:59:20Z

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

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]

As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]

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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]
[[file:Event_vs_sample_time_gUSBamp.png]]

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

User Reference:Validating the Event Logging Mechanism

2026-07-28T21:59:07Z

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

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]
As one may see from this graph, event time stamp disagreement from sample position is within +/-0.5 ms, so the Event time mechanism is working close to perfectly.

[[file:Event_vs_sample_time_SignalGenerator.png]]
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.

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]
[[file:Event_vs_sample_time_gUSBamp.png]]

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

User Reference:Validating the Event Logging Mechanism

2026-07-28T21:54:04Z

Mellinger: /* Example Results */

==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 <tt>START EXECUTABLE</tt> 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 distinct purposes:

# Assessing whether the Event software mechanism works as designed,
# 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. Any differences are due to the sources of imprecision discussed above.

===Example Results===
====Data recorded with SignalGenerator source module====
[[file:Event_vs_SourceTime_SignalGenerator.png]]
[[file:Event_vs_sample_time_SignalGenerator.png]]

====Data recorded with g.USBamp source module====
[[file:Event_vs_SourceTime_gUSBamp.png]]
[[file:Event_vs_sample_time_gUSBamp.png]]

===Matlab Analysis Script===
filename = 'RefLogger_gUSBampS001R01.dat';
%
[signal, states, parameters] = load_bcidat(filename);
SampleBlockSize = parameters.SampleBlockSize.NumericValue;
SamplingRateHz = parse_sampling_rate(parameters.SamplingRate.Value{1});
SampleBlockDurationMs = SampleBlockSize / SamplingRateHz * 1e3;
%
% prepare SourceTime state by first reducing to a single value per block,
% then interpolating across block
SourceTime = double(states.SourceTime);
SourceTime2 = SourceTime(1:SampleBlockSize:end);
SourceTime2 = extend_timestamp(SourceTime2);
SourceTime3 = interp1([1:length(SourceTime2)], SourceTime2, [1:1/SampleBlockSize:length(SourceTime2)])';
% SourceTime reflects the time of acquisition, so sample time is earlier
% by a sample block duration
SourceTime3 = SourceTime3 - SampleBlockDurationMs;
%
% prepare a vector of equally spaced sample times (SourceTime may be
% jittered)
sample_time = linspace(SourceTime3(1), SourceTime3(end), length(SourceTime3))';
%
% prepare RefTime state
RefTime = double(states.RefTime);
RefTime = RefTime(1:length(SourceTime3));
% replace "unused" placeholder value with nan
RefTime(RefTime > 65535) = nan;
valid_idx = ~isnan(RefTime);
RefTime2 = RefTime(valid_idx);
RefTime2 = extend_timestamp(RefTime2);
%
% determine difference between RefTime values, and interpolated SourceTime
% values
delta1 = RefTime2 - SourceTime3(valid_idx);
%
figure;
hist(delta1, 40);
title('RefTime vs SourceTime disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta1), sqrt(var(delta1))));
xlabel('offset in ms');
%
% determine difference between RefTime values, and interpolated sample time
% values
delta2 = RefTime2 - sample_time(valid_idx);
%
figure;
hist(delta2, 40);
title('RefTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta2), sqrt(var(delta2))));
xlabel('offset in ms');
%
% determine difference between interpolated SourceTime, and interpolated sample time
% values
delta3 = SourceTime3(valid_idx) - sample_time(valid_idx);
%
figure;
hist(delta3, 40);
title('SourceTime vs sample time disagreement');
subtitle(sprintf('mean: %f ms, sdev: %f ms', mean(delta3), sqrt(var(delta3))));
xlabel('offset in ms');
%
%
function result = extend_timestamp(input)
% extend timestamp from the 0..65535 to full range
result = input;
add = 0;
for i = 2:length(input)
if input(i) < input(i-1)
add = add + 65536;
end
result(i) = input(i) + add;
end
end
%
function result = parse_sampling_rate(input)
[token, remain] = strtok(input, 'Hk');
result = str2double(token);
if strcmp(remain, 'kHz')
result = result * 1e3;
end
end

File:Event vs sample time gUSBamp.png

2026-07-28T21:48:28Z

Mellinger:

File:Event vs SourceTime gUSBamp.png

2026-07-28T21:48:13Z

Mellinger:

File:Event vs sample time SignalGenerator.png

2026-07-28T21:46:27Z

Mellinger:

File:Event vs SourceTime SignalGenerator.png

2026-07-28T21:44:40Z

Mellinger:

User Reference:Validating the Event Logging Mechanism

2026-07-28T21:42:32Z

Mellinger: /* Analyzing RefLogger Data */

User Reference:Validating the Event Logging Mechanism

2026-07-28T21:34:10Z

Mellinger: /* Analyzing RefLogger Data */

User Reference:Validating the Event Logging Mechanism

2026-07-28T17:00:53Z

Mellinger: /* The RefLogger Component */

User Reference:Validating the Event Logging Mechanism

2026-07-28T16:58:49Z

Mellinger: /* Synopsis */

User Reference:Validating the Event Logging Mechanism

2026-07-28T16:58:18Z

Mellinger:

User Reference:Validating the Event Logging Mechanism

2026-07-28T16:22:46Z

Mellinger:

User Reference:Validating the Event Logging Mechanism

2026-07-28T15:57:28Z

Mellinger: Created page with "==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 RefLog..."

Contributions:NeusenW4

2026-07-27T07:38:03Z

Mellinger:

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/SignalSource/NeusenW4

==Versioning==
===Authors===
Jintao Li, Frontier Lab for Applied Neurotechnology (https://ant.chenfrontierlab.com), Tianqiao and Chrissy Chen Institute

Jürgen Mellinger, Neurotechcenter

===Source Code Revisions===
9405: first working version of NeusenW4 source module

==Functional Description==
This Source module allows BCI2000 to receive electrophysiological data from one single NeusenW device.
It requires version 4 of the Neuracle API.

==Usage of Device==
<gallery mode="packed" widths=800px heights=350px>
File:Neusenw_picture_1.jpg|Figure 1: NeusenW
</gallery>
<gallery mode="packed" widths=800px heights=350px>
File:Neusenw_picture_2.jpg|Figure 2: Smart Sync Center
</gallery>
<gallery mode="packed" widths=800px heights=350px>
File:Neusenw_picture_3.jpg|Figure 3: Dongle
</gallery>
These are all devices you need to use the Source module: NeusenW amplifier, Smart Sync Center, and the dongle provided by Neuracle.
Start by connecting the Smart Sync Center to the power source. Then, turn on the amplifier and plug the dongle into the computer. No other software is needed. Make sure the computer and amplifier are connected to the Smart Sync Center through Wi-Fi.
<gallery mode="packed" widths=800px heights=350px>
File:Neusenw_picture_4.jpg|Figure 4: Trigger Box
</gallery>
The trigger box can record a variety of types of events (such as sound, light, program output), with sufficiently high timing accuracy and neurophysiological data synchronously, but it is not supported by the current version of the Source module.

==Setting Up BCI2000==
Once you compiled BCI2000 correctly and generated the solution, create a batch file to run the NeusenW Source Module. Just copy one of the existing batch files in BCI2000/batch. Then replace the first line beginning with
Start executable
with
Start executable NeusenW --local
.

==Usage Steps==
Make sure that the device and computer are connecting to Smart Sync Center and the dongle is plugged in before you start BCI2000.
# Double click the batch file you just created.
# Click the "Config" button.
# Set suitable parameters. Detail about these parameters can be found below.
# Click "Set Config".
# Click "Start" to start the experiment.

==Parameters==
===SourceCh===
Defines the number of signal channels to be acquired from the NeusenW device given the following constraints. Only certain numbers of channels are supported for specific sampling rates defined by ''SamplingRate''.

When ''SamplingRate'' is not bigger than 1000 Hz (250 Hz/500 Hz/1000 Hz), there is no limit to this parameter. When ''SamplingRate'' is 2000 Hz, ''SourceCh '' cannot be bigger than 32. When ''SamplingRate'' is 4000 Hz, the maximum of ''SourceCh'' is 16. When ''SamplingRate'' is 8000 Hz, the maximum of ''SourceCh'' is 8. When ''SamplingRate'' is 16000 Hz, the maximum of ''SourceCh'' is 4.

If this parameter is set to "auto", it will automatically be set to the number of available amplifier channels, as is suitable for ''SamplingRate'' settings up to, and including, 1000 Hz.

===SampleBlockSize===
If you set ''SampleBlockSize'' to "auto", a data block duration of 100ms will be chosen.

===SamplingRate===
The NeusenW device supports 7 different sampling rates: 250 Hz, 500 Hz, 1000 Hz, 2000 Hz, 4000 Hz, 8000 Hz, and 16000 Hz. This parameter may limit the value of SourceCh as described above. When set to "auto", a sampling rate of 1000 Hz will be chosen.

===SourceChGain===
Use "auto" to have the correct values filled in by the source module.

===SourceChOffset===
Use "auto", or a list of length ''SourceCh'' with all zero entries.

===ChannelNames===
When set to "auto", channel names will be filled in automatically.
If ''SourceCh'' is set to 64, EEG 10-20 electrode names from the Neuracle cap will be used.
Otherwise, generic channel names indicating the sensor type and number will be created.

===SerialNumber===
The serial number of the desired NeusenW amplifier to connect to, as printed on the device.
If set to "auto", and only a single NeusenW amplifier is available, that will be chosen.
If set to "auto" with more than one NeusenW amplifiers available, an error message will be issued.

==See also==
[[User Reference:DataIOFilter]], [[Programming Reference:GenericADC Class]]
[[Category:Filters]][[Category:Data Acquisition]]