TCP Tagging (Software Tagging)

  • NB: Document updated for OpenViBE 1.3.0 (doc updated 09.Jan.2017).

Background

This text describes TCP Tagging, a software tagging mechanism for accurate placement of event markers (stimulations in OpenViBE) in EEG signals in order to process Event-Related Potentials (ERP) such as P300.

ERP is a neurophysiological response to a specific stimulus. In order to obtain signal segment corresponding to the ERP, one needs to have an accurately aligned event marker in the signal, corresponding to the stimulus that elicited the ERP. Here we call jitter the delay between the exact moment when the stimulus is presented to the user and the moment corresponding to the event marker in the signal acquisition. A constant jitter generally has little impact on ERP processing, provided that the jitter is either measurable or not too large. A varying jitter on the other hand may have a huge impact on classification score.

This chart represents the cross-validation score of XDAWN+LDA classifier with an artificial varying jitter. The simulated jitter was uniformly generated over an increasing interval (x-axis). This chart represents the cross-validation score of XDAWN+LDA classifier with an artificial varying jitter. The simulated jitter was uniformly generated over an increasing interval (x-axis).

Some acquisition devices allow to insert event markers directly in the signal during acquisition with an approach called hardware tagging. For instance some TMSI acquisition devices have a dedicated parallel port that can be connected to the station. This method is generally accurate but is not supported by all devices.

Therefore a software solution to this problem is often needed. However this is not an easy task because it requires to have a precise measure of time for the signal, which we don’t always have with the hardware at hand.

TCP Tagging has been designed to achieve a good accuracy for the correct placement of markers, while keeping the design simple. Starting from OpenViBE 1.2.0, TCP Tagging is intended to replace the alternative External Stimulations approach, which has been deprecated.

Design and operation

Basically, TCP Tagging is a plugin in Acquisition Server that opens a TCP/IP port. The stimulator rendering the events causing the ERP are supposed to open a connection to this port, and send the stimulation (event marker) there, possibly immediately after rendering of the event. The TCP Tagging plugin running on the server will then attach the received marker to the EEG stream as closely as possible. Subsequent processing in Designer can then use these markers to segment the signal.

Format to send to the server :

[uint64 padding ; uint64 stimulus ; uint64 timestamp]

equals 24 bytes, i.e. you can send triplets of uint64s to the AS while the TCP Tagging connection is open. If the timestamp is 0, the stimulus is interpreted to be immediate. The padding is used to keep compatibility with the External Stimulations format.

Careful: there does not appear to be byte order conversions in the TCP Tagging at the moment, i.e. AS expects the uint64s to be in the same byte order as the system the server is running on.

Note that the port the client must connect to is 15361 by default. However you can set up a different port with the acquisition server, by clicking Preferences and change the TCP Tagging port setting.

preferences_panel-highlighted

How to send tags from an external application

Basically all the clients just open a TCP socket to the server and send stimulations to the socket. If your Acquisition Server and the application are on different computers, you need to replace ‘localhost’ with the host computers address and use the port you configured in AS. In case of problems, remember to check that a firewall is not blocking the connection.

 

N.b. : Later in Designer, in order to be able to configure processing related to the stimuli, all the numeric stimulus identifiers should be included in this list. Other stimuli may not be selectable in the Designer GUI. If you wish to work with other numbers, you need to modify the OpenViBE source code and register them.

Here are TCP Tagging client examples in different programming languages.

Python

An example of a python client able to send tags to the acquistion server is provided in contrib/plugins/server-extensions/tcp-tagging/client-example.

In order to use it you need first to start the acquisition server, connect with a driver and play acquisition. To send a tag to the acquisition server, simply run:

$ python example-client.py

Explore the source code of example-client.py to see how to implement a client to send a tag to the acquisition server. Note that in OV v1.2.0 – v1.2.1 there is a bug in the python example which requires you to use python 3. To run it with python 2, replace ‘bytes()’ function in the python code with ‘bytearray()’.

Java

To send stimulations from Java, you can try this simple class.

C++

Finally, in modules/tcptagging/src/CStimulusSender.cpp of the OpenViBE source tree you can find a simple C++ class that implements a TCP Tagging client. The class is used by e.g. the P300 Stimulator and Graz Visualization boxes bundled with OpenViBE.

Implementing custom hardware tagging

To be really precise, you might want to send the markers directly to your EEG amplifier. There are currently no standard to do this. As the OpenViBE boxes that support TCP Tagging send the software stimulations over a very simple interface of the IStimulusSender.h, it is relatively straightforward to change them to use hardware tagging with your specific hardware. Simply create another implementation of the CStimulusSender class and change TCPTagging::createStimulusSender() to return pointer to your custom implementation. Then write the low-level device-specific messaging logic in the implementation. Recompiling OpenViBE, the boxes now should use your hardware tagging instead.

This entry was posted in Acquisition Server documentation, Documentation and tagged , , , . Bookmark the permalink.