|`[TABLE]`| Database table name or file path where the sleep intraday data is stored. The configuration keys in [Device Data Source Configuration](../../setup/configuration/#device-data-source-configuration) control whether this parameter is interpreted as table or file.
|`[INCLUDE_SLEEP_LATER_THAN]`| All resampled sleep rows (bin interval: one minute) that started after this time will be included in the feature computation. It is a number ranging from 0 (midnight) to 1439 (23:59) which denotes the number of minutes after midnight. If a segment is longer than one day, this value is for every day.
|`[REFERENCE_TIME]`| The reference point from which the `[ROUTINE]` features are to be computed. Chosen from `MIDNIGHT` and `START_OF_THE_SEGMENT`, default is `MIDNIGHT`. If you have multiple time segments per day it might be more informative to set this flag to `START_OF_THE_SEGMENT`.
The format of the column(s) containing the Fitbit sensor data can be `JSON` or `PLAIN_TEXT`. The data in `JSON` format is obtained directly from the Fitbit API. We support `PLAIN_TEXT` in case you already parsed your data and don't have access to your participants' Fitbit accounts anymore. If your data is in `JSON` format then summary and intraday data come packed together.
We provide examples of the input format that RAPIDS expects, note that both examples for `JSON` and `PLAIN_TEXT` are tabular and the actual format difference comes in the `fitbit_data` column (we truncate the `JSON` example for brevity).
??? example "Example of the structure of source data with Fitbit’s sleep API Version 1"
All columns are mandatory, however, all except `local_date_time` and `duration` can be empty if you don't have that data. Just have in mind that some features might be inaccurate or empty as `type_episode_id`, `level`, `is_main_sleep`, and `type` are used for sleep episodes extraction. `type_episode_id` is based on where it is extracted: if it is extracted from the 1st "minutesData" block, the `type_episode_id` field will be 0. Similarly, the kth block will be k-1.
All columns are mandatory, however, all except `local_date_time` and `duration` can be empty if you don't have that data. Just have in mind that some features might be inaccurate or empty as `type_episode_id`, `level`, `is_main_sleep`, and `type` are used for sleep episodes extraction. `type_episode_id` is based on where it is extracted: if it is extracted from the 1st "data" and "shortData" block, the `type_episode_id` field will be 0. Similarly, the kth block will be k-1.
|`[SLEEP_LEVELS]` | Fitbit’s sleep API Version 1 only provides `CLASSIC` records. However, Version 1.2 provides 2 types of records: `CLASSIC` and `STAGES`. `STAGES` is only available in devices with a heart rate sensor and even those devices will fail to report it if the battery is low or the device is not tight enough. While `CLASSIC` contains 3 sleep levels (`awake`, `restless`, and `asleep`), `STAGES` contains 4 sleep levels (`wake`, `deep`, `light`, `rem`). To make it consistent, RAPIDS grouped them into 2 `UNIFIED` sleep levels: `awake` (`CLASSIC`: `awake` and `restless`; `STAGES`: `wake`) and `asleep` (`CLASSIC`: `asleep`; `STAGES`: `deep`, `light`, and `rem`).
|`[SLEEP_TYPES]` | Types of sleep to be included in the feature extraction computation. Fitbit provides 2 types of sleep: `main`, `nap`.
|countepisode`[LEVEL][TYPE]` |episodes |Number of `[LEVEL][TYPE]`sleep episodes. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]`and `[TYPE]` can also be `all` when ``LEVELS_AND_TYPES_COMBINING_ALL`` is True, which ignores the levels and groups by sleep types.
|sumduration`[LEVEL][TYPE]` |minutes |Total duration of all `[LEVEL][TYPE]`sleep episodes. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]` and `[TYPE]`can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which ignores the levels and groups by sleep types.
|maxduration`[LEVEL][TYPE]` |minutes | Longest duration of any `[LEVEL][TYPE]`sleep episode. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]` and `[TYPE]`can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which ignores the levels and groups by sleep types.
|minduration`[LEVEL][TYPE]` |minutes | Shortest duration of any `[LEVEL][TYPE]`sleep episode. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]` and `[TYPE]`can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which ignores the levels and groups by sleep types.
|avgduration`[LEVEL][TYPE]` |minutes | Average duration of all `[LEVEL][TYPE]`sleep episodes. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]` and `[TYPE]`can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which ignores the levels and groups by sleep types.
|medianduration`[LEVEL][TYPE]` |minutes | Median duration of all `[LEVEL][TYPE]`sleep episodes. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]` and `[TYPE]`can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which ignores the levels and groups by sleep types.
|stdduration`[LEVEL][TYPE]` |minutes | Standard deviation duration of all `[LEVEL][TYPE]`sleep episodes. `[LEVEL]`is one of `[SLEEP_LEVELS]` (e.g. awake-classic or rem-stages) and `[TYPE]` is one of `[SLEEP_TYPES]` (e.g. main). Both `[LEVEL]` and `[TYPE]`can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which ignores the levels and groups by sleep types.
|ratiocount`[LEVEL]` |-|Ratio between the **count** of episodes of a single sleep `[LEVEL]` and the **count** of all episodes of all levels during both `main` and `nap` sleep types. This answers the question: what percentage of all `wake`, `deep`, `light`, and `rem` episodes were `rem`? (e.g., $countepisode[remstages][all] / countepisode[all][all]$)
|ratioduration`[LEVEL]` |-|Ratio between the **duration** of episodes of a single sleep `[LEVEL]` and the **duration** of all episodes of all levels during both `main` and `nap` sleep types. This answers the question: what percentage of all `wake`, `deep`, `light`, and `rem` time was `rem`? (e.g., $sumduration[remstages][all] / sumduration[all][all]$)
|ratiocountmain |- |Ratio between the **count** of all `main` episodes (independently of the levels inside) divided by the **count** of all `main` and `nap` episodes. This answers the question: what percentage of all sleep episodes (`main` and `nap`) were `main`? We do not provide the ratio for `nap` because is complementary. ($countepisode[all][main] / countepisode[all][all]$)
|ratiodurationmain |- |Ratio between the **duration** of all `main` episodes (independently of the levels inside) divided by the **duration** of all `main` and `nap` episodes. This answers the question: what percentage of all sleep time (`main` and `nap`) was `main`? We do not provide the ratio for `nap` because is complementary. ($sumduration[all][main] / sumduration[all][all]$)
|ratiocount`[TYPE]`within`[LEVEL]` |- |Ratio between the **count** of episodes of a single sleep `[LEVEL]` during `main` sleep divided by the **count** of episodes of a single sleep `[LEVEL]` during `main`**and**`nap`. This answers the question: are `rem` episodes more frequent during `main` than `nap` sleep? We do not provide the ratio for `nap` because is complementary. ($countepisode[remstages][main] / countepisode[remstages][all]$)
|ratioduration`[TYPE]`within`[LEVEL]` |- |Ratio between the **duration** of episodes of a single sleep `[LEVEL]` during `main` sleep divided by the **duration** of episodes of a single sleep `[LEVEL]` during `main`**and**`nap`. This answers the question: is `rem` time more frequent during `main` than `nap` sleep? We do not provide the ratio for `nap` because is complementary. ($countepisode[remstages][main] / countepisode[remstages][all]$)
|ratiocount`[LEVEL]`within`[TYPE]` |-|Ratio between the **count** of episodes of a single sleep `[LEVEL]` and the **count** of all episodes of all levels during either `main` or `nap` sleep types. This answers the question: what percentage of all `wake`, `deep`, `light`, and `rem` episodes were `rem` during `main`/`nap` sleep time? (e.g., $countepisode[remstages][main] / countepisode[all][main]$)
|ratioduration`[LEVEL]`within`[TYPE]` |-|Ratio between the **duration** of episodes of a single sleep `[LEVEL]` and the **duration** of all episodes of all levels during either `main` or `nap` sleep types. This answers the question: what percentage of all `wake`, `deep`, `light`, and `rem` time was `rem` during `main`/`nap` sleep time? (e.g., $sumduration[remstages][main] / sumduration[all][main]$)
1. Deleting values from `[SLEEP_LEVELS]` or `[SLEEP_TYPES]` will only change the features you receive from `[LEVELS_AND_TYPES]`. For example if `STAGES` only contains `[rem, light]` you will not receive `countepisode[wake|deep][TYPE]` or sum, max, min, avg, median, or std `duration`. These values will not influence `RATIOS` or `ROUTINE` features.
2. Any `[LEVEL]` grouping is done within the elements of each class `CLASSIC`, `STAGES`, and `UNIFIED`. That is, we never combine `CLASSIC` or `STAGES` types to compute features when `LEVELS_AND_TYPES_COMBINING_ALL` is True or when computing `RATIOS`.
|`[COMPUTE]` | Set to `True` to extract `FITBIT_SLEEP_INTRADAY` features from the `PRICE` provider |
|`[FEATURES]` | Features to be computed from sleep intraday data, see table below |
|`[INCLUDE_EPISODES_INTERSECTING]` | This parameter contains 2 values: `[START_TIME]` and `[LENGTH]`. Only `main` sleep episodes end later than `[START_TIME]` or start before `[START_TIME]` + `[LENGTH]` are considered. Both `[START_TIME]` and `[LENGTH]` are in minutes. `[START_TIME]` is a number ranging from 0 (midnight) to 1439 (23:59) which denotes the number of minutes after midnight. `[LENGTH]` is a number less than 1440 (24 hours). |
Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][PRICE]`:
|avgratioawaketoinbedmain`[DAY_TYPE]` |- | For each day, ratio between awake duration and in bed duration of `main` sleep episodes (ratioawaketoinbedmain) could be calculated. This feature is the average value of the selected `DAY_TYPE` days' (weekend, weekday, or both) ratioawaketoinbedmain features during a `time_segment`.
|avgstarttimeofepisodemain`[DAY_TYPE]` |minutes | For each day, start time of `main` sleep episodes (starttimeofepisodemain) could be calculated. This feature is the average value of the selected `DAY_TYPE` days' (weekend, weekday, or both) starttimeofepisodemain features during a `time_segment`.
|avgendtimeofepisodemain`[DAY_TYPE]` |minutes | For each day, end time of `main` sleep episodes (endtimeofepisodemain) could be calculated. This feature is the average value of the selected `DAY_TYPE` days' (weekend, weekday, or both) endtimeofepisodemain features during a `time_segment`.
|avgmidpointofepisodemain`[DAY_TYPE]` |minutes | For each day, the average of the start time and end time of `main` sleep episodes (midpointofepisodemain) could be calculated. This feature is the average value of the selected `DAY_TYPE` days' (weekend, weekday, or both) midpointofepisodemain features during a `time_segment`.
|socialjetlag |minutes | Number of minutes later to go to bed during the weekends than during the weekdays: avgstarttimeofepisodemain`[weekend]` - avgstarttimeofepisodemain`[weekday]`
|meanssdstarttimeofepisodemain |minutes squared | For each day, start time of `main` sleep episodes (starttimeofepisodemain) could be calculated. This feature is the mean successive squared difference of starttimeofepisodemain features: calculate the squared difference between two consecutive days' starttimeofepisodemain features and then compute the average value across those squared differences.
|meanssdendtimeofepisodemain |minutes squared | For each day, end time of `main` sleep episodes (endtimeofepisodemain) could be calculated. This feature is the mean successive squared difference of endtimeofepisodemain features: calculate the squared difference between two consecutive days' endtimeofepisodemain features and then compute the average value across those squared differences.
|meanssdmidpointofepisodemain |minutes squared | For each day, the average of the start time and end time of `main` sleep episodes (midpointofepisodemain) could be calculated. This feature is the mean successive squared difference of midpointofepisodemain features: calculate the squared difference between two consecutive days' midpointofepisodemain features and then compute the average value across those squared differences.
|medianssdstarttimeofepisodemain |minutes squared | For each day, start time of `main` sleep episodes (starttimeofepisodemain) could be calculated. This feature is the median successive squared difference of starttimeofepisodemain features: calculate the squared difference between two consecutive days' starttimeofepisodemain features and then get the median of those squared differences.
|medianssdendtimeofepisodemain |minutes squared | For each day, end time of `main` sleep episodes (endtimeofepisodemain) could be calculated. This feature is the median successive squared difference of endtimeofepisodemain features: calculate the squared difference between two consecutive days' endtimeofepisodemain features and then get the median of those squared differences.
|medianssdmidpointofepisodemain |minutes squared | For each day, the average of the start time and end time of `main` sleep episodes (midpointofepisodemain) could be calculated. This feature is the median successive squared difference of midpointofepisodemain features: calculate the squared difference between two consecutive days' midpointofepisodemain features and then get the median of those squared differences.
!!! note "Assumptions/Observations"
1. Even though Fitbit provides 2 types of sleep episodes (`main` and `nap`), only `main` sleep episodes are considered.
2. All the time related features are the number of minutes since `[INCLUDE_EPISODES_INTERSECTING][START_TIME]`.
2.`main` sleep episodes end later than `[START_TIME]` or start before `[START_TIME]` + `[LENGTH]` are regraded as the same day's sleep episodes even if it started yesterday and ended today. For example:
- Original `main` sleep episodes: (start datetime 2021-02-01 12:00, end datetime 2021-02-01 15:00), (start datetime 2021-02-01 21:00, end datetime 2021-02-02 03:00), (start datetime 2021-02-02 05:00, end datetime 2021-02-02 08:00), (start datetime 2021-02-02 11:00, end datetime 2021-02-02 14:00).
- Parameters of our settings: `[INCLUDE_EPISODES_INTERSECTING][START_TIME]` is 1320 (today's 22:00) and `[INCLUDE_EPISODES_INTERSECTING][LENGTH]` is 720 (12*60, end time: today's 22:00 + 12h = tomorrow's 10:00).
- On 2021-02-01, the following two `main` episodes will be considered: (start datetime 2021-02-01 21:00, end datetime 2021-02-02 03:00), (start datetime 2021-02-02 05:00, end datetime 2021-02-02 08:00).
3. Daily features will be extracted first. Then features of each segments will be generated according to the related daily features. Let's continue with the above example, the following daily features on 2021-02-01 will be extracted first:
