Data sample object

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:

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.

To interpret the values in the <stream> array, you must check the field cols from the result of the subscribe method.

How to interpret the values

Suppose you want to get the mental command stream. You successfully subscribe to the stream "com", and you receive this response:

{
    "id":8,
    "jsonrpc":"2.0",
    "result":{
        "failure":[],
        "success":[{
            "cols":["act","pow"],
            "sid":"7f899d66-442b-4bf4-9752-ed06d57b72c3",
            "streamName":"com"
        }]
    }
}

The important part is the field cols:

["act","pow"]

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:

{
    "com": ["push", 0.376],
    "sid": "7f899d66-442b-4bf4-9752-ed06d57b72c3",
    "time": 1559900743.3318
}

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.

EEG

The stream "eeg" uses these labels:

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

The maker objects include these fields:

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.

Example for an INSIGHT:

[
  "COUNTER",
  "INTERPOLATED",
  "AF3","T7","Pz","T8","AF4",
  "RAW_CQ",
  "MARKER_HARDWARE",
  "MARKERS"
]

{
  "eeg": [
    8,
    0,
    4202.051, 4235.385, 4146.667, 4210.769, 4108.718,
    0,
    0,
    []
  ],
  "sid": "8bbc58bd-0ab1-404e-b472-dac1322dbe5b",
  "time": 1590402103.9016
}

Example for an EPOC+ or EPOC X:

[
    "COUNTER",
    "INTERPOLATED",
    "AF3","F7","F3","FC5","T7","P7","O1","O2","P8","T8","FC6","F4","F8","AF4",
    "RAW_CQ",
    "MARKER_HARDWARE",
    "MARKERS"
]

{
    "eeg":[
        14,
        0,
        4161.41,4212.051,4135,4161.538,4195,4184.103,4182,
        0,
        0, 
        [{
            "applicationId": "com.emotiv.emotivpro",
            "isStop": false,
            "label": "Blink eye while relaxing",
            "markerId": "cc577d88-f404-482a-9629-3e08a0dbcc02",
            "port": "KeyStroke",
            "recordId": "f3c76112-9b7f-43ab-a906-5c15dc4dd55e",
            "value": 22
        }]
    ],
    "sid":"01e1e0f1-4416-436f-8f9d-5bf21e2e4784",
    "time":1559902873.8976
}

Motion

The stream "mot" uses these labels:

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)

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:

[
  "COUNTER_MEMS","INTERPOLATED_MEMS",
  "Q0","Q1","Q2","Q3",
  "ACCX","ACCY","ACCZ",
  "MAGX","MAGY","MAGZ"
]

{
  "mot": [
    48,
    0,
    0.735341, 0.255615, 0.627441, -0.015869,
    0.948257, -0.354986, -0.083497,
    -44.656766, -86.970985, 23.221568
  ],
  "sid": "da18712c-a292-46b7-a5a0-1bd64a3dc6f3",
  "time": 1590402244.8242
}

Example for an older INSIGHT:

[
    "COUNTER_MEMS","INTERPOLATED_MEMS",
    "GYROX","GYROY","GYROZ",
    "ACCX","ACCY","ACCZ",
    "MAGX","MAGY","MAGZ"
]

{
    "mot":[
        14,0,
        8206,8187,8181,
        4235,8668,8128,
        8294,8237,7938
    ],
    "sid":"462c4d75-113f-4664-a443-3aaa02c178d0",
    "time":1559902927.7428
}

Device information

The stream "dev" uses these labels:

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

Example with INSIGHT:

[
  "Battery",
  "Signal",
  ["AF3","T7","Pz","T8","AF4","OVERALL"],
  "BatteryPercent"
]

{
  "dev": [
    3,
    1,
    [4,1,1,2,4,25],
    74
  ],
  "sid": "edcb9287-f6d5-4c22-9b3f-783d72750f24",
  "time": 1590403053.5002
}

Example with EPOC+ or EPOC X:

[
    "Battery","Signal",
    ["AF3","F7","F3","FC5","T7","P7","O1","O2","P8","T8","FC6","F4","F8","AF4","OVERALL"],
    "BatteryPercent"
]

{
    "dev":[
        4,2,
        [2,0,1,0,1,0,0,4,0,1,0,1,0,1,24],
        98
    ],
    "sid":"d02af7d5-2bc0-46f4-8804-026a42ad7841",
    "time":1559903194.6721
}

EEG Quality

Please read this page to understand the difference between the contact quality and the EEG quality.

The stream "eq" uses these labels:

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.

This stream was added in Cortex 2.7.0

Example with INSIGHT:

[
  "batteryPercent",
  "overall",
  "sampleRateQuality",
  "AF3","T7","Pz","T8","AF4"
]

{
  "eq": [
    78,
    25,
    1.0,
    4,1,1,2,4
  ],
  "sid": "edcb9287-f6d5-4c22-9b3f-783d72750f24",
  "time": 1590403053.5002
}

Band power

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:

[
    "AF3/theta","AF3/alpha","AF3/betaL","AF3/betaH","AF3/gamma",
    "T7/theta","T7/alpha","T7/betaL","T7/betaH","T7/gamma",
    "Pz/theta","Pz/alpha","Pz/betaL","Pz/betaH","Pz/gamma",
    "T8/theta","T8/alpha","T8/betaL","T8/betaH","T8/gamma",
    "AF4/theta","AF4/alpha","AF4/betaL","AF4/betaH","AF4/gamma"
]

{
  "pow": [
    1.246,0.706,0.566,1.065,0.602,
    10.293,4.374,11.638,351.767,40.273,
    50.159,4.585,0.467,1.481,3.764,
    9.861,3.139,2.094,3.342,4.452,
    75.652,1.972,2.932,2.555,7.005
  ],
  "sid": "ff0245d1-9531-424c-9f6d-9f736f465516",
  "time": 1590403491.0307
}

Example with EPOC+ or EPOC X:

[
    "AF3/theta","AF3/alpha","AF3/betaL","AF3/betaH","AF3/gamma",
    "F7/theta","F7/alpha","F7/betaL","F7/betaH","F7/gamma",
    "F3/theta","F3/alpha","F3/betaL","F3/betaH","F3/gamma",
    "FC5/theta","FC5/alpha","FC5/betaL","FC5/betaH","FC5/gamma",
    "T7/theta","T7/alpha","T7/betaL","T7/betaH","T7/gamma",
    "P7/theta","P7/alpha","P7/betaL","P7/betaH","P7/gamma",
    "O1/theta","O1/alpha","O1/betaL","O1/betaH","O1/gamma",
    "O2/theta","O2/alpha","O2/betaL","O2/betaH","O2/gamma",
    "P8/theta","P8/alpha","P8/betaL","P8/betaH","P8/gamma",
    "T8/theta","T8/alpha","T8/betaL","T8/betaH","T8/gamma",
    "FC6/theta","FC6/alpha","FC6/betaL","FC6/betaH","FC6/gamma",
    "F4/theta","F4/alpha","F4/betaL","F4/betaH","F4/gamma",
    "F8/theta","F8/alpha","F8/betaL","F8/betaH","F8/gamma",
    "AF4/theta","AF4/alpha","AF4/betaL","AF4/betaH","AF4/gamma"
]

{
    "pow":[
        0.225,0.213,0.537,0.19,0.34,
        0.511,0.808,1.706,0.839,0.416,
        ...
        0.92,0.469,1.657,1.443,0.912,
        2.675,0.824,0.951,0.303,0.881
    ],
    "sid":"f581b2bb-c043-4a00-8737-1e8e09a9a81b",
    "time":1559902987.133
}

Performance metric

The stream "met" uses these labels:

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.

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

[
    "eng.isActive","eng",
    "exc.isActive","exc","lex",
    "str.isActive","str",
    "rel.isActive","rel",
    "int.isActive","int",
    "foc.isActive","foc"
]

{
    "met":[false,null,false,null,null,false,null,true,0.266589,false,null,true,0.098421],
    "sid":"6a68b92a-cb1f-4062-bf1f-74424fbae065",
    "time":1559903137.1741
}

Mental command

The stream "com" uses these labels:

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".

["act","pow"]

{
    "com":["pull",0.564],
    "sid":"79cc669b-af2e-465a-bdc2-0e9bd4aebe80",
    "time":1559903099.348
}

Facial expression

The stream "fac" uses these labels:

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".

Use the method getDetectionInfo to get the possible actions.

["eyeAct","uAct","uPow","lAct","lPow"]

{
    "fac":["neutral","neutral",0,"clench",0.0576],
    "sid":"a4f69c56-9769-4a4d-950c-490eb5ebe372",
    "time":1559903035.2961
}

System events

The stream "sys" is used for the training of the mental command and facial expression. It uses these labels:

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.

For example, just after you start a training for the mental command detection, you receive a system event like this:

["event","msg"]

{
    "sid":"c7e7b527-2b2e-4ec6-8c74-cf16aae8540b",
    "sys":["mentalCommand","MC_Started"],
    "time":1559903035.2961
}