====== Age of sample: BrainVision EEG recording with LSL ======
Copyright: Ole Traupe (2017).

===== Motivation =====
LSL syncs multi-source multi-modal (multi-channel) time series data on our lab network (https://github.com/sccn/labstreaminglayer). However, it cannot account for anything it does not know. Most importantly, LSL does not know how old those samples are, i.e. how long it took from the occurrence of e.g. a scalp potential to time-stamping its digitized sample. We have to measure this "age of sample" ourselves in order to compensate for it in the data to enable markers make useful statements about experimental timing.

===== EEG hardware =====
Here we look at the age of the EEG samples recorded with our BrainVision equipment, i.e. our active ActiCap electrodes (incl. control boxes), our wireless MOVE EEG transmission system (senders and receivers; optional) and our BrainAmps DC (incl. USB adapters).

===== Test setup and procedure =====
The test involves sending electrical impulses (n=3600, 50 ms average recurrence) from a low-latency interface (the parallel port, controlled via MATLAB) of a PC directly to our ActiCap EEG electrodes. Impulse amplitude is limited to ~150 mV via a voltage divider (ratio: 1:20). "At the same time" this PC sends "LSL makers" (string formatted irregularly sampled time series data) over the network, the "ground truth" in this setup. Another PC runs the BrainVision Recorder (gathering data from the USB adapters), the BrainVision LSL app ("converting" these data samples into an LSL stream), and LSL's LabRecorder recording the "EEG data" (electrical impulses) and the markers sent from the first PC. The age of sample then is given by the time stamp difference of the markers and the corresponding impulse flanks in the BrainVision data.

The low latency of the parallel interface was confirmed earlier by sending and receiving electrical impulses from one parallel port to a second parallel port on the same PC and by measuring the time from "immediately" before to "immediately" after this transmission (controlled via MATLAB).

Low latency and accuracy of the LSL markers were confirmed earlier by sending them over the network in parallel to the transmission of electrical impulses from one PC to another via a parallel port connection (also controlled via MATLAB).

Notions like "at the same time", "low latency", and "immediately" refer to time spans far below of what is of interest here (i.e. "How many milliseconds…?).

===== PC and network specifications =====
The sending PC was equipped with an Intel Core i5 3570 Quad-Core processor (@ 3.4 GHz) and 16 GB of RAM. The recording PC was equipped with an Intel Xeon E5 2620 Hexa-Core processor (@ 2.0 GHz) and 64 GB of RAM. Both machines used only a small fraction of their resources during the test. Both were equipped with a 1 Gbit/s ethernet interface and were running in 1 Gbit/s mode (verified).

===== Software versions =====
Experience shows that "device latency" depends on a lot of factors. Virtually all parts of the signal processing cascade contribute to it, be it hard- or software. The age of sample can be seen as an integrated property of all the "functional" parts (ignoring electrical conduction, i.e.) of the contributing lab equipment as it is at the time of the measurement.

The sending PC employed MATLAB R2012b and the low-level interface controlling driver "io64" (inpoutx64.dll) ver. 1.20.

The recording PC ran the BrainVision Recorder ver. 1.20.0601, the BrainAmpSeries and the BrainVisionRDA LSL apps ver. 1.10, and LSL's LabRecorder ver. 1.12b (Windows executable).

===== Varied parameters =====
As we don't use one and the same setup all the time, this test varied those parameters which should have the strongest practical implications. Those are:
  - Signal transmission from the ActiCap Control Boxes to the BrainAmps: WIFI (MOVE) vs. tethered (standard ribbon cables)
  - LSL sample collection: from the BrainVision Recorder's RDA interface (BrainVisionRDA) vs. "directly" via querying the USB adapters (BrainAmpSeries)
  - Sampling rate: 5000 vs. 1000 vs. 250 Hz
  - Channel count: 128 vs. 32 channels

===== Test results =====
The following measurements were taken (each series of time stamp differences is shown in 3 different scales: 100 ms range, 10 ms range, and auto-scale):

a) tethered_direct_5000_32: 50.6 ms
{{:software:lsl-test:lsl1.png?800|}}
 
b) tethered_direct_5000_128: 49.8 ms
{{:software:lsl-test:lsl2.png?800|}}

c) tethered_rda_5000_32: 59.0 ms
{{:software:lsl-test:lsl3.png?800|}}

d) tethered_rda_5000_128: 60.5 ms
{{:software:lsl-test:lsl4.png?800|}}

e) tethered_rda_1000_32: 59.5 ms
{{:software:lsl-test:lsl5.png?800|}}

f) tethered_rda_1000_128: 59.8 ms
{{:software:lsl-test:lsl6.png?800|}}

g) tethered_rda_256_32: 66.9 ms
{{:software:lsl-test:lsl7.png?800|}}

h) tethered_rda_256_128: 67.6 ms
{{:software:lsl-test:lsl8.png?800|}}

i) wifi_rda_5000_32: 63.5 ms
{{:software:lsl-test:lsl9.png?800|}}

j) wifi_rda_5000_128: 65.1 ms
{{:software:lsl-test:lsl10.png?800|}}

k) wifi_rda_1000_32: 64.0 ms
{{:software:lsl-test:lsl11.png?800|}}

l) wifi_rda_1000_128: 66.5 ms
{{:software:lsl-test:lsl12.png?800|}}
 
===== Conclusions =====
Several findings seem noteworthy and are presented here in the order of impact.
  * Directly interfacing the **USB adapters** is the fastest way to get hands on our BrainVision EEG data with an age of sample of **~50 ms** [a, b].
  * **RDA interface** latency increment is **~10 ms** [c, d vs. a, b].
  * Sampling rate shows some seemingly paradox results. Increasing the sampling rate from a typical general purpose value of 1000 Hz to 5000 Hz results in no substantial change in latency of [-0,425 ms; c, d, I, j vs. e, f, k, l]. However, reducing the sampling rate to **256 Hz** (from 1000 Hz) results in a latency increase of **~8 ms** [g, h vs. e, f]. This latter value likely results from software down-sampling by the BrainVision Recorder which apparently is rather costly in terms of processing time.
  * **WIFI (MOVE) transmission** results in an additional latency of **~5 ms** [I, j, k, l vs. c, d, e, f] (resembling prior results not presented here).
  * Channel count remains inconclusive overall. An increase of the age of sample due to an increased channel count seems plausible at least. And the results from the "RDA" condition seem to back this view with **128 channels** (vs. 32) leading to a latency increase of **~1-2 ms** [d, f, h, j, l vs. c, e, g, I, k], which is consistent over all individual measurement pairs. However, in the "direct" interface condition – even if only with n=1 observations – the result is the opposite (reduction of ~0.9 ms) [b vs. a]. The reason for this is unclear so far and might lie in some obscure properties of the BrainVision hard- or software.
Following these conclusions, the "worst case" scenario would be the RDA access (60 ms) of 160 EEG channels (+ 1-2 ms) sampled with 256 Hz (+ 8 ms) and transmitted via the MOVE system (+5 ms) with an age of sample of up to 75 ms, whereas our **"standard setup"** of RDA access of 160 channels sampled with 1000 Hz transmitted via MOVE defaults to a value of **< 67 ms**.

===== Problems =====
Several problems were encountered during data acquisition and are addressed briefly.
  * Some of the WIFI (MOVE) transmitted "EEG" data showed attrition in detected impulse flanks. In consequence, two of the time series pairs (impulses/markers) had to be trimmed to a corresponding range [j, l]. Closer inspection revealed that the MOVE transmission resulted in less steep impulse flanks, likely due to some filtering properties of the additional hardware. Future recordings will employ wider impulses in order to allow full-amplitude plateau phases for a most reliable flank detection.
  * Some of the measurements indicate a certain variance of the age-of-sample due to pronounced value oscillation (e.g. c,d). Such oscillations might occur due to timing interactions of different parts of the measurement cascade, or as a result of temperature fluctuations of certain hardware components (CPU, network hardware etc.). Future recordings will employ longer recording durations for more reliable measurements--and hopefully better insight into the dynamics underlying this oscillation.

===== Warnings =====
The following warnings must be issued with regard to the presented results and conclusions.
  * Each of the conditions was assessed only via a few, short measurements. So the presented values don't come with any high certainty. They can help you getting an idea of the orders of magnitude, though, as well as the relative influences of individual factors. 
  * Following the above notions, the presented results are valid only for the employed software versions. As one (drastic) example, using a previous version of the BrainVisionRDA LSL app in this otherwise unaltered setup resulted in a latency gain of ~35 ms!
  * The notable variance in measured latencies (due to temperature fluctuations, timing interactions etc.), together with the known influence of software version, makes it mandatory to assess important setups on an individual basis.
  * PARTICULARLY, there might also be future updates of hardware versions (BrainAmps, USB Adapters) with timing implications making the re-assessment of lab setups necessary.
  * At the moment of testing there was a severe timing issue with the markers collected from the RDA interface. As LSL pushed them into an irregularly sampled stream (no fixed sampling rate), the missing linearization (de-jittering) during import disrupted the contingency with the corresponding EEG stream. However, as the above procedure did not involve any markers collected from the BrainVision system, this did not affect the detected latencies. To see whether this issue now is fixed, check up with the LSL repo on GitHub: [[https://github.com/sccn/labstreaminglayer]]. 
  * Although the BrainAmpSeries LSL app yields the lowest age of sample, the "direct" approach might not always prove helpful for the average BrainVision EEG user. The BrainVision Recorder provides superior monitoring of online data and also is easier to configure for some than the BrainAmpSeries graphical user interface.