From 65760bc02e21077a54cbb13077bb610f7bb8bfa0 Mon Sep 17 00:00:00 2001 From: JulioV Date: Fri, 6 Nov 2020 16:37:38 -0500 Subject: [PATCH] Add screen and update absolute links --- docs/features/feature-introduction.md | 2 +- docs/features/phone-screen.md | 58 +++++++++++++++++++++++++++ docs/file-structure.md | 6 +-- docs/index.md | 2 +- mkdocs.yml | 1 + 5 files changed, 64 insertions(+), 5 deletions(-) create mode 100644 docs/features/phone-screen.md diff --git a/docs/features/feature-introduction.md b/docs/features/feature-introduction.md index 5f9b445d..9cd3d391 100644 --- a/docs/features/feature-introduction.md +++ b/docs/features/feature-introduction.md @@ -2,7 +2,7 @@ Every phone or Fitbit sensor has a corresponding config section e.g. `[PHONE_CALLS]` in `config.yaml` and 0, 1 or more **providers**. A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. -If you want to extract features from any sensor, set the corresponding `[PROVIDER][COMPUTE]` variable to `TRUE`, the `[TABLE]` variable to the sensor's table name in your database, and change any other parameters as [desired](https://www.rapids.science/setup/configuration/#sensor-and-features-to-process), and [execute](https://www.rapids.science/setup/execution/) RAPIDS: +If you want to extract features from any sensor, set the corresponding `[PROVIDER][COMPUTE]` variable to `TRUE`, the `[TABLE]` variable to the sensor's table name in your database, and change any other parameters as [desired](/setup/configuration/#sensor-and-features-to-process), and [execute](/setup/execution/) RAPIDS: !!! example In this example the `config.yaml` file has been configured to extract `PHONE_CALLS` features from a table called `calls`: diff --git a/docs/features/phone-screen.md b/docs/features/phone-screen.md new file mode 100644 index 00000000..c1203f7b --- /dev/null +++ b/docs/features/phone-screen.md @@ -0,0 +1,58 @@ +# Phone Screen + +Sensor parameters description for `[PHONE_SCREEN]`: + +|Key                              | Description | +|----------------|----------------------------------------------------------------------------------------------------------------------------------- +|`[TABLE]`| Database table where the screen data is stored + +## RAPIDS provider + +!!! info "Available day segments and platforms" + - Available for all day segments + - Available for Android and iOS + +!!! info "File Sequence" + ```bash + - data/raw/{pid}/phone_screen_raw.csv + - data/raw/{pid}/phone_screen_with_datetime.csv + - data/raw/{pid}/phone_screen_with_datetime_unified.csv + - data/interim/{pid}/phone_screen_episodes.csv + - data/interim/{pid}/phone_screen_episodes_resampled.csv + - data/interim/{pid}/phone_screen_episodes_resampled_with_datetime.csv + - data/interim/{pid}/phone_screen_features/phone_screen_{language}_{provider_key}.csv + - data/processed/features/{pid}/phone_screen.csv + ``` + + +Parameters description for `[PHONE_SCREEN][PROVIDERS][RAPIDS]`: + +|Key                                                           | Description | +|----------------|----------------------------------------------------------------------------------------------------------------------------------- +|`[COMPUTE]`| Set to `True` to extract `PHONE_SCREEN` features from the `RAPIDS` provider| +|`[FEATURES]` | Features to be computed, see table below +|`[REFERENCE_HOUR_FIRST_USE]` | The reference point from which `firstuseafter` is to be computed, default is midnight +|`[IGNORE_EPISODES_SHORTER_THAN]` | Ignore episodes that are shorter than this threshold (minutes). Set to 0 to disable this filter. +|`[IGNORE_EPISODES_LONGER_THAN]` | Ignore episodes that are longer than this threshold (minutes). Set to 0 to disable this filter. +|`[EPISODE_TYPES]` | Currently we only support `unlock` episodes (from when the phone is unlocked until the screen is off) + + +Features description for `[PHONE_SCREEN][PROVIDERS][RAPIDS]`: + +|Feature |Units |Description| +|-------------------------- |---------- |---------------------------| +|sumduration |minutes |Total duration of all unlock episodes. +|maxduration |minutes |Longest duration of any unlock episode. +|minduration |minutes |Shortest duration of any unlock episode. +|avgduration |minutes |Average duration of all unlock episodes. +|stdduration |minutes |Standard deviation duration of all unlock episodes. +|countepisode |episodes |Number of all unlock episodes + +|firstuseafter |minutes |Minutes until the first unlock episode. + +!!! note "Assumptions/Observations" + 1. In Android, `lock` events can happen right after an `off` event, after a few seconds of an `off` event, or never happen depending on the phone\'s settings, therefore, an `unlock` episode is defined as the time between an `unlock` and a `off` event. In iOS, `on` and `off` events do not exist, so an `unlock` episode is defined as the time between an `unlock` and a `lock` event. + + 2. Events in iOS are recorded reliably albeit some duplicated `lock` events within milliseconds from each other, so we only keep consecutive unlock/lock pairs. In Android you cand find multiple consecutive `unlock` or `lock` events, so we only keep consecutive unlock/off pairs. In our experiments these cases are less than 10% of the screen events collected and this happens because `ACTION_SCREEN_OFF` and `ACTION_SCREEN_ON` are `sent when the device becomes non-interactive which may have nothing to do with the screen turning off`. In addition to unlock/off episodes, in Android it is possible to measure the time spent on the lock screen before an `unlock` event as well as the total screen time (i.e. `ON` to `OFF`) but these are not implemented at the moment. + + 3. We transform iOS screen events to match Android's format, we replace `lock` episodes with `off` episodes (2 with 0) in iOS. However, as mentioned above this is still computing `unlock` to `lock` episodes. diff --git a/docs/file-structure.md b/docs/file-structure.md index d731ed90..0e4ee709 100644 --- a/docs/file-structure.md +++ b/docs/file-structure.md @@ -1,18 +1,18 @@ # File Structure !!! tip - Read this page if you want to learn more about how RAPIDS is structured. If you want to start using it go to [Installation](https://www.rapids.science/setup/installation/) and then to [Initial Configuration](https://www.rapids.science/setup/configuration/) + Read this page if you want to learn more about how RAPIDS is structured. If you want to start using it go to [Installation](/setup/installation/) and then to [Initial Configuration](/setup/configuration/) All paths mentioned in this page are relative to RAPIDS' root folder. -If you want to extract the behavioral features that RAPIDS offers, you will only have to create or modify the [`.env` file](https://www.rapids.science/setup/configuration/#database-credentials), [participants files](https://www.rapids.science/setup/configuration/#participant-files), [day segment files](https://www.rapids.science/setup/configuration/#day-segments), and the `config.yaml` file. The `config.yaml` file is the heart of RAPIDS and includes parameters to manage participants, data sources, sensor data, visualizations and more. +If you want to extract the behavioral features that RAPIDS offers, you will only have to create or modify the [`.env` file](/setup/configuration/#database-credentials), [participants files](/setup/configuration/#participant-files), [day segment files](/setup/configuration/#day-segments), and the `config.yaml` file. The `config.yaml` file is the heart of RAPIDS and includes parameters to manage participants, data sources, sensor data, visualizations and more. All data is saved in `data/`. The `data/external/` folder stores any data imported or created by the user, `data/raw/` stores sensor data as imported from your database, `data/interim/` has intermediate files necessary to compute behavioral features from raw data, and `data/processed/` has all the final files with the behavioral features in folders per participant and sensor. All the source code is saved in `src/`. The `src/data/` folder stores scripts to download, clean and pre-process sensor data, `src/features` has scripts to extract behavioral features organized in their respective subfolders , `src/models/` can host any script to create models or statistical analyses with the behavioral features you extract, and `src/visualization/` has scripts to create plots of the raw and processed data. -There are other important files and folders but only relevant if you are interested in extending RAPIDS (e.g. virtual env files, docs, tests, Dockerfile, the Snakefile, etc.). In the figure below, we represent the interactions between users and files. After a user modifies `config.yaml` and `.env` the `Snakefile` file will decide what Snakemake rules have to be executed to produce the required output files (behavioral features) and what scripts are in charge of producing such files. In addition, users can add or modifiy files in the `data` folder (for example to configure the [participants files](https://www.rapids.science/setup/configuration/#participant-files) or the [day segment files](https://www.rapids.science/setup/configuration/#day-segments)). +There are other important files and folders but only relevant if you are interested in extending RAPIDS (e.g. virtual env files, docs, tests, Dockerfile, the Snakefile, etc.). In the figure below, we represent the interactions between users and files. After a user modifies `config.yaml` and `.env` the `Snakefile` file will decide what Snakemake rules have to be executed to produce the required output files (behavioral features) and what scripts are in charge of producing such files. In addition, users can add or modifiy files in the `data` folder (for example to configure the [participants files](/setup/configuration/#participant-files) or the [day segment files](/setup/configuration/#day-segments)).
diff --git a/docs/index.md b/docs/index.md index c95b1133..ff8e2162 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,7 @@ RAPIDS is open source, documented, modular, tested, and reproducible. At the mom :fontawesome-solid-tasks: Join our discussions on our algorithms and assumptions for feature [processing](https://github.com/carissalow/rapids/issues?q=is%3Aissue+is%3Aopen+label%3Adiscussion). -:fontawesome-solid-play: Ready to start? Go to [Installation](https://www.rapids.science/setup/installation/) and then to [Initial Configuration](https://www.rapids.science/setup/configuration/) +:fontawesome-solid-play: Ready to start? Go to [Installation](/setup/installation/) and then to [Initial Configuration](/setup/configuration/) ## How does it work? diff --git a/mkdocs.yml b/mkdocs.yml index ae145af4..58630c73 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,6 +74,7 @@ nav: - Phone Light: features/phone-light.md - Phone Locations: features/phone-locations.md - Phone Messages: features/phone-messages.md + - Phone Screen: features/phone-screen.md - Phone WiFI Connected: features/phone-wifi-connected.md - Phone WiFI Visible: features/phone-wifi-visible.md - Frequently Asked Questions: faq.md