diff --git a/docs/features/add-new-features.md b/docs/features/add-new-features.md index d1dfd8e4..14eb6627 100644 --- a/docs/features/add-new-features.md +++ b/docs/features/add-new-features.md @@ -41,6 +41,7 @@ As a tutorial, we will add a new provider for `PHONE_ACCELEROMETER` called `VEGA - Fitbit Heart Rate Summary - Fitbit Heart Rate Intraday - Fitbit Sleep Summary + - Fitbit Sleep Intraday - Fitbit Steps Summary - Fitbit Steps Intraday diff --git a/docs/features/fitbit-sleep-intraday.md b/docs/features/fitbit-sleep-intraday.md new file mode 100644 index 00000000..49149a1b --- /dev/null +++ b/docs/features/fitbit-sleep-intraday.md @@ -0,0 +1,127 @@ +# Fitbit Sleep Intraday + +Sensor parameters description for `[FITBIT_SLEEP_INTRADAY]`: + +|Key                              | Description | +|----------------|----------------------------------------------------------------------------------------------------------------------------------- +|`[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_EPISODES_LATER_THAN]`| Earliest time of episodes to be included for sleep intraday feature extraction. It is a number ranged 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`. + +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" + + === "JSON" + + |device_id |fitbit_data | + |---------------------------------------- |--------------------------------------------------------- | + |a748ee1a-1d0b-4ae9-9074-279a2b6ba524 |{"sleep": [{"awakeCount": 2, "awakeDuration": 3, "awakeningsCount": 10, "dateOfSleep": "2020-10-07", "duration": 8100000, "efficiency": 91, "endTime": "2020-10-07T18:10:00.000", "isMainSleep": true, "logId": 14147921940, "minuteData": [{"dateTime": "15:55:00", "value": "3"}, {"dateTime": "15:56:00", "value": "3"}, {"dateTime": "15:57:00", "value": "2"},...], "minutesAfterWakeup": 0, "minutesAsleep": 123, "minutesAwake": 12, "minutesToFallAsleep": 0, "restlessCount": 8, "restlessDuration": 9, "startTime": "2020-10-07T15:55:00.000", "timeInBed": 135}, {"awakeCount": 0, "awakeDuration": 0, "awakeningsCount": 1, "dateOfSleep": "2020-10-07", "duration": 3780000, "efficiency": 100, "endTime": "2020-10-07T10:52:30.000", "isMainSleep": false, "logId": 14144903977, "minuteData": [{"dateTime": "09:49:00", "value": "1"}, {"dateTime": "09:50:00", "value": "1"}, {"dateTime": "09:51:00", "value": "1"},...], "minutesAfterWakeup": 1, "minutesAsleep": 62, "minutesAwake": 0, "minutesToFallAsleep": 0, "restlessCount": 1, "restlessDuration": 1, "startTime": "2020-10-07T09:49:00.000", "timeInBed": 63}], "summary": {"totalMinutesAsleep": 185, "totalSleepRecords": 2, "totalTimeInBed": 198}} + |a748ee1a-1d0b-4ae9-9074-279a2b6ba524 |{"sleep": [{"awakeCount": 3, "awakeDuration": 21, "awakeningsCount": 16, "dateOfSleep": "2020-10-08", "duration": 19260000, "efficiency": 89, "endTime": "2020-10-08T06:01:30.000", "isMainSleep": true, "logId": 14150613895, "minuteData": [{"dateTime": "00:40:00", "value": "3"}, {"dateTime": "00:41:00", "value": "3"}, {"dateTime": "00:42:00", "value": "3"},...], "minutesAfterWakeup": 0, "minutesAsleep": 275, "minutesAwake": 33, "minutesToFallAsleep": 0, "restlessCount": 13, "restlessDuration": 25, "startTime": "2020-10-08T00:40:00.000", "timeInBed": 321}], "summary": {"totalMinutesAsleep": 275, "totalSleepRecords": 1, "totalTimeInBed": 321}} + |a748ee1a-1d0b-4ae9-9074-279a2b6ba524 |{"sleep": [{"awakeCount": 1, "awakeDuration": 3, "awakeningsCount": 8, "dateOfSleep": "2020-10-09", "duration": 19320000, "efficiency": 96, "endTime": "2020-10-09T05:57:30.000", "isMainSleep": true, "logId": 14161136803, "minuteData": [{"dateTime": "00:35:30", "value": "2"}, {"dateTime": "00:36:30", "value": "1"}, {"dateTime": "00:37:30", "value": "1"},...], "minutesAfterWakeup": 0, "minutesAsleep": 309, "minutesAwake": 13, "minutesToFallAsleep": 0, "restlessCount": 7, "restlessDuration": 10, "startTime": "2020-10-09T00:35:30.000", "timeInBed": 322}], "summary": {"totalMinutesAsleep": 309, "totalSleepRecords": 1, "totalTimeInBed": 322}} + + === "PLAIN_TEXT" + Will update this section later. + +??? example "Example of the structure of source data with Fitbit’s sleep API Version 1.2" + + === "JSON" + + |device_id |fitbit_data | + |---------------------------------------- |--------------------------------------------------------- | + |a748ee1a-1d0b-4ae9-9074-279a2b6ba524 |{"sleep":[{"dateOfSleep":"2020-10-10","duration":3600000,"efficiency":92,"endTime":"2020-10-10T16:37:00.000","infoCode":2,"isMainSleep":false,"levels":{"data":[{"dateTime":"2020-10-10T15:36:30.000","level":"restless","seconds":60},{"dateTime":"2020-10-10T15:37:30.000","level":"asleep","seconds":660},{"dateTime":"2020-10-10T15:48:30.000","level":"restless","seconds":60},...], "summary":{"asleep":{"count":0,"minutes":56},"awake":{"count":0,"minutes":0},"restless":{"count":3,"minutes":4}}},"logId":26315914306,"minutesAfterWakeup":0,"minutesAsleep":55,"minutesAwake":5,"minutesToFallAsleep":0,"startTime":"2020-10-10T15:36:30.000","timeInBed":60,"type":"classic"},{"dateOfSleep":"2020-10-10","duration":22980000,"efficiency":88,"endTime":"2020-10-10T08:10:00.000","infoCode":0,"isMainSleep":true,"levels":{"data":[{"dateTime":"2020-10-10T01:46:30.000","level":"light","seconds":420},{"dateTime":"2020-10-10T01:53:30.000","level":"deep","seconds":1230},{"dateTime":"2020-10-10T02:14:00.000","level":"light","seconds":360},...], "summary":{"deep":{"count":3,"minutes":92,"thirtyDayAvgMinutes":0},"light":{"count":29,"minutes":193,"thirtyDayAvgMinutes":0},"rem":{"count":4,"minutes":33,"thirtyDayAvgMinutes":0},"wake":{"count":28,"minutes":65,"thirtyDayAvgMinutes":0}}},"logId":26311786557,"minutesAfterWakeup":0,"minutesAsleep":318,"minutesAwake":65,"minutesToFallAsleep":0,"startTime":"2020-10-10T01:46:30.000","timeInBed":383,"type":"stages"}],"summary":{"stages":{"deep":92,"light":193,"rem":33,"wake":65},"totalMinutesAsleep":373,"totalSleepRecords":2,"totalTimeInBed":443}} + |a748ee1a-1d0b-4ae9-9074-279a2b6ba524 |{"sleep":[{"dateOfSleep":"2020-10-11","duration":41640000,"efficiency":89,"endTime":"2020-10-11T11:47:00.000","infoCode":0,"isMainSleep":true,"levels":{"data":[{"dateTime":"2020-10-11T00:12:30.000","level":"wake","seconds":450},{"dateTime":"2020-10-11T00:20:00.000","level":"light","seconds":870},{"dateTime":"2020-10-11T00:34:30.000","level":"wake","seconds":780},...], "summary":{"deep":{"count":4,"minutes":52,"thirtyDayAvgMinutes":62},"light":{"count":32,"minutes":442,"thirtyDayAvgMinutes":364},"rem":{"count":6,"minutes":68,"thirtyDayAvgMinutes":58},"wake":{"count":29,"minutes":132,"thirtyDayAvgMinutes":94}}},"logId":26589710670,"minutesAfterWakeup":1,"minutesAsleep":562,"minutesAwake":132,"minutesToFallAsleep":0,"startTime":"2020-10-11T00:12:30.000","timeInBed":694,"type":"stages"}],"summary":{"stages":{"deep":52,"light":442,"rem":68,"wake":132},"totalMinutesAsleep":562,"totalSleepRecords":1,"totalTimeInBed":694}} + |a748ee1a-1d0b-4ae9-9074-279a2b6ba524 |{"sleep":[{"dateOfSleep":"2020-10-12","duration":28980000,"efficiency":93,"endTime":"2020-10-12T09:34:30.000","infoCode":0,"isMainSleep":true,"levels":{"data":[{"dateTime":"2020-10-12T01:31:00.000","level":"wake","seconds":600},{"dateTime":"2020-10-12T01:41:00.000","level":"light","seconds":60},{"dateTime":"2020-10-12T01:42:00.000","level":"deep","seconds":2340},...], "summary":{"deep":{"count":4,"minutes":63,"thirtyDayAvgMinutes":59},"light":{"count":27,"minutes":257,"thirtyDayAvgMinutes":364},"rem":{"count":5,"minutes":94,"thirtyDayAvgMinutes":58},"wake":{"count":24,"minutes":69,"thirtyDayAvgMinutes":95}}},"logId":26589710673,"minutesAfterWakeup":0,"minutesAsleep":415,"minutesAwake":68,"minutesToFallAsleep":0,"startTime":"2020-10-12T01:31:00.000","timeInBed":483,"type":"stages"}],"summary":{"stages":{"deep":63,"light":257,"rem":94,"wake":69},"totalMinutesAsleep":415,"totalSleepRecords":1,"totalTimeInBed":483}} + + === "PLAIN_TEXT" + Will update this section later. + +## RAPIDS provider + +!!! info "Available time segments" + - Available for all time segments + +!!! info "File Sequence" + ```bash + # [might update this section later] + - data/raw/{pid}/fitbit_sleep_intraday_raw.csv + - data/raw/{pid}/fitbit_sleep_intraday_parsed.csv + - data/raw/{pid}/fitbit_sleep_intraday_parsed_with_datetime.csv + - data/interim/{pid}/fitbit_sleep_intraday_features/fitbit_sleep_intraday_{language}_{provider_key}.csv + - data/processed/features/{pid}/fitbit_sleep_intraday.csv + ``` + + +Parameters description for `[FITBIT_SLEEP_INTRADAY][PROVIDERS][RAPIDS]`: + +|Key                              | Description | +|----------------|----------------------------------------------------------------------------------------------------------------------------------- +|`[COMPUTE]` | Set to `True` to extract `FITBIT_SLEEP_INTRADAY` features from the `RAPIDS` provider| +|`[FEATURES]` | Features to be computed from sleep intraday data, see table below | +|`[SLEEP_LEVELS]` | Fitbit’s sleep API Version 1 only provides `CLASSIC` record. However, Version 1.2 provides 2 types of records: `CLASSIC` and `STAGES`. 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 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. + + +Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][RAPIDS]` LEVELS_AND_TYPES: + +|Feature |Units |Description | +|-------------------------- |-------------- |-------------------------------------------------------------| +|countepisode[LEVEL][TYPE] |episodes |Number of [LEVEL][TYPE] sleep episodes. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). Both [LEVEL] and [TYPE] can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which denotes all levels or all types are considered. +|sumduration[LEVEL][TYPE] |minutes |Total duration of all [LEVEL][TYPE] sleep episodes. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). Both [LEVEL] and [TYPE] can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which denotes all levels or all types are considered. +|maxduration[LEVEL][TYPE] |minutes | Longest duration of any [LEVEL][TYPE] sleep episode. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). Both [LEVEL] and [TYPE] can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which denotes all levels or all types are considered. +|minduration[LEVEL][TYPE] |minutes | Shortest duration of any [LEVEL][TYPE] sleep episode. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). Both [LEVEL] and [TYPE] can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which denotes all levels or all types are considered. +|avgduration[LEVEL][TYPE] |minutes | Average duration of all [LEVEL][TYPE] sleep episodes. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). Both [LEVEL] and [TYPE] can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which denotes all levels or all types are considered. +|stdduration[LEVEL][TYPE] |minutes | Standard deviation duration of all [LEVEL][TYPE] sleep episodes. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). Both [LEVEL] and [TYPE] can also be `all` when `LEVELS_AND_TYPES_COMBINING_ALL` is True, which denotes all levels or all types are considered. + + +Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][RAPIDS]` RATIOS ACROSS_LEVELS: + +|Feature |Units |Description | +|-------------------------- |-------------- |-------------------------------------------------------------| +|ratiocount[LEVEL] |- |Ratio of countepisode[LEVEL]all to countepisodeallall. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) +|ratioduration[LEVEL] |- |Ratio of sumduration[LEVEL]all to sumdurationallall. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) + + +Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][RAPIDS]` RATIOS ACROSS_TYPES: + +|Feature |Units |Description | +|-------------------------- |-------------- |-------------------------------------------------------------| +|ratiocountmain |- |Ratio of countepisodeallmain to countepisodeallall +|ratiodurationmain |- |Ratio of sumdurationallmain to sumdurationallall + + +Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][RAPIDS]` RATIOS WITHIN_LEVELS: + +|Feature |Units |Description | +|--------------------------------- |-------------- |-------------------------------------------------------------| +|ratiocount[TYPE]within[LEVEL] |- |Ratio of countepisode[LEVEL][TYPE] to countepisode[LEVEL]all. [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main) and [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic). +|ratioduration[TYPE]within[LEVEL] |- |Ratio of sumduration[LEVEL][TYPE] to sumduration[LEVEL]all. [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main) and [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic). + + +Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][RAPIDS]` RATIOS WITHIN_TYPES: + +|Feature |Units |Description | +|--------------------------------- |-------------- |-------------------------------------------------------------| +|ratiocount[LEVEL]within[TYPE] |- |Ratio of countepisode[LEVEL][TYPE] to countepisodeall[TYPE]. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). +|ratioduration[LEVEL]within[TYPE] |- |Ratio of sumduration[LEVEL][TYPE] to sumdurationall[TYPE]. [LEVEL] is chosen from `[SLEEP_LEVELS]` (e.g. awakeclassic) and [TYPE] is chosen from `[SLEEP_TYPES]` (e.g. main). + + +Features description for `[FITBIT_STEPS_INTRADAY][PROVIDERS][RAPIDS]` ROUTINE: + +|Feature |Units |Description | +|--------------------------------- |-------------- |-------------------------------------------------------------| +|starttimefirstmainsleep |minutes |Start time in minutes (based on `REFERENCE_TIME`) of the first main sleep episode after `INCLUDE_EPISODES_LATER_THAN`. +|endtimelastmainsleep |minutes |End time in minutes (based on `REFERENCE_TIME`) of the last main sleep episode after `INCLUDE_EPISODES_LATER_THAN`. +|starttimefirstnap |minutes |Start time in minutes (based on `REFERENCE_TIME`) of the first nap episode after `INCLUDE_EPISODES_LATER_THAN`. +|endtimelastnap |minutes |End time in minutes (based on `REFERENCE_TIME`) of the last nap episode after `INCLUDE_EPISODES_LATER_THAN`. + + + + + +!!! note "Assumptions/Observations" + + + diff --git a/mkdocs.yml b/mkdocs.yml index 2b2bf0cb..5786590d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -105,6 +105,7 @@ nav: - Fitbit Heart Rate Summary: features/fitbit-heartrate-summary.md - Fitbit Heart Rate Intraday: features/fitbit-heartrate-intraday.md - Fitbit Sleep Summary: features/fitbit-sleep-summary.md + - Fitbit Sleep Intraday: features/fitbit-sleep-intraday.md - Fitbit Steps Summary: features/fitbit-steps-summary.md - Fitbit Steps Intraday: features/fitbit-steps-intraday.md - Empatica: