rapids/docs/features/phone-screen.md

59 lines
4.7 KiB
Markdown

# Phone Screen
Sensor parameters description for `[PHONE_SCREEN]`:
|Key                              | Description |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------
|`[CONTAINER]`| Data stream [container](../../datastreams/data-streams-introduction/) (database table, CSV file, etc.) where the screen data is stored
## RAPIDS provider
!!! info "Available time segments and platforms"
- Available for all time 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/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), default is 6 hours. 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.
<!-- |episodepersensedminutes |episodes/minute |The ratio between the total number of episodes in an epoch divided by the total time (minutes) the phone was sensing data. -->
!!! 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.