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

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

label

string

port

string

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

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

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
}
PreviousunsubscribeNextRecords

Last updated