diff --git a/docs/conf.py b/docs/conf.py index 614d8497..a7cd7752 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,7 +91,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/features/battery.rst b/docs/features/battery.rst deleted file mode 100644 index 38e6009a..00000000 --- a/docs/features/battery.rst +++ /dev/null @@ -1,11 +0,0 @@ -Battery Features -================ - -Available epochs: daily, morning, afternoon, evening, and night - -- Count discharge: number of battery discharging episodes -- Sum duration discharge: total duration of all discharging episodes (time the phone was discharging) -- Average consumption rate: average of the ratios between discharging episodes’ battery delta and duration -- Max consumption rate: max of the ratios between discharging episodes’ battery delta and duration -- Count charge: number of battery charging episodes -- Sum duration charge: total duration of all charging episodes (time the phone was charging) diff --git a/docs/features/bluetooth.rst b/docs/features/bluetooth.rst deleted file mode 100644 index f85df757..00000000 --- a/docs/features/bluetooth.rst +++ /dev/null @@ -1,8 +0,0 @@ -Bluetooth Features -================== - -Available epochs: daily, morning, afternoon, evening, and night - -- Count of scans (a scan is a row containing a single Bluetooth device detected by Aware) -- Unique devices (number of unique devices identified by their hardware address -bt_address field) -- Count of scans of the most unique device across each participant’s dataset diff --git a/docs/features/calls.rst b/docs/features/calls.rst deleted file mode 100644 index 334b0703..00000000 --- a/docs/features/calls.rst +++ /dev/null @@ -1,8 +0,0 @@ -Call Features -============= - -Available epochs: daily, morning, afternoon, evening, and night - -- Outgoing: count, count of distinct contacts, mean duration, sum duration, min duration, max duration, std duration, mode duration, entropy duration, time of first call (hours), time of last call (hours), count of most frequent contact. -- Received: count, count of distinct contacts, mean duration, sum duration, min duration, max duration, std duration, mode duration, entropy duration, time of first call (hours), time of last call (hours), count of most frequent contact. -- Missed: count, distinct contacts, time of first call (hours), time of last call (hours), count of most frequent contact. diff --git a/docs/features/extracted.rst b/docs/features/extracted.rst new file mode 100644 index 00000000..c95bf5bd --- /dev/null +++ b/docs/features/extracted.rst @@ -0,0 +1,92 @@ +Extracted Features +================== + +Battery +-------- + +Available epochs: daily, morning, afternoon, evening, and night + +- Count discharge: number of battery discharging episodes +- Sum duration discharge: total duration of all discharging episodes (time the phone was discharging) +- Average consumption rate: average of the ratios between discharging episodes’ battery delta and duration +- Max consumption rate: max of the ratios between discharging episodes’ battery delta and duration +- Count charge: number of battery charging episodes +- Sum duration charge: total duration of all charging episodes (time the phone was charging) + +Bluetooth +--------- + +Available epochs: daily, morning, afternoon, evening, and night + +- Count of scans (a scan is a row containing a single Bluetooth device detected by Aware) +- Unique devices (number of unique devices identified by their hardware address -bt_address field) +- Count of scans of the most unique device across each participant’s dataset + +Calls +----- + +Available epochs: daily, morning, afternoon, evening, and night + +- Outgoing: count, count of distinct contacts, mean duration, sum duration, min duration, max duration, std duration, mode duration, entropy duration, time of first call (hours), time of last call (hours), count of most frequent contact. +- Received: count, count of distinct contacts, mean duration, sum duration, min duration, max duration, std duration, mode duration, entropy duration, time of first call (hours), time of last call (hours), count of most frequent contact. +- Missed: count, distinct contacts, time of first call (hours), time of last call (hours), count of most frequent contact. + +Google Activity Recognition +--------------------------- + +Available epochs: daily, morning, afternoon, evening, and night + +- Count (number of rows) +- Most common activity +- Number of unique activities +- Activity change count (any transition between two different activities, sitting to running for example) +- Sum stationary: total duration of episodes of still and tilting (phone) activities +- Sum mobile: total duration of episodes of on foot, running, and on bicycle activities +- Sum vehicle: total duration of episodes of on vehicle activity + +Location (Barnett’s) Fetures +----------------------------- + +Available epochs: daily + +Barnett’s location features are based on the concept of flights and pauses. GPS coordinates are converted into a sequence of flights (straight line movements) and pauses (time spent stationary). Data is imputed before metrics are computed (https://arxiv.org/abs/1606.06328) + +- Time at home. Time spent at home in minutes. Home is the most visited significant location between 8 pm and 8 am including any pauses within a 200-meter radius. +- Max home distance. Maximum distance from home in meters. +- Pause probability. The fraction of a day spent in a pause (as opposed to a flight) +- Circadian routine. A continuous metric that can take any value between 0 and 1, where 0 represents a daily routine completely different from any other sensed days and 1 a routine the same as every other sensed day. +- Wkn circadian routine. Same as Circadian routine but computed separately for weekends and weekdays. +- Distance travelled. Total distance travelled over a day. +- Radius of Gyration (RoG). It is a measure in meters of the area covered by a person over a day. A centroid is calculated for all the places (pauses) visited during a day and a weighted distance between all places and the centroid is computed. The weights are proportional to the time spent in each place. +- Maximum diameter. Largest distance in meters between any two pauses. +- Avg flight duration. Mean duration of all flights. +- Avg flight length. Mean length of all flights +- Std flight duration. The standard deviation of the duration of all flights. +- Std flight length. The standard deviation of the length of all flights. +- Significant locations. The number of significant locations visited during the day. Significant locations are computed using k-means clustering over pauses found in the whole monitoring period. The number of clusters is found iterating from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another. +- Significant location entropy. Entropy measurement based on the proportion of time spent at each significant location visited during a day. + +Screen +------ + +Available epochs: daily, morning, afternoon, evening, and night + +Notes. An unlock episode is considered as the time between an unlock event and a lock event. iOS recorded these episodes reliable (albeit duplicated lock events within milliseconds from each other). However, in Android there are multiple consecutive unlock/lock events so we keep the closest pair. This happens because ACTION_SCREEN_OFF and ON are "sent when the device becomes non-interactive which may have nothing to do with the screen turning off" see this link + +- Count on: count of screen on events (only available for Android) +- Count unlock: count of screen unlock events +- Diff count on off: For debug purposes, on and off events should come in pairs, difference should be close to zero then. +- Diff count unlock lock, For debug purposes, unlock and lock events should come in pairs, difference should be close to zero then. +- Sum duration unlock: sum duration of unlock episodes +- Max duration unlock: maximum duration of unlock episodes +- Min duration unlock: minimum duration of unlock episodes +- Average duration unlock: average duration of unlock episodes +- Std duration unlock: standard deviation of the duration of unlock episodes + +SMS +--- + +Available epochs: daily, morning, afternoon, evening, and night + +- Sent: count, distinct contacts, time first sms, time last sms, count most frequent contact +- Received: count, distinct contacts, time first sms, time last sms, count most frequent contact diff --git a/docs/features/gar.rst b/docs/features/gar.rst deleted file mode 100644 index a10e26fe..00000000 --- a/docs/features/gar.rst +++ /dev/null @@ -1,12 +0,0 @@ -Google Activity Recognition -=========================== - -Available epochs: daily, morning, afternoon, evening, and night - -- Count (number of rows) -- Most common activity -- Number of unique activities -- Activity change count (any transition between two different activities, sitting to running for example) -- Sum stationary: total duration of episodes of still and tilting (phone) activities -- Sum mobile: total duration of episodes of on foot, running, and on bicycle activities -- Sum vehicle: total duration of episodes of on vehicle activity diff --git a/docs/features/location_barnetts.rst b/docs/features/location_barnetts.rst deleted file mode 100644 index 91da068c..00000000 --- a/docs/features/location_barnetts.rst +++ /dev/null @@ -1,21 +0,0 @@ -Location (Barnett’s) Fetures -============================= - -Available epochs: daily - -Barnett’s location features are based on the concept of flights and pauses. GPS coordinates are converted into a sequence of flights (straight line movements) and pauses (time spent stationary). Data is imputed before metrics are computed (https://arxiv.org/abs/1606.06328) - -- Time at home. Time spent at home in minutes. Home is the most visited significant location between 8 pm and 8 am including any pauses within a 200-meter radius. -- Max home distance. Maximum distance from home in meters. -- Pause probability. The fraction of a day spent in a pause (as opposed to a flight) -- Circadian routine. A continuous metric that can take any value between 0 and 1, where 0 represents a daily routine completely different from any other sensed days and 1 a routine the same as every other sensed day. -- Wkn circadian routine. Same as Circadian routine but computed separately for weekends and weekdays. -- Distance travelled. Total distance travelled over a day. -- Radius of Gyration (RoG). It is a measure in meters of the area covered by a person over a day. A centroid is calculated for all the places (pauses) visited during a day and a weighted distance between all places and the centroid is computed. The weights are proportional to the time spent in each place. -- Maximum diameter. Largest distance in meters between any two pauses. -- Avg flight duration. Mean duration of all flights. -- Avg flight length. Mean length of all flights -- Std flight duration. The standard deviation of the duration of all flights. -- Std flight length. The standard deviation of the length of all flights. -- Significant locations. The number of significant locations visited during the day. Significant locations are computed using k-means clustering over pauses found in the whole monitoring period. The number of clusters is found iterating from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another. -- Significant location entropy. Entropy measurement based on the proportion of time spent at each significant location visited during a day. diff --git a/docs/features/screen.rst b/docs/features/screen.rst deleted file mode 100644 index fc359a1c..00000000 --- a/docs/features/screen.rst +++ /dev/null @@ -1,16 +0,0 @@ -Screen features -=============== - -Available epochs: daily, morning, afternoon, evening, and night - -Notes. An unlock episode is considered as the time between an unlock event and a lock event. iOS recorded these episodes reliable (albeit duplicated lock events within milliseconds from each other). However, in Android there are multiple consecutive unlock/lock events so we keep the closest pair. This happens because ACTION_SCREEN_OFF and ON are "sent when the device becomes non-interactive which may have nothing to do with the screen turning off" see this link - -- Count on: count of screen on events (only available for Android) -- Count unlock: count of screen unlock events -- Diff count on off: For debug purposes, on and off events should come in pairs, difference should be close to zero then. -- Diff count unlock lock, For debug purposes, unlock and lock events should come in pairs, difference should be close to zero then. -- Sum duration unlock: sum duration of unlock episodes -- Max duration unlock: maximum duration of unlock episodes -- Min duration unlock: minimum duration of unlock episodes -- Average duration unlock: average duration of unlock episodes -- Std duration unlock: standard deviation of the duration of unlock episodes diff --git a/docs/features/sms.rst b/docs/features/sms.rst deleted file mode 100644 index 1a70c844..00000000 --- a/docs/features/sms.rst +++ /dev/null @@ -1,7 +0,0 @@ -SMS Features -============ - -Available epochs: daily, morning, afternoon, evening, and night - -- Sent: count, distinct contacts, time first sms, time last sms, count most frequent contact -- Received: count, distinct contacts, time first sms, time last sms, count most frequent contact diff --git a/docs/index.rst b/docs/index.rst index f97316f2..8a592c9f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,13 +10,13 @@ Contents: .. toctree:: :maxdepth: 2 + :caption: Getting Started - usage/getting-started + usage/introduction usage/installation - features/battery - features/bluetooth - features/calls - features/gar - features/location_barnetts - features/screen - features/sms + +.. toctree:: + :maxdepth: 2 + :caption: Features + + features/extracted diff --git a/docs/usage/getting-started.rst b/docs/usage/introduction.rst similarity index 96% rename from docs/usage/getting-started.rst rename to docs/usage/introduction.rst index f08c8f5f..cb93e421 100644 --- a/docs/usage/getting-started.rst +++ b/docs/usage/introduction.rst @@ -1,5 +1,5 @@ -Getting started -=============== +Quick Introduction +================== The goal of this pipeline is to standardize the data cleaning, featuring extraction, analysis, and evaluation of mobile sensing projects. It leverages Cookiecutter, Snakemake, Sphinx, Scypy, R, and Conda to create an end-to-end reproducible environment that can be published along with research papers.