From c734c8b415c3b293e62a8540ff23365f9ee1c35f Mon Sep 17 00:00:00 2001 From: JulioV Date: Wed, 25 Nov 2020 18:24:43 -0500 Subject: [PATCH] Update fitbit docs --- docs/features/feature-introduction.md | 7 +++++-- docs/features/fitbit-heartrate-intraday.md | 6 ++++-- docs/features/fitbit-heartrate-summary.md | 6 ++++-- docs/features/fitbit-sleep-summary.md | 6 ++++-- docs/features/fitbit-steps-intraday.md | 6 ++++-- docs/features/fitbit-steps-summary.md | 6 ++++-- docs/index.md | 2 +- 7 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/features/feature-introduction.md b/docs/features/feature-introduction.md index 5d4b309f..403ce42f 100644 --- a/docs/features/feature-introduction.md +++ b/docs/features/feature-introduction.md @@ -5,6 +5,9 @@ Every phone or Fitbit sensor has a corresponding config section in `config.yaml` !!! hint We recommend reading this page if you are using RAPIDS for the first time +!!! hint + All sensor features are stored under `/data/processed/features` on files per sensor, per participant and per study (all participants). + !!! example "Config section example for `PHONE_ACCELEROMETER`" ```yaml @@ -38,7 +41,7 @@ Every phone or Fitbit sensor has a corresponding config section in `config.yaml` ``` ## Sensor Parameters -Each sensor configuration section has a `Parameters` subsection (see `#2` in the example). These are parameters that affect different aspects of how the raw data is downloaded, and processed. The `TABLE` parameter exists for every sensor, but some sensors will have extra parameters like [`[PHONE_LOCATIONS]`](../phone-locations/). We explain these parameters in a table at the top of each sensor documentation page. +Each sensor configuration section has a "parameters" subsection (see `#2` in the example). These are parameters that affect different aspects of how the raw data is downloaded, and processed. The `TABLE` parameter exists for every sensor, but some sensors will have extra parameters like [`[PHONE_LOCATIONS]`](../phone-locations/). We explain these parameters in a table at the top of each sensor documentation page. ## Sensor Providers Each sensor configuration section can have zero, one or more behavioral feature **providers** (see `#3` in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. In this example, accelerometer has two providers: RAPIDS (see `#4`) and PANDA (see `#5`). @@ -49,7 +52,7 @@ Each provider has parameters that affect the computation of the behavioral featu We explain every provider's parameter in a table under the `Parameters description` heading on each provider documentation page. ### Provider Features -Each provider offers a set of behavioral features (see `#4.2` or `#5.2` in the example). For some providers these features are grouped in an array (like those for `RAPIDS` provider in `#4.2`) but for others they are grouped in a collection of arrays (like those for `PANDAS` provider in `#5.2`) depending on the meaning and purpose of those features. In either case you can delete the features you are not interested in and they will not be included in the sensor's output feature file. +Each provider offers a set of behavioral features (see `#4.2` or `#5.2` in the example). For some providers these features are grouped in an array (like those for `RAPIDS` provider in `#4.2`) but for others they are grouped in a collection of arrays depending on the meaning and purpose of those features (like those for `PANDAS` provider in `#5.2`). In either case, you can delete the features you are not interested in and they will not be included in the sensor's output feature file. We explain each behavioral feature in a table under the `Features description` heading on each provider documentation page. diff --git a/docs/features/fitbit-heartrate-intraday.md b/docs/features/fitbit-heartrate-intraday.md index 42d783bf..bafb8944 100644 --- a/docs/features/fitbit-heartrate-intraday.md +++ b/docs/features/fitbit-heartrate-intraday.md @@ -4,9 +4,11 @@ Sensor parameters description for `[FITBIT_HEARTRATE_INTRADAY]`: |Key                              | Description | |----------------|----------------------------------------------------------------------------------------------------------------------------------- -|`[TABLE]`| Database table name or file path where the heart rate intraday data is stored. Source data type and column format are defined in [Device Data Source Configuration](../../setup/configuration/#device-data-source-configuration). +|`[TABLE]`| Database table name or file path where the heart rate 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. -Column format could be `JSON` or `PLAIN_TEXT`. Data with `JSON` column format is obtained from Fitbit API directly. Summary data and intraday data come together in `JSON` format. Each row doesn't have to contain the data for a single day as it depends on the way Fitbit API is queried. Examples of the source data with two formats are as follows. Data with `JSON` format is chunked. +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" diff --git a/docs/features/fitbit-heartrate-summary.md b/docs/features/fitbit-heartrate-summary.md index 9c64f9b4..553421c1 100644 --- a/docs/features/fitbit-heartrate-summary.md +++ b/docs/features/fitbit-heartrate-summary.md @@ -4,9 +4,11 @@ Sensor parameters description for `[FITBIT_HEARTRATE_SUMMARY]`: |Key                              | Description | |----------------|----------------------------------------------------------------------------------------------------------------------------------- -|`[TABLE]`| Database table name or file path where the heart rate summary data is stored. Source data type and column format are defined in [Device Data Source Configuration](../../setup/configuration/#device-data-source-configuration). +|`[TABLE]`| Database table name or file path where the heart rate summary 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. -Column format could be `JSON` or `PLAIN_TEXT`. Data with `JSON` column format is obtained from Fitbit API directly. Summary data and intraday data come together in `JSON` format. Each row doesn't have to contain the data for a single day as it depends on the way Fitbit API is queried. Examples of the source data with two formats are as follows. Data with `JSON` format is chunked. +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" diff --git a/docs/features/fitbit-sleep-summary.md b/docs/features/fitbit-sleep-summary.md index 4ab433de..c9bc8064 100644 --- a/docs/features/fitbit-sleep-summary.md +++ b/docs/features/fitbit-sleep-summary.md @@ -4,9 +4,11 @@ Sensor parameters description for `[FITBIT_SLEEP_SUMMARY]`: |Key                              | Description | |----------------|----------------------------------------------------------------------------------------------------------------------------------- -|`[TABLE]`| Database table name or file path where the sleep summary data is stored. Source data type and column format are defined in [Device Data Source Configuration](../../setup/configuration/#device-data-source-configuration). +|`[TABLE]`| Database table name or file path where the sleep summary 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. -Column format could be `JSON` or `PLAIN_TEXT`. Data with `JSON` column format is obtained from Fitbit API directly. Summary data and intraday data come together in `JSON` format. Each row doesn't have to contain the data for a single day as it depends on the way Fitbit API is queried. Examples of the source data with two formats are as follows. Data with `JSON` format is chunked. +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" diff --git a/docs/features/fitbit-steps-intraday.md b/docs/features/fitbit-steps-intraday.md index 17270bf7..aba4da84 100644 --- a/docs/features/fitbit-steps-intraday.md +++ b/docs/features/fitbit-steps-intraday.md @@ -4,9 +4,11 @@ Sensor parameters description for `[FITBIT_STEPS_INTRADAY]`: |Key                              | Description | |----------------|----------------------------------------------------------------------------------------------------------------------------------- -|`[TABLE]`| Database table name or file path where the steps intraday data is stored. Source data type and column format are defined in [Device Data Source Configuration](../../setup/configuration/#device-data-source-configuration). +|`[TABLE]`| Database table name or file path where the steps 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. -Column format could be `JSON` or `PLAIN_TEXT`. Data with `JSON` column format is obtained from Fitbit API directly. Summary data and intraday data come together in `JSON` format. Each row doesn't have to contain the data for a single day as it depends on the way Fitbit API is queried. Examples of the source data with two formats are as follows. Data with `JSON` format is chunked. +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" diff --git a/docs/features/fitbit-steps-summary.md b/docs/features/fitbit-steps-summary.md index b239c2c3..a9b5298a 100644 --- a/docs/features/fitbit-steps-summary.md +++ b/docs/features/fitbit-steps-summary.md @@ -4,9 +4,11 @@ Sensor parameters description for `[FITBIT_STEPS_SUMMARY]`: |Key                              | Description | |----------------|----------------------------------------------------------------------------------------------------------------------------------- -|`[TABLE]`| Database table name or file path where the steps summary data is stored. Source data type and column format are defined in [Device Data Source Configuration](../../setup/configuration/#device-data-source-configuration). +|`[TABLE]`| Database table name or file path where the steps summary 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. -Column format could be `JSON` or `PLAIN_TEXT`. Data with `JSON` column format is obtained from Fitbit API directly. Summary data and intraday data come together in `JSON` format. Each row doesn't have to contain the data for a single day as it depends on the way Fitbit API is queried. Examples of the source data with two formats are as follows. Data with `JSON` format is chunked. +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" diff --git a/docs/index.md b/docs/index.md index a7713b26..c6edd6d8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,4 +33,4 @@ RAPIDS is formed by R and Python scripts orchestrated by [Snakemake](https://sna ## How is it organized? -In broad terms the `config.yaml`, `.env` files, participant files, and day segment files are the only ones that you will have to modify. All data is stored in `data/` and all scripts are stored in `src/`. For more information see RAPIDS' [File Structure](file-structure.md). \ No newline at end of file +In broad terms the `config.yaml`, [`.env` file](../setup/configuration/#database-credentials), [participants files](../setup/configuration/#participant-files), [day segment files](../setup/configuration/#day-segments) are the only ones that you will have to modify. All data is stored in `data/` and all scripts are stored in `src/`. For more information see RAPIDS' [File Structure](file-structure.md). \ No newline at end of file