Lab Streaming Layer (LSL)
Notes on the data
CSV files

Header

The CSV file has a header made of 2 lines. The first line contains information about the record and its data streams. The second line is a classic CSV header with the name of the columns.

First line

The first line of the CSV file is a comma separated list of key and value pairs. The key is separated from the value by a colon. It looks like key1:value1, key2:value2, key3:value3
Here is the meaning of each key and value pair:
Key
Value
title
The title of the record
start timestamp
The timestamp of the first EEG sample of the record
stop timestamp
The timestamp of the last EEG sample of the record
headset type
The type of the headset used during this record. It can be INSIGHT, EPOC, EPOCPLUS, EPOCFLEX, EPOCX, MN8
headset serial
The serial number of the headset
headset firmware
The firmware version of the headset
channels
The number of columns in this CSV file
sampling rate
The sample rate of each data stream.
samples
The number of data samples in this CSV file.
Example:
title:foo, start timestamp:1623658701.491566, stop timestamp:1623658723.788441, headset type:INSIGHT, headset serial:7AEC4253, headset firmware:931, channels:28, sampling rate:128, samples:2855 , version:2.1,

Second line

The comma separated list of the column names of this CSV file.
Example:
Timestamp,EEG.Counter,EEG.Interpolated,EEG.AF3,EEG.T7,EEG.Pz,EEG.T8,EEG.AF4,EEG.RawCq,EEG.Battery,EEG.BatteryPercent,MarkerIndex,MarkerType,MarkerValueInt,EEG.MarkerHardware,CQ.AF3,CQ.T7,CQ.Pz,CQ.T8,CQ.AF4,CQ.Overall,EQ.SampleRateQuality,EQ.OVERALL,EQ.AF3,EQ.T7,EQ.Pz,EQ.T8,EQ.AF4

Columns

The CSV file contains many columns. For clarity, we divide them into categories in this documentation. The exact content of your CSV file depends on the options you selected when you exported the record.

EEG and markers

Column name
Value
EEG.Counter
Increment by 1 for each sample, reset to zero every second.
EEG.Interpolated
0 if this EEG sample was received from the headset. Greater than 0 if this sample was interpolated by Cortex.
EEG.<sensor>
Examples: EEG.AF3, EEG.T7, EEG.Pz, EEG.T8
For each EEG sensor, you get 1 value in microvolt.
EEG.Battery
The battery level of the headset, from 0 to 4.
EEG.BatteryPercent
The battery level of the headset, from 0 to 100. It has the same purpose as the column "Battery", but it is more precise.
EEG.MarkerHardware
1 if a hardware marker was received for this EEG sample.
0 otherwise.
Hardware markers are created with the Extender

Motion

Column name
Value
MOT.CounterMems
Increment by 1 for each sample, reset to zero every second.
MOT.InterpolatedMems
0 if this motion sample was received from the headset. Greater than 0 if this sample was interpolated by Cortex.
MOT.Q0, MOT.Q1, MOT.Q2, MOT.Q3
Quaternions of the gyroscope (newer EMOTIV headsets)
MOT.GYROX, MOT.GYROY, MOT.GYROZ
X, Y, Z axis of the gyroscope (older EMOTIV headsets)
MOT.AccX, MOT.AccY, MOT.AccZ
X, Y, Z axis of the accelerometer.
MOT.MagX, MOT.MagY, MOT.MagZ
X, Y, Z axis of the magnetometer.

Contact quality

Column name
Value
CQ.Overall
The overall contact quality is a value from 0 to 100 that is calculated from the contact quality of all the EEG sensors.
CQ.<sensor> Examples: CQ.AF3, CQ.T7, CQ.Pz, CQ.T8, CQ.AF4
The contact quality of each EEG sensor, from 0 to 4.

EEG quality

Column name
Value
EQ.SampleRateQuality
A float value from 0 to 1 that evaluates the actual sample rate of the EEG data coming from the headset.
If the wireless connection between the headset and the computer is perfect (no data loss) then the sample rate quality is 1. If X percent of the EEG samples were lost over the last 2 seconds, then the SRQ is (100 - X) / 100.
If we lost more than 300 ms of data over the last 2 seconds, then the SRQ takes the special value -1.
EQ.OVERALL
A value from 0 to 100 that is calculated from the EEG quality of all the EEG sensors.
EQ.<sensor>
Examples: EQ.AF3,EQ.T7,EQ.Pz,EQ.T8,EQ.AF4
The EEG quality of each EEG sensor, from 0 to 4.

Performance metrics

The name of the columns has the format PM.<name>.<value> The <name> is the name of a performance metric. There are 6 possible values: Engagement, Excitement, Stress, Relaxation, Interest, Focus. The <value> can be IsActive, Scaled, Raw, Min, Max.
Examples: PM.Engagement.Min, PM.Stress.IsActive, PM.Relaxation.Scaled
Value
Meaning
IsActive
1 if the detection is running properly. It is 0 if the detection cannot run. This can happen if the EEG signal from the headset is of poor quality.
Scaled
The Scaled column shows the Raw value scaled to fit on a 0 to 1 scale to provide more context for each individual's scores. The scaling is based on a successive approximation of the mean and variance for each recording, calculated as the session progresses. The data file reflects this progressive scaling which usually stabilizes after a few minutes.
Raw
The Raw column shows the raw value outputted from our Performance Metrics algorithm, which can range from single digit negative numbers to single digit positive numbers. Different individuals can have non-overlapping ranges. These numbers are meaningful when looked at relatively.
Min, Max
Min and Max values set lower and upper bounds for the Scaled value and are calculated from the current mean and variance of the Raw value. Initial values of Min and Max are set based on population data. The current value is scaled so that Min maps to .05 and Max maps to .95 on the 0-1 scale. We use a logistic scale to prevent data cutoff at 0 and 1 boundaries; the range around the mean value (mapped to 0.5) is close to linear while the extremes get steadily more nonlinear.
To scale the Raw value post hoc for a given recording, you can use the Min and Max values at the end of the recording (where they are most stable) and the following equation:
AVERAGE = (MAX + MIN)/2.0;
RANGE = MAX - MIN;
scaled = 1.0 / (1 + exp( -5.0 * (raw - AVERAGE) / RANGE));
There is one additional column, named "PM.LongTermExcitement". Long Term Excitement is a metric derived from the Excitement metric. It is a better measurement of overall mood, rather than acute changes in mental arousal.

Mental commands

Column name
Value
MC.Action
A mental command action. See the meaning of each value below.
MC.ActionPower
The power of the action. It is a decimal number between 0 and 1, zero means "low power", 1 means "high power".
MC.IsActive
1 if the detection is running properly. It is 0 if the detection cannot run. This can happen if the EEG signal from the headset is of poor quality.
The possible values for MC.Action are:
MC.Action
Meaning
1
Neutral
2
Push
4
Pull
8
Lift
16
Drop
32
Left
64
Right
128
Rotate Left
256
Rotate Right
512
Rotate Clockwise
1024
Rotate Counter-Clockwise
2048
Rotate Forward
4096
Rotate Backward
8192
Disappear

Facial expressions

Column name
Value
FE.BlinkWink
1 for "Neutral"
10 for "Blink"
11 for "Wink Left"
12 for "Wink Right"
FE.HorizontalEyesDirection
-1 for "Look Left"
0 for "Neutral"
1 for "Look Right"
FE.UpperFaceAction
1 for "Neutral"
32 for "Raise Brows"
64 for "Furrow Brows"
FE.UpperFaceActionPower
The power of the upper face action. It is a decimal number between 0 and 1, zero means "low power", 1 means "high power".
FE.LowerFaceAction
1 for "Neutral"
128 for "Smile"
256 for "Clench Teeth"
512 for "Laugh"
1024 for "Smirk Left" 2048 for "Smirk Right"
FE.LowerFaceActionPower
The power of the lower face action. It is a decimal number between 0 and 1, zero means "low power", 1 means "high power".

Frequency band

The file contains 5 columns for each EEG sensor of the headset. The name of the columns has the format POW.<sensor>.<band>
The bands are:
  • Theta: 4-8 Hertz
  • Alpha: 8-12 Hertz
  • BetaL: 12-16 Hertz
  • BetaH: 16-25 Hertz
  • Gamma: 25-45 Hertz
For example, for the EEG sensor AF3, the file has 5 columns: POW.AF3.Theta, POW.AF3.Alpha, POW.AF3.BetaL, POW.AF3.BetaH, POW.AF3.Gamma.
Last modified 7mo ago