# Data sample object

After you successfully [subscribe](https://emotiv.gitbook.io/cortex-api/data-subscription/subscribe) to a data stream, Cortex will keep sending you data sample objects. See [Data Subscription](https://emotiv.gitbook.io/cortex-api/data-subscription) for details.

A data sample object contains these fields:

| Name      | Type     | Description                                                                                                                                                                                                      |
| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \<stream> | `array`  | <p>The name of this field is the name of the data stream, for example "eeg", "met", "com"...</p><p>This array contains the values of a data sample. The type and meaning of each value depend on the stream.</p> |
| 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](https://emotiv.gitbook.io/cortex-api/data-subscription/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:

```javascript
{
    "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**:

```javascript
["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:

```javascript
{
    "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`           | <p>0 if this sample was received from the headset.<br>1 if this sample was interpolated by Cortex.</p>                                                                                 |
| \<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`           | <p>1 if a hardware marker was received for this EEG sample.</p><p>0 otherwise.</p>                                                                                                     |
| MARKERS          | `array of objects` | <p>An array of <a href="../markers">markers</a>. It includes the markers sent by all the applications working with this headset.</p><p><em>This label was added in Cortex 2.1</em></p> |

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](https://emotiv.gitbook.io/cortex-api/markers/injectmarker). |
| label         | `string`           | The label of this marker, set by [injectMarker](https://emotiv.gitbook.io/cortex-api/markers/injectmarker). |
| port          | `string`           | The port of this marker, set by [injectMarker](https://emotiv.gitbook.io/cortex-api/markers/injectmarker).  |
| isStop        | `boolean`          | <p>False if this is an instance marker.</p><p>True if this marks the end of an interval marker.</p>         |

Example for an INSIGHT:

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

```javascript
{
  "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:

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

```javascript
{
    "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` | <p>0 if this sample was received from the headset.<br>1 if this sample was interpolated by Cortex.</p> |
| 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:

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

```javascript
{
  "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:

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

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

To understand the meaning of motion data, you can refer [EmotivPRO Documentation](https://app.gitbook.com/s/-MjlJG3HPUEdtWl0dfjx/data-streams/motion).

## 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` | <p>The contact quality of each EEG sensor, from 0 to 4.</p><p>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.<br><em>The label OVERALL was added in Cortex 2.4</em> </p> |
| BatteryPercent | `number` | <p>The battery level of the headset, from 0 to 100. It has the same purpose as the label "Battery", but it is more precise.</p><p><em>This label was added in Cortex 2.7</em></p>                                                                                                                                 |

Example with INSIGHT:

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

```javascript
{
  "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:

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

```javascript
{
    "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](https://emotiv.gitbook.io/cortex-manual/setting_up_your_eeg_device/view_contact_quality_map/contact-quality-cq-vs.-eeg-quality-eq) 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` | <p>A float value from 0 to 1 that evaluates the actual sample rate of the EEG data coming from the headset.</p><p>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.</p><p>If we lost more than 300 ms of data over the last 2 seconds, then the SRQ takes the special value -1.</p> |
| \<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:

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

```javascript
{
  "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:

```javascript
[
    "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"
]
```

```javascript
{
  "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:

```javascript
[
    "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"
]
```

```javascript
{
    "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

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**.&#x20;

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.\
\&#xNAN;*This flag was added in Cortex 2.2.1*

The "met" stream labels vary depending on the headset type, as shown in the tables below:

### The "met" Stream Labels of MN8

| Label                    | Type      | Description                                                                              |
| ------------------------ | --------- | ---------------------------------------------------------------------------------------- |
| cognitiveStress          | `number`  | Cognitive Stress measures the mental strain caused by challenging tasks or environments. |
| attention                | `number`  | Attention measures sustained focus on a single task.                                     |
| cognitiveStress.isActive | `boolean` | Active flag for cognitiveStress                                                          |
| attention.isActive       | `boolean` | Active flag for attention.                                                               |

#### **Example** <a href="#epoc-insight-flex-with-epoc-config-only" id="epoc-insight-flex-with-epoc-config-only"></a>

<pre class="language-javascript"><code class="lang-javascript">[
    "attention.isActive",
<strong>    "attention",
</strong>    "cognitiveStress.isActive",
    "cognitiveStress"
]
</code></pre>

```javascript
{
  "met": [True, 0.8, True, 0.4],
  "sid":"6a68b92a-cb1f-4062-bf1f-74424fbae066",
  "time": 1759225262.5052
  }
```

### **The "met" Stream Labels of EPOC / INSIGHT / FLEX - (with EPOC config only)** <a href="#epoc-insight-flex-with-epoc-config-only" id="epoc-insight-flex-with-epoc-config-only"></a>

| Label              | Type      | Description                                                                           |
| ------------------ | --------- | ------------------------------------------------------------------------------------- |
| eng                | `number`  | Engagement measures immersion in an activity.                                         |
| exc                | `number`  | Excitement measures the intensity of reactions to stimuli or environments.            |
| lex                | `number`  | Long term excitement. It is calculated from the excitement values of the last minute. |
| str                | `number`  | Stress measures emotional tension experienced when completing a task.                 |
| rel                | `number`  | Relaxation measures calm focus after a period of intense concentration.               |
| int                | `number`  | Interest measures attraction or aversion to stimuli.                                  |
| attention          | `number`  | Attention measures sustained focus on a single task.                                  |
| eng.isActive       | `boolean` | Active flag for engagement.                                                           |
| exc.isActive       | `boolean` | Active flag for excitement.                                                           |
| str.isActive       | `boolean` | Active flag for stress.                                                               |
| rel.isActive       | `boolean` | Active flag for relaxation.                                                           |
| int.isActive       | `boolean` | Active flag for interest                                                              |
| attention.isActive | `boolean` | Active flag for attention.                                                            |

#### Example

```javascript
[
    "eng.isActive","eng",
    "exc.isActive","exc","lex",
    "str.isActive","str",
    "rel.isActive","rel",
    "int.isActive","int",
    "attention.isActive","attention"
]
```

```javascript
{
    "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
}
```

To understand the meaning of each performance metrics, you can refer [EmotivPRO Documentation](https://app.gitbook.com/s/-MjlJG3HPUEdtWl0dfjx/data-streams/performance-metrics).

## Mental command

The stream "com" uses these labels:

| Label | Type     | Description                                                                                                                                        |
| ----- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| act   | `string` | A mental command action. Use the method [getDetectionInfo](https://emotiv.gitbook.io/cortex-api/bci/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".                                     |

```javascript
["act","pow"]
```

```javascript
{
    "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](https://emotiv.gitbook.io/cortex-api/bci/getdetectioninfo) to get the possible actions.

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

```javascript
{
    "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](https://emotiv.gitbook.io/cortex-api/bci/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](https://emotiv.gitbook.io/cortex-api/bci/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:

```javascript
["event","msg"]
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://emotiv.gitbook.io/cortex-api/data-subscription/data-sample-object.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.