Add docs of Fitbit sleep intraday features
Meng Li
parent
44c2a191f4
commit
d0c0f876f4
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
||||
|
||||
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue