Data sample object
Last updated
Last updated
After you successfully subscribe to a data stream, Cortex will keep sending you data sample objects. See Data Subscription for details.
A data sample object contains these fields:
To interpret the values in the <stream> array, you must check the field cols from the result of the subscribe method.
Suppose you want to get the mental command stream. You successfully subscribe to the stream "com", and you receive this response:
The important part is the field cols:
So, the labels for the mental command samples are "act" (action) and "pow" (power), in this order. Then you will receive some mental command samples. They look like this:
The values in the array com match the labels in the array cols. So "push" is the value for "act" , and 0.376 is the value for "pow".
Below is the description of the labels used in each data stream.
The stream "eeg" uses these labels:
The maker objects include these fields:
Example for an INSIGHT:
Example for an EPOC+ or EPOC X:
The stream "mot" uses these labels:
Depending on the headset, the labels for the gyroscope will be GYROX, GYROY, GYROZ or the quaternions. You will never get both these labels.
Example for a newer INSIGHT:
Example for an older INSIGHT:
The stream "dev" uses these labels:
Example with INSIGHT:
Example with EPOC+ or EPOC X:
Please read this page to understand the difference between the contact quality and the EEG quality.
The stream "eq" uses these labels:
This stream was added in Cortex 2.7.0
Example with INSIGHT:
This stream gives you the power of the EEG data. The values are absolute, the unit is uV^2 / Hz. Each sample is calculated based on the last 2 seconds of EEG data.
The labels of the stream "pow" use the format "SENSOR/BAND", when SENSOR is the name of the EEG sensor and BAND is the name of the band power. Cortex provides these bands:
theta (4-8Hz)
alpha (8-12Hz)
betaL (low beta, 12-16Hz)
betaH (high beta, 16-25Hz)
gamma (25-45Hz)
So the low beta for AF3 has the label "AF3/betaL". The gamma for Pz has the label "Pz/gamma".
Example with INSIGHT:
Example with EPOC+ or EPOC X:
The stream "met" uses these labels:
Each performance metric is a decimal number between 0 and 1. Zero means "low power", 1 means "high power". So for example, a value of 0.1 for "eng" means that the user is not engaged, a value of 1.0 means the user is very engaged. If the detection cannot run because of a poor EEG signal quality then the value is null.
For each performance metrics, the flag isActive is true if the detection of this metrics is running properly. It is false if the detection cannot run. This can happen if the EEG signal from the headset is of poor quality. This flag was added in Cortex 2.2.1
The stream "com" uses these labels:
The stream "fac" uses these labels:
Use the method getDetectionInfo to get the possible actions.
The stream "sys" is used for the training of the mental command and facial expression. It uses these labels:
For example, just after you start a training for the mental command detection, you receive a system event like this:
Name
Type
Description
<stream>
array
The name of this field is the name of the data stream, for example "eeg", "met", "com"...
This array contains the values of a data sample. The type and meaning of each value depend on the stream.
sid
string
The session id used to subscribe to this data stream.
time
number
The timestamp of this sample. It is the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970 UTC.
Label
Type
Description
COUNTER
number
Increment by 1 for each sample, reset to zero every second.
INTERPOLATED
number
0 if this sample was received from the headset. 1 if this sample was interpolated by Cortex.
<EEG sensors>
number
For each EEG sensor, you get 1 value in microvolt.
RAW_CQ
number
Raw value of the contact quality.
MARKER_HARDWARE
number
1 if a hardware marker was received for this EEG sample.
0 otherwise.
MARKERS
array of objects
An array of markers. It includes the markers sent by all the applications working with this headset.
This label was added in Cortex 2.1
Name
Type
Description
applicationId
string
The id of the application that created this marker.
recordId
string
The id of the record this marker belongs to.
markerId
string
The id of this marker.
value
string or number
The value of this marker, set by injectMarker.
label
string
The label of this marker, set by injectMarker.
port
string
The port of this marker, set by injectMarker.
isStop
boolean
False if this is an instance marker.
True if this marks the end of an interval marker.
Label
Type
Description
COUNTER_MEMS
number
Increment by 1 for each sample, reset to zero every second.
INTERPOLATED_MEMS
number
0 if this sample was received from the headset. 1 if this sample was interpolated by Cortex.
ACCX, ACCY, ACCZ
number
X, Y, Z axis of the accelerometer.
MAGX, MAGY, MAGZ
number
X, Y, Z axis of the magnetometer.
Q0, Q1, Q2, Q3
number
Quaternions of the gyroscope (newer EMOTIV headsets)
GYROX, GYROY, GYROZ
number
X, Y, Z axis of the gyroscope (older EMOTIV headsets)
Label
Type
Description
Battery
number
The battery level of the headset, from 0 to 4.
Signal
number
The strength of the wireless signal received from the headset, from 0 to 1.
<EEG sensors>
number
The contact quality of each EEG sensor, from 0 to 4.
There is an additional label "OVERALL" at the end of the array. The overall contact quality is a value from 0 to 100 that is calculated from the contact quality of all the EEG sensors. The label OVERALL was added in Cortex 2.4
BatteryPercent
number
The battery level of the headset, from 0 to 100. It has the same purpose as the label "Battery", but it is more precise.
This label was added in Cortex 2.7
Label
Type
Description
batteryPercent
number
The battery level of the headset, from 0 to 100.
overall
number
A value from 0 to 100 that is calculated from the EEG quality of all the EEG sensors.
sampleRateQuality
number
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.
<EEG sensors>
number
The EEG quality of each EEG sensor, from 0 to 4.
Label
Type
Description
eng
number
Engagement
exc
number
Excitement
lex
number
Long term excitement. It is calculated from the excitement values of the last minute.
str
number
Stress / Frustration
rel
number
Relaxation
int
number
Interest / Affinity
foc
number
Focus
eng.isActive
boolean
Active flag for engagement.
exc.isActive
boolean
Active flag for excitement.
str.isActive
boolean
Active flag for stress / frustration.
rel.isActive
boolean
Active flag for relaxation.
int.isActive
boolean
Active flag for interest / affinity.
foc.isActive
boolean
Active flag for focus.
Label
Type
Description
act
string
A mental command action. Use the method getDetectionInfo to get the possible actions.
pow
number
The power of the action. It is a decimal number between 0 and 1, zero means "low power", 1 means "high power".
Label
Type
Description
eyeAct
string
The action of the eyes.
uAct
string
The upper face action.
uPow
number
Power of the upper face action. Zero means "low power", 1 means "high power".
lAct
string
The lower face action.
lPow
number
Power of the lower face action. Zero means "low power", 1 means "high power".
Label
Type
Description
event
string
The name of the detection. Can be "mentalCommand" or "facialExpression"
msg
string
Depends on the detection. Use the method getDetectionInfo to get the possible values, check the field events in the result.