CSV files

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 updated