RAPIDS is a community effort and as such we want to continue recognizing the contributions from other researchers. Besides citing RAPIDS, we ask you to cite any of the authors listed below if you used those sensor providers in your analysis, thank you!
Vega J, Li M, Aguillera K, Goel N, Joshi E, Durica KC, Kunta AR, Low CA
+RAPIDS: Reproducible Analysis Pipeline for Data Streams Collected with Mobile Devices
+JMIR Preprints. 18/08/2020:23246
+DOI: 10.2196/preprints.23246
+URL: https://preprints.jmir.org/preprint/23246
If you computed accelerometer features using the provider [PHONE_ACCLEROMETER][PANDA] cite this paper in addition to RAPIDS.
+
+
Panda et al. citation
+
Panda N, Solsky I, Huang EJ, Lipsitz S, Pradarelli JC, Delisle M, Cusack JC, Gadd MA, Lubitz CC, Mullen JT, Qadan M, Smith BL, Specht M, Stephen AE, Tanabe KK, Gawande AA, Onnela JP, Haynes AB. Using Smartphones to Capture Novel Recovery Metrics After Cancer Surgery. JAMA Surg. 2020 Feb 1;155(2):123-129. doi: 10.1001/jamasurg.2019.4702. PMID: 31657854; PMCID: PMC6820047.
If you computed applications foreground features using the app category (genre) catalogue in [PHONE_APPLICATIONS_FOREGROUND][RAPIDS] cite this paper in addition to RAPIDS.
+
+
Stachl et al. citation
+
Clemens Stachl, Quay Au, Ramona Schoedel, Samuel D. Gosling, Gabriella M. Harari, Daniel Buschek, Sarah Theres Völkel, Tobias Schuwerk, Michelle Oldemeier, Theresa Ullmann, Heinrich Hussmann, Bernd Bischl, Markus Bühner. Proceedings of the National Academy of Sciences Jul 2020, 117 (30) 17680-17687; DOI: 10.1073/pnas.1920484117
If you computed locations features using the provider [PHONE_LOCATIONS][BARNETT] cite this paper and this paper in addition to RAPIDS.
+
+
Barnett et al. citation
+
Ian Barnett, Jukka-Pekka Onnela, Inferring mobility measures from GPS traces with missing data, Biostatistics, Volume 21, Issue 2, April 2020, Pages e98–e112, https://doi.org/10.1093/biostatistics/kxy059
+
+
+
Canzian et al. citation
+
Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp ‘15). Association for Computing Machinery, New York, NY, USA, 1293–1304. DOI:https://doi.org/10.1145/2750858.2805845
If you computed locations features using the provider [PHONE_LOCATIONS][DORYAB] cite this paper and this paper in addition to RAPIDS.
+
+
Doryab et al. citation
+
Doryab, A., Chikarsel, P., Liu, X., & Dey, A. K. (2019). Extraction of Behavioral Features from Smartphone and Wearable Data. ArXiv:1812.10394 [Cs, Stat]. http://arxiv.org/abs/1812.10394
+
+
+
Canzian et al. citation
+
Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp ‘15). Association for Computing Machinery, New York, NY, USA, 1293–1304. DOI:https://doi.org/10.1145/2750858.2805845
We use mkdocs with the material theme to write these docs. Whenever you make any changes, just push them back to the repo and the documentation will be deployed automatically.
The documentation config file is /mkdocs.yml, if you are adding new .md files to the docs modify the nav attribute at the bottom of that file. You can use the hierarchy there to find all the files that appear in the documentation.
Check this page to get familiar with the different visual elements we can use in the docs (admonitions, code blocks, tables, etc.) You can also refer to /docs/setup/installation.md and /docs/setup/configuration.md to see practical examples of these elements.
Along with the continued development and the addition of new sensors and features to the RAPIDS pipeline, tests for the currently available sensors and features are being implemented. Since this is a Work In Progress this page will be updated with the list of sensors and features for which testing is available. For each of the sensors listed a description of the data used for testing (test cases) are outline. Currently for all intent and testing purposes the tests/data/raw/test01/ contains all the test data files for testing android data formats and tests/data/raw/test02/ contains all the test data files for testing iOS data formats. It follows that the expected (verified output) are contained in the tests/data/processed/test01/ and tests/data/processed/test02/ for Android and iOS respectively. tests/data/raw/test03/ and tests/data/raw/test04/ contain data files for testing empty raw data files for android and iOS respectively.
+
The following is a list of the sensors that testing is currently available.
The raw message data file contains data for 2 separate days.
+
The data for the first day contains records 5 records for every
+ epoch.
+
The second day's data contains 6 records for each of only 2
+ epoch (currently morning and evening)
+
The raw message data contains records for both message_types
+ (i.e. recieved and sent) in both days in all epochs. The
+ number records with each message_types per epoch is randomly
+ distributed There is at least one records with each
+ message_types per epoch.
+
There is one raw message data file each, as described above, for
+ testing both iOS and Android data.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
Due to the difference in the format of the raw call data for iOS and Android the following is the expected results the calls_with_datetime_unified.csv. This would give a better idea of the use cases being tested since the calls_with_datetime_unified.csv would make both the iOS and Android data comparable.
+
+
The call data would contain data for 2 days.
+
The data for the first day contains 6 records for every epoch.
+
The second day's data contains 6 records for each of only 2
+ epoch (currently morning and evening)
+
The call data contains records for all call_types (i.e.
+ incoming, outgoing and missed) in both days in all epochs.
+ The number records with each of the call_types per epoch is
+ randomly distributed. There is at least one records with each
+ call_types per epoch.
+
There is one call data file each, as described above, for testing
+ both iOS and Android data.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
Due to the difference in the format of the raw screen data for iOS and Android the following is the expected results the screen_deltas.csv. This would give a better idea of the use cases being tested since the screen_eltas.csv would make both the iOS and Android data comparable These files are used to calculate the features for the screen sensor
+
+
The screen delta data file contains data for 1 day.
+
The screen delta data contains 1 record to represent an unlock
+ episode that falls within an epoch for every epoch.
+
The screen delta data contains 1 record to represent an unlock
+ episode that falls across the boundary of 2 epochs. Namely the
+ unlock episode starts in one epoch and ends in the next, thus
+ there is a record for unlock episodes that fall across night
+ to morning, morning to afternoon and finally afternoon to
+ night
+
The testing is done for unlock episode_type.
+
There is one screen data file each for testing both iOS and
+ Android data formats.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
Due to the difference in the format of the raw battery data for iOS and Android as well as versions of iOS the following is the expected results the battery_deltas.csv. This would give a better idea of the use cases being tested since the battery_deltas.csv would make both the iOS and Android data comparable. These files are used to calculate the features for the battery sensor.
+
+
The battery delta data file contains data for 1 day.
+
The battery delta data contains 1 record each for a charging and
+ discharging episode that falls within an epoch for every
+ epoch. Thus, for the daily epoch there would be multiple
+ charging and discharging episodes
+
Since either a charging episode or a discharging episode and
+ not both can occur across epochs, in order to test episodes that
+ occur across epochs alternating episodes of charging and
+ discharging episodes that fall across night to morning,
+ morning to afternoon and finally afternoon to night are
+ present in the battery delta data. This starts with a
+ discharging episode that begins in night and end in morning.
+
There is one battery data file each, for testing both iOS and
+ Android data formats.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
The raw Bluetooth data file contains data for 1 day.
+
The raw Bluetooth data contains at least 2 records for each
+ epoch. Each epoch has a record with a timestamp for the
+ beginning boundary for that epoch and a record with a
+ timestamp for the ending boundary for that epoch. (e.g. For
+ the morning epoch there is a record with a timestamp for
+ 6:00AM and another record with a timestamp for 11:59:59AM.
+ These are to test edge cases)
+
An option of 5 Bluetooth devices are randomly distributed
+ throughout the data records.
+
There is one raw Bluetooth data file each, for testing both iOS
+ and Android data formats.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files.
There are 2 data files (wifi_raw.csv and sensor_wifi_raw.csv)
+ for each fake participant for each phone platform.
+
The raw WIFI data files contain data for 1 day.
+
The sensor_wifi_raw.csv data contains at least 2 records for
+ each epoch. Each epoch has a record with a timestamp for the
+ beginning boundary for that epoch and a record with a
+ timestamp for the ending boundary for that epoch. (e.g. For
+ the morning epoch there is a record with a timestamp for
+ 6:00AM and another record with a timestamp for 11:59:59AM.
+ These are to test edge cases)
+
The wifi_raw.csv data contains 3 records with random timestamps
+ for each epoch to represent visible broadcasting WIFI network.
+ This file is empty for the iOS phone testing data.
+
An option of 10 access point devices is randomly distributed
+ throughout the data records. 5 each for sensor_wifi_raw.csv and
+ wifi_raw.csv.
+
There data files for testing both iOS and Android data formats.
+
There are also additional empty data files for both android and
+ iOS for testing empty data files.
The raw light data contains 3 or 4 rows of data for each epoch
+ except night. The single row of data for night is for testing
+ features for single values inputs. (Example testing the standard
+ deviation of one input value)
+
Since light is only available for Android there is only one file
+ that contains data for Android. All other files (i.e. for iPhone)
+ are empty data files.
The raw application foreground data file contains data for 1 day.
+
The raw application foreground data contains 7 - 9 rows of data
+ for each epoch. The records for each epoch contains apps that
+ are randomly selected from a list of apps that are from the
+ MULTIPLE_CATEGORIES and SINGLE_CATEGORIES (See
+ testing_config.yaml). There are also records in each epoch
+ that have apps randomly selected from a list of apps that are from
+ the EXCLUDED_CATEGORIES and EXCLUDED_APPS. This is to test
+ that these apps are actually being excluded from the calculations
+ of features. There are also records to test SINGLE_APPS
+ calculations.
+
Since application foreground is only available for Android there
+ is only one file that contains data for Android. All other files
+ (i.e. for iPhone) are empty data files.
The raw Activity Recognition data file contains data for 1 day.
+
The raw Activity Recognition data each epoch period contains
+ rows that records 2 - 5 different activity_types. The is such
+ that durations of activities can be tested. Additionally, there
+ are records that mimic the duration of an activity over the time
+ boundary of neighboring epochs. (For example, there a set of
+ records that mimic the participant in_vehicle from afternoon
+ into evening)
+
There is one file each with raw Activity Recognition data for
+ testing both iOS and Android data formats.
+ (plugin_google_activity_recognition_raw.csv for android and
+ plugin_ios_activity_recognition_raw.csv for iOS)
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files.
The raw conversation data file contains data for 2 day.
+
The raw conversation data contains records with a sample of both
+ datatypes (i.e. voice/noise = 0, and conversation = 2 )
+ as well as rows with for samples of each of the inference values
+ (i.e. silence = 0, noise = 1, voice = 2, and unknown
+ = 3) for each epoch. The different datatype and inference
+ records are randomly distributed throughout the epoch.
+
Additionally there are 2 - 5 records for conversations (datatype
+ = 2, and inference = -1) in each epoch and for each epoch
+ except night, there is a conversation record that has a
+ double_convo_starttimestamp that is from the previous
+ epoch. This is to test the calculations of features across
+ epochs.
+
There is a raw conversation data file for both android and iOS
+ platforms (plugin_studentlife_audio_android_raw.csv and
+ plugin_studentlife_audio_raw.csv respectively).
+
Finally, there are also additional empty data files for both
+ android and iOS for testing empty data files
To begin testing RAPIDS place the fake raw input data csv files in
+ tests/data/raw/. The fake participant files should be placed in
+ tests/data/external/. The expected output files of RAPIDS after
+ processing the input data should be placed in
+ tests/data/processesd/.
+
The Snakemake rule(s) that are to be tested must be placed in the
+ tests/Snakemake file. The current tests/Snakemake is a good
+ example of how to define them. (At the time of writing this
+ documentation the snakefile contains rules messages (SMS), calls and
+ screen)
+
Edit the tests/settings/config.yaml. Add and/or remove the rules
+ to be run for testing from the forcerun list.
+
Edit the tests/settings/testing_config.yaml with the necessary
+ configuration settings for running the rules to be tested.
+
Add any additional testscripts in tests/scripts.
+
Uncomment or comment off lines in the testing shell script
+ tests/scripts/run_tests.sh.
+
+
Run the testing shell script.
+
tests/scripts/run_tests.sh
+
+
+
+
The following is a snippet of the output you should see after running your test.
The results above show that the first test test_sensors_files_exist passed while test_sensors_features_calculations failed. In addition you should get the traceback of the failure (not shown here). For more information on how to implement test scripts and use unittest please see Unittest Documentation
+
Testing of the RAPIDS sensors and features is a work-in-progress. Please see test-cases for a list of sensors and features that have testing currently available.
+
Currently the repository is set up to test a number of sensors out of the box by simply running the tests/scripts/run_tests.sh command once the RAPIDS python environment is active.
Try to install any new package using conda. If a package is not available in one of conda‘s channels you can install it with pip but make sure your virtual environment is active.
After installing a new package you can use the following command in your terminal to update your environment.yaml before publishing your pipeline. Note that we ignore the package version for libfortran to keep compatibility with Linux:
**Error in .local(drv, \...) :** **Failed to connect to database: Error:
+Can\'t initialize character set unknown (path: compiled\_in)** :
+
+Calls: dbConnect -> dbConnect -> .local -> .Call
+Execution halted
+[Tue Mar 1019:40:15 2020]
+Error in rule download_dataset:
+ jobid: 531
+ output: data/raw/p60/locations_raw.csv
+
+RuleException:
+CalledProcessError in line 20 of /home/ubuntu/rapids/rules/preprocessing.snakefile:
+Command 'set -euo pipefail; Rscript --vanilla /home/ubuntu/rapids/.snakemake/scripts/tmp_2jnvqs7.download_dataset.R' returned non-zero exit status 1.
+File "/home/ubuntu/rapids/rules/preprocessing.snakefile", line 20, in __rule_download_dataset
+File "/home/ubuntu/anaconda3/envs/moshi-env/lib/python3.7/concurrent/futures/thread.py", line 57, in run
+Shutting down, this might take some time.
+Exiting because a job execution failed. Look above for error message
+
+
+Solution
Please make sure the DATABASE_GROUP in config.yaml matches your DB credentials group in .env.
+
+
+
Cannot start mysql in linux via brew services start mysql¶
+Problem
Cannot start mysql in linux via brew services start mysql
+
+Solution
Use mysql.server start
+
+
+
Every time I run force the download_dataset rule all rules are executed¶
+Problem
When running snakemake -j1 -R download_phone_data or ./rapids -j1 -R download_phone_data all the rules and files are re-computed
+
+Solution
This is expected behavior. The advantage of using snakemake under the hood is that every time a file containing data is modified every rule that depends on that file will be re-executed to update their results. In this case, since download_dataset updates all the raw data, and you are forcing the rule with the flag -R every single rule that depends on those raw files will be executed.
+
+
+
Error Table XXX doesn't exist while running the download_phone_data or download_fitbit_data rule.¶
+Problem
Error in .local(conn, statement, ...) :
+ could not run statement: Table 'db_name.table_name' doesn't exist
+Calls: colnames ... .local -> dbSendQuery -> dbSendQuery -> .local -> .Call
+Execution halted
+
+
+Solution
Please make sure the sensors listed in [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] and the [TABLE] of each sensor you activated in config.yaml match your database tables.
This is a bug in Ubuntu 20.04 when trying to connect to an old MySQL server with MySQL client 8.0. You should get the same error message if you try to connect from the command line. There you can add the option --ssl-mode=DISABLED but we can't do this from the R connector.
+
If you can't update your server, the quickest solution would be to import your database to another server or to a local environment. Alternatively, you could replace mysql-client and libmysqlclient-dev with mariadb-client and libmariadbclient-dev and reinstall renv. More info about this issue here
If you get the following error KeyError in line 43 of preprocessing.smk: 'PHONE_SENSORS', it means that the indentation of the key [PHONE_SENSORS] is not matching the other child elements of PHONE_VALID_SENSED_BINS
+
+Solution
You need to add or remove any leading whitespaces as needed on that line.
+
PHONE_VALID_SENSED_BINS:
+ COMPUTE:False# This flag is automatically ignored (set to True) if you are extracting PHONE_VALID_SENSED_DAYS or screen or Barnett's location features
+ BIN_SIZE:&bin_size5# (in minutes)
+ PHONE_SENSORS:[]
+
+
+
+
Error while updating your conda environment in Ubuntu¶
+Problem
You get the following error:
+
CondaMultiError: CondaVerificationError: The package for tk located at /home/ubuntu/miniconda2/pkgs/tk-8.6.9-hed695b0_1003
+ appears to be corrupted. The path 'include/mysqlStubs.h'
+ specified in the package manifest cannot be found.
+ClobberError: This transaction has incompatible packages due to a shared path.
+ packages: conda-forge/linux-64::llvm-openmp-10.0.0-hc9558a2_0, anaconda/linux-64::intel-openmp-2019.4-243
+ path: 'lib/libiomp5.so'
+
You won’t have to deal with time zones, dates, times, data cleaning or preprocessing. The data that RAPIDS pipes to your feature extraction code is ready to process.
As a tutorial, we will add a new provider for PHONE_ACCELEROMETER called VEGA that extracts feature1, feature2, feature3 in Python and that it requires a parameter from the user called MY_PARAMETER.
+Existing Sensors
An existing sensor is any of the phone or Fitbit sensors with a configuration entry in config.yaml:
In this step you need to add your provider configuration section under the relevant sensor in config.yaml. See our example for our tutorial’s VEGA provider for PHONE_ACCELEROMETER:
+Example configuration for a new accelerometer provider VEGA
In this step you need to add a folder, script and function for your provider.
+
+
Create your provider folder under src/feature/DEVICE_SENSOR/YOUR_PROVIDER, in our example src/feature/phone_accelerometer/vega (same as [SRC_FOLDER] in the step above).
+
Create your provider script inside your provider folder, it can be a Python file called main.py or an R file called main.R.
+
+
Add your provider function in your provider script. The name of such function should be [providername]_features, in our example vega_features
The provider function that you created in the step above will receive the following parameters:
+
+
+
+
Parameter
+
Description
+
+
+
+
+
sensor_data_files
+
Path to the CSV file containing the data of a single participant. This data has been cleaned and preprocessed. Your function will be automatically called for each participant in your study (in the [PIDS] array in config.yaml)
+
+
+
day_segment
+
The label of the day segment that should be processed.
+
+
+
provider
+
The parameters you configured for your provider in config.yaml will be available in this variable as a dictionary in Python or a list in R. In our example this dictionary contains {MY_PARAMETER:"a_string"}
+
+
+
filter_data_by_segment
+
Python only. A function that you will use to filter your data. In R this function is already available in the environment.
+
+
+
*args
+
Python only. Not used for now
+
+
+
**kwargs
+
Python only. Not used for now
+
+
+
+
The code to extract your behavioral features should be implemented in your provider function and in general terms it will have three stages:
+1. Read a participant’s data by loading the CSV data stored in the file pointed by sensor_data_files
Note that phone’s battery, screen, and activity recognition data is given as episodes instead of event rows (for example, start and end timestamps of the periods the phone screen was on)
+
+2. Filter your data to process only those rows that belong to day_segment
This step is only one line of code, but to undersand why we need it, keep reading.
+
Let’s understand the filter_data_by_segment() function with an example. A RAPIDS user can extract features on any arbitrary day segment. A day segment is a period of time that has a label and one or more instances. For example, the user (or you) could have requested features on a daily, weekly, and week-end basis for p01. The labels are arbritrary and the instances depend on the days a participant was monitored for:
+
+
the daily segment could be named my_days and if p01 was monitored for 14 days, it would have 14 instances
+
the weekly segment could be named my_weeks and if p01 was monitored for 14 days, it would have 2 instances.
+
the weekend segment could be named my_weekends and if p01 was monitored for 14 days, it would have 2 instances.
+
+
For this example, RAPIDS will call your provider function three times for p01, once where day_segment is my_days, once where day_segment is my_weeks and once where day_segment is my_weekends. In this example not every row in p01‘s data needs to take part in the feature computation for either segment and the rows need to be grouped differently.
+
Thus filter_data_by_segment() comes in handy, it will return a data frame that contains the rows that were logged during a day segment plus an extra column called local_segment. This new column will have as many unique values as day segment instances exist (14, 2, and 2 for our p01‘s my_days, my_weeks, and my_weekends examples). After filtering, you should group the data frame by this column and compute any desired features, for example:
The reason RAPIDS does not filter the participant’s data set for you is because your code might need to compute something based on a participant’s complete dataset before computing their features. For example, you might want to identify the number that called a participant the most throughout the study before computing a feature with the number of calls the participant received from this number.
+
+3. Return a data frame with your features
After filtering, grouping your data, and computing your features, your provider function should return a data frame that has:
+
+
One row per day segment instance (e.g. 14 our p01‘s my_days example)
+
The local_segment column added by filter_data_by_segment()
+
One column per feature. Your feature columns should be named SENSOR_PROVIDER_FEATURE, for example accelerometr_vega_feature1
+
+
+PHONE_ACCELEROMETER Provider Example
For your reference, this a short example of our own provider (RAPIDS) for PHONE_ACCELEROMETER that computes five acceleration features
+
defrapids_features(sensor_data_files,day_segment,provider,filter_data_by_segment,*args,**kwargs):
+
+acc_data=pd.read_csv(sensor_data_files["sensor_data"])
+requested_features=provider["FEATURES"]
+# name of the features this function can compute
+base_features_names=["maxmagnitude","minmagnitude","avgmagnitude","medianmagnitude","stdmagnitude"]
+# the subset of requested features this function can compute
+features_to_compute=list(set(requested_features)&set(base_features_names))
+
+acc_features=pd.DataFrame(columns=["local_segment"]+["acc_rapids_"+xforxinfeatures_to_compute])
+ifnotacc_data.empty:
+ acc_data=filter_data_by_segment(acc_data,day_segment)
+
+ ifnotacc_data.empty:
+ acc_features=pd.DataFrame()
+ # get magnitude related features: magnitude = sqrt(x^2+y^2+z^2)
+ magnitude=acc_data.apply(lambdarow:np.sqrt(row["double_values_0"]**2+row["double_values_1"]**2+row["double_values_2"]**2),axis=1)
+ acc_data=acc_data.assign(magnitude=magnitude.values)
+
+ if"maxmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_maxmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].max()
+ if"minmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_minmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].min()
+ if"avgmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_avgmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].mean()
+ if"medianmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_medianmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].median()
+ if"stdmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_stdmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].std()
+
+ acc_features=acc_features.reset_index()
+
+returnacc_features
+
If you want to add features for a device or a sensor that we do not support at the moment (those that do not appear in the "Existing Sensors" list above), contact us or request it on Slack and we can add the necessary code so you can follow the instructions above.
Every phone or Fitbit sensor has a corresponding config section in config.yaml, these sections follow a similar structure and we’ll use PHONE_ACCELEROMETER as an example to explain this structure.
+
+
Hint
+
We recommend reading this page if you are using RAPIDS for the first time
+
+
+
Config section example for PHONE_ACCELEROMETER
+
# 1) Config section
+PHONE_ACCELEROMETER:
+ # 2) Parameters for PHONE_ACCELEROMETER
+ TABLE:accelerometer
+
+ # 3) Providers for PHONE_ACCELEROMETER
+ PROVIDERS:
+ # 4) RAPIDS provider
+ RAPIDS:
+ # 4.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER
+ COMPUTE:False
+ # 4.2) Features of RAPIDS provider of PHONE_ACCELEROMETER
+ FEATURES:["maxmagnitude","minmagnitude","avgmagnitude","medianmagnitude","stdmagnitude"]
+ SRC_FOLDER:"rapids"# inside src/features/phone_accelerometer
+ SRC_LANGUAGE:"python"
+
+ # 5) PANDA provider
+ PANDA:
+ # 5.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER
+ COMPUTE:False
+ VALID_SENSED_MINUTES:False
+ # 5.2) Features of RAPIDS provider of PHONE_ACCELEROMETER
+ FEATURES:
+ exertional_activity_episode:["sumduration","maxduration","minduration","avgduration","medianduration","stdduration"]
+ nonexertional_activity_episode:["sumduration","maxduration","minduration","avgduration","medianduration","stdduration"]
+ SRC_FOLDER:"panda"# inside src/features/phone_accelerometer
+ SRC_LANGUAGE:"python"
+
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 download, and processed. The TABLE parameter exists for every sensor, but some sensors will have extra para meters like [PHONE_LOCATIONS]. We explain these parameters in a table at the top of each sensor documentation page.
Each sensor configuration section can have zero, one or more behavioral feature providers (see #2 in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. For this accelerometer example we have two providers RAPIDS (see #4) and PANDA (see #5).
Each provider has parameters that affect the computation of the behavioral features it offers (see #4.1 or #5.1 in the example). These parameters will include at least a [COMPUTE] flag that you switch to True to extract a provider’s behavioral features.
+
We explain each provider parameter in a table under the Parameters description heading on each provider documentation page.
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.
+
We explain each behavioral feature in a table under the Features description heading on each provider documentation page.
+
+
Hint
+
Every time you change any sensor parameters, provider parameters or provider features, all the necessary files will be updated as soon as you execute RAPIDS.
Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_ACCELEROMETER features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
maxmagnitude
+
m/s2
+
The maximum magnitude of acceleration (\(\|acceleration\| = \sqrt{x^2 + y^2 + z^2}\)).
+
+
+
minmagnitude
+
m/s2
+
The minimum magnitude of acceleration.
+
+
+
avgmagnitude
+
m/s2
+
The average magnitude of acceleration.
+
+
+
medianmagnitude
+
m/s2
+
The median magnitude of acceleration.
+
+
+
stdmagnitude
+
m/s2
+
The standard deviation of acceleration.
+
+
+
+
+
Assumptions/Observations
+
+
Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem.
Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_ACCELEROMETER features from the PANDA provider
+
+
+
[FEATURES]
+
Features to be computed for exertional and non-exertional activity episodes, see table below
+
+
+
+
Features description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
sumduration
+
minutes
+
Total duration of all exertional or non-exertional activity episodes.
+
+
+
maxduration
+
minutes
+
Longest duration of any exertional or non-exertional activity episode.
+
+
+
minduration
+
minutes
+
Shortest duration of any exertional or non-exertional activity episode.
+
+
+
avgduration
+
minutes
+
Average duration of any exertional or non-exertional activity episode.
+
+
+
medianduration
+
minutes
+
Median duration of any exertional or non-exertional activity episode.
+
+
+
stdduration
+
minutes
+
Standard deviation of the duration of all exertional or non-exertional activity episodes.
+
+
+
+
+
Assumptions/Observations
+
+
Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem.
+
See Panda et al for a definition of exertional and non-exertional activity episodes
Parameters description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_ACTIVITY_RECOGNITION features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[ACTIVITY_CLASSES][STATIONARY]
+
An array of the activity labels to be considered in the STATIONARY category choose any of still, tilting
+
+
+
[ACTIVITY_CLASSES][MOBILE]
+
An array of the activity labels to be considered in the MOBILE category choose any of on_foot, walking, running, on_bicycle
+
+
+
[ACTIVITY_CLASSES][VEHICLE]
+
An array of the activity labels to be considered in the VEHICLE category choose any of in_vehicule
+
+
+
+
Features description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
rows
+
Number of episodes.
+
+
+
mostcommonactivity
+
activity type
+
The most common activity type (e.g. still, on_foot, etc.). If there is a tie, the first one is chosen.
+
+
+
countuniqueactivities
+
activity type
+
Number of unique activities.
+
+
+
durationstationary
+
minutes
+
The total duration of [ACTIVITY_CLASSES][STATIONARY] episodes
+
+
+
durationmobile
+
minutes
+
The total duration of [ACTIVITY_CLASSES][MOBILE] episodes of on foot, running, and on bicycle activities
+
+
+
durationvehicle
+
minutes
+
The total duration of [ACTIVITY_CLASSES][VEHICLE] episodes of on vehicle activity
+
+
+
+
+
Assumptions/Observations
+
+
+
iOS Activity Recognition names and types are unified with Android labels:
+
+
+
+
iOS Activity Name
+
Android Activity Name
+
Android Activity Type
+
+
+
+
+
walking
+
walking
+
7
+
+
+
running
+
running
+
8
+
+
+
cycling
+
on_bicycle
+
1
+
+
+
automotive
+
in_vehicle
+
0
+
+
+
stationary
+
still
+
3
+
+
+
unknown
+
unknown
+
4
+
+
+
+
+
+
In AWARE, Activity Recognition data for Android and iOS are stored in two different database tables, RAPIDS automatically infers what platform each participant belongs to based on their participant file.
Sensor parameters description for [PHONE_APPLICATIONS_FOREGROUND] (these parameters are used by the only provider available at the moment, RAPIDS):
+
+
+
+
Key
+
Description
+
+
+
+
+
[TABLE]
+
Database table where the applications foreground data is stored
+
+
+
[APPLICATION_CATEGORIES][CATALOGUE_SOURCE]
+
FILE or GOOGLE. If FILE, app categories (genres) are read from [CATALOGUE_FILE]. If [GOOGLE], app categories (genres) are scrapped from the Play Store
+
+
+
[APPLICATION_CATEGORIES][CATALOGUE_FILE]
+
CSV file with a package_name and genre column. By default we provide the catalogue created by Stachl et al in data/external/stachl_application_genre_catalogue.csv
+
+
+
[APPLICATION_CATEGORIES][UPDATE_CATALOGUE_FILE]
+
if [CATALOGUE_SOURCE] is equal to FILE, this flag signals whether or not to update [CATALOGUE_FILE], if [CATALOGUE_SOURCE] is equal to GOOGLE all scraped genres will be saved to [CATALOGUE_FILE]
This flag signals whether or not to scrape categories (genres) missing from the [CATALOGUE_FILE]. If [CATALOGUE_SOURCE] is equal to GOOGLE, all genres are scraped anyway (this flag is ignored)
Parameters description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_APPLICATIONS_FOREGROUND features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[SINGLE_CATEGORIES]
+
An array of app categories to be included in the feature extraction computation. The special keyword all represents a category with all the apps from each participant. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above)
+
+
+
[MULTIPLE_CATEGORIES]
+
An array of collections representing meta-categories (a group of categories). They key of each element is the name of the meta-category and the value is an array of member app categories. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above)
+
+
+
[SINGLE_APPS]
+
An array of apps to be included in the feature extraction computation. Use their package name (e.g. com.google.android.youtube) or the reserved keyword top1global (the most used app by a participant over the whole monitoring study)
+
+
+
[EXCLUDED_CATEGORIES]
+
An array of app categories to be excluded from the feature extraction computation. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above)
+
+
+
[EXCLUDED_APPS]
+
An array of apps to be excluded from the feature extraction computation. Use their package name, for example: com.google.android.youtube
+
+
+
+
Features description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
apps
+
Number of times a single app or apps within a category were used (i.e. they were brought to the foreground either by tapping their icon or switching to it from another app)
+
+
+
timeoffirstuse
+
minutes
+
The time in minutes between 12:00am (midnight) and the first use of a single app or apps within a category during a day_segment
+
+
+
timeoflastuse
+
minutes
+
The time in minutes between 12:00am (midnight) and the last use of a single app or apps within a category during a day_segment
+
+
+
frequencyentropy
+
nats
+
The entropy of the used apps within a category during a day_segment (each app is seen as a unique event, the more apps were used, the higher the entropy). This is especially relevant when computed over all apps. Entropy cannot be obtained for a single app
+
+
+
+
+
Assumptions/Observations
+
Features can be computed by app, by apps grouped under a single category (genre) and by multiple categories grouped together (meta-categories). For example, we can get features for Facebook (single app), for Social Network apps (a category including Facebook and other social media apps) or for Social (a meta-category formed by Social Network and Social Media Tools categories).
+
Apps installed by default like YouTube are considered systems apps on some phones. We do an exact match to exclude apps where “genre” == EXCLUDED_CATEGORIES or “package_name” == EXCLUDED_APPS.
+
We provide three ways of classifying and app within a category (genre): a) by automatically scraping its official category from the Google Play Store, b) by using the catalogue created by Stachl et al. which we provide in RAPIDS (data/external/stachl_application_genre_catalogue.csv), or c) by manually creating a personalized catalogue. You can choose a, b or c by modifying [APPLICATION_GENRES] keys and values (see the Sensor parameters description table above).
Parameters description for [PHONE_BATTERY][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_BATTERY features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_BATTERY][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
countdischarge
+
episodes
+
Number of discharging episodes.
+
+
+
sumdurationdischarge
+
minutes
+
The total duration of all discharging episodes.
+
+
+
countcharge
+
episodes
+
Number of battery charging episodes.
+
+
+
sumdurationcharge
+
minutes
+
The total duration of all charging episodes.
+
+
+
avgconsumptionrate
+
episodes/minutes
+
The average of all episodes’ consumption rates. An episode’s consumption rate is defined as the ratio between its battery delta and duration
+
+
+
maxconsumptionrate
+
episodes/minutes
+
The highest of all episodes’ consumption rates. An episode’s consumption rate is defined as the ratio between its battery delta and duration
+
+
+
+
+
Assumptions/Observations
+
+
We convert battery data collected with iOS client v1 (autodetected because battery status 4 do not exist) to match Android battery format: we swap status 3 for 5 and 1 for 3
+
We group battery data into discharge or charge episodes considering any contiguous rows with consecutive reductions or increases of the battery level if they are logged within [EPISODE_THRESHOLD_BETWEEN_ROWS] minutes from each other.
Parameters description for [PHONE_CALLS][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_CALLS features from the RAPIDS provider
+
+
+
[CALL_TYPES]
+
The particular call_type that will be analyzed. The options for this parameter are incoming, outgoing or missed.
+
+
+
[FEATURES]
+
Features to be computed for outgoing, incoming, and missed calls. Note that the same features are available for both incoming and outgoing calls, while missed calls has its own set of features. See the tables below.
+
+
+
+
Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] incoming and outgoing calls:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
calls
+
Number of calls of a particular call_type occurred during a particular day_segment.
+
+
+
distinctcontacts
+
contacts
+
Number of distinct contacts that are associated with a particular call_type for a particular day_segment
+
+
+
meanduration
+
seconds
+
The mean duration of all calls of a particular call_type during a particular day_segment.
+
+
+
sumduration
+
seconds
+
The sum of the duration of all calls of a particular call_type during a particular day_segment.
+
+
+
minduration
+
seconds
+
The duration of the shortest call of a particular call_type during a particular day_segment.
+
+
+
maxduration
+
seconds
+
The duration of the longest call of a particular call_type during a particular day_segment.
+
+
+
stdduration
+
seconds
+
The standard deviation of the duration of all the calls of a particular call_type during a particular day_segment.
+
+
+
modeduration
+
seconds
+
The mode of the duration of all the calls of a particular call_type during a particular day_segment.
+
+
+
entropyduration
+
nats
+
The estimate of the Shannon entropy for the the duration of all the calls of a particular call_type during a particular day_segment.
+
+
+
timefirstcall
+
minutes
+
The time in minutes between 12:00am (midnight) and the first call of call_type.
+
+
+
timelastcall
+
minutes
+
The time in minutes between 12:00am (midnight) and the last call of call_type.
+
+
+
countmostfrequentcontact
+
calls
+
The number of calls of a particular call_type during a particular day_segment of the most frequent contact throughout the monitored period.
+
+
+
+
Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] missed calls:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
calls
+
Number of missed calls that occurred during a particular day_segment.
+
+
+
distinctcontacts
+
contacts
+
Number of distinct contacts that are associated with missed calls for a particular day_segment
+
+
+
timefirstcall
+
minutes
+
The time in hours from 12:00am (Midnight) that the first missed call occurred.
+
+
+
timelastcall
+
minutes
+
The time in hours from 12:00am (Midnight) that the last missed call occurred.
+
+
+
countmostfrequentcontact
+
calls
+
The number of missed calls during a particular day_segment of the most frequent contact throughout the monitored period.
+
+
+
+
+
Assumptions/Observations
+
+
Traces for iOS calls are unique even for the same contact calling a participant more than once which renders countmostfrequentcontact meaningless and distinctcontacts equal to the total number of traces.
+
[CALL_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [CALL_TYPES]outgoing matches the [FEATURES] key outgoing
+
iOS calls data is transformed to match Android calls data format. See our algorithm
Parameters description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_CONVERSATION features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[RECORDING_MINUTES]
+
Minutes the plugin was recording audio (default 1 min)
+
+
+
[PAUSED_MINUTES]
+
Minutes the plugin was NOT recording audio (default 3 min)
+
+
+
+
Features description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
minutessilence
+
minutes
+
Minutes labeled as silence
+
+
+
minutesnoise
+
minutes
+
Minutes labeled as noise
+
+
+
minutesvoice
+
minutes
+
Minutes labeled as voice
+
+
+
minutesunknown
+
minutes
+
Minutes labeled as unknown
+
+
+
sumconversationduration
+
minutes
+
Total duration of all conversations
+
+
+
maxconversationduration
+
minutes
+
Longest duration of all conversations
+
+
+
minconversationduration
+
minutes
+
Shortest duration of all conversations
+
+
+
avgconversationduration
+
minutes
+
Average duration of all conversations
+
+
+
sdconversationduration
+
minutes
+
Standard Deviation of the duration of all conversations
+
+
+
timefirstconversation
+
minutes
+
Minutes since midnight when the first conversation for a day segment was detected
+
+
+
timelastconversation
+
minutes
+
Minutes since midnight when the last conversation for a day segment was detected
+
+
+
noisesumenergy
+
L2-norm
+
Sum of all energy values when inference is noise
+
+
+
noiseavgenergy
+
L2-norm
+
Average of all energy values when inference is noise
+
+
+
noisesdenergy
+
L2-norm
+
Standard Deviation of all energy values when inference is noise
+
+
+
noiseminenergy
+
L2-norm
+
Minimum of all energy values when inference is noise
+
+
+
noisemaxenergy
+
L2-norm
+
Maximum of all energy values when inference is noise
+
+
+
voicesumenergy
+
L2-norm
+
Sum of all energy values when inference is voice
+
+
+
voiceavgenergy
+
L2-norm
+
Average of all energy values when inference is voice
+
+
+
voicesdenergy
+
L2-norm
+
Standard Deviation of all energy values when inference is voice
+
+
+
voiceminenergy
+
L2-norm
+
Minimum of all energy values when inference is voice
+
+
+
voicemaxenergy
+
L2-norm
+
Maximum of all energy values when inference is voice
+
+
+
silencesensedfraction
+
-
+
Ratio between minutessilence and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
noisesensedfraction
+
-
+
Ratio between minutesnoise and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
voicesensedfraction
+
-
+
Ratio between minutesvoice and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
unknownsensedfraction
+
-
+
Ratio between minutesunknown and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
silenceexpectedfraction
+
-
+
Ration between minutessilence and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
noiseexpectedfraction
+
-
+
Ration between minutesnoise and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
voiceexpectedfraction
+
-
+
Ration between minutesvoice and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
unknownexpectedfraction
+
-
+
Ration between minutesunknown and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
+
+
Assumptions/Observations
+
+
The timestamp of conversation rows in iOS is in seconds so we convert it to milliseconds to match Android’s format
A valid bin is any period of BIN_SIZE minutes starting from midnight with at least 1 row from any phone sensor. PHONE_VALID_SENSED_BINS are used to compute PHONE_VALID_SENSED_DAYS, to resample fused location data and to compute some screen features.
+
+
Hint
+
PHONE_VALID_SENSED_DAYS are an approximation to the time the phone was sensing data so add as many sensors as you have to [PHONE_VALID_SENSED_BINS][PHONE_SENSORS]
+
+
Parameters description for PHONE_VALID_SENSED_BINS:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to compute
+
+
+
[BIN_SIZE]
+
Size of each bin in minutes
+
+
+
[PHONE_SENSORS]
+
One or more sensor config keys (e.g. PHONE_MESSAGE) to be used to flag a bin as valid or not (whether or not a bin contains at least one row from any sensor)
+
+
+
+
+
Possible values for [PHONE_VALID_SENSED_BINS][PHONE_SENSORS]
On any given day, a phone could have sensed data only for a few minutes or for 24 hours. Features should considered more reliable the more hours the phone was logging data, for example, 10 calls logged on a day when only 1 hour of data was recorded is a less reliable feature compared to 10 calls on a day when 23 hours of data were recorded.
+
Therefore, we define a valid hour as those that contain a minimum number of valid bins (see above). We mark an hour as valid when contains at least MIN_VALID_BINS_PER_HOUR (out of 60min/BIN_SIZE bins). In turn, we mark a day as valid if it has at least MIN_VALID_HOURS_PER_DAY. You can use PHONE_VALID_SENSED_DAYS to manually discard days when not enough data was collected after your features are computed.
+
Parameters description for PHONE_VALID_SENSED_DAYS:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to compute
+
+
+
[MIN_VALID_BINS_PER_HOUR]
+
An array of integer values, 6 by default. Minimum number of valid bins to mark an hour as valid
+
+
+
[MIN_VALID_HOURS_PER_DAY]
+
An array of integer values, 16 by default. Minimum number of valid hours to mark a day as valid
Sensor parameters description for [PHONE_LOCATIONS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[TABLE]
+
Database table where the location data is stored
+
+
+
[LOCATIONS_TO_USE]
+
Type of location data to use, one of ALL, GPS or FUSED_RESAMPLED. This filter is based on the provider column of the AWARE locations table, ALL includes every row, GPS only includes rows where provider is gps, and FUSED_RESAMPLED only includes rows where provider is fused after being resampled.
+
+
+
[FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD]
+
if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled to the next valid timestamp (see the Assumptions/Observations below) only if the time difference between them is less or equal than this threshold (in minutes).
+
+
+
[FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION]
+
if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled at most for this long (in minutes)
+
+
+
+
+
Assumptions/Observations
+
Types of location data to use
+AWARE Android and iOS clients can collect location coordinates through the phone's GPS, the network cellular towers around the phone or Google's fused location API. If you want to use only the GPS provider set [LOCATIONS_TO_USE] to GPS, if you want to use all providers (not recommended due to the difference in accuracy) set [LOCATIONS_TO_USE] to ALL, if your AWARE client was configured to use fused location only or want to focus only on this provider, set [LOCATIONS_TO_USE] to RESAMPLE_FUSED. RESAMPLE_FUSED takes the original fused location coordinates and replicates each pair forward in time as long as the phone was sensing data as indicated by PHONE_VALID_SENSED_BINS, this is done because Google's API only logs a new location coordinate pair when it is sufficiently different in time or space from the previous one.
+
There are two parameters associated with resampling fused location. FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD (in minutes, default 30) controls the maximum gap between any two coordinate pairs to replicate the last known pair (for example, participant A's phone did not collect data between 10.30am and 10:50am and between 11:05am and 11:40am, the last known coordinate pair will be replicated during the first period but not the second, in other words, we assume that we cannot longer guarantee the participant stayed at the last known location if the phone did not sense data for more than 30 minutes). FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION (in minutes, default 720 or 12 hours) stops the last known fused location from being replicated longer that this threshold even if the phone was sensing data continuously (for example, participant A went home at 9pm and their phone was sensing data without gaps until 11am the next morning, the last known location will only be replicated until 9am). If you have suggestions to modify or improve this resampling, let us know.
Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_LOCATIONS features from the BARNETT provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[ACCURACY_LIMIT]
+
An integer in meters, any location rows with an accuracy higher than this will be dropped. This number means there’s a 68% probability the true location is within this radius
+
+
+
[TIMEZONE]
+
Timezone where the location data was collected. By default points to the one defined in the Initial configuration
+
+
+
[MINUTES_DATA_USED]
+
Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough.
+
+
+
+
Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] adapted from Beiwe Summary Statistics:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
hometime
+
minutes
+
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.
+
+
+
disttravelled
+
meters
+
Total distance travelled over a day (flights).
+
+
+
rog
+
meters
+
The Radius of Gyration (rog) 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 the places and that centroid is computed. The weights are proportional to the time spent in each place.
+
+
+
maxdiam
+
meters
+
The maximum diameter is the largest distance between any two pauses.
+
+
+
maxhomedist
+
meters
+
The maximum distance from home in meters.
+
+
+
siglocsvisited
+
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 k from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another.
+
+
+
avgflightlen
+
meters
+
Mean length of all flights.
+
+
+
stdflightlen
+
meters
+
Standard deviation of the length of all flights.
+
+
+
avgflightdur
+
seconds
+
Mean duration of all flights.
+
+
+
stdflightdur
+
seconds
+
The standard deviation of the duration of all flights.
+
+
+
probpause
+
-
+
The fraction of a day spent in a pause (as opposed to a flight)
+
+
+
siglocentropy
+
nats
+
Shannon’s entropy measurement based on the proportion of time spent at each significant location visited during a day.
+
+
+
circdnrtn
+
-
+
A continuous metric quantifying a person’s circadian routine 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.
+
+
+
wkenddayrtn
+
-
+
Same as circdnrtn but computed separately for weekends and weekdays.
+
+
+
+
+
Assumptions/Observations
+
Barnett's et al features
+These features are based on a Pause-Flight model. A pause is defined as a mobiity trace (location pings) within a certain duration and distance (by default 300 seconds and 60 meters). A flight is any mobility trace between two pauses. Data is resampled and imputed before the features are computed. See Barnett et al for more information. In RAPIDS we only expose two parameters for these features (timezone and accuracy limit). You can change other parameters in src/features/phone_locations/barnett/library/MobilityFeatures.R.
+
Significant Locations
+Significant locations are determined using K-means clustering on pauses longer than 10 minutes. The number of clusters (K) is increased until no two clusters are within 400 meters from each other. After this, pauses within a certain range of a cluster (200 meters by default) will count as a visit to that significant location. This description was adapted from the Supplementary Materials of Barnett et al.
+
The Circadian Calculation
+For a detailed description of how this is calculated, see Canzian et al.
Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_LOCATIONS features from the BARNETT provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[DBSCAN_EPS]
+
The maximum distance in meters between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function.
+
+
+
[DBSCAN_MINSAMPLES]
+
The number of samples (or total weight) in a neighborhood for a point to be considered as a core point of a cluster. This includes the point itself.
+
+
+
[THRESHOLD_STATIC]
+
It is the threshold value in km/hr which labels a row as Static or Moving.
+
+
+
[MAXIMUM_GAP_ALLOWED]
+
The maximum gap (in seconds) allowed between any two consecutive rows for them to be considered part of the same displacement. If this threshold is too high, it can throw speed and distance calculations off for periods when the the phone was not sensing.
+
+
+
[MINUTES_DATA_USED]
+
Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough.
+
+
+
[SAMPLING_FREQUENCY]
+
Expected time difference between any two location rows in minutes. If set to 0, the sampling frequency will be inferred automatically as the median of all the differences between any two consecutive row timestamps (recommended if you are using FUSED_RESAMPLED data). This parameter impacts all the time calculations.
+
+
+
+
Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
locationvariance
+
\(meters^2\)
+
The sum of the variances of the latitude and longitude columns.
+
+
+
loglocationvariance
+
-
+
Log of the sum of the variances of the latitude and longitude columns.
+
+
+
totaldistance
+
meters
+
Total distance travelled in a day segment using the haversine formula.
+
+
+
averagespeed
+
km/hr
+
Average speed in a day segment considering only the instances labeled as Moving.
+
+
+
varspeed
+
km/hr
+
Speed variance in a day segment considering only the instances labeled as Moving.
+
+
+
circadianmovement
+
-
+
"It encodes the extent to which a person’s location patterns follow a 24-hour circadian cycle." Doryab et al..
+
+
+
numberofsignificantplaces
+
places
+
Number of significant locations visited. It is calculated using the DBSCAN clustering algorithm which takes in EPS and MIN_SAMPLES as parameters to identify clusters. Each cluster is a significant place.
+
+
+
numberlocationtransitions
+
transitions
+
Number of movements between any two clusters in a day segment.
+
+
+
radiusgyration
+
meters
+
Quantifies the area covered by a participant
+
+
+
timeattop1location
+
minutes
+
Time spent at the most significant location.
+
+
+
timeattop2location
+
minutes
+
Time spent at the 2nd most significant location.
+
+
+
timeattop3location
+
minutes
+
Time spent at the 3rd most significant location.
+
+
+
movingtostaticratio
+
-
+
Ratio between the number of rows labeled Moving versus Static
+
+
+
outlierstimepercent
+
-
+
Ratio between the number of rows that belong to non-significant clusters divided by the total number of rows in a day segment.
+
+
+
maxlengthstayatclusters
+
minutes
+
Maximum time spent in a cluster (significant location).
+
+
+
minlengthstayatclusters
+
minutes
+
Minimum time spent in a cluster (significant location).
+
+
+
meanlengthstayatclusters
+
minutes
+
Average time spent in a cluster (significant location).
+
+
+
stdlengthstayatclusters
+
minutes
+
Standard deviation of time spent in a cluster (significant location).
+
+
+
locationentropy
+
nats
+
Shannon Entropy computed over the row count of each cluster (significant location), it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location).
+
+
+
normalizedlocationentropy
+
nats
+
Shannon Entropy computed over the row count of each cluster (significant location) divided by the number of clusters, it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location).
+
+
+
+
+
Assumptions/Observations
+
Significant Locations Identified
+Significant locations are determined using DBSCAN clustering on locations that a patient visit over the course of the period of data collection.
+
The Circadian Calculation
+For a detailed description of how this is calculated, see Canzian et al.
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.
+
+
Assumptions/Observations
+
+
+
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.
+
+
+
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.
+
+
+
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.
Parameters description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_WIFI_CONNECTED features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
countscans
+
devices
+
Number of scanned WiFi access points connected during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately
+
+
+
uniquedevices
+
devices
+
Number of unique access point during a day_segment as identified by their hardware address
+
+
+
countscansmostuniquedevice
+
scans
+
Number of scans of the most scanned access point during a day_segment across the whole monitoring period
+
+
+
+
+
Assumptions/Observations
+
+
A connected WiFI access point is one that a phone was connected to.
+
By default AWARE stores this data in the sensor_wifi table.
Parameters description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_WIFI_VISIBLE features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
countscans
+
devices
+
Number of scanned WiFi access points visible during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately
+
+
+
uniquedevices
+
devices
+
Number of unique access point during a day_segment as identified by their hardware address
+
+
+
countscansmostuniquedevice
+
scans
+
Number of scans of the most scanned access point during a day_segment across the whole monitoring period
+
+
+
+
+
Assumptions/Observations
+
+
A visible WiFI access point is one that a phone sensed around itself but that it was not connected to. Due to API restrictions, this sensor is not available on iOS.
+
By default AWARE stores this data in the wifi table.
Read this page if you want to learn more about how RAPIDS is structured. If you want to start using it go to Installation and then to Initial 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, participants files, day segment files, 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 or the day segment files).
+
+
+ Interaction diagram between the user, and important files in RAPIDS
+
+
+
+
+
+
+
+
+
+
Reproducible Analysis Pipeline for Data Streams (RAPIDS) allows you to process smartphone and wearable data to extract behavioral features (a.k.a. digital biomarkers/phenotypes).
+
RAPIDS is open source, documented, modular, tested, and reproducible. At the moment we support smartphone data collected with AWARE and wearable data from Fitbit devices.
+
Questions or feedback can be posted on #rapids in AWARE Framework's slack.
RAPIDS is formed by R and Python scripts orchestrated by Snakemake. We suggest you read Snakemake’s docs but in short: every link in the analysis chain is atomic and has files as input and output. Behavioral features are processed per sensor and per participant.
Consistent analysis. Every participant sensor dataset is analyzed in the exact same way and isolated from each other.
+
Efficient analysis. Every analysis step is executed only once. Whenever your data or configuration changes only the affected files are updated.
+
Parallel execution. Thanks to Snakemake, your analysis can be executed over multiple cores without changing your code.
+
Extensible code. You can easily add your own behavioral features in R or Python and keep authorship and citations.
+
Timezone aware. Your data is adjusted to the specified timezone (multiple timezones suport coming soon).
+
Flexible day segments. You can extract behavioral features on time windows of any length (e.g. 5 minutes, 3 hours, 2 days), on every day or particular days (e.g. weekends, Mondays, the 1st of each month, etc.) or around events of interest (e.g. surveys or clinical relapses).
+
Tested code. We are constantly adding tests to make sure our behavioral features are correct.
+
Reproducible code. You can be sure your code will run in other computers as intended thanks to R and Python virtual environments. You can share your analysis code along your publications without any overhead.
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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/0.1/search/search_index.json b/0.1/search/search_index.json
new file mode 100644
index 00000000..798daaf8
--- /dev/null
+++ b/0.1/search/search_index.json
@@ -0,0 +1 @@
+{"config":{"lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Welcome to RAPIDS documentation \u00b6 Test v1.0 Reproducible Analysis Pipeline for Data Streams (RAPIDS) allows you to process smartphone and wearable data to extract behavioral features (a.k.a. digital biomarkers/phenotypes). RAPIDS is open source, documented, modular, tested, and reproducible. At the moment we support smartphone data collected with AWARE and wearable data from Fitbit devices. Questions or feedback can be posted on #rapids in AWARE Framework's slack . Bugs should be reported on Github . Join our discussions on our algorithms and assumptions for feature processing . Ready to start? Go to Installation and then to Initial Configuration How does it work? \u00b6 RAPIDS is formed by R and Python scripts orchestrated by Snakemake . We suggest you read Snakemake\u2019s docs but in short: every link in the analysis chain is atomic and has files as input and output. Behavioral features are processed per sensor and per participant. What are the benefits of using RAPIDS? \u00b6 Consistent analysis . Every participant sensor dataset is analyzed in the exact same way and isolated from each other. Efficient analysis . Every analysis step is executed only once. Whenever your data or configuration changes only the affected files are updated. Parallel execution . Thanks to Snakemake, your analysis can be executed over multiple cores without changing your code. Extensible code . You can easily add your own behavioral features in R or Python and keep authorship and citations. Timezone aware . Your data is adjusted to the specified timezone (multiple timezones suport coming soon ). Flexible day segments . You can extract behavioral features on time windows of any length (e.g. 5 minutes, 3 hours, 2 days), on every day or particular days (e.g. weekends, Mondays, the 1 st of each month, etc.) or around events of interest (e.g. surveys or clinical relapses). Tested code . We are constantly adding tests to make sure our behavioral features are correct. Reproducible code . You can be sure your code will run in other computers as intended thanks to R and Python virtual environments. You can share your analysis code along your publications without any overhead. Private . All your data is processed locally. How is it organized? \u00b6 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\u2019 File Structure .","title":"Home"},{"location":"#welcome-to-rapids-documentation","text":"Test v1.0 Reproducible Analysis Pipeline for Data Streams (RAPIDS) allows you to process smartphone and wearable data to extract behavioral features (a.k.a. digital biomarkers/phenotypes). RAPIDS is open source, documented, modular, tested, and reproducible. At the moment we support smartphone data collected with AWARE and wearable data from Fitbit devices. Questions or feedback can be posted on #rapids in AWARE Framework's slack . Bugs should be reported on Github . Join our discussions on our algorithms and assumptions for feature processing . Ready to start? Go to Installation and then to Initial Configuration","title":"Welcome to RAPIDS documentation"},{"location":"#how-does-it-work","text":"RAPIDS is formed by R and Python scripts orchestrated by Snakemake . We suggest you read Snakemake\u2019s docs but in short: every link in the analysis chain is atomic and has files as input and output. Behavioral features are processed per sensor and per participant.","title":"How does it work?"},{"location":"#what-are-the-benefits-of-using-rapids","text":"Consistent analysis . Every participant sensor dataset is analyzed in the exact same way and isolated from each other. Efficient analysis . Every analysis step is executed only once. Whenever your data or configuration changes only the affected files are updated. Parallel execution . Thanks to Snakemake, your analysis can be executed over multiple cores without changing your code. Extensible code . You can easily add your own behavioral features in R or Python and keep authorship and citations. Timezone aware . Your data is adjusted to the specified timezone (multiple timezones suport coming soon ). Flexible day segments . You can extract behavioral features on time windows of any length (e.g. 5 minutes, 3 hours, 2 days), on every day or particular days (e.g. weekends, Mondays, the 1 st of each month, etc.) or around events of interest (e.g. surveys or clinical relapses). Tested code . We are constantly adding tests to make sure our behavioral features are correct. Reproducible code . You can be sure your code will run in other computers as intended thanks to R and Python virtual environments. You can share your analysis code along your publications without any overhead. Private . All your data is processed locally.","title":"What are the benefits of using RAPIDS?"},{"location":"#how-is-it-organized","text":"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\u2019 File Structure .","title":"How is it organized?"},{"location":"citation/","text":"Cite RAPIDS and providers \u00b6 RAPIDS and the community RAPIDS is a community effort and as such we want to continue recognizing the contributions from other researchers. Besides citing RAPIDS, we ask you to cite any of the authors listed below if you used those sensor providers in your analysis, thank you! RAPIDS \u00b6 If you used RAPIDS, please cite this paper . RAPIDS et al. citation Vega J, Li M, Aguillera K, Goel N, Joshi E, Durica KC, Kunta AR, Low CA RAPIDS: Reproducible Analysis Pipeline for Data Streams Collected with Mobile Devices JMIR Preprints. 18/08/2020:23246 DOI: 10.2196/preprints.23246 URL: https://preprints.jmir.org/preprint/23246 Panda (accelerometer) \u00b6 If you computed accelerometer features using the provider [PHONE_ACCLEROMETER][PANDA] cite this paper in addition to RAPIDS. Panda et al. citation Panda N, Solsky I, Huang EJ, Lipsitz S, Pradarelli JC, Delisle M, Cusack JC, Gadd MA, Lubitz CC, Mullen JT, Qadan M, Smith BL, Specht M, Stephen AE, Tanabe KK, Gawande AA, Onnela JP, Haynes AB. Using Smartphones to Capture Novel Recovery Metrics After Cancer Surgery. JAMA Surg. 2020 Feb 1;155(2):123-129. doi: 10.1001/jamasurg.2019.4702. PMID: 31657854; PMCID: PMC6820047. Stachl (applications foreground) \u00b6 If you computed applications foreground features using the app category (genre) catalogue in [PHONE_APPLICATIONS_FOREGROUND][RAPIDS] cite this paper in addition to RAPIDS. Stachl et al. citation Clemens Stachl, Quay Au, Ramona Schoedel, Samuel D. Gosling, Gabriella M. Harari, Daniel Buschek, Sarah Theres V\u00f6lkel, Tobias Schuwerk, Michelle Oldemeier, Theresa Ullmann, Heinrich Hussmann, Bernd Bischl, Markus B\u00fchner. Proceedings of the National Academy of Sciences Jul 2020, 117 (30) 17680-17687; DOI: 10.1073/pnas.1920484117 Barnett (locations) \u00b6 If you computed locations features using the provider [PHONE_LOCATIONS][BARNETT] cite this paper and this paper in addition to RAPIDS. Barnett et al. citation Ian Barnett, Jukka-Pekka Onnela, Inferring mobility measures from GPS traces with missing data, Biostatistics, Volume 21, Issue 2, April 2020, Pages e98\u2013e112, https://doi.org/10.1093/biostatistics/kxy059 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845 Doryab (locations) \u00b6 If you computed locations features using the provider [PHONE_LOCATIONS][DORYAB] cite this paper and this paper in addition to RAPIDS. Doryab et al. citation Doryab, A., Chikarsel, P., Liu, X., & Dey, A. K. (2019). Extraction of Behavioral Features from Smartphone and Wearable Data. ArXiv:1812.10394 [Cs, Stat]. http://arxiv.org/abs/1812.10394 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845","title":"Citation"},{"location":"citation/#cite-rapids-and-providers","text":"RAPIDS and the community RAPIDS is a community effort and as such we want to continue recognizing the contributions from other researchers. Besides citing RAPIDS, we ask you to cite any of the authors listed below if you used those sensor providers in your analysis, thank you!","title":"Cite RAPIDS and providers"},{"location":"citation/#rapids","text":"If you used RAPIDS, please cite this paper . RAPIDS et al. citation Vega J, Li M, Aguillera K, Goel N, Joshi E, Durica KC, Kunta AR, Low CA RAPIDS: Reproducible Analysis Pipeline for Data Streams Collected with Mobile Devices JMIR Preprints. 18/08/2020:23246 DOI: 10.2196/preprints.23246 URL: https://preprints.jmir.org/preprint/23246","title":"RAPIDS"},{"location":"citation/#panda-accelerometer","text":"If you computed accelerometer features using the provider [PHONE_ACCLEROMETER][PANDA] cite this paper in addition to RAPIDS. Panda et al. citation Panda N, Solsky I, Huang EJ, Lipsitz S, Pradarelli JC, Delisle M, Cusack JC, Gadd MA, Lubitz CC, Mullen JT, Qadan M, Smith BL, Specht M, Stephen AE, Tanabe KK, Gawande AA, Onnela JP, Haynes AB. Using Smartphones to Capture Novel Recovery Metrics After Cancer Surgery. JAMA Surg. 2020 Feb 1;155(2):123-129. doi: 10.1001/jamasurg.2019.4702. PMID: 31657854; PMCID: PMC6820047.","title":"Panda (accelerometer)"},{"location":"citation/#stachl-applications-foreground","text":"If you computed applications foreground features using the app category (genre) catalogue in [PHONE_APPLICATIONS_FOREGROUND][RAPIDS] cite this paper in addition to RAPIDS. Stachl et al. citation Clemens Stachl, Quay Au, Ramona Schoedel, Samuel D. Gosling, Gabriella M. Harari, Daniel Buschek, Sarah Theres V\u00f6lkel, Tobias Schuwerk, Michelle Oldemeier, Theresa Ullmann, Heinrich Hussmann, Bernd Bischl, Markus B\u00fchner. Proceedings of the National Academy of Sciences Jul 2020, 117 (30) 17680-17687; DOI: 10.1073/pnas.1920484117","title":"Stachl (applications foreground)"},{"location":"citation/#barnett-locations","text":"If you computed locations features using the provider [PHONE_LOCATIONS][BARNETT] cite this paper and this paper in addition to RAPIDS. Barnett et al. citation Ian Barnett, Jukka-Pekka Onnela, Inferring mobility measures from GPS traces with missing data, Biostatistics, Volume 21, Issue 2, April 2020, Pages e98\u2013e112, https://doi.org/10.1093/biostatistics/kxy059 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845","title":"Barnett (locations)"},{"location":"citation/#doryab-locations","text":"If you computed locations features using the provider [PHONE_LOCATIONS][DORYAB] cite this paper and this paper in addition to RAPIDS. Doryab et al. citation Doryab, A., Chikarsel, P., Liu, X., & Dey, A. K. (2019). Extraction of Behavioral Features from Smartphone and Wearable Data. ArXiv:1812.10394 [Cs, Stat]. http://arxiv.org/abs/1812.10394 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845","title":"Doryab (locations)"},{"location":"faq/","text":"Frequently Asked Questions \u00b6 Cannot connect to your MySQL server \u00b6 Problem **Error in .local ( drv, \\. .. ) :** **Failed to connect to database: Error: Can \\' t initialize character set unknown ( path: compiled \\_ in ) ** : Calls: dbConnect -> dbConnect -> .local -> .Call Execution halted [ Tue Mar 10 19 :40:15 2020 ] Error in rule download_dataset: jobid: 531 output: data/raw/p60/locations_raw.csv RuleException: CalledProcessError in line 20 of /home/ubuntu/rapids/rules/preprocessing.snakefile: Command 'set -euo pipefail; Rscript --vanilla /home/ubuntu/rapids/.snakemake/scripts/tmp_2jnvqs7.download_dataset.R' returned non-zero exit status 1 . File \"/home/ubuntu/rapids/rules/preprocessing.snakefile\" , line 20 , in __rule_download_dataset File \"/home/ubuntu/anaconda3/envs/moshi-env/lib/python3.7/concurrent/futures/thread.py\" , line 57 , in run Shutting down, this might take some time. Exiting because a job execution failed. Look above for error message Solution Please make sure the DATABASE_GROUP in config.yaml matches your DB credentials group in .env . Cannot start mysql in linux via brew services start mysql \u00b6 Problem Cannot start mysql in linux via brew services start mysql Solution Use mysql.server start Every time I run force the download_dataset rule all rules are executed \u00b6 Problem When running snakemake -j1 -R download_phone_data or ./rapids -j1 -R download_phone_data all the rules and files are re-computed Solution This is expected behavior. The advantage of using snakemake under the hood is that every time a file containing data is modified every rule that depends on that file will be re-executed to update their results. In this case, since download_dataset updates all the raw data, and you are forcing the rule with the flag -R every single rule that depends on those raw files will be executed. Error Table XXX doesn't exist while running the download_phone_data or download_fitbit_data rule. \u00b6 Problem Error in .local ( conn, statement, ... ) : could not run statement: Table 'db_name.table_name' doesn ' t exist Calls: colnames ... .local -> dbSendQuery -> dbSendQuery -> .local -> .Call Execution halted Solution Please make sure the sensors listed in [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] and the [TABLE] of each sensor you activated in config.yaml match your database tables. How do I install RAPIDS on Ubuntu 16.04 \u00b6 Solution Install dependencies (Homebrew - if not installed): sudo apt-get install libmariadb-client-lgpl-dev libxml2-dev libssl-dev Install brew for linux and add the following line to ~/.bashrc : export PATH=$HOME/.linuxbrew/bin:$PATH source ~/.bashrc Install MySQL brew install mysql brew services start mysql Install R, pandoc and rmarkdown: brew install r brew install gcc@6 (needed due to this bug ) HOMEBREW_CC=gcc-6 brew install pandoc Install miniconda using these instructions Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake renv_install snakemake renv_init snakemake renv_restore This step could take several minutes to complete. Please be patient and let it run until completion. mysql.h cannot be found \u00b6 Problem -------------------------- [ ERROR MESSAGE ] ---------------------------- :1:10: fatal error: mysql.h: No such file or directory compilation terminated. ----------------------------------------------------------------------- ERROR: configuration failed for package 'RMySQL' Solution sudo apt install libmariadbclient-dev No package libcurl found \u00b6 Problem libcurl cannot be found Solution Install libcurl sudo apt install libcurl4-openssl-dev Configuration failed because openssl was not found. \u00b6 Problem openssl cannot be found Solution Install openssl sudo apt install libssl-dev Configuration failed because libxml-2.0 was not found \u00b6 Problem libxml-2.0 cannot be found Solution Install libxml-2.0 sudo apt install libxml2-dev SSL connection error when running RAPIDS \u00b6 Problem You are getting the following error message when running RAPIDS: Error: Failed to connect: SSL connection error: error:1425F102:SSL routines:ssl_choose_client_version:unsupported protocol. Solution This is a bug in Ubuntu 20.04 when trying to connect to an old MySQL server with MySQL client 8.0. You should get the same error message if you try to connect from the command line. There you can add the option --ssl-mode=DISABLED but we can't do this from the R connector. If you can't update your server, the quickest solution would be to import your database to another server or to a local environment. Alternatively, you could replace mysql-client and libmysqlclient-dev with mariadb-client and libmariadbclient-dev and reinstall renv. More info about this issue here DB_TABLES key not found \u00b6 Problem If you get the following error KeyError in line 43 of preprocessing.smk: 'PHONE_SENSORS' , it means that the indentation of the key [PHONE_SENSORS] is not matching the other child elements of PHONE_VALID_SENSED_BINS Solution You need to add or remove any leading whitespaces as needed on that line. PHONE_VALID_SENSED_BINS : COMPUTE : False # This flag is automatically ignored (set to True) if you are extracting PHONE_VALID_SENSED_DAYS or screen or Barnett's location features BIN_SIZE : &bin_size 5 # (in minutes) PHONE_SENSORS : [] Error while updating your conda environment in Ubuntu \u00b6 Problem You get the following error: CondaMultiError: CondaVerificationError: The package for tk located at /home/ubuntu/miniconda2/pkgs/tk-8.6.9-hed695b0_1003 appears to be corrupted. The path 'include/mysqlStubs.h' specified in the package manifest cannot be found. ClobberError: This transaction has incompatible packages due to a shared path. packages: conda-forge/linux-64::llvm-openmp-10.0.0-hc9558a2_0, anaconda/linux-64::intel-openmp-2019.4-243 path: 'lib/libiomp5.so' Solution Reinstall conda","title":"Frequently Asked Questions"},{"location":"faq/#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"faq/#cannot-connect-to-your-mysql-server","text":"Problem **Error in .local ( drv, \\. .. ) :** **Failed to connect to database: Error: Can \\' t initialize character set unknown ( path: compiled \\_ in ) ** : Calls: dbConnect -> dbConnect -> .local -> .Call Execution halted [ Tue Mar 10 19 :40:15 2020 ] Error in rule download_dataset: jobid: 531 output: data/raw/p60/locations_raw.csv RuleException: CalledProcessError in line 20 of /home/ubuntu/rapids/rules/preprocessing.snakefile: Command 'set -euo pipefail; Rscript --vanilla /home/ubuntu/rapids/.snakemake/scripts/tmp_2jnvqs7.download_dataset.R' returned non-zero exit status 1 . File \"/home/ubuntu/rapids/rules/preprocessing.snakefile\" , line 20 , in __rule_download_dataset File \"/home/ubuntu/anaconda3/envs/moshi-env/lib/python3.7/concurrent/futures/thread.py\" , line 57 , in run Shutting down, this might take some time. Exiting because a job execution failed. Look above for error message Solution Please make sure the DATABASE_GROUP in config.yaml matches your DB credentials group in .env .","title":"Cannot connect to your MySQL server"},{"location":"faq/#cannot-start-mysql-in-linux-via-brew-services-start-mysql","text":"Problem Cannot start mysql in linux via brew services start mysql Solution Use mysql.server start","title":"Cannot start mysql in linux via brew services start mysql"},{"location":"faq/#every-time-i-run-force-the-download_dataset-rule-all-rules-are-executed","text":"Problem When running snakemake -j1 -R download_phone_data or ./rapids -j1 -R download_phone_data all the rules and files are re-computed Solution This is expected behavior. The advantage of using snakemake under the hood is that every time a file containing data is modified every rule that depends on that file will be re-executed to update their results. In this case, since download_dataset updates all the raw data, and you are forcing the rule with the flag -R every single rule that depends on those raw files will be executed.","title":"Every time I run force the download_dataset rule all rules are executed"},{"location":"faq/#error-table-xxx-doesnt-exist-while-running-the-download_phone_data-or-download_fitbit_data-rule","text":"Problem Error in .local ( conn, statement, ... ) : could not run statement: Table 'db_name.table_name' doesn ' t exist Calls: colnames ... .local -> dbSendQuery -> dbSendQuery -> .local -> .Call Execution halted Solution Please make sure the sensors listed in [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] and the [TABLE] of each sensor you activated in config.yaml match your database tables.","title":"Error Table XXX doesn't exist while running the download_phone_data or download_fitbit_data rule."},{"location":"faq/#how-do-i-install-rapids-on-ubuntu-1604","text":"Solution Install dependencies (Homebrew - if not installed): sudo apt-get install libmariadb-client-lgpl-dev libxml2-dev libssl-dev Install brew for linux and add the following line to ~/.bashrc : export PATH=$HOME/.linuxbrew/bin:$PATH source ~/.bashrc Install MySQL brew install mysql brew services start mysql Install R, pandoc and rmarkdown: brew install r brew install gcc@6 (needed due to this bug ) HOMEBREW_CC=gcc-6 brew install pandoc Install miniconda using these instructions Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake renv_install snakemake renv_init snakemake renv_restore This step could take several minutes to complete. Please be patient and let it run until completion.","title":"How do I install RAPIDS on Ubuntu 16.04"},{"location":"faq/#mysqlh-cannot-be-found","text":"Problem -------------------------- [ ERROR MESSAGE ] ---------------------------- :1:10: fatal error: mysql.h: No such file or directory compilation terminated. ----------------------------------------------------------------------- ERROR: configuration failed for package 'RMySQL' Solution sudo apt install libmariadbclient-dev","title":"mysql.h cannot be found"},{"location":"faq/#no-package-libcurl-found","text":"Problem libcurl cannot be found Solution Install libcurl sudo apt install libcurl4-openssl-dev","title":"No package libcurl found"},{"location":"faq/#configuration-failed-because-openssl-was-not-found","text":"Problem openssl cannot be found Solution Install openssl sudo apt install libssl-dev","title":"Configuration failed because openssl was not found."},{"location":"faq/#configuration-failed-because-libxml-20-was-not-found","text":"Problem libxml-2.0 cannot be found Solution Install libxml-2.0 sudo apt install libxml2-dev","title":"Configuration failed because libxml-2.0 was not found"},{"location":"faq/#ssl-connection-error-when-running-rapids","text":"Problem You are getting the following error message when running RAPIDS: Error: Failed to connect: SSL connection error: error:1425F102:SSL routines:ssl_choose_client_version:unsupported protocol. Solution This is a bug in Ubuntu 20.04 when trying to connect to an old MySQL server with MySQL client 8.0. You should get the same error message if you try to connect from the command line. There you can add the option --ssl-mode=DISABLED but we can't do this from the R connector. If you can't update your server, the quickest solution would be to import your database to another server or to a local environment. Alternatively, you could replace mysql-client and libmysqlclient-dev with mariadb-client and libmariadbclient-dev and reinstall renv. More info about this issue here","title":"SSL connection error when running RAPIDS"},{"location":"faq/#db_tables-key-not-found","text":"Problem If you get the following error KeyError in line 43 of preprocessing.smk: 'PHONE_SENSORS' , it means that the indentation of the key [PHONE_SENSORS] is not matching the other child elements of PHONE_VALID_SENSED_BINS Solution You need to add or remove any leading whitespaces as needed on that line. PHONE_VALID_SENSED_BINS : COMPUTE : False # This flag is automatically ignored (set to True) if you are extracting PHONE_VALID_SENSED_DAYS or screen or Barnett's location features BIN_SIZE : &bin_size 5 # (in minutes) PHONE_SENSORS : []","title":"DB_TABLES key not found"},{"location":"faq/#error-while-updating-your-conda-environment-in-ubuntu","text":"Problem You get the following error: CondaMultiError: CondaVerificationError: The package for tk located at /home/ubuntu/miniconda2/pkgs/tk-8.6.9-hed695b0_1003 appears to be corrupted. The path 'include/mysqlStubs.h' specified in the package manifest cannot be found. ClobberError: This transaction has incompatible packages due to a shared path. packages: conda-forge/linux-64::llvm-openmp-10.0.0-hc9558a2_0, anaconda/linux-64::intel-openmp-2019.4-243 path: 'lib/libiomp5.so' Solution Reinstall conda","title":"Error while updating your conda environment in Ubuntu"},{"location":"file-structure/","text":"File Structure \u00b6 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 and then to Initial Configuration All paths mentioned in this page are relative to RAPIDS\u2019 root folder. If you want to extract the behavioral features that RAPIDS offers, you will only have to create or modify the .env file , participants files , day segment files , 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 or the day segment files ). Interaction diagram between the user, and important files in RAPIDS","title":"File Structure"},{"location":"file-structure/#file-structure","text":"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 and then to Initial Configuration All paths mentioned in this page are relative to RAPIDS\u2019 root folder. If you want to extract the behavioral features that RAPIDS offers, you will only have to create or modify the .env file , participants files , day segment files , 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 or the day segment files ). Interaction diagram between the user, and important files in RAPIDS","title":"File Structure"},{"location":"team/","text":"RAPIDS Team \u00b6 If you are interested in contributing feel free to submit a pull request or contact us. Core Team \u00b6 Julio Vega (Designer and Lead Developer) \u00b6 About Julio Vega is a postdoctoral associate at the Mobile Sensing + Health Institute. He is interested in personalized methodologies to monitor chronic conditions that affect daily human behavior using mobile and wearable data. vegaju at upmc . edu Personal Website Meng Li \u00b6 About Meng Li received her Master of Science degree in Information Science from the University of Pittsburgh. She is interested in applying machine learning algorithms to the medical field. lim11 at upmc . edu Linkedin Profile Github Profile Abhineeth Reddy Kunta \u00b6 About Abhineeth Reddy Kunta is a Senior Software Engineer with the Mobile Sensing + Health Institute. He is experienced in software development and specializes in building solutions using machine learning. Abhineeth likes exploring ways to leverage technology in advancing medicine and education. Previously he worked as a Computer Programmer at Georgia Department of Public Health. He has a master\u2019s degree in Computer Science from George Mason University. Kwesi Aguillera \u00b6 About Kwesi Aguillera is currently in his first year at the University of Pittsburgh pursuing a Master of Sciences in Information Science specializing in Big Data Analytics. He received his Bachelor of Science degree in Computer Science and Management from the University of the West Indies. Kwesi considers himself a full stack developer and looks forward to applying this knowledge to big data analysis. Linkedin Profile Echhit Joshi \u00b6 About Echhit Joshi is a Masters student at the School of Computing and Information at University of Pittsburgh. His areas of interest are Machine/Deep Learning, Data Mining, and Analytics. Linkedin Profile Nicolas Leo \u00b6 About Nicolas is a rising senior studying computer science at the University of Pittsburgh. His academic interests include databases, machine learning, and application development. After completing his undergraduate degree, he plans to attend graduate school for a MS in Computer Science with a focus on Intelligent Systems. Nikunj Goel \u00b6 About Nik is a graduate student at the University of Pittsburgh pursuing Master of Science in Information Science. He earned his Bachelor of Technology degree in Information Technology from India. He is a Data Enthusiasts and passionate about finding the meaning out of raw data. In a long term, his goal is to create a breakthrough in Data Science and Deep Learning. Linkedin Profile Community Contributors \u00b6 Agam Kumar \u00b6 About Agam is a junior at Carnegie Mellon University studying Statistics and Machine Learning and pursuing an additional major in Computer Science. He is a member of the Data Science team in the Health and Human Performance Lab at CMU and has keen interests in software development and data science. His research interests include ML applications in medicine. Linkedin Profile Github Profile Yasaman S. Sefidgar \u00b6 About Linkedin Profile Advisors \u00b6 Afsaneh Doryab \u00b6 About Personal Website Carissa Low \u00b6 About Profile","title":"Team"},{"location":"team/#rapids-team","text":"If you are interested in contributing feel free to submit a pull request or contact us.","title":"RAPIDS Team"},{"location":"team/#core-team","text":"","title":"Core Team"},{"location":"team/#julio-vega-designer-and-lead-developer","text":"About Julio Vega is a postdoctoral associate at the Mobile Sensing + Health Institute. He is interested in personalized methodologies to monitor chronic conditions that affect daily human behavior using mobile and wearable data. vegaju at upmc . edu Personal Website","title":"Julio Vega (Designer and Lead Developer)"},{"location":"team/#meng-li","text":"About Meng Li received her Master of Science degree in Information Science from the University of Pittsburgh. She is interested in applying machine learning algorithms to the medical field. lim11 at upmc . edu Linkedin Profile Github Profile","title":"Meng Li"},{"location":"team/#abhineeth-reddy-kunta","text":"About Abhineeth Reddy Kunta is a Senior Software Engineer with the Mobile Sensing + Health Institute. He is experienced in software development and specializes in building solutions using machine learning. Abhineeth likes exploring ways to leverage technology in advancing medicine and education. Previously he worked as a Computer Programmer at Georgia Department of Public Health. He has a master\u2019s degree in Computer Science from George Mason University.","title":"Abhineeth Reddy Kunta"},{"location":"team/#kwesi-aguillera","text":"About Kwesi Aguillera is currently in his first year at the University of Pittsburgh pursuing a Master of Sciences in Information Science specializing in Big Data Analytics. He received his Bachelor of Science degree in Computer Science and Management from the University of the West Indies. Kwesi considers himself a full stack developer and looks forward to applying this knowledge to big data analysis. Linkedin Profile","title":"Kwesi Aguillera"},{"location":"team/#echhit-joshi","text":"About Echhit Joshi is a Masters student at the School of Computing and Information at University of Pittsburgh. His areas of interest are Machine/Deep Learning, Data Mining, and Analytics. Linkedin Profile","title":"Echhit Joshi"},{"location":"team/#nicolas-leo","text":"About Nicolas is a rising senior studying computer science at the University of Pittsburgh. His academic interests include databases, machine learning, and application development. After completing his undergraduate degree, he plans to attend graduate school for a MS in Computer Science with a focus on Intelligent Systems.","title":"Nicolas Leo"},{"location":"team/#nikunj-goel","text":"About Nik is a graduate student at the University of Pittsburgh pursuing Master of Science in Information Science. He earned his Bachelor of Technology degree in Information Technology from India. He is a Data Enthusiasts and passionate about finding the meaning out of raw data. In a long term, his goal is to create a breakthrough in Data Science and Deep Learning. Linkedin Profile","title":"Nikunj Goel"},{"location":"team/#community-contributors","text":"","title":"Community Contributors"},{"location":"team/#agam-kumar","text":"About Agam is a junior at Carnegie Mellon University studying Statistics and Machine Learning and pursuing an additional major in Computer Science. He is a member of the Data Science team in the Health and Human Performance Lab at CMU and has keen interests in software development and data science. His research interests include ML applications in medicine. Linkedin Profile Github Profile","title":"Agam Kumar"},{"location":"team/#yasaman-s-sefidgar","text":"About Linkedin Profile","title":"Yasaman S. Sefidgar"},{"location":"team/#advisors","text":"","title":"Advisors"},{"location":"team/#afsaneh-doryab","text":"About Personal Website","title":"Afsaneh Doryab"},{"location":"team/#carissa-low","text":"About Profile","title":"Carissa Low"},{"location":"developers/documentation/","text":"Documentation \u00b6 We use mkdocs with the material theme to write these docs. Whenever you make any changes, just push them back to the repo and the documentation will be deployed automatically. Set up development environment \u00b6 Make sure your conda environment is active pip install mkdocs pip install mkdocs-material Preview \u00b6 Run the following command in RAPIDS root folder and go to http://127.0.0.1:8000 : mkdocs serve File Structure \u00b6 The documentation config file is /mkdocs.yml , if you are adding new .md files to the docs modify the nav attribute at the bottom of that file. You can use the hierarchy there to find all the files that appear in the documentation. Reference \u00b6 Check this page to get familiar with the different visual elements we can use in the docs (admonitions, code blocks, tables, etc.) You can also refer to /docs/setup/installation.md and /docs/setup/configuration.md to see practical examples of these elements. Extras \u00b6 You can insert emojis using this syntax :[SOURCE]-[ICON_NAME] from the following sources: https://materialdesignicons.com/ https://fontawesome.com/icons/tasks?style=solid https://primer.style/octicons/ You can use this page to create markdown tables more easily","title":"Documentation"},{"location":"developers/documentation/#documentation","text":"We use mkdocs with the material theme to write these docs. Whenever you make any changes, just push them back to the repo and the documentation will be deployed automatically.","title":"Documentation"},{"location":"developers/documentation/#set-up-development-environment","text":"Make sure your conda environment is active pip install mkdocs pip install mkdocs-material","title":"Set up development environment"},{"location":"developers/documentation/#preview","text":"Run the following command in RAPIDS root folder and go to http://127.0.0.1:8000 : mkdocs serve","title":"Preview"},{"location":"developers/documentation/#file-structure","text":"The documentation config file is /mkdocs.yml , if you are adding new .md files to the docs modify the nav attribute at the bottom of that file. You can use the hierarchy there to find all the files that appear in the documentation.","title":"File Structure"},{"location":"developers/documentation/#reference","text":"Check this page to get familiar with the different visual elements we can use in the docs (admonitions, code blocks, tables, etc.) You can also refer to /docs/setup/installation.md and /docs/setup/configuration.md to see practical examples of these elements.","title":"Reference"},{"location":"developers/documentation/#extras","text":"You can insert emojis using this syntax :[SOURCE]-[ICON_NAME] from the following sources: https://materialdesignicons.com/ https://fontawesome.com/icons/tasks?style=solid https://primer.style/octicons/ You can use this page to create markdown tables more easily","title":"Extras"},{"location":"developers/remote-support/","text":"Remote Support \u00b6 We use the Live Share extension of Visual Studio Code to debug bugs when sharing data or database credentials is not possible. Install Visual Studio Code Open you RAPIDS root folder in a new VSCode window Open a new Terminal Terminal > New terminal Install the Live Share extension pack Press Ctrl + P or Cmd + P and run this command: >live share: start collaboration session 6. Follow the instructions and share the session link you receive","title":"Remote Support"},{"location":"developers/remote-support/#remote-support","text":"We use the Live Share extension of Visual Studio Code to debug bugs when sharing data or database credentials is not possible. Install Visual Studio Code Open you RAPIDS root folder in a new VSCode window Open a new Terminal Terminal > New terminal Install the Live Share extension pack Press Ctrl + P or Cmd + P and run this command: >live share: start collaboration session 6. Follow the instructions and share the session link you receive","title":"Remote Support"},{"location":"developers/test-cases/","text":"Test Cases \u00b6 Along with the continued development and the addition of new sensors and features to the RAPIDS pipeline, tests for the currently available sensors and features are being implemented. Since this is a Work In Progress this page will be updated with the list of sensors and features for which testing is available. For each of the sensors listed a description of the data used for testing (test cases) are outline. Currently for all intent and testing purposes the tests/data/raw/test01/ contains all the test data files for testing android data formats and tests/data/raw/test02/ contains all the test data files for testing iOS data formats. It follows that the expected (verified output) are contained in the tests/data/processed/test01/ and tests/data/processed/test02/ for Android and iOS respectively. tests/data/raw/test03/ and tests/data/raw/test04/ contain data files for testing empty raw data files for android and iOS respectively. The following is a list of the sensors that testing is currently available. Messages (SMS) \u00b6 The raw message data file contains data for 2 separate days. The data for the first day contains records 5 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The raw message data contains records for both message_types (i.e. recieved and sent ) in both days in all epochs. The number records with each message_types per epoch is randomly distributed There is at least one records with each message_types per epoch. There is one raw message data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files Calls \u00b6 Due to the difference in the format of the raw call data for iOS and Android the following is the expected results the calls_with_datetime_unified.csv . This would give a better idea of the use cases being tested since the calls_with_datetime_unified.csv would make both the iOS and Android data comparable. The call data would contain data for 2 days. The data for the first day contains 6 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The call data contains records for all call_types (i.e. incoming , outgoing and missed ) in both days in all epochs. The number records with each of the call_types per epoch is randomly distributed. There is at least one records with each call_types per epoch. There is one call data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files Screen \u00b6 Due to the difference in the format of the raw screen data for iOS and Android the following is the expected results the screen_deltas.csv . This would give a better idea of the use cases being tested since the screen_eltas.csv would make both the iOS and Android data comparable These files are used to calculate the features for the screen sensor The screen delta data file contains data for 1 day. The screen delta data contains 1 record to represent an unlock episode that falls within an epoch for every epoch . The screen delta data contains 1 record to represent an unlock episode that falls across the boundary of 2 epochs. Namely the unlock episode starts in one epoch and ends in the next, thus there is a record for unlock episodes that fall across night to morning , morning to afternoon and finally afternoon to night The testing is done for unlock episode_type. There is one screen data file each for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files Battery \u00b6 Due to the difference in the format of the raw battery data for iOS and Android as well as versions of iOS the following is the expected results the battery_deltas.csv . This would give a better idea of the use cases being tested since the battery_deltas.csv would make both the iOS and Android data comparable. These files are used to calculate the features for the battery sensor. The battery delta data file contains data for 1 day. The battery delta data contains 1 record each for a charging and discharging episode that falls within an epoch for every epoch . Thus, for the daily epoch there would be multiple charging and discharging episodes Since either a charging episode or a discharging episode and not both can occur across epochs, in order to test episodes that occur across epochs alternating episodes of charging and discharging episodes that fall across night to morning , morning to afternoon and finally afternoon to night are present in the battery delta data. This starts with a discharging episode that begins in night and end in morning . There is one battery data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files Bluetooth \u00b6 The raw Bluetooth data file contains data for 1 day. The raw Bluetooth data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) An option of 5 Bluetooth devices are randomly distributed throughout the data records. There is one raw Bluetooth data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files. WIFI \u00b6 There are 2 data files ( wifi_raw.csv and sensor_wifi_raw.csv ) for each fake participant for each phone platform. The raw WIFI data files contain data for 1 day. The sensor_wifi_raw.csv data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) The wifi_raw.csv data contains 3 records with random timestamps for each epoch to represent visible broadcasting WIFI network. This file is empty for the iOS phone testing data. An option of 10 access point devices is randomly distributed throughout the data records. 5 each for sensor_wifi_raw.csv and wifi_raw.csv . There data files for testing both iOS and Android data formats. There are also additional empty data files for both android and iOS for testing empty data files. Light \u00b6 The raw light data file contains data for 1 day. The raw light data contains 3 or 4 rows of data for each epoch except night . The single row of data for night is for testing features for single values inputs. (Example testing the standard deviation of one input value) Since light is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files. Application Foreground \u00b6 The raw application foreground data file contains data for 1 day. The raw application foreground data contains 7 - 9 rows of data for each epoch . The records for each epoch contains apps that are randomly selected from a list of apps that are from the MULTIPLE_CATEGORIES and SINGLE_CATEGORIES (See testing_config.yaml ). There are also records in each epoch that have apps randomly selected from a list of apps that are from the EXCLUDED_CATEGORIES and EXCLUDED_APPS . This is to test that these apps are actually being excluded from the calculations of features. There are also records to test SINGLE_APPS calculations. Since application foreground is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files. Activity Recognition \u00b6 The raw Activity Recognition data file contains data for 1 day. The raw Activity Recognition data each epoch period contains rows that records 2 - 5 different activity_types . The is such that durations of activities can be tested. Additionally, there are records that mimic the duration of an activity over the time boundary of neighboring epochs. (For example, there a set of records that mimic the participant in_vehicle from afternoon into evening ) There is one file each with raw Activity Recognition data for testing both iOS and Android data formats. (plugin_google_activity_recognition_raw.csv for android and plugin_ios_activity_recognition_raw.csv for iOS) There is also an additional empty data file for both android and iOS for testing empty data files. Conversation \u00b6 The raw conversation data file contains data for 2 day. The raw conversation data contains records with a sample of both datatypes (i.e. voice/noise = 0 , and conversation = 2 ) as well as rows with for samples of each of the inference values (i.e. silence = 0 , noise = 1 , voice = 2 , and unknown = 3 ) for each epoch . The different datatype and inference records are randomly distributed throughout the epoch . Additionally there are 2 - 5 records for conversations ( datatype = 2, and inference = -1) in each epoch and for each epoch except night, there is a conversation record that has a double_convo_start timestamp that is from the previous epoch . This is to test the calculations of features across epochs . There is a raw conversation data file for both android and iOS platforms ( plugin_studentlife_audio_android_raw.csv and plugin_studentlife_audio_raw.csv respectively). Finally, there are also additional empty data files for both android and iOS for testing empty data files","title":"Test cases"},{"location":"developers/test-cases/#test-cases","text":"Along with the continued development and the addition of new sensors and features to the RAPIDS pipeline, tests for the currently available sensors and features are being implemented. Since this is a Work In Progress this page will be updated with the list of sensors and features for which testing is available. For each of the sensors listed a description of the data used for testing (test cases) are outline. Currently for all intent and testing purposes the tests/data/raw/test01/ contains all the test data files for testing android data formats and tests/data/raw/test02/ contains all the test data files for testing iOS data formats. It follows that the expected (verified output) are contained in the tests/data/processed/test01/ and tests/data/processed/test02/ for Android and iOS respectively. tests/data/raw/test03/ and tests/data/raw/test04/ contain data files for testing empty raw data files for android and iOS respectively. The following is a list of the sensors that testing is currently available.","title":"Test Cases"},{"location":"developers/test-cases/#messages-sms","text":"The raw message data file contains data for 2 separate days. The data for the first day contains records 5 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The raw message data contains records for both message_types (i.e. recieved and sent ) in both days in all epochs. The number records with each message_types per epoch is randomly distributed There is at least one records with each message_types per epoch. There is one raw message data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Messages (SMS)"},{"location":"developers/test-cases/#calls","text":"Due to the difference in the format of the raw call data for iOS and Android the following is the expected results the calls_with_datetime_unified.csv . This would give a better idea of the use cases being tested since the calls_with_datetime_unified.csv would make both the iOS and Android data comparable. The call data would contain data for 2 days. The data for the first day contains 6 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The call data contains records for all call_types (i.e. incoming , outgoing and missed ) in both days in all epochs. The number records with each of the call_types per epoch is randomly distributed. There is at least one records with each call_types per epoch. There is one call data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Calls"},{"location":"developers/test-cases/#screen","text":"Due to the difference in the format of the raw screen data for iOS and Android the following is the expected results the screen_deltas.csv . This would give a better idea of the use cases being tested since the screen_eltas.csv would make both the iOS and Android data comparable These files are used to calculate the features for the screen sensor The screen delta data file contains data for 1 day. The screen delta data contains 1 record to represent an unlock episode that falls within an epoch for every epoch . The screen delta data contains 1 record to represent an unlock episode that falls across the boundary of 2 epochs. Namely the unlock episode starts in one epoch and ends in the next, thus there is a record for unlock episodes that fall across night to morning , morning to afternoon and finally afternoon to night The testing is done for unlock episode_type. There is one screen data file each for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Screen"},{"location":"developers/test-cases/#battery","text":"Due to the difference in the format of the raw battery data for iOS and Android as well as versions of iOS the following is the expected results the battery_deltas.csv . This would give a better idea of the use cases being tested since the battery_deltas.csv would make both the iOS and Android data comparable. These files are used to calculate the features for the battery sensor. The battery delta data file contains data for 1 day. The battery delta data contains 1 record each for a charging and discharging episode that falls within an epoch for every epoch . Thus, for the daily epoch there would be multiple charging and discharging episodes Since either a charging episode or a discharging episode and not both can occur across epochs, in order to test episodes that occur across epochs alternating episodes of charging and discharging episodes that fall across night to morning , morning to afternoon and finally afternoon to night are present in the battery delta data. This starts with a discharging episode that begins in night and end in morning . There is one battery data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Battery"},{"location":"developers/test-cases/#bluetooth","text":"The raw Bluetooth data file contains data for 1 day. The raw Bluetooth data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) An option of 5 Bluetooth devices are randomly distributed throughout the data records. There is one raw Bluetooth data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files.","title":"Bluetooth"},{"location":"developers/test-cases/#wifi","text":"There are 2 data files ( wifi_raw.csv and sensor_wifi_raw.csv ) for each fake participant for each phone platform. The raw WIFI data files contain data for 1 day. The sensor_wifi_raw.csv data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) The wifi_raw.csv data contains 3 records with random timestamps for each epoch to represent visible broadcasting WIFI network. This file is empty for the iOS phone testing data. An option of 10 access point devices is randomly distributed throughout the data records. 5 each for sensor_wifi_raw.csv and wifi_raw.csv . There data files for testing both iOS and Android data formats. There are also additional empty data files for both android and iOS for testing empty data files.","title":"WIFI"},{"location":"developers/test-cases/#light","text":"The raw light data file contains data for 1 day. The raw light data contains 3 or 4 rows of data for each epoch except night . The single row of data for night is for testing features for single values inputs. (Example testing the standard deviation of one input value) Since light is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files.","title":"Light"},{"location":"developers/test-cases/#application-foreground","text":"The raw application foreground data file contains data for 1 day. The raw application foreground data contains 7 - 9 rows of data for each epoch . The records for each epoch contains apps that are randomly selected from a list of apps that are from the MULTIPLE_CATEGORIES and SINGLE_CATEGORIES (See testing_config.yaml ). There are also records in each epoch that have apps randomly selected from a list of apps that are from the EXCLUDED_CATEGORIES and EXCLUDED_APPS . This is to test that these apps are actually being excluded from the calculations of features. There are also records to test SINGLE_APPS calculations. Since application foreground is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files.","title":"Application Foreground"},{"location":"developers/test-cases/#activity-recognition","text":"The raw Activity Recognition data file contains data for 1 day. The raw Activity Recognition data each epoch period contains rows that records 2 - 5 different activity_types . The is such that durations of activities can be tested. Additionally, there are records that mimic the duration of an activity over the time boundary of neighboring epochs. (For example, there a set of records that mimic the participant in_vehicle from afternoon into evening ) There is one file each with raw Activity Recognition data for testing both iOS and Android data formats. (plugin_google_activity_recognition_raw.csv for android and plugin_ios_activity_recognition_raw.csv for iOS) There is also an additional empty data file for both android and iOS for testing empty data files.","title":"Activity Recognition"},{"location":"developers/test-cases/#conversation","text":"The raw conversation data file contains data for 2 day. The raw conversation data contains records with a sample of both datatypes (i.e. voice/noise = 0 , and conversation = 2 ) as well as rows with for samples of each of the inference values (i.e. silence = 0 , noise = 1 , voice = 2 , and unknown = 3 ) for each epoch . The different datatype and inference records are randomly distributed throughout the epoch . Additionally there are 2 - 5 records for conversations ( datatype = 2, and inference = -1) in each epoch and for each epoch except night, there is a conversation record that has a double_convo_start timestamp that is from the previous epoch . This is to test the calculations of features across epochs . There is a raw conversation data file for both android and iOS platforms ( plugin_studentlife_audio_android_raw.csv and plugin_studentlife_audio_raw.csv respectively). Finally, there are also additional empty data files for both android and iOS for testing empty data files","title":"Conversation"},{"location":"developers/testing/","text":"Testing \u00b6 The following is a simple guide to testing RAPIDS. All files necessary for testing are stored in the /tests directory Steps for Testing \u00b6 To begin testing RAPIDS place the fake raw input data csv files in tests/data/raw/ . The fake participant files should be placed in tests/data/external/ . The expected output files of RAPIDS after processing the input data should be placed in tests/data/processesd/ . The Snakemake rule(s) that are to be tested must be placed in the tests/Snakemake file. The current tests/Snakemake is a good example of how to define them. (At the time of writing this documentation the snakefile contains rules messages (SMS), calls and screen) Edit the tests/settings/config.yaml . Add and/or remove the rules to be run for testing from the forcerun list. Edit the tests/settings/testing_config.yaml with the necessary configuration settings for running the rules to be tested. Add any additional testscripts in tests/scripts . Uncomment or comment off lines in the testing shell script tests/scripts/run_tests.sh . Run the testing shell script. tests/scripts/run_tests.sh The following is a snippet of the output you should see after running your test. test_sensors_files_exist ( test_sensor_features.TestSensorFeatures ) ... ok test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ... FAIL ====================================================================== FAIL: test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ---------------------------------------------------------------------- The results above show that the first test test_sensors_files_exist passed while test_sensors_features_calculations failed. In addition you should get the traceback of the failure (not shown here). For more information on how to implement test scripts and use unittest please see Unittest Documentation Testing of the RAPIDS sensors and features is a work-in-progress. Please see test-cases for a list of sensors and features that have testing currently available. Currently the repository is set up to test a number of sensors out of the box by simply running the tests/scripts/run_tests.sh command once the RAPIDS python environment is active.","title":"Testing"},{"location":"developers/testing/#testing","text":"The following is a simple guide to testing RAPIDS. All files necessary for testing are stored in the /tests directory","title":"Testing"},{"location":"developers/testing/#steps-for-testing","text":"To begin testing RAPIDS place the fake raw input data csv files in tests/data/raw/ . The fake participant files should be placed in tests/data/external/ . The expected output files of RAPIDS after processing the input data should be placed in tests/data/processesd/ . The Snakemake rule(s) that are to be tested must be placed in the tests/Snakemake file. The current tests/Snakemake is a good example of how to define them. (At the time of writing this documentation the snakefile contains rules messages (SMS), calls and screen) Edit the tests/settings/config.yaml . Add and/or remove the rules to be run for testing from the forcerun list. Edit the tests/settings/testing_config.yaml with the necessary configuration settings for running the rules to be tested. Add any additional testscripts in tests/scripts . Uncomment or comment off lines in the testing shell script tests/scripts/run_tests.sh . Run the testing shell script. tests/scripts/run_tests.sh The following is a snippet of the output you should see after running your test. test_sensors_files_exist ( test_sensor_features.TestSensorFeatures ) ... ok test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ... FAIL ====================================================================== FAIL: test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ---------------------------------------------------------------------- The results above show that the first test test_sensors_files_exist passed while test_sensors_features_calculations failed. In addition you should get the traceback of the failure (not shown here). For more information on how to implement test scripts and use unittest please see Unittest Documentation Testing of the RAPIDS sensors and features is a work-in-progress. Please see test-cases for a list of sensors and features that have testing currently available. Currently the repository is set up to test a number of sensors out of the box by simply running the tests/scripts/run_tests.sh command once the RAPIDS python environment is active.","title":"Steps for Testing"},{"location":"developers/virtual-environments/","text":"Virtual Environments \u00b6 Add new packages \u00b6 Try to install any new package using conda . If a package is not available in one of conda \u2018s channels you can install it with pip but make sure your virtual environment is active. Update your conda environment.yaml \u00b6 After installing a new package you can use the following command in your terminal to update your environment.yaml before publishing your pipeline. Note that we ignore the package version for libfortran to keep compatibility with Linux: conda env export --no-builds | sed 's/^.*libgfortran.*$/ - libgfortran/' > environment.yml Update and prune your conda environment from a environment.yaml file \u00b6 Execute the following command in your terminal, see these docs for more information conda env update --prefix ./env --file environment.yml --prune","title":"Virtual Environments"},{"location":"developers/virtual-environments/#virtual-environments","text":"","title":"Virtual Environments"},{"location":"developers/virtual-environments/#add-new-packages","text":"Try to install any new package using conda . If a package is not available in one of conda \u2018s channels you can install it with pip but make sure your virtual environment is active.","title":"Add new packages"},{"location":"developers/virtual-environments/#update-your-conda-environmentyaml","text":"After installing a new package you can use the following command in your terminal to update your environment.yaml before publishing your pipeline. Note that we ignore the package version for libfortran to keep compatibility with Linux: conda env export --no-builds | sed 's/^.*libgfortran.*$/ - libgfortran/' > environment.yml","title":"Update your conda environment.yaml"},{"location":"developers/virtual-environments/#update-and-prune-your-conda-environment-from-a-environmentyaml-file","text":"Execute the following command in your terminal, see these docs for more information conda env update --prefix ./env --file environment.yml --prune","title":"Update and prune your conda environment from a environment.yaml file"},{"location":"features/add-new-features/","text":"Add New Features \u00b6 Hint We recommend reading the Behavioral Features Introduction before reading this page Hint You won\u2019t have to deal with time zones, dates, times, data cleaning or preprocessing. The data that RAPIDS pipes to your feature extraction code is ready to process. New Features for Existing Sensors \u00b6 You can add new features to any existing sensors (see list below) by adding a new provider in three steps: Modify the config.yaml file Create a provider folder, script and function Implement your features extraction code As a tutorial, we will add a new provider for PHONE_ACCELEROMETER called VEGA that extracts feature1 , feature2 , feature3 in Python and that it requires a parameter from the user called MY_PARAMETER . Existing Sensors An existing sensor is any of the phone or Fitbit sensors with a configuration entry in config.yaml : Phone Accelerometer Phone Activity Recognition Phone Applications Foreground Phone Battery Phone Bluetooth Phone Calls Phone Conversation Phone Light Phone Locations Phone Messages Phone Screen Phone WiFI Connected Phone WiFI Visible Modify the config.yaml file \u00b6 In this step you need to add your provider configuration section under the relevant sensor in config.yaml . See our example for our tutorial\u2019s VEGA provider for PHONE_ACCELEROMETER : Example configuration for a new accelerometer provider VEGA PHONE_ACCELEROMETER : TABLE : accelerometer PROVIDERS : RAPIDS : COMPUTE : False ... PANDA : COMPUTE : False ... VEGA : COMPUTE : False FEATURES : [ \"feature1\" , \"feature2\" , \"feature3\" ] MY_PARAMTER : a_string SRC_FOLDER : \"vega\" SRC_LANGUAGE : \"python\" Key Description [COMPUTE] Flag to activate/deactivate your provider [FEATURES] List of features your provider supports. Your provider code should only return the features on this list [MY_PARAMTER] An arbitrary parameter that our example provider VEGA needs. This can be a boolean, integer, float, string or an array of any of such types. [SRC_LANGUAGE] The programming language of your provider script, it can be python or r , in our example python [SRC_FOLDER] The name of your provider in lower case, in our example vega (this will be the name of your folder in the next step) Create a provider folder, script and function \u00b6 In this step you need to add a folder, script and function for your provider. Create your provider folder under src/feature/DEVICE_SENSOR/YOUR_PROVIDER , in our example src/feature/phone_accelerometer/vega (same as [SRC_FOLDER] in the step above). Create your provider script inside your provider folder, it can be a Python file called main.py or an R file called main.R . Add your provider function in your provider script. The name of such function should be [providername]_features , in our example vega_features Python function def [ providername ] _features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): R function [ providername ] _ features <- function ( sensor_data , day_segment , provider ) Implement your feature extraction code \u00b6 The provider function that you created in the step above will receive the following parameters: Parameter Description sensor_data_files Path to the CSV file containing the data of a single participant. This data has been cleaned and preprocessed. Your function will be automatically called for each participant in your study (in the [PIDS] array in config.yaml ) day_segment The label of the day segment that should be processed. provider The parameters you configured for your provider in config.yaml will be available in this variable as a dictionary in Python or a list in R. In our example this dictionary contains {MY_PARAMETER:\"a_string\"} filter_data_by_segment Python only. A function that you will use to filter your data. In R this function is already available in the environment. *args Python only. Not used for now **kwargs Python only. Not used for now The code to extract your behavioral features should be implemented in your provider function and in general terms it will have three stages: 1. Read a participant\u2019s data by loading the CSV data stored in the file pointed by sensor_data_files acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) Note that phone\u2019s battery, screen, and activity recognition data is given as episodes instead of event rows (for example, start and end timestamps of the periods the phone screen was on) 2. Filter your data to process only those rows that belong to day_segment This step is only one line of code, but to undersand why we need it, keep reading. acc_data = filter_data_by_segment ( acc_data , day_segment ) You should use the filter_data_by_segment() function to process and group those rows that belong to each of the day segments RAPIDS could be configured with . Let\u2019s understand the filter_data_by_segment() function with an example. A RAPIDS user can extract features on any arbitrary day segment . A day segment is a period of time that has a label and one or more instances. For example, the user (or you) could have requested features on a daily, weekly, and week-end basis for p01 . The labels are arbritrary and the instances depend on the days a participant was monitored for: the daily segment could be named my_days and if p01 was monitored for 14 days, it would have 14 instances the weekly segment could be named my_weeks and if p01 was monitored for 14 days, it would have 2 instances. the weekend segment could be named my_weekends and if p01 was monitored for 14 days, it would have 2 instances. For this example, RAPIDS will call your provider function three times for p01 , once where day_segment is my_days , once where day_segment is my_weeks and once where day_segment is my_weekends . In this example not every row in p01 \u2018s data needs to take part in the feature computation for either segment and the rows need to be grouped differently. Thus filter_data_by_segment() comes in handy, it will return a data frame that contains the rows that were logged during a day segment plus an extra column called local_segment . This new column will have as many unique values as day segment instances exist (14, 2, and 2 for our p01 \u2018s my_days , my_weeks , and my_weekends examples). After filtering, you should group the data frame by this column and compute any desired features , for example: acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () The reason RAPIDS does not filter the participant\u2019s data set for you is because your code might need to compute something based on a participant\u2019s complete dataset before computing their features. For example, you might want to identify the number that called a participant the most throughout the study before computing a feature with the number of calls the participant received from this number. 3. Return a data frame with your features After filtering, grouping your data, and computing your features, your provider function should return a data frame that has: One row per day segment instance (e.g. 14 our p01 \u2018s my_days example) The local_segment column added by filter_data_by_segment() One column per feature. Your feature columns should be named SENSOR_PROVIDER_FEATURE , for example accelerometr_vega_feature1 PHONE_ACCELEROMETER Provider Example For your reference, this a short example of our own provider ( RAPIDS ) for PHONE_ACCELEROMETER that computes five acceleration features def rapids_features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) requested_features = provider [ \"FEATURES\" ] # name of the features this function can compute base_features_names = [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] # the subset of requested features this function can compute features_to_compute = list ( set ( requested_features ) & set ( base_features_names )) acc_features = pd . DataFrame ( columns = [ \"local_segment\" ] + [ \"acc_rapids_\" + x for x in features_to_compute ]) if not acc_data . empty : acc_data = filter_data_by_segment ( acc_data , day_segment ) if not acc_data . empty : acc_features = pd . DataFrame () # get magnitude related features: magnitude = sqrt(x^2+y^2+z^2) magnitude = acc_data . apply ( lambda row : np . sqrt ( row [ \"double_values_0\" ] ** 2 + row [ \"double_values_1\" ] ** 2 + row [ \"double_values_2\" ] ** 2 ), axis = 1 ) acc_data = acc_data . assign ( magnitude = magnitude . values ) if \"maxmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () if \"minmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_minmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . min () if \"avgmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_avgmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . mean () if \"medianmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_medianmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . median () if \"stdmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_stdmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . std () acc_features = acc_features . reset_index () return acc_features New Features for Non-Existing Sensors \u00b6 If you want to add features for a device or a sensor that we do not support at the moment (those that do not appear in the \"Existing Sensors\" list above), contact us or request it on Slack and we can add the necessary code so you can follow the instructions above.","title":"Add New Features"},{"location":"features/add-new-features/#add-new-features","text":"Hint We recommend reading the Behavioral Features Introduction before reading this page Hint You won\u2019t have to deal with time zones, dates, times, data cleaning or preprocessing. The data that RAPIDS pipes to your feature extraction code is ready to process.","title":"Add New Features"},{"location":"features/add-new-features/#new-features-for-existing-sensors","text":"You can add new features to any existing sensors (see list below) by adding a new provider in three steps: Modify the config.yaml file Create a provider folder, script and function Implement your features extraction code As a tutorial, we will add a new provider for PHONE_ACCELEROMETER called VEGA that extracts feature1 , feature2 , feature3 in Python and that it requires a parameter from the user called MY_PARAMETER . Existing Sensors An existing sensor is any of the phone or Fitbit sensors with a configuration entry in config.yaml : Phone Accelerometer Phone Activity Recognition Phone Applications Foreground Phone Battery Phone Bluetooth Phone Calls Phone Conversation Phone Light Phone Locations Phone Messages Phone Screen Phone WiFI Connected Phone WiFI Visible","title":"New Features for Existing Sensors"},{"location":"features/add-new-features/#modify-the-configyaml-file","text":"In this step you need to add your provider configuration section under the relevant sensor in config.yaml . See our example for our tutorial\u2019s VEGA provider for PHONE_ACCELEROMETER : Example configuration for a new accelerometer provider VEGA PHONE_ACCELEROMETER : TABLE : accelerometer PROVIDERS : RAPIDS : COMPUTE : False ... PANDA : COMPUTE : False ... VEGA : COMPUTE : False FEATURES : [ \"feature1\" , \"feature2\" , \"feature3\" ] MY_PARAMTER : a_string SRC_FOLDER : \"vega\" SRC_LANGUAGE : \"python\" Key Description [COMPUTE] Flag to activate/deactivate your provider [FEATURES] List of features your provider supports. Your provider code should only return the features on this list [MY_PARAMTER] An arbitrary parameter that our example provider VEGA needs. This can be a boolean, integer, float, string or an array of any of such types. [SRC_LANGUAGE] The programming language of your provider script, it can be python or r , in our example python [SRC_FOLDER] The name of your provider in lower case, in our example vega (this will be the name of your folder in the next step)","title":"Modify the config.yaml file"},{"location":"features/add-new-features/#create-a-provider-folder-script-and-function","text":"In this step you need to add a folder, script and function for your provider. Create your provider folder under src/feature/DEVICE_SENSOR/YOUR_PROVIDER , in our example src/feature/phone_accelerometer/vega (same as [SRC_FOLDER] in the step above). Create your provider script inside your provider folder, it can be a Python file called main.py or an R file called main.R . Add your provider function in your provider script. The name of such function should be [providername]_features , in our example vega_features Python function def [ providername ] _features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): R function [ providername ] _ features <- function ( sensor_data , day_segment , provider )","title":"Create a provider folder, script and function"},{"location":"features/add-new-features/#implement-your-feature-extraction-code","text":"The provider function that you created in the step above will receive the following parameters: Parameter Description sensor_data_files Path to the CSV file containing the data of a single participant. This data has been cleaned and preprocessed. Your function will be automatically called for each participant in your study (in the [PIDS] array in config.yaml ) day_segment The label of the day segment that should be processed. provider The parameters you configured for your provider in config.yaml will be available in this variable as a dictionary in Python or a list in R. In our example this dictionary contains {MY_PARAMETER:\"a_string\"} filter_data_by_segment Python only. A function that you will use to filter your data. In R this function is already available in the environment. *args Python only. Not used for now **kwargs Python only. Not used for now The code to extract your behavioral features should be implemented in your provider function and in general terms it will have three stages: 1. Read a participant\u2019s data by loading the CSV data stored in the file pointed by sensor_data_files acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) Note that phone\u2019s battery, screen, and activity recognition data is given as episodes instead of event rows (for example, start and end timestamps of the periods the phone screen was on) 2. Filter your data to process only those rows that belong to day_segment This step is only one line of code, but to undersand why we need it, keep reading. acc_data = filter_data_by_segment ( acc_data , day_segment ) You should use the filter_data_by_segment() function to process and group those rows that belong to each of the day segments RAPIDS could be configured with . Let\u2019s understand the filter_data_by_segment() function with an example. A RAPIDS user can extract features on any arbitrary day segment . A day segment is a period of time that has a label and one or more instances. For example, the user (or you) could have requested features on a daily, weekly, and week-end basis for p01 . The labels are arbritrary and the instances depend on the days a participant was monitored for: the daily segment could be named my_days and if p01 was monitored for 14 days, it would have 14 instances the weekly segment could be named my_weeks and if p01 was monitored for 14 days, it would have 2 instances. the weekend segment could be named my_weekends and if p01 was monitored for 14 days, it would have 2 instances. For this example, RAPIDS will call your provider function three times for p01 , once where day_segment is my_days , once where day_segment is my_weeks and once where day_segment is my_weekends . In this example not every row in p01 \u2018s data needs to take part in the feature computation for either segment and the rows need to be grouped differently. Thus filter_data_by_segment() comes in handy, it will return a data frame that contains the rows that were logged during a day segment plus an extra column called local_segment . This new column will have as many unique values as day segment instances exist (14, 2, and 2 for our p01 \u2018s my_days , my_weeks , and my_weekends examples). After filtering, you should group the data frame by this column and compute any desired features , for example: acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () The reason RAPIDS does not filter the participant\u2019s data set for you is because your code might need to compute something based on a participant\u2019s complete dataset before computing their features. For example, you might want to identify the number that called a participant the most throughout the study before computing a feature with the number of calls the participant received from this number. 3. Return a data frame with your features After filtering, grouping your data, and computing your features, your provider function should return a data frame that has: One row per day segment instance (e.g. 14 our p01 \u2018s my_days example) The local_segment column added by filter_data_by_segment() One column per feature. Your feature columns should be named SENSOR_PROVIDER_FEATURE , for example accelerometr_vega_feature1 PHONE_ACCELEROMETER Provider Example For your reference, this a short example of our own provider ( RAPIDS ) for PHONE_ACCELEROMETER that computes five acceleration features def rapids_features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) requested_features = provider [ \"FEATURES\" ] # name of the features this function can compute base_features_names = [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] # the subset of requested features this function can compute features_to_compute = list ( set ( requested_features ) & set ( base_features_names )) acc_features = pd . DataFrame ( columns = [ \"local_segment\" ] + [ \"acc_rapids_\" + x for x in features_to_compute ]) if not acc_data . empty : acc_data = filter_data_by_segment ( acc_data , day_segment ) if not acc_data . empty : acc_features = pd . DataFrame () # get magnitude related features: magnitude = sqrt(x^2+y^2+z^2) magnitude = acc_data . apply ( lambda row : np . sqrt ( row [ \"double_values_0\" ] ** 2 + row [ \"double_values_1\" ] ** 2 + row [ \"double_values_2\" ] ** 2 ), axis = 1 ) acc_data = acc_data . assign ( magnitude = magnitude . values ) if \"maxmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () if \"minmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_minmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . min () if \"avgmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_avgmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . mean () if \"medianmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_medianmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . median () if \"stdmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_stdmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . std () acc_features = acc_features . reset_index () return acc_features","title":"Implement your feature extraction code"},{"location":"features/add-new-features/#new-features-for-non-existing-sensors","text":"If you want to add features for a device or a sensor that we do not support at the moment (those that do not appear in the \"Existing Sensors\" list above), contact us or request it on Slack and we can add the necessary code so you can follow the instructions above.","title":"New Features for Non-Existing Sensors"},{"location":"features/feature-introduction/","text":"Behavioral Features Introduction \u00b6 Every phone or Fitbit sensor has a corresponding config section in config.yaml , these sections follow a similar structure and we\u2019ll use PHONE_ACCELEROMETER as an example to explain this structure. Hint We recommend reading this page if you are using RAPIDS for the first time Config section example for PHONE_ACCELEROMETER # 1) Config section PHONE_ACCELEROMETER : # 2) Parameters for PHONE_ACCELEROMETER TABLE : accelerometer # 3) Providers for PHONE_ACCELEROMETER PROVIDERS : # 4) RAPIDS provider RAPIDS : # 4.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False # 4.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] SRC_FOLDER : \"rapids\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\" # 5) PANDA provider PANDA : # 5.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False VALID_SENSED_MINUTES : False # 5.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : exertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] nonexertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] SRC_FOLDER : \"panda\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\" Sensor Parameters \u00b6 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 download, and processed. The TABLE parameter exists for every sensor, but some sensors will have extra para meters like [PHONE_LOCATIONS] . We explain these parameters in a table at the top of each sensor documentation page. Sensor Providers \u00b6 Each sensor configuration section can have zero, one or more behavioral feature providers (see #2 in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. For this accelerometer example we have two providers RAPIDS (see #4 ) and PANDA (see #5 ). Provider Parameters \u00b6 Each provider has parameters that affect the computation of the behavioral features it offers (see #4.1 or #5.1 in the example). These parameters will include at least a [COMPUTE] flag that you switch to True to extract a provider\u2019s behavioral features. We explain each provider parameter in a table under the Parameters description heading on each provider documentation page. Provider Features \u00b6 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\u2019s output feature file. We explain each behavioral feature in a table under the Features description heading on each provider documentation page. Hint Every time you change any sensor parameters, provider parameters or provider features, all the necessary files will be updated as soon as you execute RAPIDS.","title":"Introduction"},{"location":"features/feature-introduction/#behavioral-features-introduction","text":"Every phone or Fitbit sensor has a corresponding config section in config.yaml , these sections follow a similar structure and we\u2019ll use PHONE_ACCELEROMETER as an example to explain this structure. Hint We recommend reading this page if you are using RAPIDS for the first time Config section example for PHONE_ACCELEROMETER # 1) Config section PHONE_ACCELEROMETER : # 2) Parameters for PHONE_ACCELEROMETER TABLE : accelerometer # 3) Providers for PHONE_ACCELEROMETER PROVIDERS : # 4) RAPIDS provider RAPIDS : # 4.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False # 4.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] SRC_FOLDER : \"rapids\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\" # 5) PANDA provider PANDA : # 5.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False VALID_SENSED_MINUTES : False # 5.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : exertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] nonexertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] SRC_FOLDER : \"panda\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\"","title":"Behavioral Features Introduction"},{"location":"features/feature-introduction/#sensor-parameters","text":"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 download, and processed. The TABLE parameter exists for every sensor, but some sensors will have extra para meters like [PHONE_LOCATIONS] . We explain these parameters in a table at the top of each sensor documentation page.","title":"Sensor Parameters"},{"location":"features/feature-introduction/#sensor-providers","text":"Each sensor configuration section can have zero, one or more behavioral feature providers (see #2 in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. For this accelerometer example we have two providers RAPIDS (see #4 ) and PANDA (see #5 ).","title":"Sensor Providers"},{"location":"features/feature-introduction/#provider-parameters","text":"Each provider has parameters that affect the computation of the behavioral features it offers (see #4.1 or #5.1 in the example). These parameters will include at least a [COMPUTE] flag that you switch to True to extract a provider\u2019s behavioral features. We explain each provider parameter in a table under the Parameters description heading on each provider documentation page.","title":"Provider Parameters"},{"location":"features/feature-introduction/#provider-features","text":"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\u2019s output feature file. We explain each behavioral feature in a table under the Features description heading on each provider documentation page. Hint Every time you change any sensor parameters, provider parameters or provider features, all the necessary files will be updated as soon as you execute RAPIDS.","title":"Provider Features"},{"location":"features/phone-accelerometer/","text":"Phone Accelerometer \u00b6 Sensor parameters description for [PHONE_ACCELEROMETER] : Key Description [TABLE] Database table where the accelerometer data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Feature Units Description maxmagnitude m/s 2 The maximum magnitude of acceleration ( \\(\\|acceleration\\| = \\sqrt{x^2 + y^2 + z^2}\\) ). minmagnitude m/s 2 The minimum magnitude of acceleration. avgmagnitude m/s 2 The average magnitude of acceleration. medianmagnitude m/s 2 The median magnitude of acceleration. stdmagnitude m/s 2 The standard deviation of acceleration. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem. PANDA provider \u00b6 These features are based on the work by Panda et al . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the PANDA provider [FEATURES] Features to be computed for exertional and non-exertional activity episodes, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Feature Units Description sumduration minutes Total duration of all exertional or non-exertional activity episodes. maxduration minutes Longest duration of any exertional or non-exertional activity episode. minduration minutes Shortest duration of any exertional or non-exertional activity episode. avgduration minutes Average duration of any exertional or non-exertional activity episode. medianduration minutes Median duration of any exertional or non-exertional activity episode. stdduration minutes Standard deviation of the duration of all exertional or non-exertional activity episodes. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem. See Panda et al for a definition of exertional and non-exertional activity episodes","title":"Phone Accelerometer"},{"location":"features/phone-accelerometer/#phone-accelerometer","text":"Sensor parameters description for [PHONE_ACCELEROMETER] : Key Description [TABLE] Database table where the accelerometer data is stored","title":"Phone Accelerometer"},{"location":"features/phone-accelerometer/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Feature Units Description maxmagnitude m/s 2 The maximum magnitude of acceleration ( \\(\\|acceleration\\| = \\sqrt{x^2 + y^2 + z^2}\\) ). minmagnitude m/s 2 The minimum magnitude of acceleration. avgmagnitude m/s 2 The average magnitude of acceleration. medianmagnitude m/s 2 The median magnitude of acceleration. stdmagnitude m/s 2 The standard deviation of acceleration. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem.","title":"RAPIDS provider"},{"location":"features/phone-accelerometer/#panda-provider","text":"These features are based on the work by Panda et al . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the PANDA provider [FEATURES] Features to be computed for exertional and non-exertional activity episodes, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Feature Units Description sumduration minutes Total duration of all exertional or non-exertional activity episodes. maxduration minutes Longest duration of any exertional or non-exertional activity episode. minduration minutes Shortest duration of any exertional or non-exertional activity episode. avgduration minutes Average duration of any exertional or non-exertional activity episode. medianduration minutes Median duration of any exertional or non-exertional activity episode. stdduration minutes Standard deviation of the duration of all exertional or non-exertional activity episodes. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem. See Panda et al for a definition of exertional and non-exertional activity episodes","title":"PANDA provider"},{"location":"features/phone-activity-recognition/","text":"Phone Activity Recognition \u00b6 Sensor parameters description for [PHONE_ACTIVITY_RECOGNITION] : Key Description [TABLE][ANDROID] Database table where the activity data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the activity data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS) [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same activity episode RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_activity_recognition_raw.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime_unified.csv - data/interim/ { pid } /phone_activity_recognition_episodes.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_activity_recognition_features/phone_activity_recognition_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_activity_recognition.csv Parameters description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACTIVITY_RECOGNITION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [ACTIVITY_CLASSES][STATIONARY] An array of the activity labels to be considered in the STATIONARY category choose any of still , tilting [ACTIVITY_CLASSES][MOBILE] An array of the activity labels to be considered in the MOBILE category choose any of on_foot , walking , running , on_bicycle [ACTIVITY_CLASSES][VEHICLE] An array of the activity labels to be considered in the VEHICLE category choose any of in_vehicule Features description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Feature Units Description count rows Number of episodes. mostcommonactivity activity type The most common activity type (e.g. still , on_foot , etc.). If there is a tie, the first one is chosen. countuniqueactivities activity type Number of unique activities. durationstationary minutes The total duration of [ACTIVITY_CLASSES][STATIONARY] episodes durationmobile minutes The total duration of [ACTIVITY_CLASSES][MOBILE] episodes of on foot, running, and on bicycle activities durationvehicle minutes The total duration of [ACTIVITY_CLASSES][VEHICLE] episodes of on vehicle activity Assumptions/Observations iOS Activity Recognition names and types are unified with Android labels: iOS Activity Name Android Activity Name Android Activity Type walking walking 7 running running 8 cycling on_bicycle 1 automotive in_vehicle 0 stationary still 3 unknown unknown 4 In AWARE, Activity Recognition data for Android and iOS are stored in two different database tables, RAPIDS automatically infers what platform each participant belongs to based on their participant file .","title":"Phone Activity Recognition"},{"location":"features/phone-activity-recognition/#phone-activity-recognition","text":"Sensor parameters description for [PHONE_ACTIVITY_RECOGNITION] : Key Description [TABLE][ANDROID] Database table where the activity data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the activity data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS) [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same activity episode","title":"Phone Activity Recognition"},{"location":"features/phone-activity-recognition/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_activity_recognition_raw.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime_unified.csv - data/interim/ { pid } /phone_activity_recognition_episodes.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_activity_recognition_features/phone_activity_recognition_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_activity_recognition.csv Parameters description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACTIVITY_RECOGNITION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [ACTIVITY_CLASSES][STATIONARY] An array of the activity labels to be considered in the STATIONARY category choose any of still , tilting [ACTIVITY_CLASSES][MOBILE] An array of the activity labels to be considered in the MOBILE category choose any of on_foot , walking , running , on_bicycle [ACTIVITY_CLASSES][VEHICLE] An array of the activity labels to be considered in the VEHICLE category choose any of in_vehicule Features description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Feature Units Description count rows Number of episodes. mostcommonactivity activity type The most common activity type (e.g. still , on_foot , etc.). If there is a tie, the first one is chosen. countuniqueactivities activity type Number of unique activities. durationstationary minutes The total duration of [ACTIVITY_CLASSES][STATIONARY] episodes durationmobile minutes The total duration of [ACTIVITY_CLASSES][MOBILE] episodes of on foot, running, and on bicycle activities durationvehicle minutes The total duration of [ACTIVITY_CLASSES][VEHICLE] episodes of on vehicle activity Assumptions/Observations iOS Activity Recognition names and types are unified with Android labels: iOS Activity Name Android Activity Name Android Activity Type walking walking 7 running running 8 cycling on_bicycle 1 automotive in_vehicle 0 stationary still 3 unknown unknown 4 In AWARE, Activity Recognition data for Android and iOS are stored in two different database tables, RAPIDS automatically infers what platform each participant belongs to based on their participant file .","title":"RAPIDS provider"},{"location":"features/phone-applications-foreground/","text":"Phone Applications Foreground \u00b6 Sensor parameters description for [PHONE_APPLICATIONS_FOREGROUND] (these parameters are used by the only provider available at the moment, RAPIDS): Key Description [TABLE] Database table where the applications foreground data is stored [APPLICATION_CATEGORIES][CATALOGUE_SOURCE] FILE or GOOGLE . If FILE , app categories (genres) are read from [CATALOGUE_FILE] . If [GOOGLE] , app categories (genres) are scrapped from the Play Store [APPLICATION_CATEGORIES][CATALOGUE_FILE] CSV file with a package_name and genre column. By default we provide the catalogue created by Stachl et al in data/external/stachl_application_genre_catalogue.csv [APPLICATION_CATEGORIES][UPDATE_CATALOGUE_FILE] if [CATALOGUE_SOURCE] is equal to FILE , this flag signals whether or not to update [CATALOGUE_FILE] , if [CATALOGUE_SOURCE] is equal to GOOGLE all scraped genres will be saved to [CATALOGUE_FILE] [APPLICATION_CATEGORIES][SCRAPE_MISSING_CATEGORIES] This flag signals whether or not to scrape categories (genres) missing from the [CATALOGUE_FILE] . If [CATALOGUE_SOURCE] is equal to GOOGLE , all genres are scraped anyway (this flag is ignored) RAPIDS provider \u00b6 The app category (genre) catalogue used in these features was originally created by Stachl et al . Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_applications_foreground_raw.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime_with_categories.csv - data/interim/ { pid } /phone_applications_foreground_features/phone_applications_foreground_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_applications_foreground.csv Parameters description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_APPLICATIONS_FOREGROUND features from the RAPIDS provider [FEATURES] Features to be computed, see table below [SINGLE_CATEGORIES] An array of app categories to be included in the feature extraction computation. The special keyword all represents a category with all the apps from each participant. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [MULTIPLE_CATEGORIES] An array of collections representing meta-categories (a group of categories). They key of each element is the name of the meta-category and the value is an array of member app categories. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [SINGLE_APPS] An array of apps to be included in the feature extraction computation. Use their package name (e.g. com.google.android.youtube ) or the reserved keyword top1global (the most used app by a participant over the whole monitoring study) [EXCLUDED_CATEGORIES] An array of app categories to be excluded from the feature extraction computation. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [EXCLUDED_APPS] An array of apps to be excluded from the feature extraction computation. Use their package name, for example: com.google.android.youtube Features description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Feature Units Description count apps Number of times a single app or apps within a category were used (i.e. they were brought to the foreground either by tapping their icon or switching to it from another app) timeoffirstuse minutes The time in minutes between 12:00am (midnight) and the first use of a single app or apps within a category during a day_segment timeoflastuse minutes The time in minutes between 12:00am (midnight) and the last use of a single app or apps within a category during a day_segment frequencyentropy nats The entropy of the used apps within a category during a day_segment (each app is seen as a unique event, the more apps were used, the higher the entropy). This is especially relevant when computed over all apps. Entropy cannot be obtained for a single app Assumptions/Observations Features can be computed by app, by apps grouped under a single category (genre) and by multiple categories grouped together (meta-categories). For example, we can get features for Facebook (single app), for Social Network apps (a category including Facebook and other social media apps) or for Social (a meta-category formed by Social Network and Social Media Tools categories). Apps installed by default like YouTube are considered systems apps on some phones. We do an exact match to exclude apps where \u201cgenre\u201d == EXCLUDED_CATEGORIES or \u201cpackage_name\u201d == EXCLUDED_APPS . We provide three ways of classifying and app within a category (genre): a) by automatically scraping its official category from the Google Play Store, b) by using the catalogue created by Stachl et al. which we provide in RAPIDS ( data/external/stachl_application_genre_catalogue.csv ), or c) by manually creating a personalized catalogue. You can choose a, b or c by modifying [APPLICATION_GENRES] keys and values (see the Sensor parameters description table above).","title":"Phone Applications Foreground"},{"location":"features/phone-applications-foreground/#phone-applications-foreground","text":"Sensor parameters description for [PHONE_APPLICATIONS_FOREGROUND] (these parameters are used by the only provider available at the moment, RAPIDS): Key Description [TABLE] Database table where the applications foreground data is stored [APPLICATION_CATEGORIES][CATALOGUE_SOURCE] FILE or GOOGLE . If FILE , app categories (genres) are read from [CATALOGUE_FILE] . If [GOOGLE] , app categories (genres) are scrapped from the Play Store [APPLICATION_CATEGORIES][CATALOGUE_FILE] CSV file with a package_name and genre column. By default we provide the catalogue created by Stachl et al in data/external/stachl_application_genre_catalogue.csv [APPLICATION_CATEGORIES][UPDATE_CATALOGUE_FILE] if [CATALOGUE_SOURCE] is equal to FILE , this flag signals whether or not to update [CATALOGUE_FILE] , if [CATALOGUE_SOURCE] is equal to GOOGLE all scraped genres will be saved to [CATALOGUE_FILE] [APPLICATION_CATEGORIES][SCRAPE_MISSING_CATEGORIES] This flag signals whether or not to scrape categories (genres) missing from the [CATALOGUE_FILE] . If [CATALOGUE_SOURCE] is equal to GOOGLE , all genres are scraped anyway (this flag is ignored)","title":"Phone Applications Foreground"},{"location":"features/phone-applications-foreground/#rapids-provider","text":"The app category (genre) catalogue used in these features was originally created by Stachl et al . Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_applications_foreground_raw.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime_with_categories.csv - data/interim/ { pid } /phone_applications_foreground_features/phone_applications_foreground_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_applications_foreground.csv Parameters description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_APPLICATIONS_FOREGROUND features from the RAPIDS provider [FEATURES] Features to be computed, see table below [SINGLE_CATEGORIES] An array of app categories to be included in the feature extraction computation. The special keyword all represents a category with all the apps from each participant. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [MULTIPLE_CATEGORIES] An array of collections representing meta-categories (a group of categories). They key of each element is the name of the meta-category and the value is an array of member app categories. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [SINGLE_APPS] An array of apps to be included in the feature extraction computation. Use their package name (e.g. com.google.android.youtube ) or the reserved keyword top1global (the most used app by a participant over the whole monitoring study) [EXCLUDED_CATEGORIES] An array of app categories to be excluded from the feature extraction computation. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [EXCLUDED_APPS] An array of apps to be excluded from the feature extraction computation. Use their package name, for example: com.google.android.youtube Features description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Feature Units Description count apps Number of times a single app or apps within a category were used (i.e. they were brought to the foreground either by tapping their icon or switching to it from another app) timeoffirstuse minutes The time in minutes between 12:00am (midnight) and the first use of a single app or apps within a category during a day_segment timeoflastuse minutes The time in minutes between 12:00am (midnight) and the last use of a single app or apps within a category during a day_segment frequencyentropy nats The entropy of the used apps within a category during a day_segment (each app is seen as a unique event, the more apps were used, the higher the entropy). This is especially relevant when computed over all apps. Entropy cannot be obtained for a single app Assumptions/Observations Features can be computed by app, by apps grouped under a single category (genre) and by multiple categories grouped together (meta-categories). For example, we can get features for Facebook (single app), for Social Network apps (a category including Facebook and other social media apps) or for Social (a meta-category formed by Social Network and Social Media Tools categories). Apps installed by default like YouTube are considered systems apps on some phones. We do an exact match to exclude apps where \u201cgenre\u201d == EXCLUDED_CATEGORIES or \u201cpackage_name\u201d == EXCLUDED_APPS . We provide three ways of classifying and app within a category (genre): a) by automatically scraping its official category from the Google Play Store, b) by using the catalogue created by Stachl et al. which we provide in RAPIDS ( data/external/stachl_application_genre_catalogue.csv ), or c) by manually creating a personalized catalogue. You can choose a, b or c by modifying [APPLICATION_GENRES] keys and values (see the Sensor parameters description table above).","title":"RAPIDS provider"},{"location":"features/phone-battery/","text":"Phone Battery \u00b6 Sensor parameters description for [PHONE_BATTERY] : Key Description [TABLE] Database table where the battery data is stored [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same battery charge or discharge episode RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_battery_raw.csv - data/interim/ { pid } /phone_battery_episodes.csv - data/interim/ { pid } /phone_battery_episodes_resampled.csv - data/interim/ { pid } /phone_battery_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_battery_features/phone_battery_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_battery.csv Parameters description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BATTERY features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Feature Units Description countdischarge episodes Number of discharging episodes. sumdurationdischarge minutes The total duration of all discharging episodes. countcharge episodes Number of battery charging episodes. sumdurationcharge minutes The total duration of all charging episodes. avgconsumptionrate episodes/minutes The average of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration maxconsumptionrate episodes/minutes The highest of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration Assumptions/Observations We convert battery data collected with iOS client v1 (autodetected because battery status 4 do not exist) to match Android battery format: we swap status 3 for 5 and 1 for 3 We group battery data into discharge or charge episodes considering any contiguous rows with consecutive reductions or increases of the battery level if they are logged within [EPISODE_THRESHOLD_BETWEEN_ROWS] minutes from each other.","title":"Phone Battery"},{"location":"features/phone-battery/#phone-battery","text":"Sensor parameters description for [PHONE_BATTERY] : Key Description [TABLE] Database table where the battery data is stored [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same battery charge or discharge episode","title":"Phone Battery"},{"location":"features/phone-battery/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_battery_raw.csv - data/interim/ { pid } /phone_battery_episodes.csv - data/interim/ { pid } /phone_battery_episodes_resampled.csv - data/interim/ { pid } /phone_battery_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_battery_features/phone_battery_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_battery.csv Parameters description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BATTERY features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Feature Units Description countdischarge episodes Number of discharging episodes. sumdurationdischarge minutes The total duration of all discharging episodes. countcharge episodes Number of battery charging episodes. sumdurationcharge minutes The total duration of all charging episodes. avgconsumptionrate episodes/minutes The average of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration maxconsumptionrate episodes/minutes The highest of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration Assumptions/Observations We convert battery data collected with iOS client v1 (autodetected because battery status 4 do not exist) to match Android battery format: we swap status 3 for 5 and 1 for 3 We group battery data into discharge or charge episodes considering any contiguous rows with consecutive reductions or increases of the battery level if they are logged within [EPISODE_THRESHOLD_BETWEEN_ROWS] minutes from each other.","title":"RAPIDS provider"},{"location":"features/phone-bluetooth/","text":"Phone Bluetooth \u00b6 Sensor parameters description for [PHONE_BLUETOOTH] : Key Description [TABLE] Database table where the bluetooth data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_bluetooth_raw.csv - data/raw/ { pid } /phone_bluetooth_with_datetime.csv - data/interim/ { pid } /phone_bluetooth_features/phone_bluetooth_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_bluetooth.csv \" Parameters description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BLUETOOTH features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned devices during a day_segment , a device can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique devices during a day_segment as identified by their hardware ( bt_address ) address countscansmostuniquedevice scans Number of scans of the most scanned device during a day_segment across the whole monitoring period Assumptions/Observations NA","title":"Phone Bluetooth"},{"location":"features/phone-bluetooth/#phone-bluetooth","text":"Sensor parameters description for [PHONE_BLUETOOTH] : Key Description [TABLE] Database table where the bluetooth data is stored","title":"Phone Bluetooth"},{"location":"features/phone-bluetooth/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_bluetooth_raw.csv - data/raw/ { pid } /phone_bluetooth_with_datetime.csv - data/interim/ { pid } /phone_bluetooth_features/phone_bluetooth_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_bluetooth.csv \" Parameters description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BLUETOOTH features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned devices during a day_segment , a device can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique devices during a day_segment as identified by their hardware ( bt_address ) address countscansmostuniquedevice scans Number of scans of the most scanned device during a day_segment across the whole monitoring period Assumptions/Observations NA","title":"RAPIDS provider"},{"location":"features/phone-calls/","text":"Phone Calls \u00b6 Sensor parameters description for [PHONE_CALLS] : Key Description [TABLE] Database table where the calls data is stored RAPIDS Provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_calls_raw.csv - data/raw/ { pid } /phone_calls_with_datetime.csv - data/raw/ { pid } /phone_calls_with_datetime_unified.csv - data/interim/ { pid } /phone_calls_features/phone_calls_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_calls.csv Parameters description for [PHONE_CALLS][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CALLS features from the RAPIDS provider [CALL_TYPES] The particular call_type that will be analyzed. The options for this parameter are incoming, outgoing or missed. [FEATURES] Features to be computed for outgoing , incoming , and missed calls. Note that the same features are available for both incoming and outgoing calls, while missed calls has its own set of features. See the tables below. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] incoming and outgoing calls: Feature Units Description count calls Number of calls of a particular call_type occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular call_type for a particular day_segment meanduration seconds The mean duration of all calls of a particular call_type during a particular day_segment . sumduration seconds The sum of the duration of all calls of a particular call_type during a particular day_segment . minduration seconds The duration of the shortest call of a particular call_type during a particular day_segment . maxduration seconds The duration of the longest call of a particular call_type during a particular day_segment . stdduration seconds The standard deviation of the duration of all the calls of a particular call_type during a particular day_segment . modeduration seconds The mode of the duration of all the calls of a particular call_type during a particular day_segment . entropyduration nats The estimate of the Shannon entropy for the the duration of all the calls of a particular call_type during a particular day_segment . timefirstcall minutes The time in minutes between 12:00am (midnight) and the first call of call_type . timelastcall minutes The time in minutes between 12:00am (midnight) and the last call of call_type . countmostfrequentcontact calls The number of calls of a particular call_type during a particular day_segment of the most frequent contact throughout the monitored period. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] missed calls: Feature Units Description count calls Number of missed calls that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with missed calls for a particular day_segment timefirstcall minutes The time in hours from 12:00am (Midnight) that the first missed call occurred. timelastcall minutes The time in hours from 12:00am (Midnight) that the last missed call occurred. countmostfrequentcontact calls The number of missed calls during a particular day_segment of the most frequent contact throughout the monitored period. Assumptions/Observations Traces for iOS calls are unique even for the same contact calling a participant more than once which renders countmostfrequentcontact meaningless and distinctcontacts equal to the total number of traces. [CALL_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [CALL_TYPES] outgoing matches the [FEATURES] key outgoing iOS calls data is transformed to match Android calls data format. See our algorithm","title":"Phone Calls"},{"location":"features/phone-calls/#phone-calls","text":"Sensor parameters description for [PHONE_CALLS] : Key Description [TABLE] Database table where the calls data is stored","title":"Phone Calls"},{"location":"features/phone-calls/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_calls_raw.csv - data/raw/ { pid } /phone_calls_with_datetime.csv - data/raw/ { pid } /phone_calls_with_datetime_unified.csv - data/interim/ { pid } /phone_calls_features/phone_calls_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_calls.csv Parameters description for [PHONE_CALLS][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CALLS features from the RAPIDS provider [CALL_TYPES] The particular call_type that will be analyzed. The options for this parameter are incoming, outgoing or missed. [FEATURES] Features to be computed for outgoing , incoming , and missed calls. Note that the same features are available for both incoming and outgoing calls, while missed calls has its own set of features. See the tables below. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] incoming and outgoing calls: Feature Units Description count calls Number of calls of a particular call_type occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular call_type for a particular day_segment meanduration seconds The mean duration of all calls of a particular call_type during a particular day_segment . sumduration seconds The sum of the duration of all calls of a particular call_type during a particular day_segment . minduration seconds The duration of the shortest call of a particular call_type during a particular day_segment . maxduration seconds The duration of the longest call of a particular call_type during a particular day_segment . stdduration seconds The standard deviation of the duration of all the calls of a particular call_type during a particular day_segment . modeduration seconds The mode of the duration of all the calls of a particular call_type during a particular day_segment . entropyduration nats The estimate of the Shannon entropy for the the duration of all the calls of a particular call_type during a particular day_segment . timefirstcall minutes The time in minutes between 12:00am (midnight) and the first call of call_type . timelastcall minutes The time in minutes between 12:00am (midnight) and the last call of call_type . countmostfrequentcontact calls The number of calls of a particular call_type during a particular day_segment of the most frequent contact throughout the monitored period. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] missed calls: Feature Units Description count calls Number of missed calls that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with missed calls for a particular day_segment timefirstcall minutes The time in hours from 12:00am (Midnight) that the first missed call occurred. timelastcall minutes The time in hours from 12:00am (Midnight) that the last missed call occurred. countmostfrequentcontact calls The number of missed calls during a particular day_segment of the most frequent contact throughout the monitored period. Assumptions/Observations Traces for iOS calls are unique even for the same contact calling a participant more than once which renders countmostfrequentcontact meaningless and distinctcontacts equal to the total number of traces. [CALL_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [CALL_TYPES] outgoing matches the [FEATURES] key outgoing iOS calls data is transformed to match Android calls data format. See our algorithm","title":"RAPIDS Provider"},{"location":"features/phone-conversation/","text":"Phone Conversation \u00b6 Sensor parameters description for [PHONE_CONVERSATION] : Key Description [TABLE][ANDROID] Database table where the conversation data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the conversation data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS) RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_conversation_raw.csv - data/raw/ { pid } /phone_conversation_with_datetime.csv - data/raw/ { pid } /phone_conversation_with_datetime_unified.csv - data/interim/ { pid } /phone_conversation_features/phone_conversation_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_conversation.csv Parameters description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CONVERSATION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [RECORDING_MINUTES] Minutes the plugin was recording audio (default 1 min) [PAUSED_MINUTES] Minutes the plugin was NOT recording audio (default 3 min) Features description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Feature Units Description minutessilence minutes Minutes labeled as silence minutesnoise minutes Minutes labeled as noise minutesvoice minutes Minutes labeled as voice minutesunknown minutes Minutes labeled as unknown sumconversationduration minutes Total duration of all conversations maxconversationduration minutes Longest duration of all conversations minconversationduration minutes Shortest duration of all conversations avgconversationduration minutes Average duration of all conversations sdconversationduration minutes Standard Deviation of the duration of all conversations timefirstconversation minutes Minutes since midnight when the first conversation for a day segment was detected timelastconversation minutes Minutes since midnight when the last conversation for a day segment was detected noisesumenergy L2-norm Sum of all energy values when inference is noise noiseavgenergy L2-norm Average of all energy values when inference is noise noisesdenergy L2-norm Standard Deviation of all energy values when inference is noise noiseminenergy L2-norm Minimum of all energy values when inference is noise noisemaxenergy L2-norm Maximum of all energy values when inference is noise voicesumenergy L2-norm Sum of all energy values when inference is voice voiceavgenergy L2-norm Average of all energy values when inference is voice voicesdenergy L2-norm Standard Deviation of all energy values when inference is voice voiceminenergy L2-norm Minimum of all energy values when inference is voice voicemaxenergy L2-norm Maximum of all energy values when inference is voice silencesensedfraction - Ratio between minutessilence and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) noisesensedfraction - Ratio between minutesnoise and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) voicesensedfraction - Ratio between minutesvoice and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) unknownsensedfraction - Ratio between minutesunknown and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) silenceexpectedfraction - Ration between minutessilence and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) noiseexpectedfraction - Ration between minutesnoise and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) voiceexpectedfraction - Ration between minutesvoice and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) unknownexpectedfraction - Ration between minutesunknown and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) Assumptions/Observations The timestamp of conversation rows in iOS is in seconds so we convert it to milliseconds to match Android\u2019s format","title":"Phone Conversation"},{"location":"features/phone-conversation/#phone-conversation","text":"Sensor parameters description for [PHONE_CONVERSATION] : Key Description [TABLE][ANDROID] Database table where the conversation data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the conversation data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS)","title":"Phone Conversation"},{"location":"features/phone-conversation/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_conversation_raw.csv - data/raw/ { pid } /phone_conversation_with_datetime.csv - data/raw/ { pid } /phone_conversation_with_datetime_unified.csv - data/interim/ { pid } /phone_conversation_features/phone_conversation_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_conversation.csv Parameters description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CONVERSATION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [RECORDING_MINUTES] Minutes the plugin was recording audio (default 1 min) [PAUSED_MINUTES] Minutes the plugin was NOT recording audio (default 3 min) Features description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Feature Units Description minutessilence minutes Minutes labeled as silence minutesnoise minutes Minutes labeled as noise minutesvoice minutes Minutes labeled as voice minutesunknown minutes Minutes labeled as unknown sumconversationduration minutes Total duration of all conversations maxconversationduration minutes Longest duration of all conversations minconversationduration minutes Shortest duration of all conversations avgconversationduration minutes Average duration of all conversations sdconversationduration minutes Standard Deviation of the duration of all conversations timefirstconversation minutes Minutes since midnight when the first conversation for a day segment was detected timelastconversation minutes Minutes since midnight when the last conversation for a day segment was detected noisesumenergy L2-norm Sum of all energy values when inference is noise noiseavgenergy L2-norm Average of all energy values when inference is noise noisesdenergy L2-norm Standard Deviation of all energy values when inference is noise noiseminenergy L2-norm Minimum of all energy values when inference is noise noisemaxenergy L2-norm Maximum of all energy values when inference is noise voicesumenergy L2-norm Sum of all energy values when inference is voice voiceavgenergy L2-norm Average of all energy values when inference is voice voicesdenergy L2-norm Standard Deviation of all energy values when inference is voice voiceminenergy L2-norm Minimum of all energy values when inference is voice voicemaxenergy L2-norm Maximum of all energy values when inference is voice silencesensedfraction - Ratio between minutessilence and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) noisesensedfraction - Ratio between minutesnoise and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) voicesensedfraction - Ratio between minutesvoice and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) unknownsensedfraction - Ratio between minutesunknown and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) silenceexpectedfraction - Ration between minutessilence and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) noiseexpectedfraction - Ration between minutesnoise and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) voiceexpectedfraction - Ration between minutesvoice and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) unknownexpectedfraction - Ration between minutesunknown and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) Assumptions/Observations The timestamp of conversation rows in iOS is in seconds so we convert it to milliseconds to match Android\u2019s format","title":"RAPIDS provider"},{"location":"features/phone-data-quality/","text":"Phone Data Quality \u00b6 Phone Valid Sensed Bins \u00b6 A valid bin is any period of BIN_SIZE minutes starting from midnight with at least 1 row from any phone sensor. PHONE_VALID_SENSED_BINS are used to compute PHONE_VALID_SENSED_DAYS , to resample fused location data and to compute some screen features. Hint PHONE_VALID_SENSED_DAYS are an approximation to the time the phone was sensing data so add as many sensors as you have to [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] Parameters description for PHONE_VALID_SENSED_BINS : Key Description [COMPUTE] Set to True to compute [BIN_SIZE] Size of each bin in minutes [PHONE_SENSORS] One or more sensor config keys (e.g. PHONE_MESSAGE ) to be used to flag a bin as valid or not (whether or not a bin contains at least one row from any sensor) Possible values for [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] PHONE_MESSAGES PHONE_CALLS PHONE_LOCATIONS PHONE_BLUETOOTH PHONE_ACTIVITY_RECOGNITION PHONE_BATTERY PHONE_SCREEN PHONE_LIGHT PHONE_ACCELEROMETER PHONE_APPLICATIONS_FOREGROUND PHONE_WIFI_VISIBLE PHONE_WIFI_CONNECTED PHONE_CONVERSATION Phone Valid Sensed Days \u00b6 On any given day, a phone could have sensed data only for a few minutes or for 24 hours. Features should considered more reliable the more hours the phone was logging data, for example, 10 calls logged on a day when only 1 hour of data was recorded is a less reliable feature compared to 10 calls on a day when 23 hours of data were recorded. Therefore, we define a valid hour as those that contain a minimum number of valid bins (see above). We mark an hour as valid when contains at least MIN_VALID_BINS_PER_HOUR (out of 60min/ BIN_SIZE bins). In turn, we mark a day as valid if it has at least MIN_VALID_HOURS_PER_DAY . You can use PHONE_VALID_SENSED_DAYS to manually discard days when not enough data was collected after your features are computed. Parameters description for PHONE_VALID_SENSED_DAYS : Key Description [COMPUTE] Set to True to compute [MIN_VALID_BINS_PER_HOUR] An array of integer values, 6 by default. Minimum number of valid bins to mark an hour as valid [MIN_VALID_HOURS_PER_DAY] An array of integer values, 16 by default. Minimum number of valid hours to mark a day as valid","title":"Phone Data Quality"},{"location":"features/phone-data-quality/#phone-data-quality","text":"","title":"Phone Data Quality"},{"location":"features/phone-data-quality/#phone-valid-sensed-bins","text":"A valid bin is any period of BIN_SIZE minutes starting from midnight with at least 1 row from any phone sensor. PHONE_VALID_SENSED_BINS are used to compute PHONE_VALID_SENSED_DAYS , to resample fused location data and to compute some screen features. Hint PHONE_VALID_SENSED_DAYS are an approximation to the time the phone was sensing data so add as many sensors as you have to [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] Parameters description for PHONE_VALID_SENSED_BINS : Key Description [COMPUTE] Set to True to compute [BIN_SIZE] Size of each bin in minutes [PHONE_SENSORS] One or more sensor config keys (e.g. PHONE_MESSAGE ) to be used to flag a bin as valid or not (whether or not a bin contains at least one row from any sensor) Possible values for [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] PHONE_MESSAGES PHONE_CALLS PHONE_LOCATIONS PHONE_BLUETOOTH PHONE_ACTIVITY_RECOGNITION PHONE_BATTERY PHONE_SCREEN PHONE_LIGHT PHONE_ACCELEROMETER PHONE_APPLICATIONS_FOREGROUND PHONE_WIFI_VISIBLE PHONE_WIFI_CONNECTED PHONE_CONVERSATION","title":"Phone Valid Sensed Bins"},{"location":"features/phone-data-quality/#phone-valid-sensed-days","text":"On any given day, a phone could have sensed data only for a few minutes or for 24 hours. Features should considered more reliable the more hours the phone was logging data, for example, 10 calls logged on a day when only 1 hour of data was recorded is a less reliable feature compared to 10 calls on a day when 23 hours of data were recorded. Therefore, we define a valid hour as those that contain a minimum number of valid bins (see above). We mark an hour as valid when contains at least MIN_VALID_BINS_PER_HOUR (out of 60min/ BIN_SIZE bins). In turn, we mark a day as valid if it has at least MIN_VALID_HOURS_PER_DAY . You can use PHONE_VALID_SENSED_DAYS to manually discard days when not enough data was collected after your features are computed. Parameters description for PHONE_VALID_SENSED_DAYS : Key Description [COMPUTE] Set to True to compute [MIN_VALID_BINS_PER_HOUR] An array of integer values, 6 by default. Minimum number of valid bins to mark an hour as valid [MIN_VALID_HOURS_PER_DAY] An array of integer values, 16 by default. Minimum number of valid hours to mark a day as valid","title":"Phone Valid Sensed Days"},{"location":"features/phone-light/","text":"Phone Light \u00b6 Sensor parameters description for [PHONE_LIGHT] : Key Description [TABLE] Database table where the light data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_light_raw.csv - data/raw/ { pid } /phone_light_with_datetime.csv - data/interim/ { pid } /phone_light_features/phone_light_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_light.csv Parameters description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_LIGHT features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Feature Units Description count rows Number light sensor rows recorded. maxlux lux The maximum ambient luminance. minlux lux The minimum ambient luminance. avglux lux The average ambient luminance. medianlux lux The median ambient luminance. stdlux lux The standard deviation of ambient luminance. Assumptions/Observations NA","title":"Phone Light"},{"location":"features/phone-light/#phone-light","text":"Sensor parameters description for [PHONE_LIGHT] : Key Description [TABLE] Database table where the light data is stored","title":"Phone Light"},{"location":"features/phone-light/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_light_raw.csv - data/raw/ { pid } /phone_light_with_datetime.csv - data/interim/ { pid } /phone_light_features/phone_light_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_light.csv Parameters description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_LIGHT features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Feature Units Description count rows Number light sensor rows recorded. maxlux lux The maximum ambient luminance. minlux lux The minimum ambient luminance. avglux lux The average ambient luminance. medianlux lux The median ambient luminance. stdlux lux The standard deviation of ambient luminance. Assumptions/Observations NA","title":"RAPIDS provider"},{"location":"features/phone-locations/","text":"Phone Locations \u00b6 Sensor parameters description for [PHONE_LOCATIONS] : Key Description [TABLE] Database table where the location data is stored [LOCATIONS_TO_USE] Type of location data to use, one of ALL , GPS or FUSED_RESAMPLED . This filter is based on the provider column of the AWARE locations table, ALL includes every row, GPS only includes rows where provider is gps, and FUSED_RESAMPLED only includes rows where provider is fused after being resampled. [FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled to the next valid timestamp (see the Assumptions/Observations below) only if the time difference between them is less or equal than this threshold (in minutes). [FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled at most for this long (in minutes) Assumptions/Observations Types of location data to use AWARE Android and iOS clients can collect location coordinates through the phone's GPS, the network cellular towers around the phone or Google's fused location API. If you want to use only the GPS provider set [LOCATIONS_TO_USE] to GPS , if you want to use all providers (not recommended due to the difference in accuracy) set [LOCATIONS_TO_USE] to ALL , if your AWARE client was configured to use fused location only or want to focus only on this provider, set [LOCATIONS_TO_USE] to RESAMPLE_FUSED . RESAMPLE_FUSED takes the original fused location coordinates and replicates each pair forward in time as long as the phone was sensing data as indicated by PHONE_VALID_SENSED_BINS , this is done because Google's API only logs a new location coordinate pair when it is sufficiently different in time or space from the previous one. There are two parameters associated with resampling fused location. FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD (in minutes, default 30) controls the maximum gap between any two coordinate pairs to replicate the last known pair (for example, participant A's phone did not collect data between 10.30am and 10:50am and between 11:05am and 11:40am, the last known coordinate pair will be replicated during the first period but not the second, in other words, we assume that we cannot longer guarantee the participant stayed at the last known location if the phone did not sense data for more than 30 minutes). FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION (in minutes, default 720 or 12 hours) stops the last known fused location from being replicated longer that this threshold even if the phone was sensing data continuously (for example, participant A went home at 9pm and their phone was sensing data without gaps until 11am the next morning, the last known location will only be replicated until 9am). If you have suggestions to modify or improve this resampling, let us know. BARNETT provider \u00b6 These features are based on the original open-source implementation by Barnett et al and some features created by Canzian et al . Available day segments and platforms Available only for segments that start at 00:00:00 and end at 23:59:59 of the same day (daily segments) Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [ACCURACY_LIMIT] An integer in meters, any location rows with an accuracy higher than this will be dropped. This number means there\u2019s a 68% probability the true location is within this radius [TIMEZONE] Timezone where the location data was collected. By default points to the one defined in the Initial configuration [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] adapted from Beiwe Summary Statistics : Feature Units Description hometime minutes 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. disttravelled meters Total distance travelled over a day (flights). rog meters The Radius of Gyration (rog) 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 the places and that centroid is computed. The weights are proportional to the time spent in each place. maxdiam meters The maximum diameter is the largest distance between any two pauses. maxhomedist meters The maximum distance from home in meters. siglocsvisited 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 k from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another. avgflightlen meters Mean length of all flights. stdflightlen meters Standard deviation of the length of all flights. avgflightdur seconds Mean duration of all flights. stdflightdur seconds The standard deviation of the duration of all flights. probpause - The fraction of a day spent in a pause (as opposed to a flight) siglocentropy nats Shannon\u2019s entropy measurement based on the proportion of time spent at each significant location visited during a day. circdnrtn - A continuous metric quantifying a person\u2019s circadian routine 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. wkenddayrtn - Same as circdnrtn but computed separately for weekends and weekdays. Assumptions/Observations Barnett's et al features These features are based on a Pause-Flight model. A pause is defined as a mobiity trace (location pings) within a certain duration and distance (by default 300 seconds and 60 meters). A flight is any mobility trace between two pauses. Data is resampled and imputed before the features are computed. See Barnett et al for more information. In RAPIDS we only expose two parameters for these features (timezone and accuracy limit). You can change other parameters in src/features/phone_locations/barnett/library/MobilityFeatures.R . Significant Locations Significant locations are determined using K-means clustering on pauses longer than 10 minutes. The number of clusters (K) is increased until no two clusters are within 400 meters from each other. After this, pauses within a certain range of a cluster (200 meters by default) will count as a visit to that significant location. This description was adapted from the Supplementary Materials of Barnett et al . The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al . DORYAB provider \u00b6 These features are based on the original implementation by Doryab et al. . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [DBSCAN_EPS] The maximum distance in meters between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function. [DBSCAN_MINSAMPLES] The number of samples (or total weight) in a neighborhood for a point to be considered as a core point of a cluster. This includes the point itself. [THRESHOLD_STATIC] It is the threshold value in km/hr which labels a row as Static or Moving. [MAXIMUM_GAP_ALLOWED] The maximum gap (in seconds) allowed between any two consecutive rows for them to be considered part of the same displacement. If this threshold is too high, it can throw speed and distance calculations off for periods when the the phone was not sensing. [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. [SAMPLING_FREQUENCY] Expected time difference between any two location rows in minutes. If set to 0 , the sampling frequency will be inferred automatically as the median of all the differences between any two consecutive row timestamps (recommended if you are using FUSED_RESAMPLED data). This parameter impacts all the time calculations. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Feature Units Description locationvariance \\(meters^2\\) The sum of the variances of the latitude and longitude columns. loglocationvariance - Log of the sum of the variances of the latitude and longitude columns. totaldistance meters Total distance travelled in a day segment using the haversine formula. averagespeed km/hr Average speed in a day segment considering only the instances labeled as Moving. varspeed km/hr Speed variance in a day segment considering only the instances labeled as Moving. circadianmovement - \"It encodes the extent to which a person\u2019s location patterns follow a 24-hour circadian cycle.\" Doryab et al. . numberofsignificantplaces places Number of significant locations visited. It is calculated using the DBSCAN clustering algorithm which takes in EPS and MIN_SAMPLES as parameters to identify clusters. Each cluster is a significant place. numberlocationtransitions transitions Number of movements between any two clusters in a day segment. radiusgyration meters Quantifies the area covered by a participant timeattop1location minutes Time spent at the most significant location. timeattop2location minutes Time spent at the 2 nd most significant location. timeattop3location minutes Time spent at the 3 rd most significant location. movingtostaticratio - Ratio between the number of rows labeled Moving versus Static outlierstimepercent - Ratio between the number of rows that belong to non-significant clusters divided by the total number of rows in a day segment. maxlengthstayatclusters minutes Maximum time spent in a cluster (significant location). minlengthstayatclusters minutes Minimum time spent in a cluster (significant location). meanlengthstayatclusters minutes Average time spent in a cluster (significant location). stdlengthstayatclusters minutes Standard deviation of time spent in a cluster (significant location). locationentropy nats Shannon Entropy computed over the row count of each cluster (significant location), it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). normalizedlocationentropy nats Shannon Entropy computed over the row count of each cluster (significant location) divided by the number of clusters, it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). Assumptions/Observations Significant Locations Identified Significant locations are determined using DBSCAN clustering on locations that a patient visit over the course of the period of data collection. The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al .","title":"Phone Locations"},{"location":"features/phone-locations/#phone-locations","text":"Sensor parameters description for [PHONE_LOCATIONS] : Key Description [TABLE] Database table where the location data is stored [LOCATIONS_TO_USE] Type of location data to use, one of ALL , GPS or FUSED_RESAMPLED . This filter is based on the provider column of the AWARE locations table, ALL includes every row, GPS only includes rows where provider is gps, and FUSED_RESAMPLED only includes rows where provider is fused after being resampled. [FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled to the next valid timestamp (see the Assumptions/Observations below) only if the time difference between them is less or equal than this threshold (in minutes). [FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled at most for this long (in minutes) Assumptions/Observations Types of location data to use AWARE Android and iOS clients can collect location coordinates through the phone's GPS, the network cellular towers around the phone or Google's fused location API. If you want to use only the GPS provider set [LOCATIONS_TO_USE] to GPS , if you want to use all providers (not recommended due to the difference in accuracy) set [LOCATIONS_TO_USE] to ALL , if your AWARE client was configured to use fused location only or want to focus only on this provider, set [LOCATIONS_TO_USE] to RESAMPLE_FUSED . RESAMPLE_FUSED takes the original fused location coordinates and replicates each pair forward in time as long as the phone was sensing data as indicated by PHONE_VALID_SENSED_BINS , this is done because Google's API only logs a new location coordinate pair when it is sufficiently different in time or space from the previous one. There are two parameters associated with resampling fused location. FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD (in minutes, default 30) controls the maximum gap between any two coordinate pairs to replicate the last known pair (for example, participant A's phone did not collect data between 10.30am and 10:50am and between 11:05am and 11:40am, the last known coordinate pair will be replicated during the first period but not the second, in other words, we assume that we cannot longer guarantee the participant stayed at the last known location if the phone did not sense data for more than 30 minutes). FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION (in minutes, default 720 or 12 hours) stops the last known fused location from being replicated longer that this threshold even if the phone was sensing data continuously (for example, participant A went home at 9pm and their phone was sensing data without gaps until 11am the next morning, the last known location will only be replicated until 9am). If you have suggestions to modify or improve this resampling, let us know.","title":"Phone Locations"},{"location":"features/phone-locations/#barnett-provider","text":"These features are based on the original open-source implementation by Barnett et al and some features created by Canzian et al . Available day segments and platforms Available only for segments that start at 00:00:00 and end at 23:59:59 of the same day (daily segments) Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [ACCURACY_LIMIT] An integer in meters, any location rows with an accuracy higher than this will be dropped. This number means there\u2019s a 68% probability the true location is within this radius [TIMEZONE] Timezone where the location data was collected. By default points to the one defined in the Initial configuration [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] adapted from Beiwe Summary Statistics : Feature Units Description hometime minutes 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. disttravelled meters Total distance travelled over a day (flights). rog meters The Radius of Gyration (rog) 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 the places and that centroid is computed. The weights are proportional to the time spent in each place. maxdiam meters The maximum diameter is the largest distance between any two pauses. maxhomedist meters The maximum distance from home in meters. siglocsvisited 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 k from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another. avgflightlen meters Mean length of all flights. stdflightlen meters Standard deviation of the length of all flights. avgflightdur seconds Mean duration of all flights. stdflightdur seconds The standard deviation of the duration of all flights. probpause - The fraction of a day spent in a pause (as opposed to a flight) siglocentropy nats Shannon\u2019s entropy measurement based on the proportion of time spent at each significant location visited during a day. circdnrtn - A continuous metric quantifying a person\u2019s circadian routine 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. wkenddayrtn - Same as circdnrtn but computed separately for weekends and weekdays. Assumptions/Observations Barnett's et al features These features are based on a Pause-Flight model. A pause is defined as a mobiity trace (location pings) within a certain duration and distance (by default 300 seconds and 60 meters). A flight is any mobility trace between two pauses. Data is resampled and imputed before the features are computed. See Barnett et al for more information. In RAPIDS we only expose two parameters for these features (timezone and accuracy limit). You can change other parameters in src/features/phone_locations/barnett/library/MobilityFeatures.R . Significant Locations Significant locations are determined using K-means clustering on pauses longer than 10 minutes. The number of clusters (K) is increased until no two clusters are within 400 meters from each other. After this, pauses within a certain range of a cluster (200 meters by default) will count as a visit to that significant location. This description was adapted from the Supplementary Materials of Barnett et al . The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al .","title":"BARNETT provider"},{"location":"features/phone-locations/#doryab-provider","text":"These features are based on the original implementation by Doryab et al. . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [DBSCAN_EPS] The maximum distance in meters between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function. [DBSCAN_MINSAMPLES] The number of samples (or total weight) in a neighborhood for a point to be considered as a core point of a cluster. This includes the point itself. [THRESHOLD_STATIC] It is the threshold value in km/hr which labels a row as Static or Moving. [MAXIMUM_GAP_ALLOWED] The maximum gap (in seconds) allowed between any two consecutive rows for them to be considered part of the same displacement. If this threshold is too high, it can throw speed and distance calculations off for periods when the the phone was not sensing. [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. [SAMPLING_FREQUENCY] Expected time difference between any two location rows in minutes. If set to 0 , the sampling frequency will be inferred automatically as the median of all the differences between any two consecutive row timestamps (recommended if you are using FUSED_RESAMPLED data). This parameter impacts all the time calculations. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Feature Units Description locationvariance \\(meters^2\\) The sum of the variances of the latitude and longitude columns. loglocationvariance - Log of the sum of the variances of the latitude and longitude columns. totaldistance meters Total distance travelled in a day segment using the haversine formula. averagespeed km/hr Average speed in a day segment considering only the instances labeled as Moving. varspeed km/hr Speed variance in a day segment considering only the instances labeled as Moving. circadianmovement - \"It encodes the extent to which a person\u2019s location patterns follow a 24-hour circadian cycle.\" Doryab et al. . numberofsignificantplaces places Number of significant locations visited. It is calculated using the DBSCAN clustering algorithm which takes in EPS and MIN_SAMPLES as parameters to identify clusters. Each cluster is a significant place. numberlocationtransitions transitions Number of movements between any two clusters in a day segment. radiusgyration meters Quantifies the area covered by a participant timeattop1location minutes Time spent at the most significant location. timeattop2location minutes Time spent at the 2 nd most significant location. timeattop3location minutes Time spent at the 3 rd most significant location. movingtostaticratio - Ratio between the number of rows labeled Moving versus Static outlierstimepercent - Ratio between the number of rows that belong to non-significant clusters divided by the total number of rows in a day segment. maxlengthstayatclusters minutes Maximum time spent in a cluster (significant location). minlengthstayatclusters minutes Minimum time spent in a cluster (significant location). meanlengthstayatclusters minutes Average time spent in a cluster (significant location). stdlengthstayatclusters minutes Standard deviation of time spent in a cluster (significant location). locationentropy nats Shannon Entropy computed over the row count of each cluster (significant location), it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). normalizedlocationentropy nats Shannon Entropy computed over the row count of each cluster (significant location) divided by the number of clusters, it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). Assumptions/Observations Significant Locations Identified Significant locations are determined using DBSCAN clustering on locations that a patient visit over the course of the period of data collection. The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al .","title":"DORYAB provider"},{"location":"features/phone-messages/","text":"Phone Messages \u00b6 Sensor parameters description for [PHONE_MESSAGES] : Key Description [TABLE] Database table where the messages data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_messages_raw.csv - data/raw/ { pid } /phone_messages_with_datetime.csv - data/interim/ { pid } /phone_messages_features/phone_messages_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_messages.csv Parameters description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_MESSAGES features from the RAPIDS provider [MESSAGES_TYPES] The messages_type that will be analyzed. The options for this parameter are received or sent . [FEATURES] Features to be computed, see table below for [MESSAGES_TYPES] received and sent Features description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Feature Units Description count messages Number of messages of type messages_type that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular messages_type during a particular day_segment . timefirstmessages minutes Number of minutes between 12:00am (midnight) and the first message of a particular messages_type during a particular day_segment . timelastmessages minutes Number of minutes between 12:00am (midnight) and the last message of a particular messages_type during a particular day_segment . countmostfrequentcontact messages Number of messages from the contact with the most messages of messages_type during a day_segment throughout the whole dataset of each participant. Assumptions/Observations [MESSAGES_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [MESSAGES_TYPES] sent matches the [FEATURES] key sent","title":"Phone Messages"},{"location":"features/phone-messages/#phone-messages","text":"Sensor parameters description for [PHONE_MESSAGES] : Key Description [TABLE] Database table where the messages data is stored","title":"Phone Messages"},{"location":"features/phone-messages/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_messages_raw.csv - data/raw/ { pid } /phone_messages_with_datetime.csv - data/interim/ { pid } /phone_messages_features/phone_messages_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_messages.csv Parameters description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_MESSAGES features from the RAPIDS provider [MESSAGES_TYPES] The messages_type that will be analyzed. The options for this parameter are received or sent . [FEATURES] Features to be computed, see table below for [MESSAGES_TYPES] received and sent Features description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Feature Units Description count messages Number of messages of type messages_type that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular messages_type during a particular day_segment . timefirstmessages minutes Number of minutes between 12:00am (midnight) and the first message of a particular messages_type during a particular day_segment . timelastmessages minutes Number of minutes between 12:00am (midnight) and the last message of a particular messages_type during a particular day_segment . countmostfrequentcontact messages Number of messages from the contact with the most messages of messages_type during a day_segment throughout the whole dataset of each participant. Assumptions/Observations [MESSAGES_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [MESSAGES_TYPES] sent matches the [FEATURES] key sent","title":"RAPIDS provider"},{"location":"features/phone-screen/","text":"Phone Screen \u00b6 Sensor parameters description for [PHONE_SCREEN] : Key Description [TABLE] Database table where the screen data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - 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. Assumptions/Observations 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. 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. We transform iOS screen events to match Android\u2019s 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.","title":"Phone Screen"},{"location":"features/phone-screen/#phone-screen","text":"Sensor parameters description for [PHONE_SCREEN] : Key Description [TABLE] Database table where the screen data is stored","title":"Phone Screen"},{"location":"features/phone-screen/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - 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. Assumptions/Observations 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. 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. We transform iOS screen events to match Android\u2019s 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.","title":"RAPIDS provider"},{"location":"features/phone-wifi-connected/","text":"Phone WiFi Connected \u00b6 Sensor parameters description for [PHONE_WIFI_CONNECTED] : Key Description [TABLE] Database table where the wifi (connected) data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_wifi_connected_raw.csv - data/raw/ { pid } /phone_wifi_connected_with_datetime.csv - data/interim/ { pid } /phone_wifi_connected_features/phone_wifi_connected_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_connected.csv Parameters description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_CONNECTED features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points connected during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A connected WiFI access point is one that a phone was connected to. By default AWARE stores this data in the sensor_wifi table.","title":"Phone WiFI Connected"},{"location":"features/phone-wifi-connected/#phone-wifi-connected","text":"Sensor parameters description for [PHONE_WIFI_CONNECTED] : Key Description [TABLE] Database table where the wifi (connected) data is stored","title":"Phone WiFi Connected"},{"location":"features/phone-wifi-connected/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_wifi_connected_raw.csv - data/raw/ { pid } /phone_wifi_connected_with_datetime.csv - data/interim/ { pid } /phone_wifi_connected_features/phone_wifi_connected_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_connected.csv Parameters description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_CONNECTED features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points connected during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A connected WiFI access point is one that a phone was connected to. By default AWARE stores this data in the sensor_wifi table.","title":"RAPIDS provider"},{"location":"features/phone-wifi-visible/","text":"Phone WiFi Visible \u00b6 Sensor parameters description for [PHONE_WIFI_VISIBLE] : Key Description [TABLE] Database table where the wifi (visible) data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_wifi_visible_raw.csv - data/raw/ { pid } /phone_wifi_visible_with_datetime.csv - data/interim/ { pid } /phone_wifi_visible_features/phone_wifi_visible_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_visible.csv Parameters description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_VISIBLE features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points visible during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A visible WiFI access point is one that a phone sensed around itself but that it was not connected to. Due to API restrictions, this sensor is not available on iOS. By default AWARE stores this data in the wifi table.","title":"Phone WiFI Visible"},{"location":"features/phone-wifi-visible/#phone-wifi-visible","text":"Sensor parameters description for [PHONE_WIFI_VISIBLE] : Key Description [TABLE] Database table where the wifi (visible) data is stored","title":"Phone WiFi Visible"},{"location":"features/phone-wifi-visible/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_wifi_visible_raw.csv - data/raw/ { pid } /phone_wifi_visible_with_datetime.csv - data/interim/ { pid } /phone_wifi_visible_features/phone_wifi_visible_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_visible.csv Parameters description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_VISIBLE features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points visible during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A visible WiFI access point is one that a phone sensed around itself but that it was not connected to. Due to API restrictions, this sensor is not available on iOS. By default AWARE stores this data in the wifi table.","title":"RAPIDS provider"},{"location":"setup/configuration/","text":"Initial Configuration \u00b6 You need to follow these steps to configure your RAPIDS deployment before you can extract behavioral features Add your database credentials Choose the timezone of your study Create your participants files Select what day segments you want to extract features on Modify your device data source configuration Select what sensors and features you want to process When you are done with this initial configuration, go to executing RAPIDS . Hint Every time you see config[\"KEY\"] or [KEY] in these docs we are referring to the corresponding key in the config.yaml file. Database credentials \u00b6 Create an empty file called .env in your RAPIDS root directory Add the following lines and replace your database-specific credentials (user, password, host, and database): [ MY_GROUP ] user=MY_USER password=MY_PASSWORD host=MY_HOST port=3306 database=MY_DATABASE Warning The label MY_GROUP is arbitrary but it has to match the following config.yaml key: DATABASE_GROUP : &database_group MY_GROUP Note You can ignore this step if you are only processing Fitbit data in CSV files. Timezone of your study \u00b6 Single timezone \u00b6 If your study only happened in a single time zone, select the appropriate code form this list and change the following config key. Double check your timezone code pick, for example US Eastern Time is America/New_York not EST TIMEZONE : &timezone America/New_York Multiple timezones \u00b6 Support coming soon. Participant files \u00b6 Participant files link together multiple devices (smartphones and wearables) to specific participants and identify them throughout RAPIDS. You can create these files manually or automatically . Participant files are stored in data/external/participant_files/pxx.yaml and follow a unified structure . Note The list PIDS in config.yaml needs to have the participant file names of the people you want to process. For example, if you created p01.yaml , p02.yaml and p03.yaml files in /data/external/participant_files/ , then PIDS should be: PIDS : [ p01 , p02 , p03 ] Tip Attribute values of the [PHONE] and [FITBIT] sections in every participant file are optional which allows you to analyze data from participants that only carried smartphones, only Fitbit devices, or both. Optional: Migrating participants files with the old format If you were using the pre-release version of RAPIDS with participant files in plain text (as opposed to yaml), you can run the following command and your old files will be converted into yaml files stored in data/external/participant_files/ python tools/update_format_participant_files.py Structure of participants files \u00b6 Example of the structure of a participant file In this example, the participant used an android phone, an ios phone, and a fitbit device throughout the study between Apr 23 rd 2020 and Oct 28 th 2020 PHONE : DEVICE_IDS : [ a748ee1a-1d0b-4ae9-9074-279a2b6ba524 , dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43 ] PLATFORMS : [ android , ios ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 FITBIT : DEVICE_IDS : [ fitbit1 ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 For [PHONE] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each smartphone, you can have more than one for when participants changed phones in the middle of the study, in this case, data from all their devices will be joined and relabeled with the last 1 on this list. [PLATFORMS] An array that specifies the OS of each smartphone in [DEVICE_IDS] , use a combination of android or ios (we support participants that changed platforms in the middle of your study!). If you have an aware_device table in your database you can set [PLATFORMS]: [multiple] and RAPIDS will infer them automatically. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis For [FITBIT] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each Fitbit, you can have more than one in case the participant changed devices in the middle of the study, in this case, data from all devices will be joined and relabeled with the last device_id on this list. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis Automatic creation of participant files \u00b6 You have two options a) use the aware_device table in your database or b) use a CSV file. In either case, in your config.yaml , set [PHONE_SECTION][ADD] or [FITBIT_SECTION][ADD] to TRUE depending on what devices you used in your study. Set [DEVICE_ID_COLUMN] to the name of the column that uniquely identifies each device and include any device ids you want to ignore in [IGNORED_DEVICE_IDS] . aware_device table Set the following keys in your config.yaml CREATE_PARTICIPANT_FILES : SOURCE : TYPE : AWARE_DEVICE_TABLE DATABASE_GROUP : *database_group CSV_FILE_PATH : \"\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Then run snakemake -j1 create_participants_files CSV file Set the following keys in your config.yaml . CREATE_PARTICIPANT_FILES : SOURCE : TYPE : CSV_FILE DATABASE_GROUP : \"\" CSV_FILE_PATH : \"your_path/to_your.csv\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Your CSV file ( [SOURCE][CSV_FILE_PATH] ) should have the following columns but you can omit any values you don\u2019t have on each column: Column Description phone device id The name of this column has to match [PHONE_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; fitbit device id The name of this column has to match [FITBIT_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; pid Unique identifiers with the format pXXX (your participant files will be named with this string platform Use android , ios or multiple as explained above, separate values with ; label A human readable string that is used in reports and visualizations. start_date A string with format YYY-MM-DD . end_date A string with format YYY-MM-DD . Example device_id,pid,label,platform,start_date,end_date,fitbit_id a748ee1a-1d0b-4ae9-9074-279a2b6ba524;dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43,p01,julio,android;ios,2020-01-01,2021-01-01,fitbit1 4c4cf7a1-0340-44bc-be0f-d5053bf7390c,p02,meng,ios,2021-01-01,2022-01-01,fitbit2 Then run snakemake -j1 create_participants_files Day Segments \u00b6 Day segments (or epochs) are the time windows on which you want to extract behavioral features. For example, you might want to process data on every day, every morning, or only during weekends. RAPIDS offers three categories of day segments that are flexible enough to cover most use cases: frequency (short time windows every day), periodic (arbitrary time windows on any day), and event (arbitrary time windows around events of interest). See also our examples . Frequency Segments These segments are computed on every day and all have the same duration (for example 30 minutes). Set the following keys in your config.yaml DAY_SEGMENTS : &day_segments TYPE : FREQUENCY FILE : \"data/external/your_frequency_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can only have 1 row. Column Description label A string that is used as a prefix in the name of your day segments length An integer representing the duration of your day segments in minutes Example label,length thirtyminutes,30 This configuration will compute 48 day segments for every day when any data from any participant was sensed. For example: start_time,length,label 00:00,30,thirtyminutes0000 00:30,30,thirtyminutes0001 01:00,30,thirtyminutes0002 01:30,30,thirtyminutes0003 ... Periodic Segments These segments can be computed every day, or on specific days of the week, month, quarter, and year. Their minimum duration is 1 minute but they can be as long as you want. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : PERIODIC FILE : \"data/external/your_periodic_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE If [INCLUDE_PAST_PERIODIC_SEGMENTS] is set to TRUE , RAPIDS will consider instances of your segments back enough in the past as to include the first row of data of each participant. For example, if the first row of data from a participant happened on Saturday March 7 th 2020 and the requested segment duration is 7 days starting on every Sunday, the first segment to be considered would start on Sunday March 1 st if [INCLUDE_PAST_PERIODIC_SEGMENTS] is TRUE or on Sunday March 8 th if FALSE . The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. It has to be unique between rows start_time A string with format HH:MM:SS representing the starting time of this segment on any day length A string representing the length of this segment.It can have one or more of the following strings XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example 7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If you set repeats_on to every_day set this to 0 , otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 morning,06:00:00,5H 59M 59S,every_day,0 afternoon,12:00:00,5H 59M 59S,every_day,0 evening,18:00:00,5H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 This configuration will create five segments instances ( daily , morning , afternoon , evening , night ) on any given day ( every_day set to 0). The daily segment will start at midnight and will last 23:59:59 , the other four segments will start at 6am, 12pm, 6pm, and 12am respectively and last for 05:59:59 . Event segments These segments can be computed before or after an event of interest (defined as any UNIX timestamp). Their minimum duration is 1 minute but they can be as long as you want. The start of each segment can be shifted backwards or forwards from the specified timestamp. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : EVENT FILE : \"data/external/your_event_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. If labels are unique is segment is completely independent, if two segments have the same label their data will be considered together when computing features like the most frequent contact for calls (the most frequent contact will be computed across these segments) start_time A string with format HH:MM:SS representing the starting time of this segment length A string representing the length of this segment.It can have one or more of the following XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example `7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,event_timestamp,length,shift,shift_direction,device_id stress1,1587661220000,1H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress2,1587747620000,4H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress3,1587906020000,3H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress4,1584291600000,7H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress5,1588172420000,9H,5M,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587661220000,1H,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587747620000,1D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587906020000,7D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 This example will create eight segments for a single participant ( a748ee1a... ), five independent stressX segments with various lengths (1,4,3,7, and 9 hours). Segments stress1 , stress3 , and stress5 are shifted forwards by 5 minutes and stress2 and stress4 are shifted backwards by 4 hours (that is, if the stress4 event happened on March 15 th at 1pm EST ( 1584291600000 ), the day segment will start on that day at 9am and end at 4pm). The three mood segments are 1 hour, 1 day and 7 days long and have no shift. In addition, these mood segments are grouped together, meaning that although RAPIDS will compute features on each one of them, some necessary information to compute a few of such features will be extracted from all three segments, for example the phone contact that called a participant the most or the location clusters visited by a participant. Segment Examples \u00b6 Device Data Source Configuration \u00b6 You might need to modify the following config keys in your config.yaml depending on what devices your participants used and where you are storing your data. Hint You can ignore [DEVICE_DATA][PHONE] or [DEVICE_DATA][FITBIT] if you are not working with either devices. The relevant config.yaml section looks as follows by default: DEVICE_DATA : PHONE : SOURCE : TYPE : DATABASE DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : device_id # column name TIMEZONE : TYPE : SINGLE VALUE : *timezone FITBIT : SOURCE : TYPE : DATABASE # DATABASE or FILES (set each FITBIT_SENSOR TABLE attribute accordingly with a table name or a file path) DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : fitbit_id # column name TIMEZONE : TYPE : SINGLE # Fitbit only supports SINGLE timezones VALUE : *timezone For [DEVICE_DATA][PHONE] Key Description [SOURCE] [TYPE] Only DATABASE is supported (phone data will be pulled from a database) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify smartphones. For data collected with AWARE this is usually device_id [TIMEZONE] [TYPE] Only SINGLE is supported [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study For [DEVICE_DATA][FITBIT] Key Description [SOURCE] [TYPE] DATABASE or FILES (set each [FITBIT_SENSOR] [TABLE] attribute accordingly with a table name or a file path) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials . Only used if [TYPE] is DATABASE . [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify Fitbit devices. [TIMEZONE] [TYPE] Only SINGLE is supported (Fitbit devices always store data in local time). [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study Sensor and Features to Process \u00b6 Finally, you need to modify the config.yaml of the sensors you want to process. All sensors follow the same naming nomenclature DEVICE_SENSOR and have the following basic attributes (we will use PHONE_MESSAGES as an example). Hint Every time you change any sensor parameters, all the necessary files will be updated as soon as you execute RAPIDS. Some sensors will have specific attributes (like MESSAGES_TYPES ) so refer to each sensor documentation. PHONE_MESSAGES : TABLE : messages PROVIDERS : RAPIDS : COMPUTE : True MESSAGES_TYPES : [ received , sent ] FEATURES : received : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] sent : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] SRC_LANGUAGE : \"r\" SRC_FOLDER : \"rapids\" # inside src/features/phone_messages Key Description [TABLE] The name of the table in your database that stores this sensor data. [PROVIDERS] A collection of providers . A provider is an author or group of authors that created specific features for the sensor at hand. The provider for all the features implemented by our team is called RAPIDS but we have also included contributions from other researchers (for example DORYAB for location features). [PROVIDER] [COMPUTE] Set this to TRUE if you want to process features for this provider . [PROVIDER] [FEATURES] A list of all the features available for the provider . Delete those that you don\u2019t want to compute. [PROVIDER] [SRC_LANGUAGE] The programming language ( r or python ) in which the features of this provider are implemented. [PROVIDER] [SRC_FOLDER] The folder where the script(s) to compute the features of this provider are stored. This folder is always inside src/features/[DEVICE_SENSOR]/","title":"Initial Configuration"},{"location":"setup/configuration/#initial-configuration","text":"You need to follow these steps to configure your RAPIDS deployment before you can extract behavioral features Add your database credentials Choose the timezone of your study Create your participants files Select what day segments you want to extract features on Modify your device data source configuration Select what sensors and features you want to process When you are done with this initial configuration, go to executing RAPIDS . Hint Every time you see config[\"KEY\"] or [KEY] in these docs we are referring to the corresponding key in the config.yaml file.","title":"Initial Configuration"},{"location":"setup/configuration/#database-credentials","text":"Create an empty file called .env in your RAPIDS root directory Add the following lines and replace your database-specific credentials (user, password, host, and database): [ MY_GROUP ] user=MY_USER password=MY_PASSWORD host=MY_HOST port=3306 database=MY_DATABASE Warning The label MY_GROUP is arbitrary but it has to match the following config.yaml key: DATABASE_GROUP : &database_group MY_GROUP Note You can ignore this step if you are only processing Fitbit data in CSV files.","title":"Database credentials"},{"location":"setup/configuration/#timezone-of-your-study","text":"","title":"Timezone of your study"},{"location":"setup/configuration/#single-timezone","text":"If your study only happened in a single time zone, select the appropriate code form this list and change the following config key. Double check your timezone code pick, for example US Eastern Time is America/New_York not EST TIMEZONE : &timezone America/New_York","title":"Single timezone"},{"location":"setup/configuration/#multiple-timezones","text":"Support coming soon.","title":"Multiple timezones"},{"location":"setup/configuration/#participant-files","text":"Participant files link together multiple devices (smartphones and wearables) to specific participants and identify them throughout RAPIDS. You can create these files manually or automatically . Participant files are stored in data/external/participant_files/pxx.yaml and follow a unified structure . Note The list PIDS in config.yaml needs to have the participant file names of the people you want to process. For example, if you created p01.yaml , p02.yaml and p03.yaml files in /data/external/participant_files/ , then PIDS should be: PIDS : [ p01 , p02 , p03 ] Tip Attribute values of the [PHONE] and [FITBIT] sections in every participant file are optional which allows you to analyze data from participants that only carried smartphones, only Fitbit devices, or both. Optional: Migrating participants files with the old format If you were using the pre-release version of RAPIDS with participant files in plain text (as opposed to yaml), you can run the following command and your old files will be converted into yaml files stored in data/external/participant_files/ python tools/update_format_participant_files.py","title":"Participant files"},{"location":"setup/configuration/#structure-of-participants-files","text":"Example of the structure of a participant file In this example, the participant used an android phone, an ios phone, and a fitbit device throughout the study between Apr 23 rd 2020 and Oct 28 th 2020 PHONE : DEVICE_IDS : [ a748ee1a-1d0b-4ae9-9074-279a2b6ba524 , dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43 ] PLATFORMS : [ android , ios ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 FITBIT : DEVICE_IDS : [ fitbit1 ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 For [PHONE] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each smartphone, you can have more than one for when participants changed phones in the middle of the study, in this case, data from all their devices will be joined and relabeled with the last 1 on this list. [PLATFORMS] An array that specifies the OS of each smartphone in [DEVICE_IDS] , use a combination of android or ios (we support participants that changed platforms in the middle of your study!). If you have an aware_device table in your database you can set [PLATFORMS]: [multiple] and RAPIDS will infer them automatically. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis For [FITBIT] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each Fitbit, you can have more than one in case the participant changed devices in the middle of the study, in this case, data from all devices will be joined and relabeled with the last device_id on this list. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis","title":"Structure of participants files"},{"location":"setup/configuration/#automatic-creation-of-participant-files","text":"You have two options a) use the aware_device table in your database or b) use a CSV file. In either case, in your config.yaml , set [PHONE_SECTION][ADD] or [FITBIT_SECTION][ADD] to TRUE depending on what devices you used in your study. Set [DEVICE_ID_COLUMN] to the name of the column that uniquely identifies each device and include any device ids you want to ignore in [IGNORED_DEVICE_IDS] . aware_device table Set the following keys in your config.yaml CREATE_PARTICIPANT_FILES : SOURCE : TYPE : AWARE_DEVICE_TABLE DATABASE_GROUP : *database_group CSV_FILE_PATH : \"\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Then run snakemake -j1 create_participants_files CSV file Set the following keys in your config.yaml . CREATE_PARTICIPANT_FILES : SOURCE : TYPE : CSV_FILE DATABASE_GROUP : \"\" CSV_FILE_PATH : \"your_path/to_your.csv\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Your CSV file ( [SOURCE][CSV_FILE_PATH] ) should have the following columns but you can omit any values you don\u2019t have on each column: Column Description phone device id The name of this column has to match [PHONE_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; fitbit device id The name of this column has to match [FITBIT_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; pid Unique identifiers with the format pXXX (your participant files will be named with this string platform Use android , ios or multiple as explained above, separate values with ; label A human readable string that is used in reports and visualizations. start_date A string with format YYY-MM-DD . end_date A string with format YYY-MM-DD . Example device_id,pid,label,platform,start_date,end_date,fitbit_id a748ee1a-1d0b-4ae9-9074-279a2b6ba524;dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43,p01,julio,android;ios,2020-01-01,2021-01-01,fitbit1 4c4cf7a1-0340-44bc-be0f-d5053bf7390c,p02,meng,ios,2021-01-01,2022-01-01,fitbit2 Then run snakemake -j1 create_participants_files","title":"Automatic creation of participant files"},{"location":"setup/configuration/#day-segments","text":"Day segments (or epochs) are the time windows on which you want to extract behavioral features. For example, you might want to process data on every day, every morning, or only during weekends. RAPIDS offers three categories of day segments that are flexible enough to cover most use cases: frequency (short time windows every day), periodic (arbitrary time windows on any day), and event (arbitrary time windows around events of interest). See also our examples . Frequency Segments These segments are computed on every day and all have the same duration (for example 30 minutes). Set the following keys in your config.yaml DAY_SEGMENTS : &day_segments TYPE : FREQUENCY FILE : \"data/external/your_frequency_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can only have 1 row. Column Description label A string that is used as a prefix in the name of your day segments length An integer representing the duration of your day segments in minutes Example label,length thirtyminutes,30 This configuration will compute 48 day segments for every day when any data from any participant was sensed. For example: start_time,length,label 00:00,30,thirtyminutes0000 00:30,30,thirtyminutes0001 01:00,30,thirtyminutes0002 01:30,30,thirtyminutes0003 ... Periodic Segments These segments can be computed every day, or on specific days of the week, month, quarter, and year. Their minimum duration is 1 minute but they can be as long as you want. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : PERIODIC FILE : \"data/external/your_periodic_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE If [INCLUDE_PAST_PERIODIC_SEGMENTS] is set to TRUE , RAPIDS will consider instances of your segments back enough in the past as to include the first row of data of each participant. For example, if the first row of data from a participant happened on Saturday March 7 th 2020 and the requested segment duration is 7 days starting on every Sunday, the first segment to be considered would start on Sunday March 1 st if [INCLUDE_PAST_PERIODIC_SEGMENTS] is TRUE or on Sunday March 8 th if FALSE . The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. It has to be unique between rows start_time A string with format HH:MM:SS representing the starting time of this segment on any day length A string representing the length of this segment.It can have one or more of the following strings XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example 7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If you set repeats_on to every_day set this to 0 , otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 morning,06:00:00,5H 59M 59S,every_day,0 afternoon,12:00:00,5H 59M 59S,every_day,0 evening,18:00:00,5H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 This configuration will create five segments instances ( daily , morning , afternoon , evening , night ) on any given day ( every_day set to 0). The daily segment will start at midnight and will last 23:59:59 , the other four segments will start at 6am, 12pm, 6pm, and 12am respectively and last for 05:59:59 . Event segments These segments can be computed before or after an event of interest (defined as any UNIX timestamp). Their minimum duration is 1 minute but they can be as long as you want. The start of each segment can be shifted backwards or forwards from the specified timestamp. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : EVENT FILE : \"data/external/your_event_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. If labels are unique is segment is completely independent, if two segments have the same label their data will be considered together when computing features like the most frequent contact for calls (the most frequent contact will be computed across these segments) start_time A string with format HH:MM:SS representing the starting time of this segment length A string representing the length of this segment.It can have one or more of the following XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example `7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,event_timestamp,length,shift,shift_direction,device_id stress1,1587661220000,1H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress2,1587747620000,4H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress3,1587906020000,3H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress4,1584291600000,7H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress5,1588172420000,9H,5M,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587661220000,1H,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587747620000,1D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587906020000,7D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 This example will create eight segments for a single participant ( a748ee1a... ), five independent stressX segments with various lengths (1,4,3,7, and 9 hours). Segments stress1 , stress3 , and stress5 are shifted forwards by 5 minutes and stress2 and stress4 are shifted backwards by 4 hours (that is, if the stress4 event happened on March 15 th at 1pm EST ( 1584291600000 ), the day segment will start on that day at 9am and end at 4pm). The three mood segments are 1 hour, 1 day and 7 days long and have no shift. In addition, these mood segments are grouped together, meaning that although RAPIDS will compute features on each one of them, some necessary information to compute a few of such features will be extracted from all three segments, for example the phone contact that called a participant the most or the location clusters visited by a participant.","title":"Day Segments"},{"location":"setup/configuration/#segment-examples","text":"","title":"Segment Examples"},{"location":"setup/configuration/#device-data-source-configuration","text":"You might need to modify the following config keys in your config.yaml depending on what devices your participants used and where you are storing your data. Hint You can ignore [DEVICE_DATA][PHONE] or [DEVICE_DATA][FITBIT] if you are not working with either devices. The relevant config.yaml section looks as follows by default: DEVICE_DATA : PHONE : SOURCE : TYPE : DATABASE DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : device_id # column name TIMEZONE : TYPE : SINGLE VALUE : *timezone FITBIT : SOURCE : TYPE : DATABASE # DATABASE or FILES (set each FITBIT_SENSOR TABLE attribute accordingly with a table name or a file path) DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : fitbit_id # column name TIMEZONE : TYPE : SINGLE # Fitbit only supports SINGLE timezones VALUE : *timezone For [DEVICE_DATA][PHONE] Key Description [SOURCE] [TYPE] Only DATABASE is supported (phone data will be pulled from a database) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify smartphones. For data collected with AWARE this is usually device_id [TIMEZONE] [TYPE] Only SINGLE is supported [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study For [DEVICE_DATA][FITBIT] Key Description [SOURCE] [TYPE] DATABASE or FILES (set each [FITBIT_SENSOR] [TABLE] attribute accordingly with a table name or a file path) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials . Only used if [TYPE] is DATABASE . [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify Fitbit devices. [TIMEZONE] [TYPE] Only SINGLE is supported (Fitbit devices always store data in local time). [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study","title":"Device Data Source Configuration"},{"location":"setup/configuration/#sensor-and-features-to-process","text":"Finally, you need to modify the config.yaml of the sensors you want to process. All sensors follow the same naming nomenclature DEVICE_SENSOR and have the following basic attributes (we will use PHONE_MESSAGES as an example). Hint Every time you change any sensor parameters, all the necessary files will be updated as soon as you execute RAPIDS. Some sensors will have specific attributes (like MESSAGES_TYPES ) so refer to each sensor documentation. PHONE_MESSAGES : TABLE : messages PROVIDERS : RAPIDS : COMPUTE : True MESSAGES_TYPES : [ received , sent ] FEATURES : received : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] sent : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] SRC_LANGUAGE : \"r\" SRC_FOLDER : \"rapids\" # inside src/features/phone_messages Key Description [TABLE] The name of the table in your database that stores this sensor data. [PROVIDERS] A collection of providers . A provider is an author or group of authors that created specific features for the sensor at hand. The provider for all the features implemented by our team is called RAPIDS but we have also included contributions from other researchers (for example DORYAB for location features). [PROVIDER] [COMPUTE] Set this to TRUE if you want to process features for this provider . [PROVIDER] [FEATURES] A list of all the features available for the provider . Delete those that you don\u2019t want to compute. [PROVIDER] [SRC_LANGUAGE] The programming language ( r or python ) in which the features of this provider are implemented. [PROVIDER] [SRC_FOLDER] The folder where the script(s) to compute the features of this provider are stored. This folder is always inside src/features/[DEVICE_SENSOR]/","title":"Sensor and Features to Process"},{"location":"setup/execution/","text":"Execution \u00b6 After you have installed and configured RAPIDS, use the following command to execute it. ./rapids -j1 Info The script ./rapids is a wrapper around Snakemake so you can pass any parameters that Snakemake accepts (e.g. -j1 ). Updating RAPIDS output after modifying config.yaml Any changes to the config.yaml file will be applied automatically and only the relevant files will be updated. This means that after modifying the features list for PHONE_MESSAGE for example, RAPIDS will update the output file with the correct features. Multi-core You can run RAPIDS over multiple cores by modifying the -j argument (e.g. use -j8 to use 8 cores). However , take into account that this means multiple sensor datasets for different participants will be load in memory at the same time. If RAPIDS crashes because it ran out of memory reduce the number of cores and try again. As reference, we have run RAPIDS over 12 cores and 32 Gb of RAM without problems for a study with 200 participants with 14 days of low-frequency smartphone data (no accelerometer, gyroscope, or magnetometer). Forcing a complete rerun If you want to update your data from your database or rerun the whole pipeline from scratch run one or both of the following commands depending on the devices you are using: ./rapids -j1 -R download_phone_data ./rapids -j1 -R download_fitbit_data Deleting RAPIDS output If you want to delete all the output files RAPIDS produces you can execute the following command (the content of these folders will be deleted: data/raw , data/interim , data/processed , reports/figures , and reports/compliance ) ./rapids -j1 -R clean Ready to extract behavioral features If you are ready to extract features head over to the Behavioral Features Introduction","title":"Execution"},{"location":"setup/execution/#execution","text":"After you have installed and configured RAPIDS, use the following command to execute it. ./rapids -j1 Info The script ./rapids is a wrapper around Snakemake so you can pass any parameters that Snakemake accepts (e.g. -j1 ). Updating RAPIDS output after modifying config.yaml Any changes to the config.yaml file will be applied automatically and only the relevant files will be updated. This means that after modifying the features list for PHONE_MESSAGE for example, RAPIDS will update the output file with the correct features. Multi-core You can run RAPIDS over multiple cores by modifying the -j argument (e.g. use -j8 to use 8 cores). However , take into account that this means multiple sensor datasets for different participants will be load in memory at the same time. If RAPIDS crashes because it ran out of memory reduce the number of cores and try again. As reference, we have run RAPIDS over 12 cores and 32 Gb of RAM without problems for a study with 200 participants with 14 days of low-frequency smartphone data (no accelerometer, gyroscope, or magnetometer). Forcing a complete rerun If you want to update your data from your database or rerun the whole pipeline from scratch run one or both of the following commands depending on the devices you are using: ./rapids -j1 -R download_phone_data ./rapids -j1 -R download_fitbit_data Deleting RAPIDS output If you want to delete all the output files RAPIDS produces you can execute the following command (the content of these folders will be deleted: data/raw , data/interim , data/processed , reports/figures , and reports/compliance ) ./rapids -j1 -R clean Ready to extract behavioral features If you are ready to extract features head over to the Behavioral Features Introduction","title":"Execution"},{"location":"setup/installation/","text":"Installation \u00b6 You can install RAPIDS using Docker (the fastest), or native instructions for MacOS and Ubuntu Docker Install Docker Pull our RAPIDS container docker pull agamk/rapids:latest ` Run RAPIDS' container (after this step is done you should see a prompt in the main RAPIDS folder with its python environment active) docker run -it agamk/rapids:latest Pull the latest version of RAPIDS git pull Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Optional . You can edit RAPIDS files with vim but we recommend using Visual Studio Code and its Remote Containers extension How to configure Remote Containers extension Make sure RAPIDS container is running Install the Remote - Containers extension Go to the Remote Explorer panel on the left hand sidebar On the top right dropdown menu choose Containers Double click on the agamk/rapids container in the CONTAINERS tree A new VS Code session should open on RAPIDS main folder insidethe container. MacOS We tested these instructions in Catalina Install brew Install MySQL brew install mysql brew services start mysql Install R 4.0, pandoc and rmarkdown. If you have other instances of R, we recommend uninstalling them brew install r brew install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install miniconda (restart your terminal afterwards) brew cask install miniconda conda init zsh # (or conda init bash) Clone our repo git clone https://github.com/carissalow/rapids Create a python virtual environment cd rapids conda env create -f environment.yml -n rapids conda activate rapids Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Ubuntu We tested on Ubuntu 18.04 & 20.04 Install dependencies sudo apt install libcurl4-openssl-dev sudo apt install libssl-dev sudo apt install libxml2-dev Install MySQL sudo apt install libmysqlclient-dev sudo apt install mysql-server Add key for R\u2019s repository. sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9 Add R\u2019s repository For 18.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu bionic-cran40/' For 20.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu focal-cran40/' Install R 4.0. If you have other instances of R, we recommend uninstalling them sudo apt update sudo apt install r-base Install Pandoc and rmarkdown sudo apt install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install git sudo apt install git Install miniconda Restart your current shell Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1","title":"Installation"},{"location":"setup/installation/#installation","text":"You can install RAPIDS using Docker (the fastest), or native instructions for MacOS and Ubuntu Docker Install Docker Pull our RAPIDS container docker pull agamk/rapids:latest ` Run RAPIDS' container (after this step is done you should see a prompt in the main RAPIDS folder with its python environment active) docker run -it agamk/rapids:latest Pull the latest version of RAPIDS git pull Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Optional . You can edit RAPIDS files with vim but we recommend using Visual Studio Code and its Remote Containers extension How to configure Remote Containers extension Make sure RAPIDS container is running Install the Remote - Containers extension Go to the Remote Explorer panel on the left hand sidebar On the top right dropdown menu choose Containers Double click on the agamk/rapids container in the CONTAINERS tree A new VS Code session should open on RAPIDS main folder insidethe container. MacOS We tested these instructions in Catalina Install brew Install MySQL brew install mysql brew services start mysql Install R 4.0, pandoc and rmarkdown. If you have other instances of R, we recommend uninstalling them brew install r brew install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install miniconda (restart your terminal afterwards) brew cask install miniconda conda init zsh # (or conda init bash) Clone our repo git clone https://github.com/carissalow/rapids Create a python virtual environment cd rapids conda env create -f environment.yml -n rapids conda activate rapids Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Ubuntu We tested on Ubuntu 18.04 & 20.04 Install dependencies sudo apt install libcurl4-openssl-dev sudo apt install libssl-dev sudo apt install libxml2-dev Install MySQL sudo apt install libmysqlclient-dev sudo apt install mysql-server Add key for R\u2019s repository. sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9 Add R\u2019s repository For 18.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu bionic-cran40/' For 20.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu focal-cran40/' Install R 4.0. If you have other instances of R, we recommend uninstalling them sudo apt update sudo apt install r-base Install Pandoc and rmarkdown sudo apt install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install git sudo apt install git Install miniconda Restart your current shell Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1","title":"Installation"},{"location":"workflow-examples/minimal/","text":"Minimal Working Example \u00b6 This is a quick guide for creating and running a simple pipeline to extract missing, outgoing, and incoming call features for daily and night epochs of one participant monitored on the US East coast. Install RAPIDS and make sure your conda environment is active (see Installation ) For the Initial Configuration steps do the following and use the example as a guide: Things to change on each configuration step 1. Setup your database connection credentials in .env . We assume your credentials group is called MY_GROUP . 2. America/New_York should be the default timezone 3. Create a participant file p01.yaml based on one of your participants and add p01 to [PIDS] in config.yaml 4. [DAY_SEGMENTS][TYPE] should be the default PERIODIC . Change [DAY_SEGMENTS][FILE] with the path of a file containing the following lines: label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 5. If you collected data with AWARE you won\u2019t need to modify the attributes of [DEVICE_DATA][PHONE] 6. Set [PHONE_CALLS][PROVIDERS][RAPIDS][COMPUTE] to True Example of the config.yaml sections after the changes outlined above PIDS: [p01] TIMEZONE: &timezone America/New_York DATABASE_GROUP: &database_group MY_GROUP # ... other irrelevant sections DAY_SEGMENTS: &day_segments TYPE: PERIODIC FILE: \"data/external/daysegments_periodic.csv\" # make sure the three lines specified above are in the file INCLUDE_PAST_PERIODIC_SEGMENTS: FALSE # No need to change this if you collected AWARE data on a database and your credentials are grouped under `MY_GROUP` in `.env` DEVICE_DATA: PHONE: SOURCE: TYPE: DATABASE DATABASE_GROUP: *database_group DEVICE_ID_COLUMN: device_id # column name TIMEZONE: TYPE: SINGLE # SINGLE or MULTIPLE VALUE: *timezone ############## PHONE ########################################################### ################################################################################ .... # Communication call features config, TYPES and FEATURES keys need to match PHONE_CALLS: TABLE: calls # change if your calls table has a different name PROVIDERS: RAPIDS: COMPUTE: True # set this to True! CALL_TYPES: ... Run RAPIDS ./rapids -j1 The call features for daily and morning day segments will be in /data/processed/features/p01/phone_calls.csv","title":"Minimal"},{"location":"workflow-examples/minimal/#minimal-working-example","text":"This is a quick guide for creating and running a simple pipeline to extract missing, outgoing, and incoming call features for daily and night epochs of one participant monitored on the US East coast. Install RAPIDS and make sure your conda environment is active (see Installation ) For the Initial Configuration steps do the following and use the example as a guide: Things to change on each configuration step 1. Setup your database connection credentials in .env . We assume your credentials group is called MY_GROUP . 2. America/New_York should be the default timezone 3. Create a participant file p01.yaml based on one of your participants and add p01 to [PIDS] in config.yaml 4. [DAY_SEGMENTS][TYPE] should be the default PERIODIC . Change [DAY_SEGMENTS][FILE] with the path of a file containing the following lines: label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 5. If you collected data with AWARE you won\u2019t need to modify the attributes of [DEVICE_DATA][PHONE] 6. Set [PHONE_CALLS][PROVIDERS][RAPIDS][COMPUTE] to True Example of the config.yaml sections after the changes outlined above PIDS: [p01] TIMEZONE: &timezone America/New_York DATABASE_GROUP: &database_group MY_GROUP # ... other irrelevant sections DAY_SEGMENTS: &day_segments TYPE: PERIODIC FILE: \"data/external/daysegments_periodic.csv\" # make sure the three lines specified above are in the file INCLUDE_PAST_PERIODIC_SEGMENTS: FALSE # No need to change this if you collected AWARE data on a database and your credentials are grouped under `MY_GROUP` in `.env` DEVICE_DATA: PHONE: SOURCE: TYPE: DATABASE DATABASE_GROUP: *database_group DEVICE_ID_COLUMN: device_id # column name TIMEZONE: TYPE: SINGLE # SINGLE or MULTIPLE VALUE: *timezone ############## PHONE ########################################################### ################################################################################ .... # Communication call features config, TYPES and FEATURES keys need to match PHONE_CALLS: TABLE: calls # change if your calls table has a different name PROVIDERS: RAPIDS: COMPUTE: True # set this to True! CALL_TYPES: ... Run RAPIDS ./rapids -j1 The call features for daily and morning day segments will be in /data/processed/features/p01/phone_calls.csv","title":"Minimal Working Example"}]}
\ No newline at end of file
diff --git a/0.1/setup/configuration/index.html b/0.1/setup/configuration/index.html
new file mode 100644
index 00000000..5d3570aa
--- /dev/null
+++ b/0.1/setup/configuration/index.html
@@ -0,0 +1,1645 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Initial Configuration - RAPIDS
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
If your study only happened in a single time zone, select the appropriate code form this list and change the following config key. Double check your timezone code pick, for example US Eastern Time is America/New_York not EST
Participant files link together multiple devices (smartphones and wearables) to specific participants and identify them throughout RAPIDS. You can create these files manually or automatically. Participant files are stored in data/external/participant_files/pxx.yaml and follow a unified structure.
+
+
Note
+
The list PIDS in config.yaml needs to have the participant file names of the people you want to process. For example, if you created p01.yaml, p02.yaml and p03.yaml files in /data/external/participant_files/, then PIDS should be:
+
PIDS:[p01,p02,p03]
+
+
+
+
Tip
+
Attribute values of the [PHONE] and [FITBIT] sections in every participant file are optional which allows you to analyze data from participants that only carried smartphones, only Fitbit devices, or both.
+
+Optional: Migrating participants files with the old format
If you were using the pre-release version of RAPIDS with participant files in plain text (as opposed to yaml), you can run the following command and your old files will be converted into yaml files stored in data/external/participant_files/
An array of the strings that uniquely identify each smartphone, you can have more than one for when participants changed phones in the middle of the study, in this case, data from all their devices will be joined and relabeled with the last 1 on this list.
+
+
+
[PLATFORMS]
+
An array that specifies the OS of each smartphone in [DEVICE_IDS] , use a combination of android or ios (we support participants that changed platforms in the middle of your study!). If you have an aware_device table in your database you can set [PLATFORMS]: [multiple] and RAPIDS will infer them automatically.
+
+
+
[LABEL]
+
A string that is used in reports and visualizations.
+
+
+
[START_DATE]
+
A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis
+
+
+
[END_DATE]
+
A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis
+
+
+
+
For [FITBIT]
+
+
+
+
Key
+
Description
+
+
+
+
+
[DEVICE_IDS]
+
An array of the strings that uniquely identify each Fitbit, you can have more than one in case the participant changed devices in the middle of the study, in this case, data from all devices will be joined and relabeled with the last device_id on this list.
+
+
+
[LABEL]
+
A string that is used in reports and visualizations.
+
+
+
[START_DATE]
+
A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis
+
+
+
[END_DATE]
+
A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis
You have two options a) use the aware_device table in your database or b) use a CSV file. In either case, in your config.yaml, set [PHONE_SECTION][ADD] or [FITBIT_SECTION][ADD] to TRUE depending on what devices you used in your study. Set [DEVICE_ID_COLUMN] to the name of the column that uniquely identifies each device and include any device ids you want to ignore in [IGNORED_DEVICE_IDS].
+
+
Set the following keys in your config.yaml
+
CREATE_PARTICIPANT_FILES:
+ SOURCE:
+ TYPE:AWARE_DEVICE_TABLE
+ DATABASE_GROUP:*database_group
+ CSV_FILE_PATH:""
+ TIMEZONE:*timezone
+ PHONE_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:device_id# column name
+ IGNORED_DEVICE_IDS:[]
+ FITBIT_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:fitbit_id# column name
+ IGNORED_DEVICE_IDS:[]
+
+
Then run
+
snakemake -j1 create_participants_files
+
+
+
+
Set the following keys in your config.yaml.
+
CREATE_PARTICIPANT_FILES:
+ SOURCE:
+ TYPE:CSV_FILE
+ DATABASE_GROUP:""
+ CSV_FILE_PATH:"your_path/to_your.csv"
+ TIMEZONE:*timezone
+ PHONE_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:device_id# column name
+ IGNORED_DEVICE_IDS:[]
+ FITBIT_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:fitbit_id# column name
+ IGNORED_DEVICE_IDS:[]
+
+Your CSV file ([SOURCE][CSV_FILE_PATH]) should have the following columns but you can omit any values you don’t have on each column:
+
+
+
+
Column
+
Description
+
+
+
+
+
phone device id
+
The name of this column has to match [PHONE_SECTION][DEVICE_ID_COLUMN]. Separate multiple ids with ;
+
+
+
fitbit device id
+
The name of this column has to match [FITBIT_SECTION][DEVICE_ID_COLUMN]. Separate multiple ids with ;
+
+
+
pid
+
Unique identifiers with the format pXXX (your participant files will be named with this string
+
+
+
platform
+
Use android, ios or multiple as explained above, separate values with ;
+
+
+
label
+
A human readable string that is used in reports and visualizations.
Day segments (or epochs) are the time windows on which you want to extract behavioral features. For example, you might want to process data on every day, every morning, or only during weekends. RAPIDS offers three categories of day segments that are flexible enough to cover most use cases: frequency (short time windows every day), periodic (arbitrary time windows on any day), and event (arbitrary time windows around events of interest). See also our examples.
+
+
These segments are computed on every day and all have the same duration (for example 30 minutes). Set the following keys in your config.yaml
These segments can be computed every day, or on specific days of the week, month, quarter, and year. Their minimum duration is 1 minute but they can be as long as you want. Set the following keys in your config.yaml.
+
DAY_SEGMENTS:&day_segments
+ TYPE:PERIODIC
+ FILE:"data/external/your_periodic_segments.csv"
+ INCLUDE_PAST_PERIODIC_SEGMENTS:FALSE# or TRUE
+
+
If [INCLUDE_PAST_PERIODIC_SEGMENTS] is set to TRUE, RAPIDS will consider instances of your segments back enough in the past as to include the first row of data of each participant. For example, if the first row of data from a participant happened on Saturday March 7th 2020 and the requested segment duration is 7 days starting on every Sunday, the first segment to be considered would start on Sunday March 1st if [INCLUDE_PAST_PERIODIC_SEGMENTS] is TRUE or on Sunday March 8th if FALSE.
+
The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows.
+
+
+
+
Column
+
Description
+
+
+
+
+
label
+
A string that is used as a prefix in the name of your day segments. It has to be unique between rows
+
+
+
start_time
+
A string with format HH:MM:SS representing the starting time of this segment on any day
+
+
+
length
+
A string representing the length of this segment.It can have one or more of the following strings XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example 7D 23H 59M 59S
+
+
+
repeats_on
+
One of the follow options every_day, wday, qday, mday, and yday. The last four represent a week, quarter, month and year day
+
+
+
repeats_value
+
An integer complementing repeats_on. If you set repeats_on to every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday, 1-91 represent a qday, and 1-366 represent a yday
This configuration will create five segments instances (daily, morning, afternoon, evening, night) on any given day (every_day set to 0). The daily segment will start at midnight and will last 23:59:59, the other four segments will start at 6am, 12pm, 6pm, and 12am respectively and last for 05:59:59.
+
+
+
+
These segments can be computed before or after an event of interest (defined as any UNIX timestamp). Their minimum duration is 1 minute but they can be as long as you want. The start of each segment can be shifted backwards or forwards from the specified timestamp. Set the following keys in your config.yaml.
+
DAY_SEGMENTS:&day_segments
+ TYPE:EVENT
+ FILE:"data/external/your_event_segments.csv"
+ INCLUDE_PAST_PERIODIC_SEGMENTS:FALSE# or TRUE
+
+
The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows.
+
+
+
+
Column
+
Description
+
+
+
+
+
label
+
A string that is used as a prefix in the name of your day segments. If labels are unique is segment is completely independent, if two segments have the same label their data will be considered together when computing features like the most frequent contact for calls (the most frequent contact will be computed across these segments)
+
+
+
start_time
+
A string with format HH:MM:SS representing the starting time of this segment
+
+
+
length
+
A string representing the length of this segment.It can have one or more of the following XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example `7D 23H 59M 59S
+
+
+
repeats_on
+
One of the follow options every_day, wday, qday, mday, and yday. The last four represent a week, quarter, month and year day
+
+
+
repeats_value
+
An integer complementing repeats_on. If every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday, 1-91 represent a qday, and 1-366 represent a yday
This example will create eight segments for a single participant (a748ee1a...), five independent stressX segments with various lengths (1,4,3,7, and 9 hours). Segments stress1, stress3, and stress5 are shifted forwards by 5 minutes and stress2 and stress4 are shifted backwards by 4 hours (that is, if the stress4 event happened on March 15th at 1pm EST (1584291600000), the day segment will start on that day at 9am and end at 4pm).
+
The three mood segments are 1 hour, 1 day and 7 days long and have no shift. In addition, these mood segments are grouped together, meaning that although RAPIDS will compute features on each one of them, some necessary information to compute a few of such features will be extracted from all three segments, for example the phone contact that called a participant the most or the location clusters visited by a participant.
You might need to modify the following config keys in your config.yaml depending on what devices your participants used and where you are storing your data.
+
+
Hint
+
You can ignore [DEVICE_DATA][PHONE] or [DEVICE_DATA][FITBIT] if you are not working with either devices.
+
+
The relevant config.yaml section looks as follows by default:
+
DEVICE_DATA:
+ PHONE:
+ SOURCE:
+ TYPE:DATABASE
+ DATABASE_GROUP:*database_group
+ DEVICE_ID_COLUMN:device_id# column name
+ TIMEZONE:
+ TYPE:SINGLE
+ VALUE:*timezone
+ FITBIT:
+ SOURCE:
+ TYPE:DATABASE# DATABASE or FILES (set each FITBIT_SENSOR TABLE attribute accordingly with a table name or a file path)
+ DATABASE_GROUP:*database_group
+ DEVICE_ID_COLUMN:fitbit_id# column name
+ TIMEZONE:
+ TYPE:SINGLE# Fitbit only supports SINGLE timezones
+ VALUE:*timezone
+
+
For [DEVICE_DATA][PHONE]
+
+
+
+
Key
+
Description
+
+
+
+
+
[SOURCE] [TYPE]
+
Only DATABASE is supported (phone data will be pulled from a database)
Finally, you need to modify the config.yaml of the sensors you want to process. All sensors follow the same naming nomenclature DEVICE_SENSOR and have the following basic attributes (we will use PHONE_MESSAGES as an example).
+
+
Hint
+
Every time you change any sensor parameters, all the necessary files will be updated as soon as you execute RAPIDS. Some sensors will have specific attributes (like MESSAGES_TYPES) so refer to each sensor documentation.
The name of the table in your database that stores this sensor data.
+
+
+
[PROVIDERS]
+
A collection of providers . A provider is an author or group of authors that created specific features for the sensor at hand. The provider for all the features implemented by our team is called RAPIDS but we have also included contributions from other researchers (for example DORYAB for location features).
+
+
+
[PROVIDER][COMPUTE]
+
Set this to TRUE if you want to process features for this provider .
+
+
+
[PROVIDER][FEATURES]
+
A list of all the features available for the provider . Delete those that you don’t want to compute.
+
+
+
[PROVIDER][SRC_LANGUAGE]
+
The programming language ( r or python ) in which the features of this provider are implemented.
+
+
+
[PROVIDER][SRC_FOLDER]
+
The folder where the script(s) to compute the features of this provider are stored. This folder is always inside src/features/[DEVICE_SENSOR]/
After you have installed and configured RAPIDS, use the following command to execute it.
+
./rapids -j1
+
+
+
Info
+
The script ./rapids is a wrapper around Snakemake so you can pass any parameters that Snakemake accepts (e.g. -j1).
+
+
+
Updating RAPIDS output after modifying config.yaml
+
Any changes to the config.yaml file will be applied automatically and only the relevant files will be updated. This means that after modifying the features list for PHONE_MESSAGE for example, RAPIDS will update the output file with the correct features.
+
+
+
Multi-core
+
You can run RAPIDS over multiple cores by modifying the -j argument (e.g. use -j8 to use 8 cores). However, take into account that this means multiple sensor datasets for different participants will be load in memory at the same time. If RAPIDS crashes because it ran out of memory reduce the number of cores and try again.
+
As reference, we have run RAPIDS over 12 cores and 32 Gb of RAM without problems for a study with 200 participants with 14 days of low-frequency smartphone data (no accelerometer, gyroscope, or magnetometer).
+
+
+
Forcing a complete rerun
+
If you want to update your data from your database or rerun the whole pipeline from scratch run one or both of the following commands depending on the devices you are using:
If you want to delete all the output files RAPIDS produces you can execute the following command (the content of these folders will be deleted: data/raw, data/interim, data/processed, reports/figures, and reports/compliance)
This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion.
This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion.
Julio Vega is a postdoctoral associate at the Mobile Sensing + Health Institute. He is interested in personalized methodologies to monitor chronic conditions that affect daily human behavior using mobile and wearable data.
Meng Li received her Master of Science degree in Information Science from the University of Pittsburgh. She is interested in applying machine learning algorithms to the medical field.
Abhineeth Reddy Kunta is a Senior Software Engineer with the Mobile Sensing + Health Institute. He is experienced in software development and specializes in building solutions using machine learning. Abhineeth likes exploring ways to leverage technology in advancing medicine and education. Previously he worked as a Computer Programmer at Georgia Department of Public Health. He has a master’s degree in Computer Science from George Mason University.
Kwesi Aguillera is currently in his first year at the University of Pittsburgh pursuing a Master of Sciences in Information Science specializing in Big Data Analytics. He received his Bachelor of Science degree in Computer Science and Management from the University of the West Indies. Kwesi considers himself a full stack developer and looks forward to applying this knowledge to big data analysis.
Echhit Joshi is a Masters student at the School of Computing and Information at University of Pittsburgh. His areas of interest are Machine/Deep Learning, Data Mining, and Analytics.
Nicolas is a rising senior studying computer science at the University of Pittsburgh. His academic interests include databases, machine learning, and application development. After completing his undergraduate degree, he plans to attend graduate school for a MS in Computer Science with a focus on Intelligent Systems.
Nik is a graduate student at the University of Pittsburgh pursuing Master of Science in Information Science. He earned his Bachelor of Technology degree in Information Technology from India. He is a Data Enthusiasts and passionate about finding the meaning out of raw data. In a long term, his goal is to create a breakthrough in Data Science and Deep Learning.
Agam is a junior at Carnegie Mellon University studying Statistics and Machine Learning and pursuing an additional major in Computer Science. He is a member of the Data Science team in the Health and Human Performance Lab at CMU and has keen interests in software development and data science. His research interests include ML applications in medicine.
This is a quick guide for creating and running a simple pipeline to extract missing, outgoing, and incoming call features for daily and night epochs of one participant monitored on the US East coast.
+
+
Install RAPIDS and make sure your conda environment is active (see Installation)
+
+
For the Initial Configuration steps do the following and use the example as a guide:
+
+
Things to change on each configuration step
+
1. Setup your database connection credentials in .env. We assume your credentials group is called MY_GROUP.
+
2. America/New_York should be the default timezone
+
3. Create a participant file p01.yaml based on one of your participants and add p01 to [PIDS] in config.yaml
+
4. [DAY_SEGMENTS][TYPE] should be the default PERIODIC. Change [DAY_SEGMENTS][FILE] with the path of a file containing the following lines:
+
5. If you collected data with AWARE you won’t need to modify the attributes of [DEVICE_DATA][PHONE]
+
6. Set [PHONE_CALLS][PROVIDERS][RAPIDS][COMPUTE] to True
+
+
+
Example of the config.yaml sections after the changes outlined above
+
PIDS: [p01]
+
+TIMEZONE: &timezone
+America/New_York
+
+DATABASE_GROUP: &database_group
+MY_GROUP
+
+# ... other irrelevant sections
+
+DAY_SEGMENTS: &day_segments
+ TYPE: PERIODIC
+ FILE: "data/external/daysegments_periodic.csv" # make sure the three lines specified above are in the file
+ INCLUDE_PAST_PERIODIC_SEGMENTS: FALSE
+
+# No need to change this if you collected AWARE data on a database and your credentials are grouped under `MY_GROUP` in `.env`
+DEVICE_DATA:
+ PHONE:
+ SOURCE:
+ TYPE: DATABASE
+ DATABASE_GROUP: *database_group
+ DEVICE_ID_COLUMN: device_id # column name
+ TIMEZONE:
+ TYPE: SINGLE # SINGLE or MULTIPLE
+ VALUE: *timezone
+
+
+############## PHONE ###########################################################
+################################################################################
+
+....
+
+# Communication call features config, TYPES and FEATURES keys need to match
+PHONE_CALLS:
+ TABLE: calls # change if your calls table has a different name
+ PROVIDERS:
+ RAPIDS:
+ COMPUTE: True # set this to True!
+ CALL_TYPES: ...
+
+
+
+
+
Run RAPIDS
+
./rapids -j1
+
+
+
The call features for daily and morning day segments will be in
+
RAPIDS is a community effort and as such we want to continue recognizing the contributions from other researchers. Besides citing RAPIDS, we ask you to cite any of the authors listed below if you used those sensor providers in your analysis, thank you!
Vega J, Li M, Aguillera K, Goel N, Joshi E, Durica KC, Kunta AR, Low CA
+RAPIDS: Reproducible Analysis Pipeline for Data Streams Collected with Mobile Devices
+JMIR Preprints. 18/08/2020:23246
+DOI: 10.2196/preprints.23246
+URL: https://preprints.jmir.org/preprint/23246
If you computed accelerometer features using the provider [PHONE_ACCLEROMETER][PANDA] cite this paper in addition to RAPIDS.
+
+
Panda et al. citation
+
Panda N, Solsky I, Huang EJ, Lipsitz S, Pradarelli JC, Delisle M, Cusack JC, Gadd MA, Lubitz CC, Mullen JT, Qadan M, Smith BL, Specht M, Stephen AE, Tanabe KK, Gawande AA, Onnela JP, Haynes AB. Using Smartphones to Capture Novel Recovery Metrics After Cancer Surgery. JAMA Surg. 2020 Feb 1;155(2):123-129. doi: 10.1001/jamasurg.2019.4702. PMID: 31657854; PMCID: PMC6820047.
If you computed applications foreground features using the app category (genre) catalogue in [PHONE_APPLICATIONS_FOREGROUND][RAPIDS] cite this paper in addition to RAPIDS.
+
+
Stachl et al. citation
+
Clemens Stachl, Quay Au, Ramona Schoedel, Samuel D. Gosling, Gabriella M. Harari, Daniel Buschek, Sarah Theres Völkel, Tobias Schuwerk, Michelle Oldemeier, Theresa Ullmann, Heinrich Hussmann, Bernd Bischl, Markus Bühner. Proceedings of the National Academy of Sciences Jul 2020, 117 (30) 17680-17687; DOI: 10.1073/pnas.1920484117
If you computed locations features using the provider [PHONE_LOCATIONS][BARNETT] cite this paper and this paper in addition to RAPIDS.
+
+
Barnett et al. citation
+
Ian Barnett, Jukka-Pekka Onnela, Inferring mobility measures from GPS traces with missing data, Biostatistics, Volume 21, Issue 2, April 2020, Pages e98–e112, https://doi.org/10.1093/biostatistics/kxy059
+
+
+
Canzian et al. citation
+
Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp ‘15). Association for Computing Machinery, New York, NY, USA, 1293–1304. DOI:https://doi.org/10.1145/2750858.2805845
If you computed locations features using the provider [PHONE_LOCATIONS][DORYAB] cite this paper and this paper in addition to RAPIDS.
+
+
Doryab et al. citation
+
Doryab, A., Chikarsel, P., Liu, X., & Dey, A. K. (2019). Extraction of Behavioral Features from Smartphone and Wearable Data. ArXiv:1812.10394 [Cs, Stat]. http://arxiv.org/abs/1812.10394
+
+
+
Canzian et al. citation
+
Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp ‘15). Association for Computing Machinery, New York, NY, USA, 1293–1304. DOI:https://doi.org/10.1145/2750858.2805845
We use mkdocs with the material theme to write these docs. Whenever you make any changes, just push them back to the repo and the documentation will be deployed automatically.
The documentation config file is /mkdocs.yml, if you are adding new .md files to the docs modify the nav attribute at the bottom of that file. You can use the hierarchy there to find all the files that appear in the documentation.
Check this page to get familiar with the different visual elements we can use in the docs (admonitions, code blocks, tables, etc.) You can also refer to /docs/setup/installation.md and /docs/setup/configuration.md to see practical examples of these elements.
Along with the continued development and the addition of new sensors and features to the RAPIDS pipeline, tests for the currently available sensors and features are being implemented. Since this is a Work In Progress this page will be updated with the list of sensors and features for which testing is available. For each of the sensors listed a description of the data used for testing (test cases) are outline. Currently for all intent and testing purposes the tests/data/raw/test01/ contains all the test data files for testing android data formats and tests/data/raw/test02/ contains all the test data files for testing iOS data formats. It follows that the expected (verified output) are contained in the tests/data/processed/test01/ and tests/data/processed/test02/ for Android and iOS respectively. tests/data/raw/test03/ and tests/data/raw/test04/ contain data files for testing empty raw data files for android and iOS respectively.
+
The following is a list of the sensors that testing is currently available.
The raw message data file contains data for 2 separate days.
+
The data for the first day contains records 5 records for every
+ epoch.
+
The second day's data contains 6 records for each of only 2
+ epoch (currently morning and evening)
+
The raw message data contains records for both message_types
+ (i.e. recieved and sent) in both days in all epochs. The
+ number records with each message_types per epoch is randomly
+ distributed There is at least one records with each
+ message_types per epoch.
+
There is one raw message data file each, as described above, for
+ testing both iOS and Android data.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
Due to the difference in the format of the raw call data for iOS and Android the following is the expected results the calls_with_datetime_unified.csv. This would give a better idea of the use cases being tested since the calls_with_datetime_unified.csv would make both the iOS and Android data comparable.
+
+
The call data would contain data for 2 days.
+
The data for the first day contains 6 records for every epoch.
+
The second day's data contains 6 records for each of only 2
+ epoch (currently morning and evening)
+
The call data contains records for all call_types (i.e.
+ incoming, outgoing and missed) in both days in all epochs.
+ The number records with each of the call_types per epoch is
+ randomly distributed. There is at least one records with each
+ call_types per epoch.
+
There is one call data file each, as described above, for testing
+ both iOS and Android data.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
Due to the difference in the format of the raw screen data for iOS and Android the following is the expected results the screen_deltas.csv. This would give a better idea of the use cases being tested since the screen_eltas.csv would make both the iOS and Android data comparable These files are used to calculate the features for the screen sensor
+
+
The screen delta data file contains data for 1 day.
+
The screen delta data contains 1 record to represent an unlock
+ episode that falls within an epoch for every epoch.
+
The screen delta data contains 1 record to represent an unlock
+ episode that falls across the boundary of 2 epochs. Namely the
+ unlock episode starts in one epoch and ends in the next, thus
+ there is a record for unlock episodes that fall across night
+ to morning, morning to afternoon and finally afternoon to
+ night
+
The testing is done for unlock episode_type.
+
There is one screen data file each for testing both iOS and
+ Android data formats.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
Due to the difference in the format of the raw battery data for iOS and Android as well as versions of iOS the following is the expected results the battery_deltas.csv. This would give a better idea of the use cases being tested since the battery_deltas.csv would make both the iOS and Android data comparable. These files are used to calculate the features for the battery sensor.
+
+
The battery delta data file contains data for 1 day.
+
The battery delta data contains 1 record each for a charging and
+ discharging episode that falls within an epoch for every
+ epoch. Thus, for the daily epoch there would be multiple
+ charging and discharging episodes
+
Since either a charging episode or a discharging episode and
+ not both can occur across epochs, in order to test episodes that
+ occur across epochs alternating episodes of charging and
+ discharging episodes that fall across night to morning,
+ morning to afternoon and finally afternoon to night are
+ present in the battery delta data. This starts with a
+ discharging episode that begins in night and end in morning.
+
There is one battery data file each, for testing both iOS and
+ Android data formats.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files
The raw Bluetooth data file contains data for 1 day.
+
The raw Bluetooth data contains at least 2 records for each
+ epoch. Each epoch has a record with a timestamp for the
+ beginning boundary for that epoch and a record with a
+ timestamp for the ending boundary for that epoch. (e.g. For
+ the morning epoch there is a record with a timestamp for
+ 6:00AM and another record with a timestamp for 11:59:59AM.
+ These are to test edge cases)
+
An option of 5 Bluetooth devices are randomly distributed
+ throughout the data records.
+
There is one raw Bluetooth data file each, for testing both iOS
+ and Android data formats.
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files.
There are 2 data files (wifi_raw.csv and sensor_wifi_raw.csv)
+ for each fake participant for each phone platform.
+
The raw WIFI data files contain data for 1 day.
+
The sensor_wifi_raw.csv data contains at least 2 records for
+ each epoch. Each epoch has a record with a timestamp for the
+ beginning boundary for that epoch and a record with a
+ timestamp for the ending boundary for that epoch. (e.g. For
+ the morning epoch there is a record with a timestamp for
+ 6:00AM and another record with a timestamp for 11:59:59AM.
+ These are to test edge cases)
+
The wifi_raw.csv data contains 3 records with random timestamps
+ for each epoch to represent visible broadcasting WIFI network.
+ This file is empty for the iOS phone testing data.
+
An option of 10 access point devices is randomly distributed
+ throughout the data records. 5 each for sensor_wifi_raw.csv and
+ wifi_raw.csv.
+
There data files for testing both iOS and Android data formats.
+
There are also additional empty data files for both android and
+ iOS for testing empty data files.
The raw light data contains 3 or 4 rows of data for each epoch
+ except night. The single row of data for night is for testing
+ features for single values inputs. (Example testing the standard
+ deviation of one input value)
+
Since light is only available for Android there is only one file
+ that contains data for Android. All other files (i.e. for iPhone)
+ are empty data files.
The raw application foreground data file contains data for 1 day.
+
The raw application foreground data contains 7 - 9 rows of data
+ for each epoch. The records for each epoch contains apps that
+ are randomly selected from a list of apps that are from the
+ MULTIPLE_CATEGORIES and SINGLE_CATEGORIES (See
+ testing_config.yaml). There are also records in each epoch
+ that have apps randomly selected from a list of apps that are from
+ the EXCLUDED_CATEGORIES and EXCLUDED_APPS. This is to test
+ that these apps are actually being excluded from the calculations
+ of features. There are also records to test SINGLE_APPS
+ calculations.
+
Since application foreground is only available for Android there
+ is only one file that contains data for Android. All other files
+ (i.e. for iPhone) are empty data files.
The raw Activity Recognition data file contains data for 1 day.
+
The raw Activity Recognition data each epoch period contains
+ rows that records 2 - 5 different activity_types. The is such
+ that durations of activities can be tested. Additionally, there
+ are records that mimic the duration of an activity over the time
+ boundary of neighboring epochs. (For example, there a set of
+ records that mimic the participant in_vehicle from afternoon
+ into evening)
+
There is one file each with raw Activity Recognition data for
+ testing both iOS and Android data formats.
+ (plugin_google_activity_recognition_raw.csv for android and
+ plugin_ios_activity_recognition_raw.csv for iOS)
+
There is also an additional empty data file for both android and
+ iOS for testing empty data files.
The raw conversation data file contains data for 2 day.
+
The raw conversation data contains records with a sample of both
+ datatypes (i.e. voice/noise = 0, and conversation = 2 )
+ as well as rows with for samples of each of the inference values
+ (i.e. silence = 0, noise = 1, voice = 2, and unknown
+ = 3) for each epoch. The different datatype and inference
+ records are randomly distributed throughout the epoch.
+
Additionally there are 2 - 5 records for conversations (datatype
+ = 2, and inference = -1) in each epoch and for each epoch
+ except night, there is a conversation record that has a
+ double_convo_starttimestamp that is from the previous
+ epoch. This is to test the calculations of features across
+ epochs.
+
There is a raw conversation data file for both android and iOS
+ platforms (plugin_studentlife_audio_android_raw.csv and
+ plugin_studentlife_audio_raw.csv respectively).
+
Finally, there are also additional empty data files for both
+ android and iOS for testing empty data files
To begin testing RAPIDS place the fake raw input data csv files in
+ tests/data/raw/. The fake participant files should be placed in
+ tests/data/external/. The expected output files of RAPIDS after
+ processing the input data should be placed in
+ tests/data/processesd/.
+
The Snakemake rule(s) that are to be tested must be placed in the
+ tests/Snakemake file. The current tests/Snakemake is a good
+ example of how to define them. (At the time of writing this
+ documentation the snakefile contains rules messages (SMS), calls and
+ screen)
+
Edit the tests/settings/config.yaml. Add and/or remove the rules
+ to be run for testing from the forcerun list.
+
Edit the tests/settings/testing_config.yaml with the necessary
+ configuration settings for running the rules to be tested.
+
Add any additional testscripts in tests/scripts.
+
Uncomment or comment off lines in the testing shell script
+ tests/scripts/run_tests.sh.
+
+
Run the testing shell script.
+
tests/scripts/run_tests.sh
+
+
+
+
The following is a snippet of the output you should see after running your test.
The results above show that the first test test_sensors_files_exist passed while test_sensors_features_calculations failed. In addition you should get the traceback of the failure (not shown here). For more information on how to implement test scripts and use unittest please see Unittest Documentation
+
Testing of the RAPIDS sensors and features is a work-in-progress. Please see test-cases for a list of sensors and features that have testing currently available.
+
Currently the repository is set up to test a number of sensors out of the box by simply running the tests/scripts/run_tests.sh command once the RAPIDS python environment is active.
Try to install any new package using conda. If a package is not available in one of conda‘s channels you can install it with pip but make sure your virtual environment is active.
After installing a new package you can use the following command in your terminal to update your environment.yaml before publishing your pipeline. Note that we ignore the package version for libfortran to keep compatibility with Linux:
**Error in .local(drv, \...) :** **Failed to connect to database: Error:
+Can\'t initialize character set unknown (path: compiled\_in)** :
+
+Calls: dbConnect -> dbConnect -> .local -> .Call
+Execution halted
+[Tue Mar 1019:40:15 2020]
+Error in rule download_dataset:
+ jobid: 531
+ output: data/raw/p60/locations_raw.csv
+
+RuleException:
+CalledProcessError in line 20 of /home/ubuntu/rapids/rules/preprocessing.snakefile:
+Command 'set -euo pipefail; Rscript --vanilla /home/ubuntu/rapids/.snakemake/scripts/tmp_2jnvqs7.download_dataset.R' returned non-zero exit status 1.
+File "/home/ubuntu/rapids/rules/preprocessing.snakefile", line 20, in __rule_download_dataset
+File "/home/ubuntu/anaconda3/envs/moshi-env/lib/python3.7/concurrent/futures/thread.py", line 57, in run
+Shutting down, this might take some time.
+Exiting because a job execution failed. Look above for error message
+
+
+Solution
Please make sure the DATABASE_GROUP in config.yaml matches your DB credentials group in .env.
+
+
+
Cannot start mysql in linux via brew services start mysql¶
+Problem
Cannot start mysql in linux via brew services start mysql
+
+Solution
Use mysql.server start
+
+
+
Every time I run force the download_dataset rule all rules are executed¶
+Problem
When running snakemake -j1 -R download_phone_data or ./rapids -j1 -R download_phone_data all the rules and files are re-computed
+
+Solution
This is expected behavior. The advantage of using snakemake under the hood is that every time a file containing data is modified every rule that depends on that file will be re-executed to update their results. In this case, since download_dataset updates all the raw data, and you are forcing the rule with the flag -R every single rule that depends on those raw files will be executed.
+
+
+
Error Table XXX doesn't exist while running the download_phone_data or download_fitbit_data rule.¶
+Problem
Error in .local(conn, statement, ...) :
+ could not run statement: Table 'db_name.table_name' doesn't exist
+Calls: colnames ... .local -> dbSendQuery -> dbSendQuery -> .local -> .Call
+Execution halted
+
+
+Solution
Please make sure the sensors listed in [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] and the [TABLE] of each sensor you activated in config.yaml match your database tables.
This is a bug in Ubuntu 20.04 when trying to connect to an old MySQL server with MySQL client 8.0. You should get the same error message if you try to connect from the command line. There you can add the option --ssl-mode=DISABLED but we can't do this from the R connector.
+
If you can't update your server, the quickest solution would be to import your database to another server or to a local environment. Alternatively, you could replace mysql-client and libmysqlclient-dev with mariadb-client and libmariadbclient-dev and reinstall renv. More info about this issue here
If you get the following error KeyError in line 43 of preprocessing.smk: 'PHONE_SENSORS', it means that the indentation of the key [PHONE_SENSORS] is not matching the other child elements of PHONE_VALID_SENSED_BINS
+
+Solution
You need to add or remove any leading whitespaces as needed on that line.
+
PHONE_VALID_SENSED_BINS:
+ COMPUTE:False# This flag is automatically ignored (set to True) if you are extracting PHONE_VALID_SENSED_DAYS or screen or Barnett's location features
+ BIN_SIZE:&bin_size5# (in minutes)
+ PHONE_SENSORS:[]
+
+
+
+
Error while updating your conda environment in Ubuntu¶
+Problem
You get the following error:
+
CondaMultiError: CondaVerificationError: The package for tk located at /home/ubuntu/miniconda2/pkgs/tk-8.6.9-hed695b0_1003
+ appears to be corrupted. The path 'include/mysqlStubs.h'
+ specified in the package manifest cannot be found.
+ClobberError: This transaction has incompatible packages due to a shared path.
+ packages: conda-forge/linux-64::llvm-openmp-10.0.0-hc9558a2_0, anaconda/linux-64::intel-openmp-2019.4-243
+ path: 'lib/libiomp5.so'
+
You won’t have to deal with time zones, dates, times, data cleaning or preprocessing. The data that RAPIDS pipes to your feature extraction code is ready to process.
As a tutorial, we will add a new provider for PHONE_ACCELEROMETER called VEGA that extracts feature1, feature2, feature3 in Python and that it requires a parameter from the user called MY_PARAMETER.
+Existing Sensors
An existing sensor is any of the phone or Fitbit sensors with a configuration entry in config.yaml:
In this step you need to add your provider configuration section under the relevant sensor in config.yaml. See our example for our tutorial’s VEGA provider for PHONE_ACCELEROMETER:
+Example configuration for a new accelerometer provider VEGA
In this step you need to add a folder, script and function for your provider.
+
+
Create your provider folder under src/feature/DEVICE_SENSOR/YOUR_PROVIDER, in our example src/feature/phone_accelerometer/vega (same as [SRC_FOLDER] in the step above).
+
Create your provider script inside your provider folder, it can be a Python file called main.py or an R file called main.R.
+
+
Add your provider function in your provider script. The name of such function should be [providername]_features, in our example vega_features
The provider function that you created in the step above will receive the following parameters:
+
+
+
+
Parameter
+
Description
+
+
+
+
+
sensor_data_files
+
Path to the CSV file containing the data of a single participant. This data has been cleaned and preprocessed. Your function will be automatically called for each participant in your study (in the [PIDS] array in config.yaml)
+
+
+
day_segment
+
The label of the day segment that should be processed.
+
+
+
provider
+
The parameters you configured for your provider in config.yaml will be available in this variable as a dictionary in Python or a list in R. In our example this dictionary contains {MY_PARAMETER:"a_string"}
+
+
+
filter_data_by_segment
+
Python only. A function that you will use to filter your data. In R this function is already available in the environment.
+
+
+
*args
+
Python only. Not used for now
+
+
+
**kwargs
+
Python only. Not used for now
+
+
+
+
The code to extract your behavioral features should be implemented in your provider function and in general terms it will have three stages:
+1. Read a participant’s data by loading the CSV data stored in the file pointed by sensor_data_files
Note that phone’s battery, screen, and activity recognition data is given as episodes instead of event rows (for example, start and end timestamps of the periods the phone screen was on)
+
+2. Filter your data to process only those rows that belong to day_segment
This step is only one line of code, but to undersand why we need it, keep reading.
+
Let’s understand the filter_data_by_segment() function with an example. A RAPIDS user can extract features on any arbitrary day segment. A day segment is a period of time that has a label and one or more instances. For example, the user (or you) could have requested features on a daily, weekly, and week-end basis for p01. The labels are arbritrary and the instances depend on the days a participant was monitored for:
+
+
the daily segment could be named my_days and if p01 was monitored for 14 days, it would have 14 instances
+
the weekly segment could be named my_weeks and if p01 was monitored for 14 days, it would have 2 instances.
+
the weekend segment could be named my_weekends and if p01 was monitored for 14 days, it would have 2 instances.
+
+
For this example, RAPIDS will call your provider function three times for p01, once where day_segment is my_days, once where day_segment is my_weeks and once where day_segment is my_weekends. In this example not every row in p01‘s data needs to take part in the feature computation for either segment and the rows need to be grouped differently.
+
Thus filter_data_by_segment() comes in handy, it will return a data frame that contains the rows that were logged during a day segment plus an extra column called local_segment. This new column will have as many unique values as day segment instances exist (14, 2, and 2 for our p01‘s my_days, my_weeks, and my_weekends examples). After filtering, you should group the data frame by this column and compute any desired features, for example:
The reason RAPIDS does not filter the participant’s data set for you is because your code might need to compute something based on a participant’s complete dataset before computing their features. For example, you might want to identify the number that called a participant the most throughout the study before computing a feature with the number of calls the participant received from this number.
+
+3. Return a data frame with your features
After filtering, grouping your data, and computing your features, your provider function should return a data frame that has:
+
+
One row per day segment instance (e.g. 14 our p01‘s my_days example)
+
The local_segment column added by filter_data_by_segment()
+
One column per feature. Your feature columns should be named SENSOR_PROVIDER_FEATURE, for example accelerometr_vega_feature1
+
+
+PHONE_ACCELEROMETER Provider Example
For your reference, this a short example of our own provider (RAPIDS) for PHONE_ACCELEROMETER that computes five acceleration features
+
defrapids_features(sensor_data_files,day_segment,provider,filter_data_by_segment,*args,**kwargs):
+
+acc_data=pd.read_csv(sensor_data_files["sensor_data"])
+requested_features=provider["FEATURES"]
+# name of the features this function can compute
+base_features_names=["maxmagnitude","minmagnitude","avgmagnitude","medianmagnitude","stdmagnitude"]
+# the subset of requested features this function can compute
+features_to_compute=list(set(requested_features)&set(base_features_names))
+
+acc_features=pd.DataFrame(columns=["local_segment"]+["acc_rapids_"+xforxinfeatures_to_compute])
+ifnotacc_data.empty:
+ acc_data=filter_data_by_segment(acc_data,day_segment)
+
+ ifnotacc_data.empty:
+ acc_features=pd.DataFrame()
+ # get magnitude related features: magnitude = sqrt(x^2+y^2+z^2)
+ magnitude=acc_data.apply(lambdarow:np.sqrt(row["double_values_0"]**2+row["double_values_1"]**2+row["double_values_2"]**2),axis=1)
+ acc_data=acc_data.assign(magnitude=magnitude.values)
+
+ if"maxmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_maxmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].max()
+ if"minmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_minmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].min()
+ if"avgmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_avgmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].mean()
+ if"medianmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_medianmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].median()
+ if"stdmagnitude"infeatures_to_compute:
+ acc_features["acc_rapids_stdmagnitude"]=acc_data.groupby(["local_segment"])["magnitude"].std()
+
+ acc_features=acc_features.reset_index()
+
+returnacc_features
+
If you want to add features for a device or a sensor that we do not support at the moment (those that do not appear in the "Existing Sensors" list above), contact us or request it on Slack and we can add the necessary code so you can follow the instructions above.
Every phone or Fitbit sensor has a corresponding config section in config.yaml, these sections follow a similar structure and we’ll use PHONE_ACCELEROMETER as an example to explain this structure.
+
+
Hint
+
We recommend reading this page if you are using RAPIDS for the first time
+
+
+
Config section example for PHONE_ACCELEROMETER
+
# 1) Config section
+PHONE_ACCELEROMETER:
+ # 2) Parameters for PHONE_ACCELEROMETER
+ TABLE:accelerometer
+
+ # 3) Providers for PHONE_ACCELEROMETER
+ PROVIDERS:
+ # 4) RAPIDS provider
+ RAPIDS:
+ # 4.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER
+ COMPUTE:False
+ # 4.2) Features of RAPIDS provider of PHONE_ACCELEROMETER
+ FEATURES:["maxmagnitude","minmagnitude","avgmagnitude","medianmagnitude","stdmagnitude"]
+ SRC_FOLDER:"rapids"# inside src/features/phone_accelerometer
+ SRC_LANGUAGE:"python"
+
+ # 5) PANDA provider
+ PANDA:
+ # 5.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER
+ COMPUTE:False
+ VALID_SENSED_MINUTES:False
+ # 5.2) Features of RAPIDS provider of PHONE_ACCELEROMETER
+ FEATURES:
+ exertional_activity_episode:["sumduration","maxduration","minduration","avgduration","medianduration","stdduration"]
+ nonexertional_activity_episode:["sumduration","maxduration","minduration","avgduration","medianduration","stdduration"]
+ SRC_FOLDER:"panda"# inside src/features/phone_accelerometer
+ SRC_LANGUAGE:"python"
+
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 download, and processed. The TABLE parameter exists for every sensor, but some sensors will have extra para meters like [PHONE_LOCATIONS]. We explain these parameters in a table at the top of each sensor documentation page.
Each sensor configuration section can have zero, one or more behavioral feature providers (see #2 in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. For this accelerometer example we have two providers RAPIDS (see #4) and PANDA (see #5).
Each provider has parameters that affect the computation of the behavioral features it offers (see #4.1 or #5.1 in the example). These parameters will include at least a [COMPUTE] flag that you switch to True to extract a provider’s behavioral features.
+
We explain each provider parameter in a table under the Parameters description heading on each provider documentation page.
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.
+
We explain each behavioral feature in a table under the Features description heading on each provider documentation page.
+
+
Hint
+
Every time you change any sensor parameters, provider parameters or provider features, all the necessary files will be updated as soon as you execute RAPIDS.
Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_ACCELEROMETER features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
maxmagnitude
+
m/s2
+
The maximum magnitude of acceleration (\(\|acceleration\| = \sqrt{x^2 + y^2 + z^2}\)).
+
+
+
minmagnitude
+
m/s2
+
The minimum magnitude of acceleration.
+
+
+
avgmagnitude
+
m/s2
+
The average magnitude of acceleration.
+
+
+
medianmagnitude
+
m/s2
+
The median magnitude of acceleration.
+
+
+
stdmagnitude
+
m/s2
+
The standard deviation of acceleration.
+
+
+
+
+
Assumptions/Observations
+
+
Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem.
Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_ACCELEROMETER features from the PANDA provider
+
+
+
[FEATURES]
+
Features to be computed for exertional and non-exertional activity episodes, see table below
+
+
+
+
Features description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
sumduration
+
minutes
+
Total duration of all exertional or non-exertional activity episodes.
+
+
+
maxduration
+
minutes
+
Longest duration of any exertional or non-exertional activity episode.
+
+
+
minduration
+
minutes
+
Shortest duration of any exertional or non-exertional activity episode.
+
+
+
avgduration
+
minutes
+
Average duration of any exertional or non-exertional activity episode.
+
+
+
medianduration
+
minutes
+
Median duration of any exertional or non-exertional activity episode.
+
+
+
stdduration
+
minutes
+
Standard deviation of the duration of all exertional or non-exertional activity episodes.
+
+
+
+
+
Assumptions/Observations
+
+
Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem.
+
See Panda et al for a definition of exertional and non-exertional activity episodes
Parameters description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_ACTIVITY_RECOGNITION features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[ACTIVITY_CLASSES][STATIONARY]
+
An array of the activity labels to be considered in the STATIONARY category choose any of still, tilting
+
+
+
[ACTIVITY_CLASSES][MOBILE]
+
An array of the activity labels to be considered in the MOBILE category choose any of on_foot, walking, running, on_bicycle
+
+
+
[ACTIVITY_CLASSES][VEHICLE]
+
An array of the activity labels to be considered in the VEHICLE category choose any of in_vehicule
+
+
+
+
Features description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
rows
+
Number of episodes.
+
+
+
mostcommonactivity
+
activity type
+
The most common activity type (e.g. still, on_foot, etc.). If there is a tie, the first one is chosen.
+
+
+
countuniqueactivities
+
activity type
+
Number of unique activities.
+
+
+
durationstationary
+
minutes
+
The total duration of [ACTIVITY_CLASSES][STATIONARY] episodes
+
+
+
durationmobile
+
minutes
+
The total duration of [ACTIVITY_CLASSES][MOBILE] episodes of on foot, running, and on bicycle activities
+
+
+
durationvehicle
+
minutes
+
The total duration of [ACTIVITY_CLASSES][VEHICLE] episodes of on vehicle activity
+
+
+
+
+
Assumptions/Observations
+
+
+
iOS Activity Recognition names and types are unified with Android labels:
+
+
+
+
iOS Activity Name
+
Android Activity Name
+
Android Activity Type
+
+
+
+
+
walking
+
walking
+
7
+
+
+
running
+
running
+
8
+
+
+
cycling
+
on_bicycle
+
1
+
+
+
automotive
+
in_vehicle
+
0
+
+
+
stationary
+
still
+
3
+
+
+
unknown
+
unknown
+
4
+
+
+
+
+
+
In AWARE, Activity Recognition data for Android and iOS are stored in two different database tables, RAPIDS automatically infers what platform each participant belongs to based on their participant file.
Sensor parameters description for [PHONE_APPLICATIONS_FOREGROUND] (these parameters are used by the only provider available at the moment, RAPIDS):
+
+
+
+
Key
+
Description
+
+
+
+
+
[TABLE]
+
Database table where the applications foreground data is stored
+
+
+
[APPLICATION_CATEGORIES][CATALOGUE_SOURCE]
+
FILE or GOOGLE. If FILE, app categories (genres) are read from [CATALOGUE_FILE]. If [GOOGLE], app categories (genres) are scrapped from the Play Store
+
+
+
[APPLICATION_CATEGORIES][CATALOGUE_FILE]
+
CSV file with a package_name and genre column. By default we provide the catalogue created by Stachl et al in data/external/stachl_application_genre_catalogue.csv
+
+
+
[APPLICATION_CATEGORIES][UPDATE_CATALOGUE_FILE]
+
if [CATALOGUE_SOURCE] is equal to FILE, this flag signals whether or not to update [CATALOGUE_FILE], if [CATALOGUE_SOURCE] is equal to GOOGLE all scraped genres will be saved to [CATALOGUE_FILE]
This flag signals whether or not to scrape categories (genres) missing from the [CATALOGUE_FILE]. If [CATALOGUE_SOURCE] is equal to GOOGLE, all genres are scraped anyway (this flag is ignored)
Parameters description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_APPLICATIONS_FOREGROUND features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[SINGLE_CATEGORIES]
+
An array of app categories to be included in the feature extraction computation. The special keyword all represents a category with all the apps from each participant. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above)
+
+
+
[MULTIPLE_CATEGORIES]
+
An array of collections representing meta-categories (a group of categories). They key of each element is the name of the meta-category and the value is an array of member app categories. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above)
+
+
+
[SINGLE_APPS]
+
An array of apps to be included in the feature extraction computation. Use their package name (e.g. com.google.android.youtube) or the reserved keyword top1global (the most used app by a participant over the whole monitoring study)
+
+
+
[EXCLUDED_CATEGORIES]
+
An array of app categories to be excluded from the feature extraction computation. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above)
+
+
+
[EXCLUDED_APPS]
+
An array of apps to be excluded from the feature extraction computation. Use their package name, for example: com.google.android.youtube
+
+
+
+
Features description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
apps
+
Number of times a single app or apps within a category were used (i.e. they were brought to the foreground either by tapping their icon or switching to it from another app)
+
+
+
timeoffirstuse
+
minutes
+
The time in minutes between 12:00am (midnight) and the first use of a single app or apps within a category during a day_segment
+
+
+
timeoflastuse
+
minutes
+
The time in minutes between 12:00am (midnight) and the last use of a single app or apps within a category during a day_segment
+
+
+
frequencyentropy
+
nats
+
The entropy of the used apps within a category during a day_segment (each app is seen as a unique event, the more apps were used, the higher the entropy). This is especially relevant when computed over all apps. Entropy cannot be obtained for a single app
+
+
+
+
+
Assumptions/Observations
+
Features can be computed by app, by apps grouped under a single category (genre) and by multiple categories grouped together (meta-categories). For example, we can get features for Facebook (single app), for Social Network apps (a category including Facebook and other social media apps) or for Social (a meta-category formed by Social Network and Social Media Tools categories).
+
Apps installed by default like YouTube are considered systems apps on some phones. We do an exact match to exclude apps where “genre” == EXCLUDED_CATEGORIES or “package_name” == EXCLUDED_APPS.
+
We provide three ways of classifying and app within a category (genre): a) by automatically scraping its official category from the Google Play Store, b) by using the catalogue created by Stachl et al. which we provide in RAPIDS (data/external/stachl_application_genre_catalogue.csv), or c) by manually creating a personalized catalogue. You can choose a, b or c by modifying [APPLICATION_GENRES] keys and values (see the Sensor parameters description table above).
Parameters description for [PHONE_BATTERY][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_BATTERY features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_BATTERY][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
countdischarge
+
episodes
+
Number of discharging episodes.
+
+
+
sumdurationdischarge
+
minutes
+
The total duration of all discharging episodes.
+
+
+
countcharge
+
episodes
+
Number of battery charging episodes.
+
+
+
sumdurationcharge
+
minutes
+
The total duration of all charging episodes.
+
+
+
avgconsumptionrate
+
episodes/minutes
+
The average of all episodes’ consumption rates. An episode’s consumption rate is defined as the ratio between its battery delta and duration
+
+
+
maxconsumptionrate
+
episodes/minutes
+
The highest of all episodes’ consumption rates. An episode’s consumption rate is defined as the ratio between its battery delta and duration
+
+
+
+
+
Assumptions/Observations
+
+
We convert battery data collected with iOS client v1 (autodetected because battery status 4 do not exist) to match Android battery format: we swap status 3 for 5 and 1 for 3
+
We group battery data into discharge or charge episodes considering any contiguous rows with consecutive reductions or increases of the battery level if they are logged within [EPISODE_THRESHOLD_BETWEEN_ROWS] minutes from each other.
Parameters description for [PHONE_CALLS][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_CALLS features from the RAPIDS provider
+
+
+
[CALL_TYPES]
+
The particular call_type that will be analyzed. The options for this parameter are incoming, outgoing or missed.
+
+
+
[FEATURES]
+
Features to be computed for outgoing, incoming, and missed calls. Note that the same features are available for both incoming and outgoing calls, while missed calls has its own set of features. See the tables below.
+
+
+
+
Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] incoming and outgoing calls:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
calls
+
Number of calls of a particular call_type occurred during a particular day_segment.
+
+
+
distinctcontacts
+
contacts
+
Number of distinct contacts that are associated with a particular call_type for a particular day_segment
+
+
+
meanduration
+
seconds
+
The mean duration of all calls of a particular call_type during a particular day_segment.
+
+
+
sumduration
+
seconds
+
The sum of the duration of all calls of a particular call_type during a particular day_segment.
+
+
+
minduration
+
seconds
+
The duration of the shortest call of a particular call_type during a particular day_segment.
+
+
+
maxduration
+
seconds
+
The duration of the longest call of a particular call_type during a particular day_segment.
+
+
+
stdduration
+
seconds
+
The standard deviation of the duration of all the calls of a particular call_type during a particular day_segment.
+
+
+
modeduration
+
seconds
+
The mode of the duration of all the calls of a particular call_type during a particular day_segment.
+
+
+
entropyduration
+
nats
+
The estimate of the Shannon entropy for the the duration of all the calls of a particular call_type during a particular day_segment.
+
+
+
timefirstcall
+
minutes
+
The time in minutes between 12:00am (midnight) and the first call of call_type.
+
+
+
timelastcall
+
minutes
+
The time in minutes between 12:00am (midnight) and the last call of call_type.
+
+
+
countmostfrequentcontact
+
calls
+
The number of calls of a particular call_type during a particular day_segment of the most frequent contact throughout the monitored period.
+
+
+
+
Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] missed calls:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
count
+
calls
+
Number of missed calls that occurred during a particular day_segment.
+
+
+
distinctcontacts
+
contacts
+
Number of distinct contacts that are associated with missed calls for a particular day_segment
+
+
+
timefirstcall
+
minutes
+
The time in hours from 12:00am (Midnight) that the first missed call occurred.
+
+
+
timelastcall
+
minutes
+
The time in hours from 12:00am (Midnight) that the last missed call occurred.
+
+
+
countmostfrequentcontact
+
calls
+
The number of missed calls during a particular day_segment of the most frequent contact throughout the monitored period.
+
+
+
+
+
Assumptions/Observations
+
+
Traces for iOS calls are unique even for the same contact calling a participant more than once which renders countmostfrequentcontact meaningless and distinctcontacts equal to the total number of traces.
+
[CALL_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [CALL_TYPES]outgoing matches the [FEATURES] key outgoing
+
iOS calls data is transformed to match Android calls data format. See our algorithm
Parameters description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_CONVERSATION features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[RECORDING_MINUTES]
+
Minutes the plugin was recording audio (default 1 min)
+
+
+
[PAUSED_MINUTES]
+
Minutes the plugin was NOT recording audio (default 3 min)
+
+
+
+
Features description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
minutessilence
+
minutes
+
Minutes labeled as silence
+
+
+
minutesnoise
+
minutes
+
Minutes labeled as noise
+
+
+
minutesvoice
+
minutes
+
Minutes labeled as voice
+
+
+
minutesunknown
+
minutes
+
Minutes labeled as unknown
+
+
+
sumconversationduration
+
minutes
+
Total duration of all conversations
+
+
+
maxconversationduration
+
minutes
+
Longest duration of all conversations
+
+
+
minconversationduration
+
minutes
+
Shortest duration of all conversations
+
+
+
avgconversationduration
+
minutes
+
Average duration of all conversations
+
+
+
sdconversationduration
+
minutes
+
Standard Deviation of the duration of all conversations
+
+
+
timefirstconversation
+
minutes
+
Minutes since midnight when the first conversation for a day segment was detected
+
+
+
timelastconversation
+
minutes
+
Minutes since midnight when the last conversation for a day segment was detected
+
+
+
noisesumenergy
+
L2-norm
+
Sum of all energy values when inference is noise
+
+
+
noiseavgenergy
+
L2-norm
+
Average of all energy values when inference is noise
+
+
+
noisesdenergy
+
L2-norm
+
Standard Deviation of all energy values when inference is noise
+
+
+
noiseminenergy
+
L2-norm
+
Minimum of all energy values when inference is noise
+
+
+
noisemaxenergy
+
L2-norm
+
Maximum of all energy values when inference is noise
+
+
+
voicesumenergy
+
L2-norm
+
Sum of all energy values when inference is voice
+
+
+
voiceavgenergy
+
L2-norm
+
Average of all energy values when inference is voice
+
+
+
voicesdenergy
+
L2-norm
+
Standard Deviation of all energy values when inference is voice
+
+
+
voiceminenergy
+
L2-norm
+
Minimum of all energy values when inference is voice
+
+
+
voicemaxenergy
+
L2-norm
+
Maximum of all energy values when inference is voice
+
+
+
silencesensedfraction
+
-
+
Ratio between minutessilence and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
noisesensedfraction
+
-
+
Ratio between minutesnoise and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
voicesensedfraction
+
-
+
Ratio between minutesvoice and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
unknownsensedfraction
+
-
+
Ratio between minutesunknown and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown)
+
+
+
silenceexpectedfraction
+
-
+
Ration between minutessilence and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
noiseexpectedfraction
+
-
+
Ration between minutesnoise and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
voiceexpectedfraction
+
-
+
Ration between minutesvoice and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
unknownexpectedfraction
+
-
+
Ration between minutesunknown and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes)
+
+
+
+
+
Assumptions/Observations
+
+
The timestamp of conversation rows in iOS is in seconds so we convert it to milliseconds to match Android’s format
A valid bin is any period of BIN_SIZE minutes starting from midnight with at least 1 row from any phone sensor. PHONE_VALID_SENSED_BINS are used to compute PHONE_VALID_SENSED_DAYS, to resample fused location data and to compute some screen features.
+
+
Hint
+
PHONE_VALID_SENSED_DAYS are an approximation to the time the phone was sensing data so add as many sensors as you have to [PHONE_VALID_SENSED_BINS][PHONE_SENSORS]
+
+
Parameters description for PHONE_VALID_SENSED_BINS:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to compute
+
+
+
[BIN_SIZE]
+
Size of each bin in minutes
+
+
+
[PHONE_SENSORS]
+
One or more sensor config keys (e.g. PHONE_MESSAGE) to be used to flag a bin as valid or not (whether or not a bin contains at least one row from any sensor)
+
+
+
+
+
Possible values for [PHONE_VALID_SENSED_BINS][PHONE_SENSORS]
On any given day, a phone could have sensed data only for a few minutes or for 24 hours. Features should considered more reliable the more hours the phone was logging data, for example, 10 calls logged on a day when only 1 hour of data was recorded is a less reliable feature compared to 10 calls on a day when 23 hours of data were recorded.
+
Therefore, we define a valid hour as those that contain a minimum number of valid bins (see above). We mark an hour as valid when contains at least MIN_VALID_BINS_PER_HOUR (out of 60min/BIN_SIZE bins). In turn, we mark a day as valid if it has at least MIN_VALID_HOURS_PER_DAY. You can use PHONE_VALID_SENSED_DAYS to manually discard days when not enough data was collected after your features are computed.
+
Parameters description for PHONE_VALID_SENSED_DAYS:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to compute
+
+
+
[MIN_VALID_BINS_PER_HOUR]
+
An array of integer values, 6 by default. Minimum number of valid bins to mark an hour as valid
+
+
+
[MIN_VALID_HOURS_PER_DAY]
+
An array of integer values, 16 by default. Minimum number of valid hours to mark a day as valid
Sensor parameters description for [PHONE_LOCATIONS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[TABLE]
+
Database table where the location data is stored
+
+
+
[LOCATIONS_TO_USE]
+
Type of location data to use, one of ALL, GPS or FUSED_RESAMPLED. This filter is based on the provider column of the AWARE locations table, ALL includes every row, GPS only includes rows where provider is gps, and FUSED_RESAMPLED only includes rows where provider is fused after being resampled.
+
+
+
[FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD]
+
if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled to the next valid timestamp (see the Assumptions/Observations below) only if the time difference between them is less or equal than this threshold (in minutes).
+
+
+
[FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION]
+
if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled at most for this long (in minutes)
+
+
+
+
+
Assumptions/Observations
+
Types of location data to use
+AWARE Android and iOS clients can collect location coordinates through the phone's GPS, the network cellular towers around the phone or Google's fused location API. If you want to use only the GPS provider set [LOCATIONS_TO_USE] to GPS, if you want to use all providers (not recommended due to the difference in accuracy) set [LOCATIONS_TO_USE] to ALL, if your AWARE client was configured to use fused location only or want to focus only on this provider, set [LOCATIONS_TO_USE] to RESAMPLE_FUSED. RESAMPLE_FUSED takes the original fused location coordinates and replicates each pair forward in time as long as the phone was sensing data as indicated by PHONE_VALID_SENSED_BINS, this is done because Google's API only logs a new location coordinate pair when it is sufficiently different in time or space from the previous one.
+
There are two parameters associated with resampling fused location. FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD (in minutes, default 30) controls the maximum gap between any two coordinate pairs to replicate the last known pair (for example, participant A's phone did not collect data between 10.30am and 10:50am and between 11:05am and 11:40am, the last known coordinate pair will be replicated during the first period but not the second, in other words, we assume that we cannot longer guarantee the participant stayed at the last known location if the phone did not sense data for more than 30 minutes). FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION (in minutes, default 720 or 12 hours) stops the last known fused location from being replicated longer that this threshold even if the phone was sensing data continuously (for example, participant A went home at 9pm and their phone was sensing data without gaps until 11am the next morning, the last known location will only be replicated until 9am). If you have suggestions to modify or improve this resampling, let us know.
Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_LOCATIONS features from the BARNETT provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[ACCURACY_LIMIT]
+
An integer in meters, any location rows with an accuracy higher than this will be dropped. This number means there’s a 68% probability the true location is within this radius
+
+
+
[TIMEZONE]
+
Timezone where the location data was collected. By default points to the one defined in the Initial configuration
+
+
+
[MINUTES_DATA_USED]
+
Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough.
+
+
+
+
Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] adapted from Beiwe Summary Statistics:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
hometime
+
minutes
+
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.
+
+
+
disttravelled
+
meters
+
Total distance travelled over a day (flights).
+
+
+
rog
+
meters
+
The Radius of Gyration (rog) 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 the places and that centroid is computed. The weights are proportional to the time spent in each place.
+
+
+
maxdiam
+
meters
+
The maximum diameter is the largest distance between any two pauses.
+
+
+
maxhomedist
+
meters
+
The maximum distance from home in meters.
+
+
+
siglocsvisited
+
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 k from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another.
+
+
+
avgflightlen
+
meters
+
Mean length of all flights.
+
+
+
stdflightlen
+
meters
+
Standard deviation of the length of all flights.
+
+
+
avgflightdur
+
seconds
+
Mean duration of all flights.
+
+
+
stdflightdur
+
seconds
+
The standard deviation of the duration of all flights.
+
+
+
probpause
+
-
+
The fraction of a day spent in a pause (as opposed to a flight)
+
+
+
siglocentropy
+
nats
+
Shannon’s entropy measurement based on the proportion of time spent at each significant location visited during a day.
+
+
+
circdnrtn
+
-
+
A continuous metric quantifying a person’s circadian routine 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.
+
+
+
wkenddayrtn
+
-
+
Same as circdnrtn but computed separately for weekends and weekdays.
+
+
+
+
+
Assumptions/Observations
+
Barnett's et al features
+These features are based on a Pause-Flight model. A pause is defined as a mobiity trace (location pings) within a certain duration and distance (by default 300 seconds and 60 meters). A flight is any mobility trace between two pauses. Data is resampled and imputed before the features are computed. See Barnett et al for more information. In RAPIDS we only expose two parameters for these features (timezone and accuracy limit). You can change other parameters in src/features/phone_locations/barnett/library/MobilityFeatures.R.
+
Significant Locations
+Significant locations are determined using K-means clustering on pauses longer than 10 minutes. The number of clusters (K) is increased until no two clusters are within 400 meters from each other. After this, pauses within a certain range of a cluster (200 meters by default) will count as a visit to that significant location. This description was adapted from the Supplementary Materials of Barnett et al.
+
The Circadian Calculation
+For a detailed description of how this is calculated, see Canzian et al.
Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_LOCATIONS features from the BARNETT provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
[DBSCAN_EPS]
+
The maximum distance in meters between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function.
+
+
+
[DBSCAN_MINSAMPLES]
+
The number of samples (or total weight) in a neighborhood for a point to be considered as a core point of a cluster. This includes the point itself.
+
+
+
[THRESHOLD_STATIC]
+
It is the threshold value in km/hr which labels a row as Static or Moving.
+
+
+
[MAXIMUM_GAP_ALLOWED]
+
The maximum gap (in seconds) allowed between any two consecutive rows for them to be considered part of the same displacement. If this threshold is too high, it can throw speed and distance calculations off for periods when the the phone was not sensing.
+
+
+
[MINUTES_DATA_USED]
+
Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough.
+
+
+
[SAMPLING_FREQUENCY]
+
Expected time difference between any two location rows in minutes. If set to 0, the sampling frequency will be inferred automatically as the median of all the differences between any two consecutive row timestamps (recommended if you are using FUSED_RESAMPLED data). This parameter impacts all the time calculations.
+
+
+
+
Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
locationvariance
+
\(meters^2\)
+
The sum of the variances of the latitude and longitude columns.
+
+
+
loglocationvariance
+
-
+
Log of the sum of the variances of the latitude and longitude columns.
+
+
+
totaldistance
+
meters
+
Total distance travelled in a day segment using the haversine formula.
+
+
+
averagespeed
+
km/hr
+
Average speed in a day segment considering only the instances labeled as Moving.
+
+
+
varspeed
+
km/hr
+
Speed variance in a day segment considering only the instances labeled as Moving.
+
+
+
circadianmovement
+
-
+
"It encodes the extent to which a person’s location patterns follow a 24-hour circadian cycle." Doryab et al..
+
+
+
numberofsignificantplaces
+
places
+
Number of significant locations visited. It is calculated using the DBSCAN clustering algorithm which takes in EPS and MIN_SAMPLES as parameters to identify clusters. Each cluster is a significant place.
+
+
+
numberlocationtransitions
+
transitions
+
Number of movements between any two clusters in a day segment.
+
+
+
radiusgyration
+
meters
+
Quantifies the area covered by a participant
+
+
+
timeattop1location
+
minutes
+
Time spent at the most significant location.
+
+
+
timeattop2location
+
minutes
+
Time spent at the 2nd most significant location.
+
+
+
timeattop3location
+
minutes
+
Time spent at the 3rd most significant location.
+
+
+
movingtostaticratio
+
-
+
Ratio between the number of rows labeled Moving versus Static
+
+
+
outlierstimepercent
+
-
+
Ratio between the number of rows that belong to non-significant clusters divided by the total number of rows in a day segment.
+
+
+
maxlengthstayatclusters
+
minutes
+
Maximum time spent in a cluster (significant location).
+
+
+
minlengthstayatclusters
+
minutes
+
Minimum time spent in a cluster (significant location).
+
+
+
meanlengthstayatclusters
+
minutes
+
Average time spent in a cluster (significant location).
+
+
+
stdlengthstayatclusters
+
minutes
+
Standard deviation of time spent in a cluster (significant location).
+
+
+
locationentropy
+
nats
+
Shannon Entropy computed over the row count of each cluster (significant location), it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location).
+
+
+
normalizedlocationentropy
+
nats
+
Shannon Entropy computed over the row count of each cluster (significant location) divided by the number of clusters, it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location).
+
+
+
+
+
Assumptions/Observations
+
Significant Locations Identified
+Significant locations are determined using DBSCAN clustering on locations that a patient visit over the course of the period of data collection.
+
The Circadian Calculation
+For a detailed description of how this is calculated, see Canzian et al.
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.
+
+
Assumptions/Observations
+
+
+
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.
+
+
+
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.
+
+
+
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.
Parameters description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_WIFI_CONNECTED features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
countscans
+
devices
+
Number of scanned WiFi access points connected during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately
+
+
+
uniquedevices
+
devices
+
Number of unique access point during a day_segment as identified by their hardware address
+
+
+
countscansmostuniquedevice
+
scans
+
Number of scans of the most scanned access point during a day_segment across the whole monitoring period
+
+
+
+
+
Assumptions/Observations
+
+
A connected WiFI access point is one that a phone was connected to.
+
By default AWARE stores this data in the sensor_wifi table.
Parameters description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS]:
+
+
+
+
Key
+
Description
+
+
+
+
+
[COMPUTE]
+
Set to True to extract PHONE_WIFI_VISIBLE features from the RAPIDS provider
+
+
+
[FEATURES]
+
Features to be computed, see table below
+
+
+
+
Features description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS]:
+
+
+
+
Feature
+
Units
+
Description
+
+
+
+
+
countscans
+
devices
+
Number of scanned WiFi access points visible during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately
+
+
+
uniquedevices
+
devices
+
Number of unique access point during a day_segment as identified by their hardware address
+
+
+
countscansmostuniquedevice
+
scans
+
Number of scans of the most scanned access point during a day_segment across the whole monitoring period
+
+
+
+
+
Assumptions/Observations
+
+
A visible WiFI access point is one that a phone sensed around itself but that it was not connected to. Due to API restrictions, this sensor is not available on iOS.
+
By default AWARE stores this data in the wifi table.
Read this page if you want to learn more about how RAPIDS is structured. If you want to start using it go to Installation and then to Initial 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, participants files, day segment files, 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 or the day segment files).
+
+
+ Interaction diagram between the user, and important files in RAPIDS
+
+
+
+
+
+
+
+
+
+
Reproducible Analysis Pipeline for Data Streams (RAPIDS) allows you to process smartphone and wearable data to extract behavioral features (a.k.a. digital biomarkers/phenotypes).
+
RAPIDS is open source, documented, modular, tested, and reproducible. At the moment we support smartphone data collected with AWARE and wearable data from Fitbit devices.
+
Questions or feedback can be posted on #rapids in AWARE Framework's slack.
RAPIDS is formed by R and Python scripts orchestrated by Snakemake. We suggest you read Snakemake’s docs but in short: every link in the analysis chain is atomic and has files as input and output. Behavioral features are processed per sensor and per participant.
Consistent analysis. Every participant sensor dataset is analyzed in the exact same way and isolated from each other.
+
Efficient analysis. Every analysis step is executed only once. Whenever your data or configuration changes only the affected files are updated.
+
Parallel execution. Thanks to Snakemake, your analysis can be executed over multiple cores without changing your code.
+
Extensible code. You can easily add your own behavioral features in R or Python and keep authorship and citations.
+
Timezone aware. Your data is adjusted to the specified timezone (multiple timezones suport coming soon).
+
Flexible day segments. You can extract behavioral features on time windows of any length (e.g. 5 minutes, 3 hours, 2 days), on every day or particular days (e.g. weekends, Mondays, the 1st of each month, etc.) or around events of interest (e.g. surveys or clinical relapses).
+
Tested code. We are constantly adding tests to make sure our behavioral features are correct.
+
Reproducible code. You can be sure your code will run in other computers as intended thanks to R and Python virtual environments. You can share your analysis code along your publications without any overhead.
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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/latest/search/search_index.json b/latest/search/search_index.json
new file mode 100644
index 00000000..798daaf8
--- /dev/null
+++ b/latest/search/search_index.json
@@ -0,0 +1 @@
+{"config":{"lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Welcome to RAPIDS documentation \u00b6 Test v1.0 Reproducible Analysis Pipeline for Data Streams (RAPIDS) allows you to process smartphone and wearable data to extract behavioral features (a.k.a. digital biomarkers/phenotypes). RAPIDS is open source, documented, modular, tested, and reproducible. At the moment we support smartphone data collected with AWARE and wearable data from Fitbit devices. Questions or feedback can be posted on #rapids in AWARE Framework's slack . Bugs should be reported on Github . Join our discussions on our algorithms and assumptions for feature processing . Ready to start? Go to Installation and then to Initial Configuration How does it work? \u00b6 RAPIDS is formed by R and Python scripts orchestrated by Snakemake . We suggest you read Snakemake\u2019s docs but in short: every link in the analysis chain is atomic and has files as input and output. Behavioral features are processed per sensor and per participant. What are the benefits of using RAPIDS? \u00b6 Consistent analysis . Every participant sensor dataset is analyzed in the exact same way and isolated from each other. Efficient analysis . Every analysis step is executed only once. Whenever your data or configuration changes only the affected files are updated. Parallel execution . Thanks to Snakemake, your analysis can be executed over multiple cores without changing your code. Extensible code . You can easily add your own behavioral features in R or Python and keep authorship and citations. Timezone aware . Your data is adjusted to the specified timezone (multiple timezones suport coming soon ). Flexible day segments . You can extract behavioral features on time windows of any length (e.g. 5 minutes, 3 hours, 2 days), on every day or particular days (e.g. weekends, Mondays, the 1 st of each month, etc.) or around events of interest (e.g. surveys or clinical relapses). Tested code . We are constantly adding tests to make sure our behavioral features are correct. Reproducible code . You can be sure your code will run in other computers as intended thanks to R and Python virtual environments. You can share your analysis code along your publications without any overhead. Private . All your data is processed locally. How is it organized? \u00b6 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\u2019 File Structure .","title":"Home"},{"location":"#welcome-to-rapids-documentation","text":"Test v1.0 Reproducible Analysis Pipeline for Data Streams (RAPIDS) allows you to process smartphone and wearable data to extract behavioral features (a.k.a. digital biomarkers/phenotypes). RAPIDS is open source, documented, modular, tested, and reproducible. At the moment we support smartphone data collected with AWARE and wearable data from Fitbit devices. Questions or feedback can be posted on #rapids in AWARE Framework's slack . Bugs should be reported on Github . Join our discussions on our algorithms and assumptions for feature processing . Ready to start? Go to Installation and then to Initial Configuration","title":"Welcome to RAPIDS documentation"},{"location":"#how-does-it-work","text":"RAPIDS is formed by R and Python scripts orchestrated by Snakemake . We suggest you read Snakemake\u2019s docs but in short: every link in the analysis chain is atomic and has files as input and output. Behavioral features are processed per sensor and per participant.","title":"How does it work?"},{"location":"#what-are-the-benefits-of-using-rapids","text":"Consistent analysis . Every participant sensor dataset is analyzed in the exact same way and isolated from each other. Efficient analysis . Every analysis step is executed only once. Whenever your data or configuration changes only the affected files are updated. Parallel execution . Thanks to Snakemake, your analysis can be executed over multiple cores without changing your code. Extensible code . You can easily add your own behavioral features in R or Python and keep authorship and citations. Timezone aware . Your data is adjusted to the specified timezone (multiple timezones suport coming soon ). Flexible day segments . You can extract behavioral features on time windows of any length (e.g. 5 minutes, 3 hours, 2 days), on every day or particular days (e.g. weekends, Mondays, the 1 st of each month, etc.) or around events of interest (e.g. surveys or clinical relapses). Tested code . We are constantly adding tests to make sure our behavioral features are correct. Reproducible code . You can be sure your code will run in other computers as intended thanks to R and Python virtual environments. You can share your analysis code along your publications without any overhead. Private . All your data is processed locally.","title":"What are the benefits of using RAPIDS?"},{"location":"#how-is-it-organized","text":"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\u2019 File Structure .","title":"How is it organized?"},{"location":"citation/","text":"Cite RAPIDS and providers \u00b6 RAPIDS and the community RAPIDS is a community effort and as such we want to continue recognizing the contributions from other researchers. Besides citing RAPIDS, we ask you to cite any of the authors listed below if you used those sensor providers in your analysis, thank you! RAPIDS \u00b6 If you used RAPIDS, please cite this paper . RAPIDS et al. citation Vega J, Li M, Aguillera K, Goel N, Joshi E, Durica KC, Kunta AR, Low CA RAPIDS: Reproducible Analysis Pipeline for Data Streams Collected with Mobile Devices JMIR Preprints. 18/08/2020:23246 DOI: 10.2196/preprints.23246 URL: https://preprints.jmir.org/preprint/23246 Panda (accelerometer) \u00b6 If you computed accelerometer features using the provider [PHONE_ACCLEROMETER][PANDA] cite this paper in addition to RAPIDS. Panda et al. citation Panda N, Solsky I, Huang EJ, Lipsitz S, Pradarelli JC, Delisle M, Cusack JC, Gadd MA, Lubitz CC, Mullen JT, Qadan M, Smith BL, Specht M, Stephen AE, Tanabe KK, Gawande AA, Onnela JP, Haynes AB. Using Smartphones to Capture Novel Recovery Metrics After Cancer Surgery. JAMA Surg. 2020 Feb 1;155(2):123-129. doi: 10.1001/jamasurg.2019.4702. PMID: 31657854; PMCID: PMC6820047. Stachl (applications foreground) \u00b6 If you computed applications foreground features using the app category (genre) catalogue in [PHONE_APPLICATIONS_FOREGROUND][RAPIDS] cite this paper in addition to RAPIDS. Stachl et al. citation Clemens Stachl, Quay Au, Ramona Schoedel, Samuel D. Gosling, Gabriella M. Harari, Daniel Buschek, Sarah Theres V\u00f6lkel, Tobias Schuwerk, Michelle Oldemeier, Theresa Ullmann, Heinrich Hussmann, Bernd Bischl, Markus B\u00fchner. Proceedings of the National Academy of Sciences Jul 2020, 117 (30) 17680-17687; DOI: 10.1073/pnas.1920484117 Barnett (locations) \u00b6 If you computed locations features using the provider [PHONE_LOCATIONS][BARNETT] cite this paper and this paper in addition to RAPIDS. Barnett et al. citation Ian Barnett, Jukka-Pekka Onnela, Inferring mobility measures from GPS traces with missing data, Biostatistics, Volume 21, Issue 2, April 2020, Pages e98\u2013e112, https://doi.org/10.1093/biostatistics/kxy059 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845 Doryab (locations) \u00b6 If you computed locations features using the provider [PHONE_LOCATIONS][DORYAB] cite this paper and this paper in addition to RAPIDS. Doryab et al. citation Doryab, A., Chikarsel, P., Liu, X., & Dey, A. K. (2019). Extraction of Behavioral Features from Smartphone and Wearable Data. ArXiv:1812.10394 [Cs, Stat]. http://arxiv.org/abs/1812.10394 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845","title":"Citation"},{"location":"citation/#cite-rapids-and-providers","text":"RAPIDS and the community RAPIDS is a community effort and as such we want to continue recognizing the contributions from other researchers. Besides citing RAPIDS, we ask you to cite any of the authors listed below if you used those sensor providers in your analysis, thank you!","title":"Cite RAPIDS and providers"},{"location":"citation/#rapids","text":"If you used RAPIDS, please cite this paper . RAPIDS et al. citation Vega J, Li M, Aguillera K, Goel N, Joshi E, Durica KC, Kunta AR, Low CA RAPIDS: Reproducible Analysis Pipeline for Data Streams Collected with Mobile Devices JMIR Preprints. 18/08/2020:23246 DOI: 10.2196/preprints.23246 URL: https://preprints.jmir.org/preprint/23246","title":"RAPIDS"},{"location":"citation/#panda-accelerometer","text":"If you computed accelerometer features using the provider [PHONE_ACCLEROMETER][PANDA] cite this paper in addition to RAPIDS. Panda et al. citation Panda N, Solsky I, Huang EJ, Lipsitz S, Pradarelli JC, Delisle M, Cusack JC, Gadd MA, Lubitz CC, Mullen JT, Qadan M, Smith BL, Specht M, Stephen AE, Tanabe KK, Gawande AA, Onnela JP, Haynes AB. Using Smartphones to Capture Novel Recovery Metrics After Cancer Surgery. JAMA Surg. 2020 Feb 1;155(2):123-129. doi: 10.1001/jamasurg.2019.4702. PMID: 31657854; PMCID: PMC6820047.","title":"Panda (accelerometer)"},{"location":"citation/#stachl-applications-foreground","text":"If you computed applications foreground features using the app category (genre) catalogue in [PHONE_APPLICATIONS_FOREGROUND][RAPIDS] cite this paper in addition to RAPIDS. Stachl et al. citation Clemens Stachl, Quay Au, Ramona Schoedel, Samuel D. Gosling, Gabriella M. Harari, Daniel Buschek, Sarah Theres V\u00f6lkel, Tobias Schuwerk, Michelle Oldemeier, Theresa Ullmann, Heinrich Hussmann, Bernd Bischl, Markus B\u00fchner. Proceedings of the National Academy of Sciences Jul 2020, 117 (30) 17680-17687; DOI: 10.1073/pnas.1920484117","title":"Stachl (applications foreground)"},{"location":"citation/#barnett-locations","text":"If you computed locations features using the provider [PHONE_LOCATIONS][BARNETT] cite this paper and this paper in addition to RAPIDS. Barnett et al. citation Ian Barnett, Jukka-Pekka Onnela, Inferring mobility measures from GPS traces with missing data, Biostatistics, Volume 21, Issue 2, April 2020, Pages e98\u2013e112, https://doi.org/10.1093/biostatistics/kxy059 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845","title":"Barnett (locations)"},{"location":"citation/#doryab-locations","text":"If you computed locations features using the provider [PHONE_LOCATIONS][DORYAB] cite this paper and this paper in addition to RAPIDS. Doryab et al. citation Doryab, A., Chikarsel, P., Liu, X., & Dey, A. K. (2019). Extraction of Behavioral Features from Smartphone and Wearable Data. ArXiv:1812.10394 [Cs, Stat]. http://arxiv.org/abs/1812.10394 Canzian et al. citation Luca Canzian and Mirco Musolesi. 2015. Trajectories of depression: unobtrusive monitoring of depressive states by means of smartphone mobility traces analysis. In Proceedings of the 2015 ACM International Joint Conference on Pervasive and Ubiquitous Computing (UbiComp \u201815). Association for Computing Machinery, New York, NY, USA, 1293\u20131304. DOI: https://doi.org/10.1145/2750858.2805845","title":"Doryab (locations)"},{"location":"faq/","text":"Frequently Asked Questions \u00b6 Cannot connect to your MySQL server \u00b6 Problem **Error in .local ( drv, \\. .. ) :** **Failed to connect to database: Error: Can \\' t initialize character set unknown ( path: compiled \\_ in ) ** : Calls: dbConnect -> dbConnect -> .local -> .Call Execution halted [ Tue Mar 10 19 :40:15 2020 ] Error in rule download_dataset: jobid: 531 output: data/raw/p60/locations_raw.csv RuleException: CalledProcessError in line 20 of /home/ubuntu/rapids/rules/preprocessing.snakefile: Command 'set -euo pipefail; Rscript --vanilla /home/ubuntu/rapids/.snakemake/scripts/tmp_2jnvqs7.download_dataset.R' returned non-zero exit status 1 . File \"/home/ubuntu/rapids/rules/preprocessing.snakefile\" , line 20 , in __rule_download_dataset File \"/home/ubuntu/anaconda3/envs/moshi-env/lib/python3.7/concurrent/futures/thread.py\" , line 57 , in run Shutting down, this might take some time. Exiting because a job execution failed. Look above for error message Solution Please make sure the DATABASE_GROUP in config.yaml matches your DB credentials group in .env . Cannot start mysql in linux via brew services start mysql \u00b6 Problem Cannot start mysql in linux via brew services start mysql Solution Use mysql.server start Every time I run force the download_dataset rule all rules are executed \u00b6 Problem When running snakemake -j1 -R download_phone_data or ./rapids -j1 -R download_phone_data all the rules and files are re-computed Solution This is expected behavior. The advantage of using snakemake under the hood is that every time a file containing data is modified every rule that depends on that file will be re-executed to update their results. In this case, since download_dataset updates all the raw data, and you are forcing the rule with the flag -R every single rule that depends on those raw files will be executed. Error Table XXX doesn't exist while running the download_phone_data or download_fitbit_data rule. \u00b6 Problem Error in .local ( conn, statement, ... ) : could not run statement: Table 'db_name.table_name' doesn ' t exist Calls: colnames ... .local -> dbSendQuery -> dbSendQuery -> .local -> .Call Execution halted Solution Please make sure the sensors listed in [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] and the [TABLE] of each sensor you activated in config.yaml match your database tables. How do I install RAPIDS on Ubuntu 16.04 \u00b6 Solution Install dependencies (Homebrew - if not installed): sudo apt-get install libmariadb-client-lgpl-dev libxml2-dev libssl-dev Install brew for linux and add the following line to ~/.bashrc : export PATH=$HOME/.linuxbrew/bin:$PATH source ~/.bashrc Install MySQL brew install mysql brew services start mysql Install R, pandoc and rmarkdown: brew install r brew install gcc@6 (needed due to this bug ) HOMEBREW_CC=gcc-6 brew install pandoc Install miniconda using these instructions Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake renv_install snakemake renv_init snakemake renv_restore This step could take several minutes to complete. Please be patient and let it run until completion. mysql.h cannot be found \u00b6 Problem -------------------------- [ ERROR MESSAGE ] ---------------------------- :1:10: fatal error: mysql.h: No such file or directory compilation terminated. ----------------------------------------------------------------------- ERROR: configuration failed for package 'RMySQL' Solution sudo apt install libmariadbclient-dev No package libcurl found \u00b6 Problem libcurl cannot be found Solution Install libcurl sudo apt install libcurl4-openssl-dev Configuration failed because openssl was not found. \u00b6 Problem openssl cannot be found Solution Install openssl sudo apt install libssl-dev Configuration failed because libxml-2.0 was not found \u00b6 Problem libxml-2.0 cannot be found Solution Install libxml-2.0 sudo apt install libxml2-dev SSL connection error when running RAPIDS \u00b6 Problem You are getting the following error message when running RAPIDS: Error: Failed to connect: SSL connection error: error:1425F102:SSL routines:ssl_choose_client_version:unsupported protocol. Solution This is a bug in Ubuntu 20.04 when trying to connect to an old MySQL server with MySQL client 8.0. You should get the same error message if you try to connect from the command line. There you can add the option --ssl-mode=DISABLED but we can't do this from the R connector. If you can't update your server, the quickest solution would be to import your database to another server or to a local environment. Alternatively, you could replace mysql-client and libmysqlclient-dev with mariadb-client and libmariadbclient-dev and reinstall renv. More info about this issue here DB_TABLES key not found \u00b6 Problem If you get the following error KeyError in line 43 of preprocessing.smk: 'PHONE_SENSORS' , it means that the indentation of the key [PHONE_SENSORS] is not matching the other child elements of PHONE_VALID_SENSED_BINS Solution You need to add or remove any leading whitespaces as needed on that line. PHONE_VALID_SENSED_BINS : COMPUTE : False # This flag is automatically ignored (set to True) if you are extracting PHONE_VALID_SENSED_DAYS or screen or Barnett's location features BIN_SIZE : &bin_size 5 # (in minutes) PHONE_SENSORS : [] Error while updating your conda environment in Ubuntu \u00b6 Problem You get the following error: CondaMultiError: CondaVerificationError: The package for tk located at /home/ubuntu/miniconda2/pkgs/tk-8.6.9-hed695b0_1003 appears to be corrupted. The path 'include/mysqlStubs.h' specified in the package manifest cannot be found. ClobberError: This transaction has incompatible packages due to a shared path. packages: conda-forge/linux-64::llvm-openmp-10.0.0-hc9558a2_0, anaconda/linux-64::intel-openmp-2019.4-243 path: 'lib/libiomp5.so' Solution Reinstall conda","title":"Frequently Asked Questions"},{"location":"faq/#frequently-asked-questions","text":"","title":"Frequently Asked Questions"},{"location":"faq/#cannot-connect-to-your-mysql-server","text":"Problem **Error in .local ( drv, \\. .. ) :** **Failed to connect to database: Error: Can \\' t initialize character set unknown ( path: compiled \\_ in ) ** : Calls: dbConnect -> dbConnect -> .local -> .Call Execution halted [ Tue Mar 10 19 :40:15 2020 ] Error in rule download_dataset: jobid: 531 output: data/raw/p60/locations_raw.csv RuleException: CalledProcessError in line 20 of /home/ubuntu/rapids/rules/preprocessing.snakefile: Command 'set -euo pipefail; Rscript --vanilla /home/ubuntu/rapids/.snakemake/scripts/tmp_2jnvqs7.download_dataset.R' returned non-zero exit status 1 . File \"/home/ubuntu/rapids/rules/preprocessing.snakefile\" , line 20 , in __rule_download_dataset File \"/home/ubuntu/anaconda3/envs/moshi-env/lib/python3.7/concurrent/futures/thread.py\" , line 57 , in run Shutting down, this might take some time. Exiting because a job execution failed. Look above for error message Solution Please make sure the DATABASE_GROUP in config.yaml matches your DB credentials group in .env .","title":"Cannot connect to your MySQL server"},{"location":"faq/#cannot-start-mysql-in-linux-via-brew-services-start-mysql","text":"Problem Cannot start mysql in linux via brew services start mysql Solution Use mysql.server start","title":"Cannot start mysql in linux via brew services start mysql"},{"location":"faq/#every-time-i-run-force-the-download_dataset-rule-all-rules-are-executed","text":"Problem When running snakemake -j1 -R download_phone_data or ./rapids -j1 -R download_phone_data all the rules and files are re-computed Solution This is expected behavior. The advantage of using snakemake under the hood is that every time a file containing data is modified every rule that depends on that file will be re-executed to update their results. In this case, since download_dataset updates all the raw data, and you are forcing the rule with the flag -R every single rule that depends on those raw files will be executed.","title":"Every time I run force the download_dataset rule all rules are executed"},{"location":"faq/#error-table-xxx-doesnt-exist-while-running-the-download_phone_data-or-download_fitbit_data-rule","text":"Problem Error in .local ( conn, statement, ... ) : could not run statement: Table 'db_name.table_name' doesn ' t exist Calls: colnames ... .local -> dbSendQuery -> dbSendQuery -> .local -> .Call Execution halted Solution Please make sure the sensors listed in [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] and the [TABLE] of each sensor you activated in config.yaml match your database tables.","title":"Error Table XXX doesn't exist while running the download_phone_data or download_fitbit_data rule."},{"location":"faq/#how-do-i-install-rapids-on-ubuntu-1604","text":"Solution Install dependencies (Homebrew - if not installed): sudo apt-get install libmariadb-client-lgpl-dev libxml2-dev libssl-dev Install brew for linux and add the following line to ~/.bashrc : export PATH=$HOME/.linuxbrew/bin:$PATH source ~/.bashrc Install MySQL brew install mysql brew services start mysql Install R, pandoc and rmarkdown: brew install r brew install gcc@6 (needed due to this bug ) HOMEBREW_CC=gcc-6 brew install pandoc Install miniconda using these instructions Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake renv_install snakemake renv_init snakemake renv_restore This step could take several minutes to complete. Please be patient and let it run until completion.","title":"How do I install RAPIDS on Ubuntu 16.04"},{"location":"faq/#mysqlh-cannot-be-found","text":"Problem -------------------------- [ ERROR MESSAGE ] ---------------------------- :1:10: fatal error: mysql.h: No such file or directory compilation terminated. ----------------------------------------------------------------------- ERROR: configuration failed for package 'RMySQL' Solution sudo apt install libmariadbclient-dev","title":"mysql.h cannot be found"},{"location":"faq/#no-package-libcurl-found","text":"Problem libcurl cannot be found Solution Install libcurl sudo apt install libcurl4-openssl-dev","title":"No package libcurl found"},{"location":"faq/#configuration-failed-because-openssl-was-not-found","text":"Problem openssl cannot be found Solution Install openssl sudo apt install libssl-dev","title":"Configuration failed because openssl was not found."},{"location":"faq/#configuration-failed-because-libxml-20-was-not-found","text":"Problem libxml-2.0 cannot be found Solution Install libxml-2.0 sudo apt install libxml2-dev","title":"Configuration failed because libxml-2.0 was not found"},{"location":"faq/#ssl-connection-error-when-running-rapids","text":"Problem You are getting the following error message when running RAPIDS: Error: Failed to connect: SSL connection error: error:1425F102:SSL routines:ssl_choose_client_version:unsupported protocol. Solution This is a bug in Ubuntu 20.04 when trying to connect to an old MySQL server with MySQL client 8.0. You should get the same error message if you try to connect from the command line. There you can add the option --ssl-mode=DISABLED but we can't do this from the R connector. If you can't update your server, the quickest solution would be to import your database to another server or to a local environment. Alternatively, you could replace mysql-client and libmysqlclient-dev with mariadb-client and libmariadbclient-dev and reinstall renv. More info about this issue here","title":"SSL connection error when running RAPIDS"},{"location":"faq/#db_tables-key-not-found","text":"Problem If you get the following error KeyError in line 43 of preprocessing.smk: 'PHONE_SENSORS' , it means that the indentation of the key [PHONE_SENSORS] is not matching the other child elements of PHONE_VALID_SENSED_BINS Solution You need to add or remove any leading whitespaces as needed on that line. PHONE_VALID_SENSED_BINS : COMPUTE : False # This flag is automatically ignored (set to True) if you are extracting PHONE_VALID_SENSED_DAYS or screen or Barnett's location features BIN_SIZE : &bin_size 5 # (in minutes) PHONE_SENSORS : []","title":"DB_TABLES key not found"},{"location":"faq/#error-while-updating-your-conda-environment-in-ubuntu","text":"Problem You get the following error: CondaMultiError: CondaVerificationError: The package for tk located at /home/ubuntu/miniconda2/pkgs/tk-8.6.9-hed695b0_1003 appears to be corrupted. The path 'include/mysqlStubs.h' specified in the package manifest cannot be found. ClobberError: This transaction has incompatible packages due to a shared path. packages: conda-forge/linux-64::llvm-openmp-10.0.0-hc9558a2_0, anaconda/linux-64::intel-openmp-2019.4-243 path: 'lib/libiomp5.so' Solution Reinstall conda","title":"Error while updating your conda environment in Ubuntu"},{"location":"file-structure/","text":"File Structure \u00b6 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 and then to Initial Configuration All paths mentioned in this page are relative to RAPIDS\u2019 root folder. If you want to extract the behavioral features that RAPIDS offers, you will only have to create or modify the .env file , participants files , day segment files , 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 or the day segment files ). Interaction diagram between the user, and important files in RAPIDS","title":"File Structure"},{"location":"file-structure/#file-structure","text":"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 and then to Initial Configuration All paths mentioned in this page are relative to RAPIDS\u2019 root folder. If you want to extract the behavioral features that RAPIDS offers, you will only have to create or modify the .env file , participants files , day segment files , 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 or the day segment files ). Interaction diagram between the user, and important files in RAPIDS","title":"File Structure"},{"location":"team/","text":"RAPIDS Team \u00b6 If you are interested in contributing feel free to submit a pull request or contact us. Core Team \u00b6 Julio Vega (Designer and Lead Developer) \u00b6 About Julio Vega is a postdoctoral associate at the Mobile Sensing + Health Institute. He is interested in personalized methodologies to monitor chronic conditions that affect daily human behavior using mobile and wearable data. vegaju at upmc . edu Personal Website Meng Li \u00b6 About Meng Li received her Master of Science degree in Information Science from the University of Pittsburgh. She is interested in applying machine learning algorithms to the medical field. lim11 at upmc . edu Linkedin Profile Github Profile Abhineeth Reddy Kunta \u00b6 About Abhineeth Reddy Kunta is a Senior Software Engineer with the Mobile Sensing + Health Institute. He is experienced in software development and specializes in building solutions using machine learning. Abhineeth likes exploring ways to leverage technology in advancing medicine and education. Previously he worked as a Computer Programmer at Georgia Department of Public Health. He has a master\u2019s degree in Computer Science from George Mason University. Kwesi Aguillera \u00b6 About Kwesi Aguillera is currently in his first year at the University of Pittsburgh pursuing a Master of Sciences in Information Science specializing in Big Data Analytics. He received his Bachelor of Science degree in Computer Science and Management from the University of the West Indies. Kwesi considers himself a full stack developer and looks forward to applying this knowledge to big data analysis. Linkedin Profile Echhit Joshi \u00b6 About Echhit Joshi is a Masters student at the School of Computing and Information at University of Pittsburgh. His areas of interest are Machine/Deep Learning, Data Mining, and Analytics. Linkedin Profile Nicolas Leo \u00b6 About Nicolas is a rising senior studying computer science at the University of Pittsburgh. His academic interests include databases, machine learning, and application development. After completing his undergraduate degree, he plans to attend graduate school for a MS in Computer Science with a focus on Intelligent Systems. Nikunj Goel \u00b6 About Nik is a graduate student at the University of Pittsburgh pursuing Master of Science in Information Science. He earned his Bachelor of Technology degree in Information Technology from India. He is a Data Enthusiasts and passionate about finding the meaning out of raw data. In a long term, his goal is to create a breakthrough in Data Science and Deep Learning. Linkedin Profile Community Contributors \u00b6 Agam Kumar \u00b6 About Agam is a junior at Carnegie Mellon University studying Statistics and Machine Learning and pursuing an additional major in Computer Science. He is a member of the Data Science team in the Health and Human Performance Lab at CMU and has keen interests in software development and data science. His research interests include ML applications in medicine. Linkedin Profile Github Profile Yasaman S. Sefidgar \u00b6 About Linkedin Profile Advisors \u00b6 Afsaneh Doryab \u00b6 About Personal Website Carissa Low \u00b6 About Profile","title":"Team"},{"location":"team/#rapids-team","text":"If you are interested in contributing feel free to submit a pull request or contact us.","title":"RAPIDS Team"},{"location":"team/#core-team","text":"","title":"Core Team"},{"location":"team/#julio-vega-designer-and-lead-developer","text":"About Julio Vega is a postdoctoral associate at the Mobile Sensing + Health Institute. He is interested in personalized methodologies to monitor chronic conditions that affect daily human behavior using mobile and wearable data. vegaju at upmc . edu Personal Website","title":"Julio Vega (Designer and Lead Developer)"},{"location":"team/#meng-li","text":"About Meng Li received her Master of Science degree in Information Science from the University of Pittsburgh. She is interested in applying machine learning algorithms to the medical field. lim11 at upmc . edu Linkedin Profile Github Profile","title":"Meng Li"},{"location":"team/#abhineeth-reddy-kunta","text":"About Abhineeth Reddy Kunta is a Senior Software Engineer with the Mobile Sensing + Health Institute. He is experienced in software development and specializes in building solutions using machine learning. Abhineeth likes exploring ways to leverage technology in advancing medicine and education. Previously he worked as a Computer Programmer at Georgia Department of Public Health. He has a master\u2019s degree in Computer Science from George Mason University.","title":"Abhineeth Reddy Kunta"},{"location":"team/#kwesi-aguillera","text":"About Kwesi Aguillera is currently in his first year at the University of Pittsburgh pursuing a Master of Sciences in Information Science specializing in Big Data Analytics. He received his Bachelor of Science degree in Computer Science and Management from the University of the West Indies. Kwesi considers himself a full stack developer and looks forward to applying this knowledge to big data analysis. Linkedin Profile","title":"Kwesi Aguillera"},{"location":"team/#echhit-joshi","text":"About Echhit Joshi is a Masters student at the School of Computing and Information at University of Pittsburgh. His areas of interest are Machine/Deep Learning, Data Mining, and Analytics. Linkedin Profile","title":"Echhit Joshi"},{"location":"team/#nicolas-leo","text":"About Nicolas is a rising senior studying computer science at the University of Pittsburgh. His academic interests include databases, machine learning, and application development. After completing his undergraduate degree, he plans to attend graduate school for a MS in Computer Science with a focus on Intelligent Systems.","title":"Nicolas Leo"},{"location":"team/#nikunj-goel","text":"About Nik is a graduate student at the University of Pittsburgh pursuing Master of Science in Information Science. He earned his Bachelor of Technology degree in Information Technology from India. He is a Data Enthusiasts and passionate about finding the meaning out of raw data. In a long term, his goal is to create a breakthrough in Data Science and Deep Learning. Linkedin Profile","title":"Nikunj Goel"},{"location":"team/#community-contributors","text":"","title":"Community Contributors"},{"location":"team/#agam-kumar","text":"About Agam is a junior at Carnegie Mellon University studying Statistics and Machine Learning and pursuing an additional major in Computer Science. He is a member of the Data Science team in the Health and Human Performance Lab at CMU and has keen interests in software development and data science. His research interests include ML applications in medicine. Linkedin Profile Github Profile","title":"Agam Kumar"},{"location":"team/#yasaman-s-sefidgar","text":"About Linkedin Profile","title":"Yasaman S. Sefidgar"},{"location":"team/#advisors","text":"","title":"Advisors"},{"location":"team/#afsaneh-doryab","text":"About Personal Website","title":"Afsaneh Doryab"},{"location":"team/#carissa-low","text":"About Profile","title":"Carissa Low"},{"location":"developers/documentation/","text":"Documentation \u00b6 We use mkdocs with the material theme to write these docs. Whenever you make any changes, just push them back to the repo and the documentation will be deployed automatically. Set up development environment \u00b6 Make sure your conda environment is active pip install mkdocs pip install mkdocs-material Preview \u00b6 Run the following command in RAPIDS root folder and go to http://127.0.0.1:8000 : mkdocs serve File Structure \u00b6 The documentation config file is /mkdocs.yml , if you are adding new .md files to the docs modify the nav attribute at the bottom of that file. You can use the hierarchy there to find all the files that appear in the documentation. Reference \u00b6 Check this page to get familiar with the different visual elements we can use in the docs (admonitions, code blocks, tables, etc.) You can also refer to /docs/setup/installation.md and /docs/setup/configuration.md to see practical examples of these elements. Extras \u00b6 You can insert emojis using this syntax :[SOURCE]-[ICON_NAME] from the following sources: https://materialdesignicons.com/ https://fontawesome.com/icons/tasks?style=solid https://primer.style/octicons/ You can use this page to create markdown tables more easily","title":"Documentation"},{"location":"developers/documentation/#documentation","text":"We use mkdocs with the material theme to write these docs. Whenever you make any changes, just push them back to the repo and the documentation will be deployed automatically.","title":"Documentation"},{"location":"developers/documentation/#set-up-development-environment","text":"Make sure your conda environment is active pip install mkdocs pip install mkdocs-material","title":"Set up development environment"},{"location":"developers/documentation/#preview","text":"Run the following command in RAPIDS root folder and go to http://127.0.0.1:8000 : mkdocs serve","title":"Preview"},{"location":"developers/documentation/#file-structure","text":"The documentation config file is /mkdocs.yml , if you are adding new .md files to the docs modify the nav attribute at the bottom of that file. You can use the hierarchy there to find all the files that appear in the documentation.","title":"File Structure"},{"location":"developers/documentation/#reference","text":"Check this page to get familiar with the different visual elements we can use in the docs (admonitions, code blocks, tables, etc.) You can also refer to /docs/setup/installation.md and /docs/setup/configuration.md to see practical examples of these elements.","title":"Reference"},{"location":"developers/documentation/#extras","text":"You can insert emojis using this syntax :[SOURCE]-[ICON_NAME] from the following sources: https://materialdesignicons.com/ https://fontawesome.com/icons/tasks?style=solid https://primer.style/octicons/ You can use this page to create markdown tables more easily","title":"Extras"},{"location":"developers/remote-support/","text":"Remote Support \u00b6 We use the Live Share extension of Visual Studio Code to debug bugs when sharing data or database credentials is not possible. Install Visual Studio Code Open you RAPIDS root folder in a new VSCode window Open a new Terminal Terminal > New terminal Install the Live Share extension pack Press Ctrl + P or Cmd + P and run this command: >live share: start collaboration session 6. Follow the instructions and share the session link you receive","title":"Remote Support"},{"location":"developers/remote-support/#remote-support","text":"We use the Live Share extension of Visual Studio Code to debug bugs when sharing data or database credentials is not possible. Install Visual Studio Code Open you RAPIDS root folder in a new VSCode window Open a new Terminal Terminal > New terminal Install the Live Share extension pack Press Ctrl + P or Cmd + P and run this command: >live share: start collaboration session 6. Follow the instructions and share the session link you receive","title":"Remote Support"},{"location":"developers/test-cases/","text":"Test Cases \u00b6 Along with the continued development and the addition of new sensors and features to the RAPIDS pipeline, tests for the currently available sensors and features are being implemented. Since this is a Work In Progress this page will be updated with the list of sensors and features for which testing is available. For each of the sensors listed a description of the data used for testing (test cases) are outline. Currently for all intent and testing purposes the tests/data/raw/test01/ contains all the test data files for testing android data formats and tests/data/raw/test02/ contains all the test data files for testing iOS data formats. It follows that the expected (verified output) are contained in the tests/data/processed/test01/ and tests/data/processed/test02/ for Android and iOS respectively. tests/data/raw/test03/ and tests/data/raw/test04/ contain data files for testing empty raw data files for android and iOS respectively. The following is a list of the sensors that testing is currently available. Messages (SMS) \u00b6 The raw message data file contains data for 2 separate days. The data for the first day contains records 5 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The raw message data contains records for both message_types (i.e. recieved and sent ) in both days in all epochs. The number records with each message_types per epoch is randomly distributed There is at least one records with each message_types per epoch. There is one raw message data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files Calls \u00b6 Due to the difference in the format of the raw call data for iOS and Android the following is the expected results the calls_with_datetime_unified.csv . This would give a better idea of the use cases being tested since the calls_with_datetime_unified.csv would make both the iOS and Android data comparable. The call data would contain data for 2 days. The data for the first day contains 6 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The call data contains records for all call_types (i.e. incoming , outgoing and missed ) in both days in all epochs. The number records with each of the call_types per epoch is randomly distributed. There is at least one records with each call_types per epoch. There is one call data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files Screen \u00b6 Due to the difference in the format of the raw screen data for iOS and Android the following is the expected results the screen_deltas.csv . This would give a better idea of the use cases being tested since the screen_eltas.csv would make both the iOS and Android data comparable These files are used to calculate the features for the screen sensor The screen delta data file contains data for 1 day. The screen delta data contains 1 record to represent an unlock episode that falls within an epoch for every epoch . The screen delta data contains 1 record to represent an unlock episode that falls across the boundary of 2 epochs. Namely the unlock episode starts in one epoch and ends in the next, thus there is a record for unlock episodes that fall across night to morning , morning to afternoon and finally afternoon to night The testing is done for unlock episode_type. There is one screen data file each for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files Battery \u00b6 Due to the difference in the format of the raw battery data for iOS and Android as well as versions of iOS the following is the expected results the battery_deltas.csv . This would give a better idea of the use cases being tested since the battery_deltas.csv would make both the iOS and Android data comparable. These files are used to calculate the features for the battery sensor. The battery delta data file contains data for 1 day. The battery delta data contains 1 record each for a charging and discharging episode that falls within an epoch for every epoch . Thus, for the daily epoch there would be multiple charging and discharging episodes Since either a charging episode or a discharging episode and not both can occur across epochs, in order to test episodes that occur across epochs alternating episodes of charging and discharging episodes that fall across night to morning , morning to afternoon and finally afternoon to night are present in the battery delta data. This starts with a discharging episode that begins in night and end in morning . There is one battery data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files Bluetooth \u00b6 The raw Bluetooth data file contains data for 1 day. The raw Bluetooth data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) An option of 5 Bluetooth devices are randomly distributed throughout the data records. There is one raw Bluetooth data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files. WIFI \u00b6 There are 2 data files ( wifi_raw.csv and sensor_wifi_raw.csv ) for each fake participant for each phone platform. The raw WIFI data files contain data for 1 day. The sensor_wifi_raw.csv data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) The wifi_raw.csv data contains 3 records with random timestamps for each epoch to represent visible broadcasting WIFI network. This file is empty for the iOS phone testing data. An option of 10 access point devices is randomly distributed throughout the data records. 5 each for sensor_wifi_raw.csv and wifi_raw.csv . There data files for testing both iOS and Android data formats. There are also additional empty data files for both android and iOS for testing empty data files. Light \u00b6 The raw light data file contains data for 1 day. The raw light data contains 3 or 4 rows of data for each epoch except night . The single row of data for night is for testing features for single values inputs. (Example testing the standard deviation of one input value) Since light is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files. Application Foreground \u00b6 The raw application foreground data file contains data for 1 day. The raw application foreground data contains 7 - 9 rows of data for each epoch . The records for each epoch contains apps that are randomly selected from a list of apps that are from the MULTIPLE_CATEGORIES and SINGLE_CATEGORIES (See testing_config.yaml ). There are also records in each epoch that have apps randomly selected from a list of apps that are from the EXCLUDED_CATEGORIES and EXCLUDED_APPS . This is to test that these apps are actually being excluded from the calculations of features. There are also records to test SINGLE_APPS calculations. Since application foreground is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files. Activity Recognition \u00b6 The raw Activity Recognition data file contains data for 1 day. The raw Activity Recognition data each epoch period contains rows that records 2 - 5 different activity_types . The is such that durations of activities can be tested. Additionally, there are records that mimic the duration of an activity over the time boundary of neighboring epochs. (For example, there a set of records that mimic the participant in_vehicle from afternoon into evening ) There is one file each with raw Activity Recognition data for testing both iOS and Android data formats. (plugin_google_activity_recognition_raw.csv for android and plugin_ios_activity_recognition_raw.csv for iOS) There is also an additional empty data file for both android and iOS for testing empty data files. Conversation \u00b6 The raw conversation data file contains data for 2 day. The raw conversation data contains records with a sample of both datatypes (i.e. voice/noise = 0 , and conversation = 2 ) as well as rows with for samples of each of the inference values (i.e. silence = 0 , noise = 1 , voice = 2 , and unknown = 3 ) for each epoch . The different datatype and inference records are randomly distributed throughout the epoch . Additionally there are 2 - 5 records for conversations ( datatype = 2, and inference = -1) in each epoch and for each epoch except night, there is a conversation record that has a double_convo_start timestamp that is from the previous epoch . This is to test the calculations of features across epochs . There is a raw conversation data file for both android and iOS platforms ( plugin_studentlife_audio_android_raw.csv and plugin_studentlife_audio_raw.csv respectively). Finally, there are also additional empty data files for both android and iOS for testing empty data files","title":"Test cases"},{"location":"developers/test-cases/#test-cases","text":"Along with the continued development and the addition of new sensors and features to the RAPIDS pipeline, tests for the currently available sensors and features are being implemented. Since this is a Work In Progress this page will be updated with the list of sensors and features for which testing is available. For each of the sensors listed a description of the data used for testing (test cases) are outline. Currently for all intent and testing purposes the tests/data/raw/test01/ contains all the test data files for testing android data formats and tests/data/raw/test02/ contains all the test data files for testing iOS data formats. It follows that the expected (verified output) are contained in the tests/data/processed/test01/ and tests/data/processed/test02/ for Android and iOS respectively. tests/data/raw/test03/ and tests/data/raw/test04/ contain data files for testing empty raw data files for android and iOS respectively. The following is a list of the sensors that testing is currently available.","title":"Test Cases"},{"location":"developers/test-cases/#messages-sms","text":"The raw message data file contains data for 2 separate days. The data for the first day contains records 5 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The raw message data contains records for both message_types (i.e. recieved and sent ) in both days in all epochs. The number records with each message_types per epoch is randomly distributed There is at least one records with each message_types per epoch. There is one raw message data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Messages (SMS)"},{"location":"developers/test-cases/#calls","text":"Due to the difference in the format of the raw call data for iOS and Android the following is the expected results the calls_with_datetime_unified.csv . This would give a better idea of the use cases being tested since the calls_with_datetime_unified.csv would make both the iOS and Android data comparable. The call data would contain data for 2 days. The data for the first day contains 6 records for every epoch . The second day's data contains 6 records for each of only 2 epoch (currently morning and evening ) The call data contains records for all call_types (i.e. incoming , outgoing and missed ) in both days in all epochs. The number records with each of the call_types per epoch is randomly distributed. There is at least one records with each call_types per epoch. There is one call data file each, as described above, for testing both iOS and Android data. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Calls"},{"location":"developers/test-cases/#screen","text":"Due to the difference in the format of the raw screen data for iOS and Android the following is the expected results the screen_deltas.csv . This would give a better idea of the use cases being tested since the screen_eltas.csv would make both the iOS and Android data comparable These files are used to calculate the features for the screen sensor The screen delta data file contains data for 1 day. The screen delta data contains 1 record to represent an unlock episode that falls within an epoch for every epoch . The screen delta data contains 1 record to represent an unlock episode that falls across the boundary of 2 epochs. Namely the unlock episode starts in one epoch and ends in the next, thus there is a record for unlock episodes that fall across night to morning , morning to afternoon and finally afternoon to night The testing is done for unlock episode_type. There is one screen data file each for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Screen"},{"location":"developers/test-cases/#battery","text":"Due to the difference in the format of the raw battery data for iOS and Android as well as versions of iOS the following is the expected results the battery_deltas.csv . This would give a better idea of the use cases being tested since the battery_deltas.csv would make both the iOS and Android data comparable. These files are used to calculate the features for the battery sensor. The battery delta data file contains data for 1 day. The battery delta data contains 1 record each for a charging and discharging episode that falls within an epoch for every epoch . Thus, for the daily epoch there would be multiple charging and discharging episodes Since either a charging episode or a discharging episode and not both can occur across epochs, in order to test episodes that occur across epochs alternating episodes of charging and discharging episodes that fall across night to morning , morning to afternoon and finally afternoon to night are present in the battery delta data. This starts with a discharging episode that begins in night and end in morning . There is one battery data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files","title":"Battery"},{"location":"developers/test-cases/#bluetooth","text":"The raw Bluetooth data file contains data for 1 day. The raw Bluetooth data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) An option of 5 Bluetooth devices are randomly distributed throughout the data records. There is one raw Bluetooth data file each, for testing both iOS and Android data formats. There is also an additional empty data file for both android and iOS for testing empty data files.","title":"Bluetooth"},{"location":"developers/test-cases/#wifi","text":"There are 2 data files ( wifi_raw.csv and sensor_wifi_raw.csv ) for each fake participant for each phone platform. The raw WIFI data files contain data for 1 day. The sensor_wifi_raw.csv data contains at least 2 records for each epoch . Each epoch has a record with a timestamp for the beginning boundary for that epoch and a record with a timestamp for the ending boundary for that epoch . (e.g. For the morning epoch there is a record with a timestamp for 6:00AM and another record with a timestamp for 11:59:59AM . These are to test edge cases) The wifi_raw.csv data contains 3 records with random timestamps for each epoch to represent visible broadcasting WIFI network. This file is empty for the iOS phone testing data. An option of 10 access point devices is randomly distributed throughout the data records. 5 each for sensor_wifi_raw.csv and wifi_raw.csv . There data files for testing both iOS and Android data formats. There are also additional empty data files for both android and iOS for testing empty data files.","title":"WIFI"},{"location":"developers/test-cases/#light","text":"The raw light data file contains data for 1 day. The raw light data contains 3 or 4 rows of data for each epoch except night . The single row of data for night is for testing features for single values inputs. (Example testing the standard deviation of one input value) Since light is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files.","title":"Light"},{"location":"developers/test-cases/#application-foreground","text":"The raw application foreground data file contains data for 1 day. The raw application foreground data contains 7 - 9 rows of data for each epoch . The records for each epoch contains apps that are randomly selected from a list of apps that are from the MULTIPLE_CATEGORIES and SINGLE_CATEGORIES (See testing_config.yaml ). There are also records in each epoch that have apps randomly selected from a list of apps that are from the EXCLUDED_CATEGORIES and EXCLUDED_APPS . This is to test that these apps are actually being excluded from the calculations of features. There are also records to test SINGLE_APPS calculations. Since application foreground is only available for Android there is only one file that contains data for Android. All other files (i.e. for iPhone) are empty data files.","title":"Application Foreground"},{"location":"developers/test-cases/#activity-recognition","text":"The raw Activity Recognition data file contains data for 1 day. The raw Activity Recognition data each epoch period contains rows that records 2 - 5 different activity_types . The is such that durations of activities can be tested. Additionally, there are records that mimic the duration of an activity over the time boundary of neighboring epochs. (For example, there a set of records that mimic the participant in_vehicle from afternoon into evening ) There is one file each with raw Activity Recognition data for testing both iOS and Android data formats. (plugin_google_activity_recognition_raw.csv for android and plugin_ios_activity_recognition_raw.csv for iOS) There is also an additional empty data file for both android and iOS for testing empty data files.","title":"Activity Recognition"},{"location":"developers/test-cases/#conversation","text":"The raw conversation data file contains data for 2 day. The raw conversation data contains records with a sample of both datatypes (i.e. voice/noise = 0 , and conversation = 2 ) as well as rows with for samples of each of the inference values (i.e. silence = 0 , noise = 1 , voice = 2 , and unknown = 3 ) for each epoch . The different datatype and inference records are randomly distributed throughout the epoch . Additionally there are 2 - 5 records for conversations ( datatype = 2, and inference = -1) in each epoch and for each epoch except night, there is a conversation record that has a double_convo_start timestamp that is from the previous epoch . This is to test the calculations of features across epochs . There is a raw conversation data file for both android and iOS platforms ( plugin_studentlife_audio_android_raw.csv and plugin_studentlife_audio_raw.csv respectively). Finally, there are also additional empty data files for both android and iOS for testing empty data files","title":"Conversation"},{"location":"developers/testing/","text":"Testing \u00b6 The following is a simple guide to testing RAPIDS. All files necessary for testing are stored in the /tests directory Steps for Testing \u00b6 To begin testing RAPIDS place the fake raw input data csv files in tests/data/raw/ . The fake participant files should be placed in tests/data/external/ . The expected output files of RAPIDS after processing the input data should be placed in tests/data/processesd/ . The Snakemake rule(s) that are to be tested must be placed in the tests/Snakemake file. The current tests/Snakemake is a good example of how to define them. (At the time of writing this documentation the snakefile contains rules messages (SMS), calls and screen) Edit the tests/settings/config.yaml . Add and/or remove the rules to be run for testing from the forcerun list. Edit the tests/settings/testing_config.yaml with the necessary configuration settings for running the rules to be tested. Add any additional testscripts in tests/scripts . Uncomment or comment off lines in the testing shell script tests/scripts/run_tests.sh . Run the testing shell script. tests/scripts/run_tests.sh The following is a snippet of the output you should see after running your test. test_sensors_files_exist ( test_sensor_features.TestSensorFeatures ) ... ok test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ... FAIL ====================================================================== FAIL: test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ---------------------------------------------------------------------- The results above show that the first test test_sensors_files_exist passed while test_sensors_features_calculations failed. In addition you should get the traceback of the failure (not shown here). For more information on how to implement test scripts and use unittest please see Unittest Documentation Testing of the RAPIDS sensors and features is a work-in-progress. Please see test-cases for a list of sensors and features that have testing currently available. Currently the repository is set up to test a number of sensors out of the box by simply running the tests/scripts/run_tests.sh command once the RAPIDS python environment is active.","title":"Testing"},{"location":"developers/testing/#testing","text":"The following is a simple guide to testing RAPIDS. All files necessary for testing are stored in the /tests directory","title":"Testing"},{"location":"developers/testing/#steps-for-testing","text":"To begin testing RAPIDS place the fake raw input data csv files in tests/data/raw/ . The fake participant files should be placed in tests/data/external/ . The expected output files of RAPIDS after processing the input data should be placed in tests/data/processesd/ . The Snakemake rule(s) that are to be tested must be placed in the tests/Snakemake file. The current tests/Snakemake is a good example of how to define them. (At the time of writing this documentation the snakefile contains rules messages (SMS), calls and screen) Edit the tests/settings/config.yaml . Add and/or remove the rules to be run for testing from the forcerun list. Edit the tests/settings/testing_config.yaml with the necessary configuration settings for running the rules to be tested. Add any additional testscripts in tests/scripts . Uncomment or comment off lines in the testing shell script tests/scripts/run_tests.sh . Run the testing shell script. tests/scripts/run_tests.sh The following is a snippet of the output you should see after running your test. test_sensors_files_exist ( test_sensor_features.TestSensorFeatures ) ... ok test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ... FAIL ====================================================================== FAIL: test_sensors_features_calculations ( test_sensor_features.TestSensorFeatures ) ---------------------------------------------------------------------- The results above show that the first test test_sensors_files_exist passed while test_sensors_features_calculations failed. In addition you should get the traceback of the failure (not shown here). For more information on how to implement test scripts and use unittest please see Unittest Documentation Testing of the RAPIDS sensors and features is a work-in-progress. Please see test-cases for a list of sensors and features that have testing currently available. Currently the repository is set up to test a number of sensors out of the box by simply running the tests/scripts/run_tests.sh command once the RAPIDS python environment is active.","title":"Steps for Testing"},{"location":"developers/virtual-environments/","text":"Virtual Environments \u00b6 Add new packages \u00b6 Try to install any new package using conda . If a package is not available in one of conda \u2018s channels you can install it with pip but make sure your virtual environment is active. Update your conda environment.yaml \u00b6 After installing a new package you can use the following command in your terminal to update your environment.yaml before publishing your pipeline. Note that we ignore the package version for libfortran to keep compatibility with Linux: conda env export --no-builds | sed 's/^.*libgfortran.*$/ - libgfortran/' > environment.yml Update and prune your conda environment from a environment.yaml file \u00b6 Execute the following command in your terminal, see these docs for more information conda env update --prefix ./env --file environment.yml --prune","title":"Virtual Environments"},{"location":"developers/virtual-environments/#virtual-environments","text":"","title":"Virtual Environments"},{"location":"developers/virtual-environments/#add-new-packages","text":"Try to install any new package using conda . If a package is not available in one of conda \u2018s channels you can install it with pip but make sure your virtual environment is active.","title":"Add new packages"},{"location":"developers/virtual-environments/#update-your-conda-environmentyaml","text":"After installing a new package you can use the following command in your terminal to update your environment.yaml before publishing your pipeline. Note that we ignore the package version for libfortran to keep compatibility with Linux: conda env export --no-builds | sed 's/^.*libgfortran.*$/ - libgfortran/' > environment.yml","title":"Update your conda environment.yaml"},{"location":"developers/virtual-environments/#update-and-prune-your-conda-environment-from-a-environmentyaml-file","text":"Execute the following command in your terminal, see these docs for more information conda env update --prefix ./env --file environment.yml --prune","title":"Update and prune your conda environment from a environment.yaml file"},{"location":"features/add-new-features/","text":"Add New Features \u00b6 Hint We recommend reading the Behavioral Features Introduction before reading this page Hint You won\u2019t have to deal with time zones, dates, times, data cleaning or preprocessing. The data that RAPIDS pipes to your feature extraction code is ready to process. New Features for Existing Sensors \u00b6 You can add new features to any existing sensors (see list below) by adding a new provider in three steps: Modify the config.yaml file Create a provider folder, script and function Implement your features extraction code As a tutorial, we will add a new provider for PHONE_ACCELEROMETER called VEGA that extracts feature1 , feature2 , feature3 in Python and that it requires a parameter from the user called MY_PARAMETER . Existing Sensors An existing sensor is any of the phone or Fitbit sensors with a configuration entry in config.yaml : Phone Accelerometer Phone Activity Recognition Phone Applications Foreground Phone Battery Phone Bluetooth Phone Calls Phone Conversation Phone Light Phone Locations Phone Messages Phone Screen Phone WiFI Connected Phone WiFI Visible Modify the config.yaml file \u00b6 In this step you need to add your provider configuration section under the relevant sensor in config.yaml . See our example for our tutorial\u2019s VEGA provider for PHONE_ACCELEROMETER : Example configuration for a new accelerometer provider VEGA PHONE_ACCELEROMETER : TABLE : accelerometer PROVIDERS : RAPIDS : COMPUTE : False ... PANDA : COMPUTE : False ... VEGA : COMPUTE : False FEATURES : [ \"feature1\" , \"feature2\" , \"feature3\" ] MY_PARAMTER : a_string SRC_FOLDER : \"vega\" SRC_LANGUAGE : \"python\" Key Description [COMPUTE] Flag to activate/deactivate your provider [FEATURES] List of features your provider supports. Your provider code should only return the features on this list [MY_PARAMTER] An arbitrary parameter that our example provider VEGA needs. This can be a boolean, integer, float, string or an array of any of such types. [SRC_LANGUAGE] The programming language of your provider script, it can be python or r , in our example python [SRC_FOLDER] The name of your provider in lower case, in our example vega (this will be the name of your folder in the next step) Create a provider folder, script and function \u00b6 In this step you need to add a folder, script and function for your provider. Create your provider folder under src/feature/DEVICE_SENSOR/YOUR_PROVIDER , in our example src/feature/phone_accelerometer/vega (same as [SRC_FOLDER] in the step above). Create your provider script inside your provider folder, it can be a Python file called main.py or an R file called main.R . Add your provider function in your provider script. The name of such function should be [providername]_features , in our example vega_features Python function def [ providername ] _features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): R function [ providername ] _ features <- function ( sensor_data , day_segment , provider ) Implement your feature extraction code \u00b6 The provider function that you created in the step above will receive the following parameters: Parameter Description sensor_data_files Path to the CSV file containing the data of a single participant. This data has been cleaned and preprocessed. Your function will be automatically called for each participant in your study (in the [PIDS] array in config.yaml ) day_segment The label of the day segment that should be processed. provider The parameters you configured for your provider in config.yaml will be available in this variable as a dictionary in Python or a list in R. In our example this dictionary contains {MY_PARAMETER:\"a_string\"} filter_data_by_segment Python only. A function that you will use to filter your data. In R this function is already available in the environment. *args Python only. Not used for now **kwargs Python only. Not used for now The code to extract your behavioral features should be implemented in your provider function and in general terms it will have three stages: 1. Read a participant\u2019s data by loading the CSV data stored in the file pointed by sensor_data_files acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) Note that phone\u2019s battery, screen, and activity recognition data is given as episodes instead of event rows (for example, start and end timestamps of the periods the phone screen was on) 2. Filter your data to process only those rows that belong to day_segment This step is only one line of code, but to undersand why we need it, keep reading. acc_data = filter_data_by_segment ( acc_data , day_segment ) You should use the filter_data_by_segment() function to process and group those rows that belong to each of the day segments RAPIDS could be configured with . Let\u2019s understand the filter_data_by_segment() function with an example. A RAPIDS user can extract features on any arbitrary day segment . A day segment is a period of time that has a label and one or more instances. For example, the user (or you) could have requested features on a daily, weekly, and week-end basis for p01 . The labels are arbritrary and the instances depend on the days a participant was monitored for: the daily segment could be named my_days and if p01 was monitored for 14 days, it would have 14 instances the weekly segment could be named my_weeks and if p01 was monitored for 14 days, it would have 2 instances. the weekend segment could be named my_weekends and if p01 was monitored for 14 days, it would have 2 instances. For this example, RAPIDS will call your provider function three times for p01 , once where day_segment is my_days , once where day_segment is my_weeks and once where day_segment is my_weekends . In this example not every row in p01 \u2018s data needs to take part in the feature computation for either segment and the rows need to be grouped differently. Thus filter_data_by_segment() comes in handy, it will return a data frame that contains the rows that were logged during a day segment plus an extra column called local_segment . This new column will have as many unique values as day segment instances exist (14, 2, and 2 for our p01 \u2018s my_days , my_weeks , and my_weekends examples). After filtering, you should group the data frame by this column and compute any desired features , for example: acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () The reason RAPIDS does not filter the participant\u2019s data set for you is because your code might need to compute something based on a participant\u2019s complete dataset before computing their features. For example, you might want to identify the number that called a participant the most throughout the study before computing a feature with the number of calls the participant received from this number. 3. Return a data frame with your features After filtering, grouping your data, and computing your features, your provider function should return a data frame that has: One row per day segment instance (e.g. 14 our p01 \u2018s my_days example) The local_segment column added by filter_data_by_segment() One column per feature. Your feature columns should be named SENSOR_PROVIDER_FEATURE , for example accelerometr_vega_feature1 PHONE_ACCELEROMETER Provider Example For your reference, this a short example of our own provider ( RAPIDS ) for PHONE_ACCELEROMETER that computes five acceleration features def rapids_features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) requested_features = provider [ \"FEATURES\" ] # name of the features this function can compute base_features_names = [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] # the subset of requested features this function can compute features_to_compute = list ( set ( requested_features ) & set ( base_features_names )) acc_features = pd . DataFrame ( columns = [ \"local_segment\" ] + [ \"acc_rapids_\" + x for x in features_to_compute ]) if not acc_data . empty : acc_data = filter_data_by_segment ( acc_data , day_segment ) if not acc_data . empty : acc_features = pd . DataFrame () # get magnitude related features: magnitude = sqrt(x^2+y^2+z^2) magnitude = acc_data . apply ( lambda row : np . sqrt ( row [ \"double_values_0\" ] ** 2 + row [ \"double_values_1\" ] ** 2 + row [ \"double_values_2\" ] ** 2 ), axis = 1 ) acc_data = acc_data . assign ( magnitude = magnitude . values ) if \"maxmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () if \"minmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_minmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . min () if \"avgmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_avgmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . mean () if \"medianmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_medianmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . median () if \"stdmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_stdmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . std () acc_features = acc_features . reset_index () return acc_features New Features for Non-Existing Sensors \u00b6 If you want to add features for a device or a sensor that we do not support at the moment (those that do not appear in the \"Existing Sensors\" list above), contact us or request it on Slack and we can add the necessary code so you can follow the instructions above.","title":"Add New Features"},{"location":"features/add-new-features/#add-new-features","text":"Hint We recommend reading the Behavioral Features Introduction before reading this page Hint You won\u2019t have to deal with time zones, dates, times, data cleaning or preprocessing. The data that RAPIDS pipes to your feature extraction code is ready to process.","title":"Add New Features"},{"location":"features/add-new-features/#new-features-for-existing-sensors","text":"You can add new features to any existing sensors (see list below) by adding a new provider in three steps: Modify the config.yaml file Create a provider folder, script and function Implement your features extraction code As a tutorial, we will add a new provider for PHONE_ACCELEROMETER called VEGA that extracts feature1 , feature2 , feature3 in Python and that it requires a parameter from the user called MY_PARAMETER . Existing Sensors An existing sensor is any of the phone or Fitbit sensors with a configuration entry in config.yaml : Phone Accelerometer Phone Activity Recognition Phone Applications Foreground Phone Battery Phone Bluetooth Phone Calls Phone Conversation Phone Light Phone Locations Phone Messages Phone Screen Phone WiFI Connected Phone WiFI Visible","title":"New Features for Existing Sensors"},{"location":"features/add-new-features/#modify-the-configyaml-file","text":"In this step you need to add your provider configuration section under the relevant sensor in config.yaml . See our example for our tutorial\u2019s VEGA provider for PHONE_ACCELEROMETER : Example configuration for a new accelerometer provider VEGA PHONE_ACCELEROMETER : TABLE : accelerometer PROVIDERS : RAPIDS : COMPUTE : False ... PANDA : COMPUTE : False ... VEGA : COMPUTE : False FEATURES : [ \"feature1\" , \"feature2\" , \"feature3\" ] MY_PARAMTER : a_string SRC_FOLDER : \"vega\" SRC_LANGUAGE : \"python\" Key Description [COMPUTE] Flag to activate/deactivate your provider [FEATURES] List of features your provider supports. Your provider code should only return the features on this list [MY_PARAMTER] An arbitrary parameter that our example provider VEGA needs. This can be a boolean, integer, float, string or an array of any of such types. [SRC_LANGUAGE] The programming language of your provider script, it can be python or r , in our example python [SRC_FOLDER] The name of your provider in lower case, in our example vega (this will be the name of your folder in the next step)","title":"Modify the config.yaml file"},{"location":"features/add-new-features/#create-a-provider-folder-script-and-function","text":"In this step you need to add a folder, script and function for your provider. Create your provider folder under src/feature/DEVICE_SENSOR/YOUR_PROVIDER , in our example src/feature/phone_accelerometer/vega (same as [SRC_FOLDER] in the step above). Create your provider script inside your provider folder, it can be a Python file called main.py or an R file called main.R . Add your provider function in your provider script. The name of such function should be [providername]_features , in our example vega_features Python function def [ providername ] _features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): R function [ providername ] _ features <- function ( sensor_data , day_segment , provider )","title":"Create a provider folder, script and function"},{"location":"features/add-new-features/#implement-your-feature-extraction-code","text":"The provider function that you created in the step above will receive the following parameters: Parameter Description sensor_data_files Path to the CSV file containing the data of a single participant. This data has been cleaned and preprocessed. Your function will be automatically called for each participant in your study (in the [PIDS] array in config.yaml ) day_segment The label of the day segment that should be processed. provider The parameters you configured for your provider in config.yaml will be available in this variable as a dictionary in Python or a list in R. In our example this dictionary contains {MY_PARAMETER:\"a_string\"} filter_data_by_segment Python only. A function that you will use to filter your data. In R this function is already available in the environment. *args Python only. Not used for now **kwargs Python only. Not used for now The code to extract your behavioral features should be implemented in your provider function and in general terms it will have three stages: 1. Read a participant\u2019s data by loading the CSV data stored in the file pointed by sensor_data_files acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) Note that phone\u2019s battery, screen, and activity recognition data is given as episodes instead of event rows (for example, start and end timestamps of the periods the phone screen was on) 2. Filter your data to process only those rows that belong to day_segment This step is only one line of code, but to undersand why we need it, keep reading. acc_data = filter_data_by_segment ( acc_data , day_segment ) You should use the filter_data_by_segment() function to process and group those rows that belong to each of the day segments RAPIDS could be configured with . Let\u2019s understand the filter_data_by_segment() function with an example. A RAPIDS user can extract features on any arbitrary day segment . A day segment is a period of time that has a label and one or more instances. For example, the user (or you) could have requested features on a daily, weekly, and week-end basis for p01 . The labels are arbritrary and the instances depend on the days a participant was monitored for: the daily segment could be named my_days and if p01 was monitored for 14 days, it would have 14 instances the weekly segment could be named my_weeks and if p01 was monitored for 14 days, it would have 2 instances. the weekend segment could be named my_weekends and if p01 was monitored for 14 days, it would have 2 instances. For this example, RAPIDS will call your provider function three times for p01 , once where day_segment is my_days , once where day_segment is my_weeks and once where day_segment is my_weekends . In this example not every row in p01 \u2018s data needs to take part in the feature computation for either segment and the rows need to be grouped differently. Thus filter_data_by_segment() comes in handy, it will return a data frame that contains the rows that were logged during a day segment plus an extra column called local_segment . This new column will have as many unique values as day segment instances exist (14, 2, and 2 for our p01 \u2018s my_days , my_weeks , and my_weekends examples). After filtering, you should group the data frame by this column and compute any desired features , for example: acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () The reason RAPIDS does not filter the participant\u2019s data set for you is because your code might need to compute something based on a participant\u2019s complete dataset before computing their features. For example, you might want to identify the number that called a participant the most throughout the study before computing a feature with the number of calls the participant received from this number. 3. Return a data frame with your features After filtering, grouping your data, and computing your features, your provider function should return a data frame that has: One row per day segment instance (e.g. 14 our p01 \u2018s my_days example) The local_segment column added by filter_data_by_segment() One column per feature. Your feature columns should be named SENSOR_PROVIDER_FEATURE , for example accelerometr_vega_feature1 PHONE_ACCELEROMETER Provider Example For your reference, this a short example of our own provider ( RAPIDS ) for PHONE_ACCELEROMETER that computes five acceleration features def rapids_features ( sensor_data_files , day_segment , provider , filter_data_by_segment , * args , ** kwargs ): acc_data = pd . read_csv ( sensor_data_files [ \"sensor_data\" ]) requested_features = provider [ \"FEATURES\" ] # name of the features this function can compute base_features_names = [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] # the subset of requested features this function can compute features_to_compute = list ( set ( requested_features ) & set ( base_features_names )) acc_features = pd . DataFrame ( columns = [ \"local_segment\" ] + [ \"acc_rapids_\" + x for x in features_to_compute ]) if not acc_data . empty : acc_data = filter_data_by_segment ( acc_data , day_segment ) if not acc_data . empty : acc_features = pd . DataFrame () # get magnitude related features: magnitude = sqrt(x^2+y^2+z^2) magnitude = acc_data . apply ( lambda row : np . sqrt ( row [ \"double_values_0\" ] ** 2 + row [ \"double_values_1\" ] ** 2 + row [ \"double_values_2\" ] ** 2 ), axis = 1 ) acc_data = acc_data . assign ( magnitude = magnitude . values ) if \"maxmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_maxmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . max () if \"minmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_minmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . min () if \"avgmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_avgmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . mean () if \"medianmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_medianmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . median () if \"stdmagnitude\" in features_to_compute : acc_features [ \"acc_rapids_stdmagnitude\" ] = acc_data . groupby ([ \"local_segment\" ])[ \"magnitude\" ] . std () acc_features = acc_features . reset_index () return acc_features","title":"Implement your feature extraction code"},{"location":"features/add-new-features/#new-features-for-non-existing-sensors","text":"If you want to add features for a device or a sensor that we do not support at the moment (those that do not appear in the \"Existing Sensors\" list above), contact us or request it on Slack and we can add the necessary code so you can follow the instructions above.","title":"New Features for Non-Existing Sensors"},{"location":"features/feature-introduction/","text":"Behavioral Features Introduction \u00b6 Every phone or Fitbit sensor has a corresponding config section in config.yaml , these sections follow a similar structure and we\u2019ll use PHONE_ACCELEROMETER as an example to explain this structure. Hint We recommend reading this page if you are using RAPIDS for the first time Config section example for PHONE_ACCELEROMETER # 1) Config section PHONE_ACCELEROMETER : # 2) Parameters for PHONE_ACCELEROMETER TABLE : accelerometer # 3) Providers for PHONE_ACCELEROMETER PROVIDERS : # 4) RAPIDS provider RAPIDS : # 4.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False # 4.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] SRC_FOLDER : \"rapids\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\" # 5) PANDA provider PANDA : # 5.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False VALID_SENSED_MINUTES : False # 5.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : exertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] nonexertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] SRC_FOLDER : \"panda\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\" Sensor Parameters \u00b6 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 download, and processed. The TABLE parameter exists for every sensor, but some sensors will have extra para meters like [PHONE_LOCATIONS] . We explain these parameters in a table at the top of each sensor documentation page. Sensor Providers \u00b6 Each sensor configuration section can have zero, one or more behavioral feature providers (see #2 in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. For this accelerometer example we have two providers RAPIDS (see #4 ) and PANDA (see #5 ). Provider Parameters \u00b6 Each provider has parameters that affect the computation of the behavioral features it offers (see #4.1 or #5.1 in the example). These parameters will include at least a [COMPUTE] flag that you switch to True to extract a provider\u2019s behavioral features. We explain each provider parameter in a table under the Parameters description heading on each provider documentation page. Provider Features \u00b6 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\u2019s output feature file. We explain each behavioral feature in a table under the Features description heading on each provider documentation page. Hint Every time you change any sensor parameters, provider parameters or provider features, all the necessary files will be updated as soon as you execute RAPIDS.","title":"Introduction"},{"location":"features/feature-introduction/#behavioral-features-introduction","text":"Every phone or Fitbit sensor has a corresponding config section in config.yaml , these sections follow a similar structure and we\u2019ll use PHONE_ACCELEROMETER as an example to explain this structure. Hint We recommend reading this page if you are using RAPIDS for the first time Config section example for PHONE_ACCELEROMETER # 1) Config section PHONE_ACCELEROMETER : # 2) Parameters for PHONE_ACCELEROMETER TABLE : accelerometer # 3) Providers for PHONE_ACCELEROMETER PROVIDERS : # 4) RAPIDS provider RAPIDS : # 4.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False # 4.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : [ \"maxmagnitude\" , \"minmagnitude\" , \"avgmagnitude\" , \"medianmagnitude\" , \"stdmagnitude\" ] SRC_FOLDER : \"rapids\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\" # 5) PANDA provider PANDA : # 5.1) Parameters of RAPIDS provider of PHONE_ACCELEROMETER COMPUTE : False VALID_SENSED_MINUTES : False # 5.2) Features of RAPIDS provider of PHONE_ACCELEROMETER FEATURES : exertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] nonexertional_activity_episode : [ \"sumduration\" , \"maxduration\" , \"minduration\" , \"avgduration\" , \"medianduration\" , \"stdduration\" ] SRC_FOLDER : \"panda\" # inside src/features/phone_accelerometer SRC_LANGUAGE : \"python\"","title":"Behavioral Features Introduction"},{"location":"features/feature-introduction/#sensor-parameters","text":"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 download, and processed. The TABLE parameter exists for every sensor, but some sensors will have extra para meters like [PHONE_LOCATIONS] . We explain these parameters in a table at the top of each sensor documentation page.","title":"Sensor Parameters"},{"location":"features/feature-introduction/#sensor-providers","text":"Each sensor configuration section can have zero, one or more behavioral feature providers (see #2 in the example). A provider is a script created by the core RAPIDS team or other researchers that extracts behavioral features for that sensor. For this accelerometer example we have two providers RAPIDS (see #4 ) and PANDA (see #5 ).","title":"Sensor Providers"},{"location":"features/feature-introduction/#provider-parameters","text":"Each provider has parameters that affect the computation of the behavioral features it offers (see #4.1 or #5.1 in the example). These parameters will include at least a [COMPUTE] flag that you switch to True to extract a provider\u2019s behavioral features. We explain each provider parameter in a table under the Parameters description heading on each provider documentation page.","title":"Provider Parameters"},{"location":"features/feature-introduction/#provider-features","text":"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\u2019s output feature file. We explain each behavioral feature in a table under the Features description heading on each provider documentation page. Hint Every time you change any sensor parameters, provider parameters or provider features, all the necessary files will be updated as soon as you execute RAPIDS.","title":"Provider Features"},{"location":"features/phone-accelerometer/","text":"Phone Accelerometer \u00b6 Sensor parameters description for [PHONE_ACCELEROMETER] : Key Description [TABLE] Database table where the accelerometer data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Feature Units Description maxmagnitude m/s 2 The maximum magnitude of acceleration ( \\(\\|acceleration\\| = \\sqrt{x^2 + y^2 + z^2}\\) ). minmagnitude m/s 2 The minimum magnitude of acceleration. avgmagnitude m/s 2 The average magnitude of acceleration. medianmagnitude m/s 2 The median magnitude of acceleration. stdmagnitude m/s 2 The standard deviation of acceleration. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem. PANDA provider \u00b6 These features are based on the work by Panda et al . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the PANDA provider [FEATURES] Features to be computed for exertional and non-exertional activity episodes, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Feature Units Description sumduration minutes Total duration of all exertional or non-exertional activity episodes. maxduration minutes Longest duration of any exertional or non-exertional activity episode. minduration minutes Shortest duration of any exertional or non-exertional activity episode. avgduration minutes Average duration of any exertional or non-exertional activity episode. medianduration minutes Median duration of any exertional or non-exertional activity episode. stdduration minutes Standard deviation of the duration of all exertional or non-exertional activity episodes. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem. See Panda et al for a definition of exertional and non-exertional activity episodes","title":"Phone Accelerometer"},{"location":"features/phone-accelerometer/#phone-accelerometer","text":"Sensor parameters description for [PHONE_ACCELEROMETER] : Key Description [TABLE] Database table where the accelerometer data is stored","title":"Phone Accelerometer"},{"location":"features/phone-accelerometer/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][RAPIDS] : Feature Units Description maxmagnitude m/s 2 The maximum magnitude of acceleration ( \\(\\|acceleration\\| = \\sqrt{x^2 + y^2 + z^2}\\) ). minmagnitude m/s 2 The minimum magnitude of acceleration. avgmagnitude m/s 2 The average magnitude of acceleration. medianmagnitude m/s 2 The median magnitude of acceleration. stdmagnitude m/s 2 The standard deviation of acceleration. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem.","title":"RAPIDS provider"},{"location":"features/phone-accelerometer/#panda-provider","text":"These features are based on the work by Panda et al . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_accelerometer_raw.csv - data/raw/ { pid } /phone_accelerometer_with_datetime.csv - data/interim/ { pid } /phone_accelerometer_features/phone_accelerometer_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_accelerometer.csv Parameters description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Key Description [COMPUTE] Set to True to extract PHONE_ACCELEROMETER features from the PANDA provider [FEATURES] Features to be computed for exertional and non-exertional activity episodes, see table below Features description for [PHONE_ACCELEROMETER][PROVIDERS][PANDA] : Feature Units Description sumduration minutes Total duration of all exertional or non-exertional activity episodes. maxduration minutes Longest duration of any exertional or non-exertional activity episode. minduration minutes Shortest duration of any exertional or non-exertional activity episode. avgduration minutes Average duration of any exertional or non-exertional activity episode. medianduration minutes Median duration of any exertional or non-exertional activity episode. stdduration minutes Standard deviation of the duration of all exertional or non-exertional activity episodes. Assumptions/Observations Analyzing accelerometer data is a memory intensive task. If RAPIDS crashes is likely because the accelerometer dataset for a participant is to big to fit in memory. We are considering different alternatives to overcome this problem. See Panda et al for a definition of exertional and non-exertional activity episodes","title":"PANDA provider"},{"location":"features/phone-activity-recognition/","text":"Phone Activity Recognition \u00b6 Sensor parameters description for [PHONE_ACTIVITY_RECOGNITION] : Key Description [TABLE][ANDROID] Database table where the activity data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the activity data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS) [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same activity episode RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_activity_recognition_raw.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime_unified.csv - data/interim/ { pid } /phone_activity_recognition_episodes.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_activity_recognition_features/phone_activity_recognition_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_activity_recognition.csv Parameters description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACTIVITY_RECOGNITION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [ACTIVITY_CLASSES][STATIONARY] An array of the activity labels to be considered in the STATIONARY category choose any of still , tilting [ACTIVITY_CLASSES][MOBILE] An array of the activity labels to be considered in the MOBILE category choose any of on_foot , walking , running , on_bicycle [ACTIVITY_CLASSES][VEHICLE] An array of the activity labels to be considered in the VEHICLE category choose any of in_vehicule Features description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Feature Units Description count rows Number of episodes. mostcommonactivity activity type The most common activity type (e.g. still , on_foot , etc.). If there is a tie, the first one is chosen. countuniqueactivities activity type Number of unique activities. durationstationary minutes The total duration of [ACTIVITY_CLASSES][STATIONARY] episodes durationmobile minutes The total duration of [ACTIVITY_CLASSES][MOBILE] episodes of on foot, running, and on bicycle activities durationvehicle minutes The total duration of [ACTIVITY_CLASSES][VEHICLE] episodes of on vehicle activity Assumptions/Observations iOS Activity Recognition names and types are unified with Android labels: iOS Activity Name Android Activity Name Android Activity Type walking walking 7 running running 8 cycling on_bicycle 1 automotive in_vehicle 0 stationary still 3 unknown unknown 4 In AWARE, Activity Recognition data for Android and iOS are stored in two different database tables, RAPIDS automatically infers what platform each participant belongs to based on their participant file .","title":"Phone Activity Recognition"},{"location":"features/phone-activity-recognition/#phone-activity-recognition","text":"Sensor parameters description for [PHONE_ACTIVITY_RECOGNITION] : Key Description [TABLE][ANDROID] Database table where the activity data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the activity data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS) [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same activity episode","title":"Phone Activity Recognition"},{"location":"features/phone-activity-recognition/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_activity_recognition_raw.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime.csv - data/raw/ { pid } /phone_activity_recognition_with_datetime_unified.csv - data/interim/ { pid } /phone_activity_recognition_episodes.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled.csv - data/interim/ { pid } /phone_activity_recognition_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_activity_recognition_features/phone_activity_recognition_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_activity_recognition.csv Parameters description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_ACTIVITY_RECOGNITION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [ACTIVITY_CLASSES][STATIONARY] An array of the activity labels to be considered in the STATIONARY category choose any of still , tilting [ACTIVITY_CLASSES][MOBILE] An array of the activity labels to be considered in the MOBILE category choose any of on_foot , walking , running , on_bicycle [ACTIVITY_CLASSES][VEHICLE] An array of the activity labels to be considered in the VEHICLE category choose any of in_vehicule Features description for [PHONE_ACTIVITY_RECOGNITION][PROVIDERS][RAPIDS] : Feature Units Description count rows Number of episodes. mostcommonactivity activity type The most common activity type (e.g. still , on_foot , etc.). If there is a tie, the first one is chosen. countuniqueactivities activity type Number of unique activities. durationstationary minutes The total duration of [ACTIVITY_CLASSES][STATIONARY] episodes durationmobile minutes The total duration of [ACTIVITY_CLASSES][MOBILE] episodes of on foot, running, and on bicycle activities durationvehicle minutes The total duration of [ACTIVITY_CLASSES][VEHICLE] episodes of on vehicle activity Assumptions/Observations iOS Activity Recognition names and types are unified with Android labels: iOS Activity Name Android Activity Name Android Activity Type walking walking 7 running running 8 cycling on_bicycle 1 automotive in_vehicle 0 stationary still 3 unknown unknown 4 In AWARE, Activity Recognition data for Android and iOS are stored in two different database tables, RAPIDS automatically infers what platform each participant belongs to based on their participant file .","title":"RAPIDS provider"},{"location":"features/phone-applications-foreground/","text":"Phone Applications Foreground \u00b6 Sensor parameters description for [PHONE_APPLICATIONS_FOREGROUND] (these parameters are used by the only provider available at the moment, RAPIDS): Key Description [TABLE] Database table where the applications foreground data is stored [APPLICATION_CATEGORIES][CATALOGUE_SOURCE] FILE or GOOGLE . If FILE , app categories (genres) are read from [CATALOGUE_FILE] . If [GOOGLE] , app categories (genres) are scrapped from the Play Store [APPLICATION_CATEGORIES][CATALOGUE_FILE] CSV file with a package_name and genre column. By default we provide the catalogue created by Stachl et al in data/external/stachl_application_genre_catalogue.csv [APPLICATION_CATEGORIES][UPDATE_CATALOGUE_FILE] if [CATALOGUE_SOURCE] is equal to FILE , this flag signals whether or not to update [CATALOGUE_FILE] , if [CATALOGUE_SOURCE] is equal to GOOGLE all scraped genres will be saved to [CATALOGUE_FILE] [APPLICATION_CATEGORIES][SCRAPE_MISSING_CATEGORIES] This flag signals whether or not to scrape categories (genres) missing from the [CATALOGUE_FILE] . If [CATALOGUE_SOURCE] is equal to GOOGLE , all genres are scraped anyway (this flag is ignored) RAPIDS provider \u00b6 The app category (genre) catalogue used in these features was originally created by Stachl et al . Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_applications_foreground_raw.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime_with_categories.csv - data/interim/ { pid } /phone_applications_foreground_features/phone_applications_foreground_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_applications_foreground.csv Parameters description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_APPLICATIONS_FOREGROUND features from the RAPIDS provider [FEATURES] Features to be computed, see table below [SINGLE_CATEGORIES] An array of app categories to be included in the feature extraction computation. The special keyword all represents a category with all the apps from each participant. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [MULTIPLE_CATEGORIES] An array of collections representing meta-categories (a group of categories). They key of each element is the name of the meta-category and the value is an array of member app categories. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [SINGLE_APPS] An array of apps to be included in the feature extraction computation. Use their package name (e.g. com.google.android.youtube ) or the reserved keyword top1global (the most used app by a participant over the whole monitoring study) [EXCLUDED_CATEGORIES] An array of app categories to be excluded from the feature extraction computation. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [EXCLUDED_APPS] An array of apps to be excluded from the feature extraction computation. Use their package name, for example: com.google.android.youtube Features description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Feature Units Description count apps Number of times a single app or apps within a category were used (i.e. they were brought to the foreground either by tapping their icon or switching to it from another app) timeoffirstuse minutes The time in minutes between 12:00am (midnight) and the first use of a single app or apps within a category during a day_segment timeoflastuse minutes The time in minutes between 12:00am (midnight) and the last use of a single app or apps within a category during a day_segment frequencyentropy nats The entropy of the used apps within a category during a day_segment (each app is seen as a unique event, the more apps were used, the higher the entropy). This is especially relevant when computed over all apps. Entropy cannot be obtained for a single app Assumptions/Observations Features can be computed by app, by apps grouped under a single category (genre) and by multiple categories grouped together (meta-categories). For example, we can get features for Facebook (single app), for Social Network apps (a category including Facebook and other social media apps) or for Social (a meta-category formed by Social Network and Social Media Tools categories). Apps installed by default like YouTube are considered systems apps on some phones. We do an exact match to exclude apps where \u201cgenre\u201d == EXCLUDED_CATEGORIES or \u201cpackage_name\u201d == EXCLUDED_APPS . We provide three ways of classifying and app within a category (genre): a) by automatically scraping its official category from the Google Play Store, b) by using the catalogue created by Stachl et al. which we provide in RAPIDS ( data/external/stachl_application_genre_catalogue.csv ), or c) by manually creating a personalized catalogue. You can choose a, b or c by modifying [APPLICATION_GENRES] keys and values (see the Sensor parameters description table above).","title":"Phone Applications Foreground"},{"location":"features/phone-applications-foreground/#phone-applications-foreground","text":"Sensor parameters description for [PHONE_APPLICATIONS_FOREGROUND] (these parameters are used by the only provider available at the moment, RAPIDS): Key Description [TABLE] Database table where the applications foreground data is stored [APPLICATION_CATEGORIES][CATALOGUE_SOURCE] FILE or GOOGLE . If FILE , app categories (genres) are read from [CATALOGUE_FILE] . If [GOOGLE] , app categories (genres) are scrapped from the Play Store [APPLICATION_CATEGORIES][CATALOGUE_FILE] CSV file with a package_name and genre column. By default we provide the catalogue created by Stachl et al in data/external/stachl_application_genre_catalogue.csv [APPLICATION_CATEGORIES][UPDATE_CATALOGUE_FILE] if [CATALOGUE_SOURCE] is equal to FILE , this flag signals whether or not to update [CATALOGUE_FILE] , if [CATALOGUE_SOURCE] is equal to GOOGLE all scraped genres will be saved to [CATALOGUE_FILE] [APPLICATION_CATEGORIES][SCRAPE_MISSING_CATEGORIES] This flag signals whether or not to scrape categories (genres) missing from the [CATALOGUE_FILE] . If [CATALOGUE_SOURCE] is equal to GOOGLE , all genres are scraped anyway (this flag is ignored)","title":"Phone Applications Foreground"},{"location":"features/phone-applications-foreground/#rapids-provider","text":"The app category (genre) catalogue used in these features was originally created by Stachl et al . Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_applications_foreground_raw.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime.csv - data/raw/ { pid } /phone_applications_foreground_with_datetime_with_categories.csv - data/interim/ { pid } /phone_applications_foreground_features/phone_applications_foreground_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_applications_foreground.csv Parameters description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_APPLICATIONS_FOREGROUND features from the RAPIDS provider [FEATURES] Features to be computed, see table below [SINGLE_CATEGORIES] An array of app categories to be included in the feature extraction computation. The special keyword all represents a category with all the apps from each participant. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [MULTIPLE_CATEGORIES] An array of collections representing meta-categories (a group of categories). They key of each element is the name of the meta-category and the value is an array of member app categories. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [SINGLE_APPS] An array of apps to be included in the feature extraction computation. Use their package name (e.g. com.google.android.youtube ) or the reserved keyword top1global (the most used app by a participant over the whole monitoring study) [EXCLUDED_CATEGORIES] An array of app categories to be excluded from the feature extraction computation. By default we use the category catalogue pointed by [APPLICATION_CATEGORIES][CATALOGUE_FILE] (see the Sensor parameters description table above) [EXCLUDED_APPS] An array of apps to be excluded from the feature extraction computation. Use their package name, for example: com.google.android.youtube Features description for [PHONE_APPLICATIONS_FOREGROUND][PROVIDERS][RAPIDS] : Feature Units Description count apps Number of times a single app or apps within a category were used (i.e. they were brought to the foreground either by tapping their icon or switching to it from another app) timeoffirstuse minutes The time in minutes between 12:00am (midnight) and the first use of a single app or apps within a category during a day_segment timeoflastuse minutes The time in minutes between 12:00am (midnight) and the last use of a single app or apps within a category during a day_segment frequencyentropy nats The entropy of the used apps within a category during a day_segment (each app is seen as a unique event, the more apps were used, the higher the entropy). This is especially relevant when computed over all apps. Entropy cannot be obtained for a single app Assumptions/Observations Features can be computed by app, by apps grouped under a single category (genre) and by multiple categories grouped together (meta-categories). For example, we can get features for Facebook (single app), for Social Network apps (a category including Facebook and other social media apps) or for Social (a meta-category formed by Social Network and Social Media Tools categories). Apps installed by default like YouTube are considered systems apps on some phones. We do an exact match to exclude apps where \u201cgenre\u201d == EXCLUDED_CATEGORIES or \u201cpackage_name\u201d == EXCLUDED_APPS . We provide three ways of classifying and app within a category (genre): a) by automatically scraping its official category from the Google Play Store, b) by using the catalogue created by Stachl et al. which we provide in RAPIDS ( data/external/stachl_application_genre_catalogue.csv ), or c) by manually creating a personalized catalogue. You can choose a, b or c by modifying [APPLICATION_GENRES] keys and values (see the Sensor parameters description table above).","title":"RAPIDS provider"},{"location":"features/phone-battery/","text":"Phone Battery \u00b6 Sensor parameters description for [PHONE_BATTERY] : Key Description [TABLE] Database table where the battery data is stored [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same battery charge or discharge episode RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_battery_raw.csv - data/interim/ { pid } /phone_battery_episodes.csv - data/interim/ { pid } /phone_battery_episodes_resampled.csv - data/interim/ { pid } /phone_battery_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_battery_features/phone_battery_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_battery.csv Parameters description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BATTERY features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Feature Units Description countdischarge episodes Number of discharging episodes. sumdurationdischarge minutes The total duration of all discharging episodes. countcharge episodes Number of battery charging episodes. sumdurationcharge minutes The total duration of all charging episodes. avgconsumptionrate episodes/minutes The average of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration maxconsumptionrate episodes/minutes The highest of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration Assumptions/Observations We convert battery data collected with iOS client v1 (autodetected because battery status 4 do not exist) to match Android battery format: we swap status 3 for 5 and 1 for 3 We group battery data into discharge or charge episodes considering any contiguous rows with consecutive reductions or increases of the battery level if they are logged within [EPISODE_THRESHOLD_BETWEEN_ROWS] minutes from each other.","title":"Phone Battery"},{"location":"features/phone-battery/#phone-battery","text":"Sensor parameters description for [PHONE_BATTERY] : Key Description [TABLE] Database table where the battery data is stored [EPISODE_THRESHOLD_BETWEEN_ROWS] Difference in minutes between any two rows for them to be considered part of the same battery charge or discharge episode","title":"Phone Battery"},{"location":"features/phone-battery/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_battery_raw.csv - data/interim/ { pid } /phone_battery_episodes.csv - data/interim/ { pid } /phone_battery_episodes_resampled.csv - data/interim/ { pid } /phone_battery_episodes_resampled_with_datetime.csv - data/interim/ { pid } /phone_battery_features/phone_battery_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_battery.csv Parameters description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BATTERY features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BATTERY][PROVIDERS][RAPIDS] : Feature Units Description countdischarge episodes Number of discharging episodes. sumdurationdischarge minutes The total duration of all discharging episodes. countcharge episodes Number of battery charging episodes. sumdurationcharge minutes The total duration of all charging episodes. avgconsumptionrate episodes/minutes The average of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration maxconsumptionrate episodes/minutes The highest of all episodes\u2019 consumption rates. An episode\u2019s consumption rate is defined as the ratio between its battery delta and duration Assumptions/Observations We convert battery data collected with iOS client v1 (autodetected because battery status 4 do not exist) to match Android battery format: we swap status 3 for 5 and 1 for 3 We group battery data into discharge or charge episodes considering any contiguous rows with consecutive reductions or increases of the battery level if they are logged within [EPISODE_THRESHOLD_BETWEEN_ROWS] minutes from each other.","title":"RAPIDS provider"},{"location":"features/phone-bluetooth/","text":"Phone Bluetooth \u00b6 Sensor parameters description for [PHONE_BLUETOOTH] : Key Description [TABLE] Database table where the bluetooth data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_bluetooth_raw.csv - data/raw/ { pid } /phone_bluetooth_with_datetime.csv - data/interim/ { pid } /phone_bluetooth_features/phone_bluetooth_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_bluetooth.csv \" Parameters description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BLUETOOTH features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned devices during a day_segment , a device can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique devices during a day_segment as identified by their hardware ( bt_address ) address countscansmostuniquedevice scans Number of scans of the most scanned device during a day_segment across the whole monitoring period Assumptions/Observations NA","title":"Phone Bluetooth"},{"location":"features/phone-bluetooth/#phone-bluetooth","text":"Sensor parameters description for [PHONE_BLUETOOTH] : Key Description [TABLE] Database table where the bluetooth data is stored","title":"Phone Bluetooth"},{"location":"features/phone-bluetooth/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_bluetooth_raw.csv - data/raw/ { pid } /phone_bluetooth_with_datetime.csv - data/interim/ { pid } /phone_bluetooth_features/phone_bluetooth_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_bluetooth.csv \" Parameters description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_BLUETOOTH features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_BLUETOOTH][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned devices during a day_segment , a device can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique devices during a day_segment as identified by their hardware ( bt_address ) address countscansmostuniquedevice scans Number of scans of the most scanned device during a day_segment across the whole monitoring period Assumptions/Observations NA","title":"RAPIDS provider"},{"location":"features/phone-calls/","text":"Phone Calls \u00b6 Sensor parameters description for [PHONE_CALLS] : Key Description [TABLE] Database table where the calls data is stored RAPIDS Provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_calls_raw.csv - data/raw/ { pid } /phone_calls_with_datetime.csv - data/raw/ { pid } /phone_calls_with_datetime_unified.csv - data/interim/ { pid } /phone_calls_features/phone_calls_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_calls.csv Parameters description for [PHONE_CALLS][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CALLS features from the RAPIDS provider [CALL_TYPES] The particular call_type that will be analyzed. The options for this parameter are incoming, outgoing or missed. [FEATURES] Features to be computed for outgoing , incoming , and missed calls. Note that the same features are available for both incoming and outgoing calls, while missed calls has its own set of features. See the tables below. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] incoming and outgoing calls: Feature Units Description count calls Number of calls of a particular call_type occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular call_type for a particular day_segment meanduration seconds The mean duration of all calls of a particular call_type during a particular day_segment . sumduration seconds The sum of the duration of all calls of a particular call_type during a particular day_segment . minduration seconds The duration of the shortest call of a particular call_type during a particular day_segment . maxduration seconds The duration of the longest call of a particular call_type during a particular day_segment . stdduration seconds The standard deviation of the duration of all the calls of a particular call_type during a particular day_segment . modeduration seconds The mode of the duration of all the calls of a particular call_type during a particular day_segment . entropyduration nats The estimate of the Shannon entropy for the the duration of all the calls of a particular call_type during a particular day_segment . timefirstcall minutes The time in minutes between 12:00am (midnight) and the first call of call_type . timelastcall minutes The time in minutes between 12:00am (midnight) and the last call of call_type . countmostfrequentcontact calls The number of calls of a particular call_type during a particular day_segment of the most frequent contact throughout the monitored period. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] missed calls: Feature Units Description count calls Number of missed calls that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with missed calls for a particular day_segment timefirstcall minutes The time in hours from 12:00am (Midnight) that the first missed call occurred. timelastcall minutes The time in hours from 12:00am (Midnight) that the last missed call occurred. countmostfrequentcontact calls The number of missed calls during a particular day_segment of the most frequent contact throughout the monitored period. Assumptions/Observations Traces for iOS calls are unique even for the same contact calling a participant more than once which renders countmostfrequentcontact meaningless and distinctcontacts equal to the total number of traces. [CALL_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [CALL_TYPES] outgoing matches the [FEATURES] key outgoing iOS calls data is transformed to match Android calls data format. See our algorithm","title":"Phone Calls"},{"location":"features/phone-calls/#phone-calls","text":"Sensor parameters description for [PHONE_CALLS] : Key Description [TABLE] Database table where the calls data is stored","title":"Phone Calls"},{"location":"features/phone-calls/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_calls_raw.csv - data/raw/ { pid } /phone_calls_with_datetime.csv - data/raw/ { pid } /phone_calls_with_datetime_unified.csv - data/interim/ { pid } /phone_calls_features/phone_calls_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_calls.csv Parameters description for [PHONE_CALLS][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CALLS features from the RAPIDS provider [CALL_TYPES] The particular call_type that will be analyzed. The options for this parameter are incoming, outgoing or missed. [FEATURES] Features to be computed for outgoing , incoming , and missed calls. Note that the same features are available for both incoming and outgoing calls, while missed calls has its own set of features. See the tables below. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] incoming and outgoing calls: Feature Units Description count calls Number of calls of a particular call_type occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular call_type for a particular day_segment meanduration seconds The mean duration of all calls of a particular call_type during a particular day_segment . sumduration seconds The sum of the duration of all calls of a particular call_type during a particular day_segment . minduration seconds The duration of the shortest call of a particular call_type during a particular day_segment . maxduration seconds The duration of the longest call of a particular call_type during a particular day_segment . stdduration seconds The standard deviation of the duration of all the calls of a particular call_type during a particular day_segment . modeduration seconds The mode of the duration of all the calls of a particular call_type during a particular day_segment . entropyduration nats The estimate of the Shannon entropy for the the duration of all the calls of a particular call_type during a particular day_segment . timefirstcall minutes The time in minutes between 12:00am (midnight) and the first call of call_type . timelastcall minutes The time in minutes between 12:00am (midnight) and the last call of call_type . countmostfrequentcontact calls The number of calls of a particular call_type during a particular day_segment of the most frequent contact throughout the monitored period. Features description for [PHONE_CALLS][PROVIDERS][RAPIDS] missed calls: Feature Units Description count calls Number of missed calls that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with missed calls for a particular day_segment timefirstcall minutes The time in hours from 12:00am (Midnight) that the first missed call occurred. timelastcall minutes The time in hours from 12:00am (Midnight) that the last missed call occurred. countmostfrequentcontact calls The number of missed calls during a particular day_segment of the most frequent contact throughout the monitored period. Assumptions/Observations Traces for iOS calls are unique even for the same contact calling a participant more than once which renders countmostfrequentcontact meaningless and distinctcontacts equal to the total number of traces. [CALL_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [CALL_TYPES] outgoing matches the [FEATURES] key outgoing iOS calls data is transformed to match Android calls data format. See our algorithm","title":"RAPIDS Provider"},{"location":"features/phone-conversation/","text":"Phone Conversation \u00b6 Sensor parameters description for [PHONE_CONVERSATION] : Key Description [TABLE][ANDROID] Database table where the conversation data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the conversation data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS) RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_conversation_raw.csv - data/raw/ { pid } /phone_conversation_with_datetime.csv - data/raw/ { pid } /phone_conversation_with_datetime_unified.csv - data/interim/ { pid } /phone_conversation_features/phone_conversation_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_conversation.csv Parameters description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CONVERSATION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [RECORDING_MINUTES] Minutes the plugin was recording audio (default 1 min) [PAUSED_MINUTES] Minutes the plugin was NOT recording audio (default 3 min) Features description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Feature Units Description minutessilence minutes Minutes labeled as silence minutesnoise minutes Minutes labeled as noise minutesvoice minutes Minutes labeled as voice minutesunknown minutes Minutes labeled as unknown sumconversationduration minutes Total duration of all conversations maxconversationduration minutes Longest duration of all conversations minconversationduration minutes Shortest duration of all conversations avgconversationduration minutes Average duration of all conversations sdconversationduration minutes Standard Deviation of the duration of all conversations timefirstconversation minutes Minutes since midnight when the first conversation for a day segment was detected timelastconversation minutes Minutes since midnight when the last conversation for a day segment was detected noisesumenergy L2-norm Sum of all energy values when inference is noise noiseavgenergy L2-norm Average of all energy values when inference is noise noisesdenergy L2-norm Standard Deviation of all energy values when inference is noise noiseminenergy L2-norm Minimum of all energy values when inference is noise noisemaxenergy L2-norm Maximum of all energy values when inference is noise voicesumenergy L2-norm Sum of all energy values when inference is voice voiceavgenergy L2-norm Average of all energy values when inference is voice voicesdenergy L2-norm Standard Deviation of all energy values when inference is voice voiceminenergy L2-norm Minimum of all energy values when inference is voice voicemaxenergy L2-norm Maximum of all energy values when inference is voice silencesensedfraction - Ratio between minutessilence and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) noisesensedfraction - Ratio between minutesnoise and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) voicesensedfraction - Ratio between minutesvoice and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) unknownsensedfraction - Ratio between minutesunknown and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) silenceexpectedfraction - Ration between minutessilence and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) noiseexpectedfraction - Ration between minutesnoise and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) voiceexpectedfraction - Ration between minutesvoice and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) unknownexpectedfraction - Ration between minutesunknown and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) Assumptions/Observations The timestamp of conversation rows in iOS is in seconds so we convert it to milliseconds to match Android\u2019s format","title":"Phone Conversation"},{"location":"features/phone-conversation/#phone-conversation","text":"Sensor parameters description for [PHONE_CONVERSATION] : Key Description [TABLE][ANDROID] Database table where the conversation data from Android devices is stored (the AWARE client saves this data on different tables for Android and iOS) [TABLE][IOS] Database table where the conversation data from iOS devices is stored (the AWARE client saves this data on different tables for Android and iOS)","title":"Phone Conversation"},{"location":"features/phone-conversation/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_conversation_raw.csv - data/raw/ { pid } /phone_conversation_with_datetime.csv - data/raw/ { pid } /phone_conversation_with_datetime_unified.csv - data/interim/ { pid } /phone_conversation_features/phone_conversation_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_conversation.csv Parameters description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_CONVERSATION features from the RAPIDS provider [FEATURES] Features to be computed, see table below [RECORDING_MINUTES] Minutes the plugin was recording audio (default 1 min) [PAUSED_MINUTES] Minutes the plugin was NOT recording audio (default 3 min) Features description for [PHONE_CONVERSATION][PROVIDERS][RAPIDS] : Feature Units Description minutessilence minutes Minutes labeled as silence minutesnoise minutes Minutes labeled as noise minutesvoice minutes Minutes labeled as voice minutesunknown minutes Minutes labeled as unknown sumconversationduration minutes Total duration of all conversations maxconversationduration minutes Longest duration of all conversations minconversationduration minutes Shortest duration of all conversations avgconversationduration minutes Average duration of all conversations sdconversationduration minutes Standard Deviation of the duration of all conversations timefirstconversation minutes Minutes since midnight when the first conversation for a day segment was detected timelastconversation minutes Minutes since midnight when the last conversation for a day segment was detected noisesumenergy L2-norm Sum of all energy values when inference is noise noiseavgenergy L2-norm Average of all energy values when inference is noise noisesdenergy L2-norm Standard Deviation of all energy values when inference is noise noiseminenergy L2-norm Minimum of all energy values when inference is noise noisemaxenergy L2-norm Maximum of all energy values when inference is noise voicesumenergy L2-norm Sum of all energy values when inference is voice voiceavgenergy L2-norm Average of all energy values when inference is voice voicesdenergy L2-norm Standard Deviation of all energy values when inference is voice voiceminenergy L2-norm Minimum of all energy values when inference is voice voicemaxenergy L2-norm Maximum of all energy values when inference is voice silencesensedfraction - Ratio between minutessilence and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) noisesensedfraction - Ratio between minutesnoise and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) voicesensedfraction - Ratio between minutesvoice and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) unknownsensedfraction - Ratio between minutesunknown and the sum of (minutessilence, minutesnoise, minutesvoice, minutesunknown) silenceexpectedfraction - Ration between minutessilence and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) noiseexpectedfraction - Ration between minutesnoise and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) voiceexpectedfraction - Ration between minutesvoice and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) unknownexpectedfraction - Ration between minutesunknown and the number of minutes that in theory should have been sensed based on the record and pause cycle of the plugin (1440 / recordingMinutes+pausedMinutes) Assumptions/Observations The timestamp of conversation rows in iOS is in seconds so we convert it to milliseconds to match Android\u2019s format","title":"RAPIDS provider"},{"location":"features/phone-data-quality/","text":"Phone Data Quality \u00b6 Phone Valid Sensed Bins \u00b6 A valid bin is any period of BIN_SIZE minutes starting from midnight with at least 1 row from any phone sensor. PHONE_VALID_SENSED_BINS are used to compute PHONE_VALID_SENSED_DAYS , to resample fused location data and to compute some screen features. Hint PHONE_VALID_SENSED_DAYS are an approximation to the time the phone was sensing data so add as many sensors as you have to [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] Parameters description for PHONE_VALID_SENSED_BINS : Key Description [COMPUTE] Set to True to compute [BIN_SIZE] Size of each bin in minutes [PHONE_SENSORS] One or more sensor config keys (e.g. PHONE_MESSAGE ) to be used to flag a bin as valid or not (whether or not a bin contains at least one row from any sensor) Possible values for [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] PHONE_MESSAGES PHONE_CALLS PHONE_LOCATIONS PHONE_BLUETOOTH PHONE_ACTIVITY_RECOGNITION PHONE_BATTERY PHONE_SCREEN PHONE_LIGHT PHONE_ACCELEROMETER PHONE_APPLICATIONS_FOREGROUND PHONE_WIFI_VISIBLE PHONE_WIFI_CONNECTED PHONE_CONVERSATION Phone Valid Sensed Days \u00b6 On any given day, a phone could have sensed data only for a few minutes or for 24 hours. Features should considered more reliable the more hours the phone was logging data, for example, 10 calls logged on a day when only 1 hour of data was recorded is a less reliable feature compared to 10 calls on a day when 23 hours of data were recorded. Therefore, we define a valid hour as those that contain a minimum number of valid bins (see above). We mark an hour as valid when contains at least MIN_VALID_BINS_PER_HOUR (out of 60min/ BIN_SIZE bins). In turn, we mark a day as valid if it has at least MIN_VALID_HOURS_PER_DAY . You can use PHONE_VALID_SENSED_DAYS to manually discard days when not enough data was collected after your features are computed. Parameters description for PHONE_VALID_SENSED_DAYS : Key Description [COMPUTE] Set to True to compute [MIN_VALID_BINS_PER_HOUR] An array of integer values, 6 by default. Minimum number of valid bins to mark an hour as valid [MIN_VALID_HOURS_PER_DAY] An array of integer values, 16 by default. Minimum number of valid hours to mark a day as valid","title":"Phone Data Quality"},{"location":"features/phone-data-quality/#phone-data-quality","text":"","title":"Phone Data Quality"},{"location":"features/phone-data-quality/#phone-valid-sensed-bins","text":"A valid bin is any period of BIN_SIZE minutes starting from midnight with at least 1 row from any phone sensor. PHONE_VALID_SENSED_BINS are used to compute PHONE_VALID_SENSED_DAYS , to resample fused location data and to compute some screen features. Hint PHONE_VALID_SENSED_DAYS are an approximation to the time the phone was sensing data so add as many sensors as you have to [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] Parameters description for PHONE_VALID_SENSED_BINS : Key Description [COMPUTE] Set to True to compute [BIN_SIZE] Size of each bin in minutes [PHONE_SENSORS] One or more sensor config keys (e.g. PHONE_MESSAGE ) to be used to flag a bin as valid or not (whether or not a bin contains at least one row from any sensor) Possible values for [PHONE_VALID_SENSED_BINS][PHONE_SENSORS] PHONE_MESSAGES PHONE_CALLS PHONE_LOCATIONS PHONE_BLUETOOTH PHONE_ACTIVITY_RECOGNITION PHONE_BATTERY PHONE_SCREEN PHONE_LIGHT PHONE_ACCELEROMETER PHONE_APPLICATIONS_FOREGROUND PHONE_WIFI_VISIBLE PHONE_WIFI_CONNECTED PHONE_CONVERSATION","title":"Phone Valid Sensed Bins"},{"location":"features/phone-data-quality/#phone-valid-sensed-days","text":"On any given day, a phone could have sensed data only for a few minutes or for 24 hours. Features should considered more reliable the more hours the phone was logging data, for example, 10 calls logged on a day when only 1 hour of data was recorded is a less reliable feature compared to 10 calls on a day when 23 hours of data were recorded. Therefore, we define a valid hour as those that contain a minimum number of valid bins (see above). We mark an hour as valid when contains at least MIN_VALID_BINS_PER_HOUR (out of 60min/ BIN_SIZE bins). In turn, we mark a day as valid if it has at least MIN_VALID_HOURS_PER_DAY . You can use PHONE_VALID_SENSED_DAYS to manually discard days when not enough data was collected after your features are computed. Parameters description for PHONE_VALID_SENSED_DAYS : Key Description [COMPUTE] Set to True to compute [MIN_VALID_BINS_PER_HOUR] An array of integer values, 6 by default. Minimum number of valid bins to mark an hour as valid [MIN_VALID_HOURS_PER_DAY] An array of integer values, 16 by default. Minimum number of valid hours to mark a day as valid","title":"Phone Valid Sensed Days"},{"location":"features/phone-light/","text":"Phone Light \u00b6 Sensor parameters description for [PHONE_LIGHT] : Key Description [TABLE] Database table where the light data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_light_raw.csv - data/raw/ { pid } /phone_light_with_datetime.csv - data/interim/ { pid } /phone_light_features/phone_light_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_light.csv Parameters description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_LIGHT features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Feature Units Description count rows Number light sensor rows recorded. maxlux lux The maximum ambient luminance. minlux lux The minimum ambient luminance. avglux lux The average ambient luminance. medianlux lux The median ambient luminance. stdlux lux The standard deviation of ambient luminance. Assumptions/Observations NA","title":"Phone Light"},{"location":"features/phone-light/#phone-light","text":"Sensor parameters description for [PHONE_LIGHT] : Key Description [TABLE] Database table where the light data is stored","title":"Phone Light"},{"location":"features/phone-light/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_light_raw.csv - data/raw/ { pid } /phone_light_with_datetime.csv - data/interim/ { pid } /phone_light_features/phone_light_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_light.csv Parameters description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_LIGHT features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_LIGHT][PROVIDERS][RAPIDS] : Feature Units Description count rows Number light sensor rows recorded. maxlux lux The maximum ambient luminance. minlux lux The minimum ambient luminance. avglux lux The average ambient luminance. medianlux lux The median ambient luminance. stdlux lux The standard deviation of ambient luminance. Assumptions/Observations NA","title":"RAPIDS provider"},{"location":"features/phone-locations/","text":"Phone Locations \u00b6 Sensor parameters description for [PHONE_LOCATIONS] : Key Description [TABLE] Database table where the location data is stored [LOCATIONS_TO_USE] Type of location data to use, one of ALL , GPS or FUSED_RESAMPLED . This filter is based on the provider column of the AWARE locations table, ALL includes every row, GPS only includes rows where provider is gps, and FUSED_RESAMPLED only includes rows where provider is fused after being resampled. [FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled to the next valid timestamp (see the Assumptions/Observations below) only if the time difference between them is less or equal than this threshold (in minutes). [FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled at most for this long (in minutes) Assumptions/Observations Types of location data to use AWARE Android and iOS clients can collect location coordinates through the phone's GPS, the network cellular towers around the phone or Google's fused location API. If you want to use only the GPS provider set [LOCATIONS_TO_USE] to GPS , if you want to use all providers (not recommended due to the difference in accuracy) set [LOCATIONS_TO_USE] to ALL , if your AWARE client was configured to use fused location only or want to focus only on this provider, set [LOCATIONS_TO_USE] to RESAMPLE_FUSED . RESAMPLE_FUSED takes the original fused location coordinates and replicates each pair forward in time as long as the phone was sensing data as indicated by PHONE_VALID_SENSED_BINS , this is done because Google's API only logs a new location coordinate pair when it is sufficiently different in time or space from the previous one. There are two parameters associated with resampling fused location. FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD (in minutes, default 30) controls the maximum gap between any two coordinate pairs to replicate the last known pair (for example, participant A's phone did not collect data between 10.30am and 10:50am and between 11:05am and 11:40am, the last known coordinate pair will be replicated during the first period but not the second, in other words, we assume that we cannot longer guarantee the participant stayed at the last known location if the phone did not sense data for more than 30 minutes). FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION (in minutes, default 720 or 12 hours) stops the last known fused location from being replicated longer that this threshold even if the phone was sensing data continuously (for example, participant A went home at 9pm and their phone was sensing data without gaps until 11am the next morning, the last known location will only be replicated until 9am). If you have suggestions to modify or improve this resampling, let us know. BARNETT provider \u00b6 These features are based on the original open-source implementation by Barnett et al and some features created by Canzian et al . Available day segments and platforms Available only for segments that start at 00:00:00 and end at 23:59:59 of the same day (daily segments) Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [ACCURACY_LIMIT] An integer in meters, any location rows with an accuracy higher than this will be dropped. This number means there\u2019s a 68% probability the true location is within this radius [TIMEZONE] Timezone where the location data was collected. By default points to the one defined in the Initial configuration [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] adapted from Beiwe Summary Statistics : Feature Units Description hometime minutes 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. disttravelled meters Total distance travelled over a day (flights). rog meters The Radius of Gyration (rog) 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 the places and that centroid is computed. The weights are proportional to the time spent in each place. maxdiam meters The maximum diameter is the largest distance between any two pauses. maxhomedist meters The maximum distance from home in meters. siglocsvisited 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 k from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another. avgflightlen meters Mean length of all flights. stdflightlen meters Standard deviation of the length of all flights. avgflightdur seconds Mean duration of all flights. stdflightdur seconds The standard deviation of the duration of all flights. probpause - The fraction of a day spent in a pause (as opposed to a flight) siglocentropy nats Shannon\u2019s entropy measurement based on the proportion of time spent at each significant location visited during a day. circdnrtn - A continuous metric quantifying a person\u2019s circadian routine 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. wkenddayrtn - Same as circdnrtn but computed separately for weekends and weekdays. Assumptions/Observations Barnett's et al features These features are based on a Pause-Flight model. A pause is defined as a mobiity trace (location pings) within a certain duration and distance (by default 300 seconds and 60 meters). A flight is any mobility trace between two pauses. Data is resampled and imputed before the features are computed. See Barnett et al for more information. In RAPIDS we only expose two parameters for these features (timezone and accuracy limit). You can change other parameters in src/features/phone_locations/barnett/library/MobilityFeatures.R . Significant Locations Significant locations are determined using K-means clustering on pauses longer than 10 minutes. The number of clusters (K) is increased until no two clusters are within 400 meters from each other. After this, pauses within a certain range of a cluster (200 meters by default) will count as a visit to that significant location. This description was adapted from the Supplementary Materials of Barnett et al . The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al . DORYAB provider \u00b6 These features are based on the original implementation by Doryab et al. . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [DBSCAN_EPS] The maximum distance in meters between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function. [DBSCAN_MINSAMPLES] The number of samples (or total weight) in a neighborhood for a point to be considered as a core point of a cluster. This includes the point itself. [THRESHOLD_STATIC] It is the threshold value in km/hr which labels a row as Static or Moving. [MAXIMUM_GAP_ALLOWED] The maximum gap (in seconds) allowed between any two consecutive rows for them to be considered part of the same displacement. If this threshold is too high, it can throw speed and distance calculations off for periods when the the phone was not sensing. [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. [SAMPLING_FREQUENCY] Expected time difference between any two location rows in minutes. If set to 0 , the sampling frequency will be inferred automatically as the median of all the differences between any two consecutive row timestamps (recommended if you are using FUSED_RESAMPLED data). This parameter impacts all the time calculations. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Feature Units Description locationvariance \\(meters^2\\) The sum of the variances of the latitude and longitude columns. loglocationvariance - Log of the sum of the variances of the latitude and longitude columns. totaldistance meters Total distance travelled in a day segment using the haversine formula. averagespeed km/hr Average speed in a day segment considering only the instances labeled as Moving. varspeed km/hr Speed variance in a day segment considering only the instances labeled as Moving. circadianmovement - \"It encodes the extent to which a person\u2019s location patterns follow a 24-hour circadian cycle.\" Doryab et al. . numberofsignificantplaces places Number of significant locations visited. It is calculated using the DBSCAN clustering algorithm which takes in EPS and MIN_SAMPLES as parameters to identify clusters. Each cluster is a significant place. numberlocationtransitions transitions Number of movements between any two clusters in a day segment. radiusgyration meters Quantifies the area covered by a participant timeattop1location minutes Time spent at the most significant location. timeattop2location minutes Time spent at the 2 nd most significant location. timeattop3location minutes Time spent at the 3 rd most significant location. movingtostaticratio - Ratio between the number of rows labeled Moving versus Static outlierstimepercent - Ratio between the number of rows that belong to non-significant clusters divided by the total number of rows in a day segment. maxlengthstayatclusters minutes Maximum time spent in a cluster (significant location). minlengthstayatclusters minutes Minimum time spent in a cluster (significant location). meanlengthstayatclusters minutes Average time spent in a cluster (significant location). stdlengthstayatclusters minutes Standard deviation of time spent in a cluster (significant location). locationentropy nats Shannon Entropy computed over the row count of each cluster (significant location), it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). normalizedlocationentropy nats Shannon Entropy computed over the row count of each cluster (significant location) divided by the number of clusters, it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). Assumptions/Observations Significant Locations Identified Significant locations are determined using DBSCAN clustering on locations that a patient visit over the course of the period of data collection. The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al .","title":"Phone Locations"},{"location":"features/phone-locations/#phone-locations","text":"Sensor parameters description for [PHONE_LOCATIONS] : Key Description [TABLE] Database table where the location data is stored [LOCATIONS_TO_USE] Type of location data to use, one of ALL , GPS or FUSED_RESAMPLED . This filter is based on the provider column of the AWARE locations table, ALL includes every row, GPS only includes rows where provider is gps, and FUSED_RESAMPLED only includes rows where provider is fused after being resampled. [FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled to the next valid timestamp (see the Assumptions/Observations below) only if the time difference between them is less or equal than this threshold (in minutes). [FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION] if FUSED_RESAMPLED is used, the original fused data has to be resampled, a location row will be resampled at most for this long (in minutes) Assumptions/Observations Types of location data to use AWARE Android and iOS clients can collect location coordinates through the phone's GPS, the network cellular towers around the phone or Google's fused location API. If you want to use only the GPS provider set [LOCATIONS_TO_USE] to GPS , if you want to use all providers (not recommended due to the difference in accuracy) set [LOCATIONS_TO_USE] to ALL , if your AWARE client was configured to use fused location only or want to focus only on this provider, set [LOCATIONS_TO_USE] to RESAMPLE_FUSED . RESAMPLE_FUSED takes the original fused location coordinates and replicates each pair forward in time as long as the phone was sensing data as indicated by PHONE_VALID_SENSED_BINS , this is done because Google's API only logs a new location coordinate pair when it is sufficiently different in time or space from the previous one. There are two parameters associated with resampling fused location. FUSED_RESAMPLED_CONSECUTIVE_THRESHOLD (in minutes, default 30) controls the maximum gap between any two coordinate pairs to replicate the last known pair (for example, participant A's phone did not collect data between 10.30am and 10:50am and between 11:05am and 11:40am, the last known coordinate pair will be replicated during the first period but not the second, in other words, we assume that we cannot longer guarantee the participant stayed at the last known location if the phone did not sense data for more than 30 minutes). FUSED_RESAMPLED_TIME_SINCE_VALID_LOCATION (in minutes, default 720 or 12 hours) stops the last known fused location from being replicated longer that this threshold even if the phone was sensing data continuously (for example, participant A went home at 9pm and their phone was sensing data without gaps until 11am the next morning, the last known location will only be replicated until 9am). If you have suggestions to modify or improve this resampling, let us know.","title":"Phone Locations"},{"location":"features/phone-locations/#barnett-provider","text":"These features are based on the original open-source implementation by Barnett et al and some features created by Canzian et al . Available day segments and platforms Available only for segments that start at 00:00:00 and end at 23:59:59 of the same day (daily segments) Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [ACCURACY_LIMIT] An integer in meters, any location rows with an accuracy higher than this will be dropped. This number means there\u2019s a 68% probability the true location is within this radius [TIMEZONE] Timezone where the location data was collected. By default points to the one defined in the Initial configuration [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] adapted from Beiwe Summary Statistics : Feature Units Description hometime minutes 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. disttravelled meters Total distance travelled over a day (flights). rog meters The Radius of Gyration (rog) 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 the places and that centroid is computed. The weights are proportional to the time spent in each place. maxdiam meters The maximum diameter is the largest distance between any two pauses. maxhomedist meters The maximum distance from home in meters. siglocsvisited 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 k from 1 to 200 stopping until the centroids of two significant locations are within 400 meters of one another. avgflightlen meters Mean length of all flights. stdflightlen meters Standard deviation of the length of all flights. avgflightdur seconds Mean duration of all flights. stdflightdur seconds The standard deviation of the duration of all flights. probpause - The fraction of a day spent in a pause (as opposed to a flight) siglocentropy nats Shannon\u2019s entropy measurement based on the proportion of time spent at each significant location visited during a day. circdnrtn - A continuous metric quantifying a person\u2019s circadian routine 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. wkenddayrtn - Same as circdnrtn but computed separately for weekends and weekdays. Assumptions/Observations Barnett's et al features These features are based on a Pause-Flight model. A pause is defined as a mobiity trace (location pings) within a certain duration and distance (by default 300 seconds and 60 meters). A flight is any mobility trace between two pauses. Data is resampled and imputed before the features are computed. See Barnett et al for more information. In RAPIDS we only expose two parameters for these features (timezone and accuracy limit). You can change other parameters in src/features/phone_locations/barnett/library/MobilityFeatures.R . Significant Locations Significant locations are determined using K-means clustering on pauses longer than 10 minutes. The number of clusters (K) is increased until no two clusters are within 400 meters from each other. After this, pauses within a certain range of a cluster (200 meters by default) will count as a visit to that significant location. This description was adapted from the Supplementary Materials of Barnett et al . The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al .","title":"BARNETT provider"},{"location":"features/phone-locations/#doryab-provider","text":"These features are based on the original implementation by Doryab et al. . Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_locations_raw.csv - data/interim/ { pid } /phone_locations_processed.csv - data/interim/ { pid } /phone_locations_processed_with_datetime.csv - data/interim/ { pid } /phone_locations_features/phone_locations_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_locations.csv Parameters description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Key Description [COMPUTE] Set to True to extract PHONE_LOCATIONS features from the BARNETT provider [FEATURES] Features to be computed, see table below [DBSCAN_EPS] The maximum distance in meters between two samples for one to be considered as in the neighborhood of the other. This is not a maximum bound on the distances of points within a cluster. This is the most important DBSCAN parameter to choose appropriately for your data set and distance function. [DBSCAN_MINSAMPLES] The number of samples (or total weight) in a neighborhood for a point to be considered as a core point of a cluster. This includes the point itself. [THRESHOLD_STATIC] It is the threshold value in km/hr which labels a row as Static or Moving. [MAXIMUM_GAP_ALLOWED] The maximum gap (in seconds) allowed between any two consecutive rows for them to be considered part of the same displacement. If this threshold is too high, it can throw speed and distance calculations off for periods when the the phone was not sensing. [MINUTES_DATA_USED] Set to True to include an extra column in the final location feature file containing the number of minutes used to compute the features on each day segment. Use this for quality control purposes, the more data minutes exist for a period, the more reliable its features should be. For fused location, a single minute can contain more than one coordinate pair if the participant is moving fast enough. [SAMPLING_FREQUENCY] Expected time difference between any two location rows in minutes. If set to 0 , the sampling frequency will be inferred automatically as the median of all the differences between any two consecutive row timestamps (recommended if you are using FUSED_RESAMPLED data). This parameter impacts all the time calculations. Features description for [PHONE_LOCATIONS][PROVIDERS][BARNETT] : Feature Units Description locationvariance \\(meters^2\\) The sum of the variances of the latitude and longitude columns. loglocationvariance - Log of the sum of the variances of the latitude and longitude columns. totaldistance meters Total distance travelled in a day segment using the haversine formula. averagespeed km/hr Average speed in a day segment considering only the instances labeled as Moving. varspeed km/hr Speed variance in a day segment considering only the instances labeled as Moving. circadianmovement - \"It encodes the extent to which a person\u2019s location patterns follow a 24-hour circadian cycle.\" Doryab et al. . numberofsignificantplaces places Number of significant locations visited. It is calculated using the DBSCAN clustering algorithm which takes in EPS and MIN_SAMPLES as parameters to identify clusters. Each cluster is a significant place. numberlocationtransitions transitions Number of movements between any two clusters in a day segment. radiusgyration meters Quantifies the area covered by a participant timeattop1location minutes Time spent at the most significant location. timeattop2location minutes Time spent at the 2 nd most significant location. timeattop3location minutes Time spent at the 3 rd most significant location. movingtostaticratio - Ratio between the number of rows labeled Moving versus Static outlierstimepercent - Ratio between the number of rows that belong to non-significant clusters divided by the total number of rows in a day segment. maxlengthstayatclusters minutes Maximum time spent in a cluster (significant location). minlengthstayatclusters minutes Minimum time spent in a cluster (significant location). meanlengthstayatclusters minutes Average time spent in a cluster (significant location). stdlengthstayatclusters minutes Standard deviation of time spent in a cluster (significant location). locationentropy nats Shannon Entropy computed over the row count of each cluster (significant location), it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). normalizedlocationentropy nats Shannon Entropy computed over the row count of each cluster (significant location) divided by the number of clusters, it will be higher the more rows belong to a cluster (i.e. the more time a participant spent at a significant location). Assumptions/Observations Significant Locations Identified Significant locations are determined using DBSCAN clustering on locations that a patient visit over the course of the period of data collection. The Circadian Calculation For a detailed description of how this is calculated, see Canzian et al .","title":"DORYAB provider"},{"location":"features/phone-messages/","text":"Phone Messages \u00b6 Sensor parameters description for [PHONE_MESSAGES] : Key Description [TABLE] Database table where the messages data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_messages_raw.csv - data/raw/ { pid } /phone_messages_with_datetime.csv - data/interim/ { pid } /phone_messages_features/phone_messages_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_messages.csv Parameters description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_MESSAGES features from the RAPIDS provider [MESSAGES_TYPES] The messages_type that will be analyzed. The options for this parameter are received or sent . [FEATURES] Features to be computed, see table below for [MESSAGES_TYPES] received and sent Features description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Feature Units Description count messages Number of messages of type messages_type that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular messages_type during a particular day_segment . timefirstmessages minutes Number of minutes between 12:00am (midnight) and the first message of a particular messages_type during a particular day_segment . timelastmessages minutes Number of minutes between 12:00am (midnight) and the last message of a particular messages_type during a particular day_segment . countmostfrequentcontact messages Number of messages from the contact with the most messages of messages_type during a day_segment throughout the whole dataset of each participant. Assumptions/Observations [MESSAGES_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [MESSAGES_TYPES] sent matches the [FEATURES] key sent","title":"Phone Messages"},{"location":"features/phone-messages/#phone-messages","text":"Sensor parameters description for [PHONE_MESSAGES] : Key Description [TABLE] Database table where the messages data is stored","title":"Phone Messages"},{"location":"features/phone-messages/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_messages_raw.csv - data/raw/ { pid } /phone_messages_with_datetime.csv - data/interim/ { pid } /phone_messages_features/phone_messages_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_messages.csv Parameters description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_MESSAGES features from the RAPIDS provider [MESSAGES_TYPES] The messages_type that will be analyzed. The options for this parameter are received or sent . [FEATURES] Features to be computed, see table below for [MESSAGES_TYPES] received and sent Features description for [PHONE_MESSAGES][PROVIDERS][RAPIDS] : Feature Units Description count messages Number of messages of type messages_type that occurred during a particular day_segment . distinctcontacts contacts Number of distinct contacts that are associated with a particular messages_type during a particular day_segment . timefirstmessages minutes Number of minutes between 12:00am (midnight) and the first message of a particular messages_type during a particular day_segment . timelastmessages minutes Number of minutes between 12:00am (midnight) and the last message of a particular messages_type during a particular day_segment . countmostfrequentcontact messages Number of messages from the contact with the most messages of messages_type during a day_segment throughout the whole dataset of each participant. Assumptions/Observations [MESSAGES_TYPES] and [FEATURES] keys in config.yaml need to match. For example, [MESSAGES_TYPES] sent matches the [FEATURES] key sent","title":"RAPIDS provider"},{"location":"features/phone-screen/","text":"Phone Screen \u00b6 Sensor parameters description for [PHONE_SCREEN] : Key Description [TABLE] Database table where the screen data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - 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. Assumptions/Observations 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. 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. We transform iOS screen events to match Android\u2019s 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.","title":"Phone Screen"},{"location":"features/phone-screen/#phone-screen","text":"Sensor parameters description for [PHONE_SCREEN] : Key Description [TABLE] Database table where the screen data is stored","title":"Phone Screen"},{"location":"features/phone-screen/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - 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. Assumptions/Observations 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. 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. We transform iOS screen events to match Android\u2019s 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.","title":"RAPIDS provider"},{"location":"features/phone-wifi-connected/","text":"Phone WiFi Connected \u00b6 Sensor parameters description for [PHONE_WIFI_CONNECTED] : Key Description [TABLE] Database table where the wifi (connected) data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_wifi_connected_raw.csv - data/raw/ { pid } /phone_wifi_connected_with_datetime.csv - data/interim/ { pid } /phone_wifi_connected_features/phone_wifi_connected_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_connected.csv Parameters description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_CONNECTED features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points connected during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A connected WiFI access point is one that a phone was connected to. By default AWARE stores this data in the sensor_wifi table.","title":"Phone WiFI Connected"},{"location":"features/phone-wifi-connected/#phone-wifi-connected","text":"Sensor parameters description for [PHONE_WIFI_CONNECTED] : Key Description [TABLE] Database table where the wifi (connected) data is stored","title":"Phone WiFi Connected"},{"location":"features/phone-wifi-connected/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android and iOS File Sequence - data/raw/ { pid } /phone_wifi_connected_raw.csv - data/raw/ { pid } /phone_wifi_connected_with_datetime.csv - data/interim/ { pid } /phone_wifi_connected_features/phone_wifi_connected_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_connected.csv Parameters description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_CONNECTED features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_CONNECTED][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points connected during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A connected WiFI access point is one that a phone was connected to. By default AWARE stores this data in the sensor_wifi table.","title":"RAPIDS provider"},{"location":"features/phone-wifi-visible/","text":"Phone WiFi Visible \u00b6 Sensor parameters description for [PHONE_WIFI_VISIBLE] : Key Description [TABLE] Database table where the wifi (visible) data is stored RAPIDS provider \u00b6 Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_wifi_visible_raw.csv - data/raw/ { pid } /phone_wifi_visible_with_datetime.csv - data/interim/ { pid } /phone_wifi_visible_features/phone_wifi_visible_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_visible.csv Parameters description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_VISIBLE features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points visible during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A visible WiFI access point is one that a phone sensed around itself but that it was not connected to. Due to API restrictions, this sensor is not available on iOS. By default AWARE stores this data in the wifi table.","title":"Phone WiFI Visible"},{"location":"features/phone-wifi-visible/#phone-wifi-visible","text":"Sensor parameters description for [PHONE_WIFI_VISIBLE] : Key Description [TABLE] Database table where the wifi (visible) data is stored","title":"Phone WiFi Visible"},{"location":"features/phone-wifi-visible/#rapids-provider","text":"Available day segments and platforms Available for all day segments Available for Android only File Sequence - data/raw/ { pid } /phone_wifi_visible_raw.csv - data/raw/ { pid } /phone_wifi_visible_with_datetime.csv - data/interim/ { pid } /phone_wifi_visible_features/phone_wifi_visible_ { language } _ { provider_key } .csv - data/processed/features/ { pid } /phone_wifi_visible.csv Parameters description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Key Description [COMPUTE] Set to True to extract PHONE_WIFI_VISIBLE features from the RAPIDS provider [FEATURES] Features to be computed, see table below Features description for [PHONE_WIFI_VISIBLE][PROVIDERS][RAPIDS] : Feature Units Description countscans devices Number of scanned WiFi access points visible during a day_segment, an access point can be detected multiple times over time and these appearances are counted separately uniquedevices devices Number of unique access point during a day_segment as identified by their hardware address countscansmostuniquedevice scans Number of scans of the most scanned access point during a day_segment across the whole monitoring period Assumptions/Observations A visible WiFI access point is one that a phone sensed around itself but that it was not connected to. Due to API restrictions, this sensor is not available on iOS. By default AWARE stores this data in the wifi table.","title":"RAPIDS provider"},{"location":"setup/configuration/","text":"Initial Configuration \u00b6 You need to follow these steps to configure your RAPIDS deployment before you can extract behavioral features Add your database credentials Choose the timezone of your study Create your participants files Select what day segments you want to extract features on Modify your device data source configuration Select what sensors and features you want to process When you are done with this initial configuration, go to executing RAPIDS . Hint Every time you see config[\"KEY\"] or [KEY] in these docs we are referring to the corresponding key in the config.yaml file. Database credentials \u00b6 Create an empty file called .env in your RAPIDS root directory Add the following lines and replace your database-specific credentials (user, password, host, and database): [ MY_GROUP ] user=MY_USER password=MY_PASSWORD host=MY_HOST port=3306 database=MY_DATABASE Warning The label MY_GROUP is arbitrary but it has to match the following config.yaml key: DATABASE_GROUP : &database_group MY_GROUP Note You can ignore this step if you are only processing Fitbit data in CSV files. Timezone of your study \u00b6 Single timezone \u00b6 If your study only happened in a single time zone, select the appropriate code form this list and change the following config key. Double check your timezone code pick, for example US Eastern Time is America/New_York not EST TIMEZONE : &timezone America/New_York Multiple timezones \u00b6 Support coming soon. Participant files \u00b6 Participant files link together multiple devices (smartphones and wearables) to specific participants and identify them throughout RAPIDS. You can create these files manually or automatically . Participant files are stored in data/external/participant_files/pxx.yaml and follow a unified structure . Note The list PIDS in config.yaml needs to have the participant file names of the people you want to process. For example, if you created p01.yaml , p02.yaml and p03.yaml files in /data/external/participant_files/ , then PIDS should be: PIDS : [ p01 , p02 , p03 ] Tip Attribute values of the [PHONE] and [FITBIT] sections in every participant file are optional which allows you to analyze data from participants that only carried smartphones, only Fitbit devices, or both. Optional: Migrating participants files with the old format If you were using the pre-release version of RAPIDS with participant files in plain text (as opposed to yaml), you can run the following command and your old files will be converted into yaml files stored in data/external/participant_files/ python tools/update_format_participant_files.py Structure of participants files \u00b6 Example of the structure of a participant file In this example, the participant used an android phone, an ios phone, and a fitbit device throughout the study between Apr 23 rd 2020 and Oct 28 th 2020 PHONE : DEVICE_IDS : [ a748ee1a-1d0b-4ae9-9074-279a2b6ba524 , dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43 ] PLATFORMS : [ android , ios ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 FITBIT : DEVICE_IDS : [ fitbit1 ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 For [PHONE] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each smartphone, you can have more than one for when participants changed phones in the middle of the study, in this case, data from all their devices will be joined and relabeled with the last 1 on this list. [PLATFORMS] An array that specifies the OS of each smartphone in [DEVICE_IDS] , use a combination of android or ios (we support participants that changed platforms in the middle of your study!). If you have an aware_device table in your database you can set [PLATFORMS]: [multiple] and RAPIDS will infer them automatically. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis For [FITBIT] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each Fitbit, you can have more than one in case the participant changed devices in the middle of the study, in this case, data from all devices will be joined and relabeled with the last device_id on this list. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis Automatic creation of participant files \u00b6 You have two options a) use the aware_device table in your database or b) use a CSV file. In either case, in your config.yaml , set [PHONE_SECTION][ADD] or [FITBIT_SECTION][ADD] to TRUE depending on what devices you used in your study. Set [DEVICE_ID_COLUMN] to the name of the column that uniquely identifies each device and include any device ids you want to ignore in [IGNORED_DEVICE_IDS] . aware_device table Set the following keys in your config.yaml CREATE_PARTICIPANT_FILES : SOURCE : TYPE : AWARE_DEVICE_TABLE DATABASE_GROUP : *database_group CSV_FILE_PATH : \"\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Then run snakemake -j1 create_participants_files CSV file Set the following keys in your config.yaml . CREATE_PARTICIPANT_FILES : SOURCE : TYPE : CSV_FILE DATABASE_GROUP : \"\" CSV_FILE_PATH : \"your_path/to_your.csv\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Your CSV file ( [SOURCE][CSV_FILE_PATH] ) should have the following columns but you can omit any values you don\u2019t have on each column: Column Description phone device id The name of this column has to match [PHONE_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; fitbit device id The name of this column has to match [FITBIT_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; pid Unique identifiers with the format pXXX (your participant files will be named with this string platform Use android , ios or multiple as explained above, separate values with ; label A human readable string that is used in reports and visualizations. start_date A string with format YYY-MM-DD . end_date A string with format YYY-MM-DD . Example device_id,pid,label,platform,start_date,end_date,fitbit_id a748ee1a-1d0b-4ae9-9074-279a2b6ba524;dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43,p01,julio,android;ios,2020-01-01,2021-01-01,fitbit1 4c4cf7a1-0340-44bc-be0f-d5053bf7390c,p02,meng,ios,2021-01-01,2022-01-01,fitbit2 Then run snakemake -j1 create_participants_files Day Segments \u00b6 Day segments (or epochs) are the time windows on which you want to extract behavioral features. For example, you might want to process data on every day, every morning, or only during weekends. RAPIDS offers three categories of day segments that are flexible enough to cover most use cases: frequency (short time windows every day), periodic (arbitrary time windows on any day), and event (arbitrary time windows around events of interest). See also our examples . Frequency Segments These segments are computed on every day and all have the same duration (for example 30 minutes). Set the following keys in your config.yaml DAY_SEGMENTS : &day_segments TYPE : FREQUENCY FILE : \"data/external/your_frequency_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can only have 1 row. Column Description label A string that is used as a prefix in the name of your day segments length An integer representing the duration of your day segments in minutes Example label,length thirtyminutes,30 This configuration will compute 48 day segments for every day when any data from any participant was sensed. For example: start_time,length,label 00:00,30,thirtyminutes0000 00:30,30,thirtyminutes0001 01:00,30,thirtyminutes0002 01:30,30,thirtyminutes0003 ... Periodic Segments These segments can be computed every day, or on specific days of the week, month, quarter, and year. Their minimum duration is 1 minute but they can be as long as you want. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : PERIODIC FILE : \"data/external/your_periodic_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE If [INCLUDE_PAST_PERIODIC_SEGMENTS] is set to TRUE , RAPIDS will consider instances of your segments back enough in the past as to include the first row of data of each participant. For example, if the first row of data from a participant happened on Saturday March 7 th 2020 and the requested segment duration is 7 days starting on every Sunday, the first segment to be considered would start on Sunday March 1 st if [INCLUDE_PAST_PERIODIC_SEGMENTS] is TRUE or on Sunday March 8 th if FALSE . The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. It has to be unique between rows start_time A string with format HH:MM:SS representing the starting time of this segment on any day length A string representing the length of this segment.It can have one or more of the following strings XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example 7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If you set repeats_on to every_day set this to 0 , otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 morning,06:00:00,5H 59M 59S,every_day,0 afternoon,12:00:00,5H 59M 59S,every_day,0 evening,18:00:00,5H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 This configuration will create five segments instances ( daily , morning , afternoon , evening , night ) on any given day ( every_day set to 0). The daily segment will start at midnight and will last 23:59:59 , the other four segments will start at 6am, 12pm, 6pm, and 12am respectively and last for 05:59:59 . Event segments These segments can be computed before or after an event of interest (defined as any UNIX timestamp). Their minimum duration is 1 minute but they can be as long as you want. The start of each segment can be shifted backwards or forwards from the specified timestamp. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : EVENT FILE : \"data/external/your_event_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. If labels are unique is segment is completely independent, if two segments have the same label their data will be considered together when computing features like the most frequent contact for calls (the most frequent contact will be computed across these segments) start_time A string with format HH:MM:SS representing the starting time of this segment length A string representing the length of this segment.It can have one or more of the following XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example `7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,event_timestamp,length,shift,shift_direction,device_id stress1,1587661220000,1H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress2,1587747620000,4H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress3,1587906020000,3H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress4,1584291600000,7H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress5,1588172420000,9H,5M,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587661220000,1H,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587747620000,1D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587906020000,7D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 This example will create eight segments for a single participant ( a748ee1a... ), five independent stressX segments with various lengths (1,4,3,7, and 9 hours). Segments stress1 , stress3 , and stress5 are shifted forwards by 5 minutes and stress2 and stress4 are shifted backwards by 4 hours (that is, if the stress4 event happened on March 15 th at 1pm EST ( 1584291600000 ), the day segment will start on that day at 9am and end at 4pm). The three mood segments are 1 hour, 1 day and 7 days long and have no shift. In addition, these mood segments are grouped together, meaning that although RAPIDS will compute features on each one of them, some necessary information to compute a few of such features will be extracted from all three segments, for example the phone contact that called a participant the most or the location clusters visited by a participant. Segment Examples \u00b6 Device Data Source Configuration \u00b6 You might need to modify the following config keys in your config.yaml depending on what devices your participants used and where you are storing your data. Hint You can ignore [DEVICE_DATA][PHONE] or [DEVICE_DATA][FITBIT] if you are not working with either devices. The relevant config.yaml section looks as follows by default: DEVICE_DATA : PHONE : SOURCE : TYPE : DATABASE DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : device_id # column name TIMEZONE : TYPE : SINGLE VALUE : *timezone FITBIT : SOURCE : TYPE : DATABASE # DATABASE or FILES (set each FITBIT_SENSOR TABLE attribute accordingly with a table name or a file path) DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : fitbit_id # column name TIMEZONE : TYPE : SINGLE # Fitbit only supports SINGLE timezones VALUE : *timezone For [DEVICE_DATA][PHONE] Key Description [SOURCE] [TYPE] Only DATABASE is supported (phone data will be pulled from a database) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify smartphones. For data collected with AWARE this is usually device_id [TIMEZONE] [TYPE] Only SINGLE is supported [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study For [DEVICE_DATA][FITBIT] Key Description [SOURCE] [TYPE] DATABASE or FILES (set each [FITBIT_SENSOR] [TABLE] attribute accordingly with a table name or a file path) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials . Only used if [TYPE] is DATABASE . [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify Fitbit devices. [TIMEZONE] [TYPE] Only SINGLE is supported (Fitbit devices always store data in local time). [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study Sensor and Features to Process \u00b6 Finally, you need to modify the config.yaml of the sensors you want to process. All sensors follow the same naming nomenclature DEVICE_SENSOR and have the following basic attributes (we will use PHONE_MESSAGES as an example). Hint Every time you change any sensor parameters, all the necessary files will be updated as soon as you execute RAPIDS. Some sensors will have specific attributes (like MESSAGES_TYPES ) so refer to each sensor documentation. PHONE_MESSAGES : TABLE : messages PROVIDERS : RAPIDS : COMPUTE : True MESSAGES_TYPES : [ received , sent ] FEATURES : received : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] sent : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] SRC_LANGUAGE : \"r\" SRC_FOLDER : \"rapids\" # inside src/features/phone_messages Key Description [TABLE] The name of the table in your database that stores this sensor data. [PROVIDERS] A collection of providers . A provider is an author or group of authors that created specific features for the sensor at hand. The provider for all the features implemented by our team is called RAPIDS but we have also included contributions from other researchers (for example DORYAB for location features). [PROVIDER] [COMPUTE] Set this to TRUE if you want to process features for this provider . [PROVIDER] [FEATURES] A list of all the features available for the provider . Delete those that you don\u2019t want to compute. [PROVIDER] [SRC_LANGUAGE] The programming language ( r or python ) in which the features of this provider are implemented. [PROVIDER] [SRC_FOLDER] The folder where the script(s) to compute the features of this provider are stored. This folder is always inside src/features/[DEVICE_SENSOR]/","title":"Initial Configuration"},{"location":"setup/configuration/#initial-configuration","text":"You need to follow these steps to configure your RAPIDS deployment before you can extract behavioral features Add your database credentials Choose the timezone of your study Create your participants files Select what day segments you want to extract features on Modify your device data source configuration Select what sensors and features you want to process When you are done with this initial configuration, go to executing RAPIDS . Hint Every time you see config[\"KEY\"] or [KEY] in these docs we are referring to the corresponding key in the config.yaml file.","title":"Initial Configuration"},{"location":"setup/configuration/#database-credentials","text":"Create an empty file called .env in your RAPIDS root directory Add the following lines and replace your database-specific credentials (user, password, host, and database): [ MY_GROUP ] user=MY_USER password=MY_PASSWORD host=MY_HOST port=3306 database=MY_DATABASE Warning The label MY_GROUP is arbitrary but it has to match the following config.yaml key: DATABASE_GROUP : &database_group MY_GROUP Note You can ignore this step if you are only processing Fitbit data in CSV files.","title":"Database credentials"},{"location":"setup/configuration/#timezone-of-your-study","text":"","title":"Timezone of your study"},{"location":"setup/configuration/#single-timezone","text":"If your study only happened in a single time zone, select the appropriate code form this list and change the following config key. Double check your timezone code pick, for example US Eastern Time is America/New_York not EST TIMEZONE : &timezone America/New_York","title":"Single timezone"},{"location":"setup/configuration/#multiple-timezones","text":"Support coming soon.","title":"Multiple timezones"},{"location":"setup/configuration/#participant-files","text":"Participant files link together multiple devices (smartphones and wearables) to specific participants and identify them throughout RAPIDS. You can create these files manually or automatically . Participant files are stored in data/external/participant_files/pxx.yaml and follow a unified structure . Note The list PIDS in config.yaml needs to have the participant file names of the people you want to process. For example, if you created p01.yaml , p02.yaml and p03.yaml files in /data/external/participant_files/ , then PIDS should be: PIDS : [ p01 , p02 , p03 ] Tip Attribute values of the [PHONE] and [FITBIT] sections in every participant file are optional which allows you to analyze data from participants that only carried smartphones, only Fitbit devices, or both. Optional: Migrating participants files with the old format If you were using the pre-release version of RAPIDS with participant files in plain text (as opposed to yaml), you can run the following command and your old files will be converted into yaml files stored in data/external/participant_files/ python tools/update_format_participant_files.py","title":"Participant files"},{"location":"setup/configuration/#structure-of-participants-files","text":"Example of the structure of a participant file In this example, the participant used an android phone, an ios phone, and a fitbit device throughout the study between Apr 23 rd 2020 and Oct 28 th 2020 PHONE : DEVICE_IDS : [ a748ee1a-1d0b-4ae9-9074-279a2b6ba524 , dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43 ] PLATFORMS : [ android , ios ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 FITBIT : DEVICE_IDS : [ fitbit1 ] LABEL : test01 START_DATE : 2020-04-23 END_DATE : 2020-10-28 For [PHONE] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each smartphone, you can have more than one for when participants changed phones in the middle of the study, in this case, data from all their devices will be joined and relabeled with the last 1 on this list. [PLATFORMS] An array that specifies the OS of each smartphone in [DEVICE_IDS] , use a combination of android or ios (we support participants that changed platforms in the middle of your study!). If you have an aware_device table in your database you can set [PLATFORMS]: [multiple] and RAPIDS will infer them automatically. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis For [FITBIT] Key Description [DEVICE_IDS] An array of the strings that uniquely identify each Fitbit, you can have more than one in case the participant changed devices in the middle of the study, in this case, data from all devices will be joined and relabeled with the last device_id on this list. [LABEL] A string that is used in reports and visualizations. [START_DATE] A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis [END_DATE] A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis","title":"Structure of participants files"},{"location":"setup/configuration/#automatic-creation-of-participant-files","text":"You have two options a) use the aware_device table in your database or b) use a CSV file. In either case, in your config.yaml , set [PHONE_SECTION][ADD] or [FITBIT_SECTION][ADD] to TRUE depending on what devices you used in your study. Set [DEVICE_ID_COLUMN] to the name of the column that uniquely identifies each device and include any device ids you want to ignore in [IGNORED_DEVICE_IDS] . aware_device table Set the following keys in your config.yaml CREATE_PARTICIPANT_FILES : SOURCE : TYPE : AWARE_DEVICE_TABLE DATABASE_GROUP : *database_group CSV_FILE_PATH : \"\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Then run snakemake -j1 create_participants_files CSV file Set the following keys in your config.yaml . CREATE_PARTICIPANT_FILES : SOURCE : TYPE : CSV_FILE DATABASE_GROUP : \"\" CSV_FILE_PATH : \"your_path/to_your.csv\" TIMEZONE : *timezone PHONE_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : device_id # column name IGNORED_DEVICE_IDS : [] FITBIT_SECTION : ADD : TRUE # or FALSE DEVICE_ID_COLUMN : fitbit_id # column name IGNORED_DEVICE_IDS : [] Your CSV file ( [SOURCE][CSV_FILE_PATH] ) should have the following columns but you can omit any values you don\u2019t have on each column: Column Description phone device id The name of this column has to match [PHONE_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; fitbit device id The name of this column has to match [FITBIT_SECTION][DEVICE_ID_COLUMN] . Separate multiple ids with ; pid Unique identifiers with the format pXXX (your participant files will be named with this string platform Use android , ios or multiple as explained above, separate values with ; label A human readable string that is used in reports and visualizations. start_date A string with format YYY-MM-DD . end_date A string with format YYY-MM-DD . Example device_id,pid,label,platform,start_date,end_date,fitbit_id a748ee1a-1d0b-4ae9-9074-279a2b6ba524;dsadas-2324-fgsf-sdwr-gdfgs4rfsdf43,p01,julio,android;ios,2020-01-01,2021-01-01,fitbit1 4c4cf7a1-0340-44bc-be0f-d5053bf7390c,p02,meng,ios,2021-01-01,2022-01-01,fitbit2 Then run snakemake -j1 create_participants_files","title":"Automatic creation of participant files"},{"location":"setup/configuration/#day-segments","text":"Day segments (or epochs) are the time windows on which you want to extract behavioral features. For example, you might want to process data on every day, every morning, or only during weekends. RAPIDS offers three categories of day segments that are flexible enough to cover most use cases: frequency (short time windows every day), periodic (arbitrary time windows on any day), and event (arbitrary time windows around events of interest). See also our examples . Frequency Segments These segments are computed on every day and all have the same duration (for example 30 minutes). Set the following keys in your config.yaml DAY_SEGMENTS : &day_segments TYPE : FREQUENCY FILE : \"data/external/your_frequency_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can only have 1 row. Column Description label A string that is used as a prefix in the name of your day segments length An integer representing the duration of your day segments in minutes Example label,length thirtyminutes,30 This configuration will compute 48 day segments for every day when any data from any participant was sensed. For example: start_time,length,label 00:00,30,thirtyminutes0000 00:30,30,thirtyminutes0001 01:00,30,thirtyminutes0002 01:30,30,thirtyminutes0003 ... Periodic Segments These segments can be computed every day, or on specific days of the week, month, quarter, and year. Their minimum duration is 1 minute but they can be as long as you want. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : PERIODIC FILE : \"data/external/your_periodic_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE If [INCLUDE_PAST_PERIODIC_SEGMENTS] is set to TRUE , RAPIDS will consider instances of your segments back enough in the past as to include the first row of data of each participant. For example, if the first row of data from a participant happened on Saturday March 7 th 2020 and the requested segment duration is 7 days starting on every Sunday, the first segment to be considered would start on Sunday March 1 st if [INCLUDE_PAST_PERIODIC_SEGMENTS] is TRUE or on Sunday March 8 th if FALSE . The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. It has to be unique between rows start_time A string with format HH:MM:SS representing the starting time of this segment on any day length A string representing the length of this segment.It can have one or more of the following strings XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example 7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If you set repeats_on to every_day set this to 0 , otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 morning,06:00:00,5H 59M 59S,every_day,0 afternoon,12:00:00,5H 59M 59S,every_day,0 evening,18:00:00,5H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 This configuration will create five segments instances ( daily , morning , afternoon , evening , night ) on any given day ( every_day set to 0). The daily segment will start at midnight and will last 23:59:59 , the other four segments will start at 6am, 12pm, 6pm, and 12am respectively and last for 05:59:59 . Event segments These segments can be computed before or after an event of interest (defined as any UNIX timestamp). Their minimum duration is 1 minute but they can be as long as you want. The start of each segment can be shifted backwards or forwards from the specified timestamp. Set the following keys in your config.yaml . DAY_SEGMENTS : &day_segments TYPE : EVENT FILE : \"data/external/your_event_segments.csv\" INCLUDE_PAST_PERIODIC_SEGMENTS : FALSE # or TRUE The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows. Column Description label A string that is used as a prefix in the name of your day segments. If labels are unique is segment is completely independent, if two segments have the same label their data will be considered together when computing features like the most frequent contact for calls (the most frequent contact will be computed across these segments) start_time A string with format HH:MM:SS representing the starting time of this segment length A string representing the length of this segment.It can have one or more of the following XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example `7D 23H 59M 59S repeats_on One of the follow options every_day , wday , qday , mday , and yday . The last four represent a week, quarter, month and year day repeats_value An integer complementing repeats_on . If every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday , 1-91 represent a qday , and 1-366 represent a yday Example label,event_timestamp,length,shift,shift_direction,device_id stress1,1587661220000,1H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress2,1587747620000,4H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress3,1587906020000,3H,5M,1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress4,1584291600000,7H,4H,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 stress5,1588172420000,9H,5M,-1,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587661220000,1H,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587747620000,1D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 mood,1587906020000,7D,0,0,a748ee1a-1d0b-4ae9-9074-279a2b6ba524 This example will create eight segments for a single participant ( a748ee1a... ), five independent stressX segments with various lengths (1,4,3,7, and 9 hours). Segments stress1 , stress3 , and stress5 are shifted forwards by 5 minutes and stress2 and stress4 are shifted backwards by 4 hours (that is, if the stress4 event happened on March 15 th at 1pm EST ( 1584291600000 ), the day segment will start on that day at 9am and end at 4pm). The three mood segments are 1 hour, 1 day and 7 days long and have no shift. In addition, these mood segments are grouped together, meaning that although RAPIDS will compute features on each one of them, some necessary information to compute a few of such features will be extracted from all three segments, for example the phone contact that called a participant the most or the location clusters visited by a participant.","title":"Day Segments"},{"location":"setup/configuration/#segment-examples","text":"","title":"Segment Examples"},{"location":"setup/configuration/#device-data-source-configuration","text":"You might need to modify the following config keys in your config.yaml depending on what devices your participants used and where you are storing your data. Hint You can ignore [DEVICE_DATA][PHONE] or [DEVICE_DATA][FITBIT] if you are not working with either devices. The relevant config.yaml section looks as follows by default: DEVICE_DATA : PHONE : SOURCE : TYPE : DATABASE DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : device_id # column name TIMEZONE : TYPE : SINGLE VALUE : *timezone FITBIT : SOURCE : TYPE : DATABASE # DATABASE or FILES (set each FITBIT_SENSOR TABLE attribute accordingly with a table name or a file path) DATABASE_GROUP : *database_group DEVICE_ID_COLUMN : fitbit_id # column name TIMEZONE : TYPE : SINGLE # Fitbit only supports SINGLE timezones VALUE : *timezone For [DEVICE_DATA][PHONE] Key Description [SOURCE] [TYPE] Only DATABASE is supported (phone data will be pulled from a database) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify smartphones. For data collected with AWARE this is usually device_id [TIMEZONE] [TYPE] Only SINGLE is supported [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study For [DEVICE_DATA][FITBIT] Key Description [SOURCE] [TYPE] DATABASE or FILES (set each [FITBIT_SENSOR] [TABLE] attribute accordingly with a table name or a file path) [SOURCE] [DATABASE_GROUP] *database_group points to the value defined before in Database credentials . Only used if [TYPE] is DATABASE . [SOURCE] [DEVICE_ID_COLUMN] The column that has strings that uniquely identify Fitbit devices. [TIMEZONE] [TYPE] Only SINGLE is supported (Fitbit devices always store data in local time). [TIMEZONE] [VALUE] *timezone points to the value defined before in Timezone of your study","title":"Device Data Source Configuration"},{"location":"setup/configuration/#sensor-and-features-to-process","text":"Finally, you need to modify the config.yaml of the sensors you want to process. All sensors follow the same naming nomenclature DEVICE_SENSOR and have the following basic attributes (we will use PHONE_MESSAGES as an example). Hint Every time you change any sensor parameters, all the necessary files will be updated as soon as you execute RAPIDS. Some sensors will have specific attributes (like MESSAGES_TYPES ) so refer to each sensor documentation. PHONE_MESSAGES : TABLE : messages PROVIDERS : RAPIDS : COMPUTE : True MESSAGES_TYPES : [ received , sent ] FEATURES : received : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] sent : [ count , distinctcontacts , timefirstmessage , timelastmessage , countmostfrequentcontact ] SRC_LANGUAGE : \"r\" SRC_FOLDER : \"rapids\" # inside src/features/phone_messages Key Description [TABLE] The name of the table in your database that stores this sensor data. [PROVIDERS] A collection of providers . A provider is an author or group of authors that created specific features for the sensor at hand. The provider for all the features implemented by our team is called RAPIDS but we have also included contributions from other researchers (for example DORYAB for location features). [PROVIDER] [COMPUTE] Set this to TRUE if you want to process features for this provider . [PROVIDER] [FEATURES] A list of all the features available for the provider . Delete those that you don\u2019t want to compute. [PROVIDER] [SRC_LANGUAGE] The programming language ( r or python ) in which the features of this provider are implemented. [PROVIDER] [SRC_FOLDER] The folder where the script(s) to compute the features of this provider are stored. This folder is always inside src/features/[DEVICE_SENSOR]/","title":"Sensor and Features to Process"},{"location":"setup/execution/","text":"Execution \u00b6 After you have installed and configured RAPIDS, use the following command to execute it. ./rapids -j1 Info The script ./rapids is a wrapper around Snakemake so you can pass any parameters that Snakemake accepts (e.g. -j1 ). Updating RAPIDS output after modifying config.yaml Any changes to the config.yaml file will be applied automatically and only the relevant files will be updated. This means that after modifying the features list for PHONE_MESSAGE for example, RAPIDS will update the output file with the correct features. Multi-core You can run RAPIDS over multiple cores by modifying the -j argument (e.g. use -j8 to use 8 cores). However , take into account that this means multiple sensor datasets for different participants will be load in memory at the same time. If RAPIDS crashes because it ran out of memory reduce the number of cores and try again. As reference, we have run RAPIDS over 12 cores and 32 Gb of RAM without problems for a study with 200 participants with 14 days of low-frequency smartphone data (no accelerometer, gyroscope, or magnetometer). Forcing a complete rerun If you want to update your data from your database or rerun the whole pipeline from scratch run one or both of the following commands depending on the devices you are using: ./rapids -j1 -R download_phone_data ./rapids -j1 -R download_fitbit_data Deleting RAPIDS output If you want to delete all the output files RAPIDS produces you can execute the following command (the content of these folders will be deleted: data/raw , data/interim , data/processed , reports/figures , and reports/compliance ) ./rapids -j1 -R clean Ready to extract behavioral features If you are ready to extract features head over to the Behavioral Features Introduction","title":"Execution"},{"location":"setup/execution/#execution","text":"After you have installed and configured RAPIDS, use the following command to execute it. ./rapids -j1 Info The script ./rapids is a wrapper around Snakemake so you can pass any parameters that Snakemake accepts (e.g. -j1 ). Updating RAPIDS output after modifying config.yaml Any changes to the config.yaml file will be applied automatically and only the relevant files will be updated. This means that after modifying the features list for PHONE_MESSAGE for example, RAPIDS will update the output file with the correct features. Multi-core You can run RAPIDS over multiple cores by modifying the -j argument (e.g. use -j8 to use 8 cores). However , take into account that this means multiple sensor datasets for different participants will be load in memory at the same time. If RAPIDS crashes because it ran out of memory reduce the number of cores and try again. As reference, we have run RAPIDS over 12 cores and 32 Gb of RAM without problems for a study with 200 participants with 14 days of low-frequency smartphone data (no accelerometer, gyroscope, or magnetometer). Forcing a complete rerun If you want to update your data from your database or rerun the whole pipeline from scratch run one or both of the following commands depending on the devices you are using: ./rapids -j1 -R download_phone_data ./rapids -j1 -R download_fitbit_data Deleting RAPIDS output If you want to delete all the output files RAPIDS produces you can execute the following command (the content of these folders will be deleted: data/raw , data/interim , data/processed , reports/figures , and reports/compliance ) ./rapids -j1 -R clean Ready to extract behavioral features If you are ready to extract features head over to the Behavioral Features Introduction","title":"Execution"},{"location":"setup/installation/","text":"Installation \u00b6 You can install RAPIDS using Docker (the fastest), or native instructions for MacOS and Ubuntu Docker Install Docker Pull our RAPIDS container docker pull agamk/rapids:latest ` Run RAPIDS' container (after this step is done you should see a prompt in the main RAPIDS folder with its python environment active) docker run -it agamk/rapids:latest Pull the latest version of RAPIDS git pull Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Optional . You can edit RAPIDS files with vim but we recommend using Visual Studio Code and its Remote Containers extension How to configure Remote Containers extension Make sure RAPIDS container is running Install the Remote - Containers extension Go to the Remote Explorer panel on the left hand sidebar On the top right dropdown menu choose Containers Double click on the agamk/rapids container in the CONTAINERS tree A new VS Code session should open on RAPIDS main folder insidethe container. MacOS We tested these instructions in Catalina Install brew Install MySQL brew install mysql brew services start mysql Install R 4.0, pandoc and rmarkdown. If you have other instances of R, we recommend uninstalling them brew install r brew install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install miniconda (restart your terminal afterwards) brew cask install miniconda conda init zsh # (or conda init bash) Clone our repo git clone https://github.com/carissalow/rapids Create a python virtual environment cd rapids conda env create -f environment.yml -n rapids conda activate rapids Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Ubuntu We tested on Ubuntu 18.04 & 20.04 Install dependencies sudo apt install libcurl4-openssl-dev sudo apt install libssl-dev sudo apt install libxml2-dev Install MySQL sudo apt install libmysqlclient-dev sudo apt install mysql-server Add key for R\u2019s repository. sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9 Add R\u2019s repository For 18.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu bionic-cran40/' For 20.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu focal-cran40/' Install R 4.0. If you have other instances of R, we recommend uninstalling them sudo apt update sudo apt install r-base Install Pandoc and rmarkdown sudo apt install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install git sudo apt install git Install miniconda Restart your current shell Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1","title":"Installation"},{"location":"setup/installation/#installation","text":"You can install RAPIDS using Docker (the fastest), or native instructions for MacOS and Ubuntu Docker Install Docker Pull our RAPIDS container docker pull agamk/rapids:latest ` Run RAPIDS' container (after this step is done you should see a prompt in the main RAPIDS folder with its python environment active) docker run -it agamk/rapids:latest Pull the latest version of RAPIDS git pull Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Optional . You can edit RAPIDS files with vim but we recommend using Visual Studio Code and its Remote Containers extension How to configure Remote Containers extension Make sure RAPIDS container is running Install the Remote - Containers extension Go to the Remote Explorer panel on the left hand sidebar On the top right dropdown menu choose Containers Double click on the agamk/rapids container in the CONTAINERS tree A new VS Code session should open on RAPIDS main folder insidethe container. MacOS We tested these instructions in Catalina Install brew Install MySQL brew install mysql brew services start mysql Install R 4.0, pandoc and rmarkdown. If you have other instances of R, we recommend uninstalling them brew install r brew install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install miniconda (restart your terminal afterwards) brew cask install miniconda conda init zsh # (or conda init bash) Clone our repo git clone https://github.com/carissalow/rapids Create a python virtual environment cd rapids conda env create -f environment.yml -n rapids conda activate rapids Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1 Ubuntu We tested on Ubuntu 18.04 & 20.04 Install dependencies sudo apt install libcurl4-openssl-dev sudo apt install libssl-dev sudo apt install libxml2-dev Install MySQL sudo apt install libmysqlclient-dev sudo apt install mysql-server Add key for R\u2019s repository. sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9 Add R\u2019s repository For 18.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu bionic-cran40/' For 20.04 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu focal-cran40/' Install R 4.0. If you have other instances of R, we recommend uninstalling them sudo apt update sudo apt install r-base Install Pandoc and rmarkdown sudo apt install pandoc Rscript --vanilla -e 'install.packages(\"rmarkdown\", repos=\"http://cran.us.r-project.org\")' Install git sudo apt install git Install miniconda Restart your current shell Clone our repo: git clone https://github.com/carissalow/rapids Create a python virtual environment: cd rapids conda env create -f environment.yml -n MY_ENV_NAME conda activate MY_ENV_NAME Install R packages and virtual environment: snakemake -j1 renv_install snakemake -j1 renv_restore Note This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion. Make RAPIDS script executable chmod +x rapids Check that RAPIDS is working ./rapids -j1","title":"Installation"},{"location":"workflow-examples/minimal/","text":"Minimal Working Example \u00b6 This is a quick guide for creating and running a simple pipeline to extract missing, outgoing, and incoming call features for daily and night epochs of one participant monitored on the US East coast. Install RAPIDS and make sure your conda environment is active (see Installation ) For the Initial Configuration steps do the following and use the example as a guide: Things to change on each configuration step 1. Setup your database connection credentials in .env . We assume your credentials group is called MY_GROUP . 2. America/New_York should be the default timezone 3. Create a participant file p01.yaml based on one of your participants and add p01 to [PIDS] in config.yaml 4. [DAY_SEGMENTS][TYPE] should be the default PERIODIC . Change [DAY_SEGMENTS][FILE] with the path of a file containing the following lines: label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 5. If you collected data with AWARE you won\u2019t need to modify the attributes of [DEVICE_DATA][PHONE] 6. Set [PHONE_CALLS][PROVIDERS][RAPIDS][COMPUTE] to True Example of the config.yaml sections after the changes outlined above PIDS: [p01] TIMEZONE: &timezone America/New_York DATABASE_GROUP: &database_group MY_GROUP # ... other irrelevant sections DAY_SEGMENTS: &day_segments TYPE: PERIODIC FILE: \"data/external/daysegments_periodic.csv\" # make sure the three lines specified above are in the file INCLUDE_PAST_PERIODIC_SEGMENTS: FALSE # No need to change this if you collected AWARE data on a database and your credentials are grouped under `MY_GROUP` in `.env` DEVICE_DATA: PHONE: SOURCE: TYPE: DATABASE DATABASE_GROUP: *database_group DEVICE_ID_COLUMN: device_id # column name TIMEZONE: TYPE: SINGLE # SINGLE or MULTIPLE VALUE: *timezone ############## PHONE ########################################################### ################################################################################ .... # Communication call features config, TYPES and FEATURES keys need to match PHONE_CALLS: TABLE: calls # change if your calls table has a different name PROVIDERS: RAPIDS: COMPUTE: True # set this to True! CALL_TYPES: ... Run RAPIDS ./rapids -j1 The call features for daily and morning day segments will be in /data/processed/features/p01/phone_calls.csv","title":"Minimal"},{"location":"workflow-examples/minimal/#minimal-working-example","text":"This is a quick guide for creating and running a simple pipeline to extract missing, outgoing, and incoming call features for daily and night epochs of one participant monitored on the US East coast. Install RAPIDS and make sure your conda environment is active (see Installation ) For the Initial Configuration steps do the following and use the example as a guide: Things to change on each configuration step 1. Setup your database connection credentials in .env . We assume your credentials group is called MY_GROUP . 2. America/New_York should be the default timezone 3. Create a participant file p01.yaml based on one of your participants and add p01 to [PIDS] in config.yaml 4. [DAY_SEGMENTS][TYPE] should be the default PERIODIC . Change [DAY_SEGMENTS][FILE] with the path of a file containing the following lines: label,start_time,length,repeats_on,repeats_value daily,00:00:00,23H 59M 59S,every_day,0 night,00:00:00,5H 59M 59S,every_day,0 5. If you collected data with AWARE you won\u2019t need to modify the attributes of [DEVICE_DATA][PHONE] 6. Set [PHONE_CALLS][PROVIDERS][RAPIDS][COMPUTE] to True Example of the config.yaml sections after the changes outlined above PIDS: [p01] TIMEZONE: &timezone America/New_York DATABASE_GROUP: &database_group MY_GROUP # ... other irrelevant sections DAY_SEGMENTS: &day_segments TYPE: PERIODIC FILE: \"data/external/daysegments_periodic.csv\" # make sure the three lines specified above are in the file INCLUDE_PAST_PERIODIC_SEGMENTS: FALSE # No need to change this if you collected AWARE data on a database and your credentials are grouped under `MY_GROUP` in `.env` DEVICE_DATA: PHONE: SOURCE: TYPE: DATABASE DATABASE_GROUP: *database_group DEVICE_ID_COLUMN: device_id # column name TIMEZONE: TYPE: SINGLE # SINGLE or MULTIPLE VALUE: *timezone ############## PHONE ########################################################### ################################################################################ .... # Communication call features config, TYPES and FEATURES keys need to match PHONE_CALLS: TABLE: calls # change if your calls table has a different name PROVIDERS: RAPIDS: COMPUTE: True # set this to True! CALL_TYPES: ... Run RAPIDS ./rapids -j1 The call features for daily and morning day segments will be in /data/processed/features/p01/phone_calls.csv","title":"Minimal Working Example"}]}
\ No newline at end of file
diff --git a/latest/setup/configuration/index.html b/latest/setup/configuration/index.html
new file mode 100644
index 00000000..5d3570aa
--- /dev/null
+++ b/latest/setup/configuration/index.html
@@ -0,0 +1,1645 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Initial Configuration - RAPIDS
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
If your study only happened in a single time zone, select the appropriate code form this list and change the following config key. Double check your timezone code pick, for example US Eastern Time is America/New_York not EST
Participant files link together multiple devices (smartphones and wearables) to specific participants and identify them throughout RAPIDS. You can create these files manually or automatically. Participant files are stored in data/external/participant_files/pxx.yaml and follow a unified structure.
+
+
Note
+
The list PIDS in config.yaml needs to have the participant file names of the people you want to process. For example, if you created p01.yaml, p02.yaml and p03.yaml files in /data/external/participant_files/, then PIDS should be:
+
PIDS:[p01,p02,p03]
+
+
+
+
Tip
+
Attribute values of the [PHONE] and [FITBIT] sections in every participant file are optional which allows you to analyze data from participants that only carried smartphones, only Fitbit devices, or both.
+
+Optional: Migrating participants files with the old format
If you were using the pre-release version of RAPIDS with participant files in plain text (as opposed to yaml), you can run the following command and your old files will be converted into yaml files stored in data/external/participant_files/
An array of the strings that uniquely identify each smartphone, you can have more than one for when participants changed phones in the middle of the study, in this case, data from all their devices will be joined and relabeled with the last 1 on this list.
+
+
+
[PLATFORMS]
+
An array that specifies the OS of each smartphone in [DEVICE_IDS] , use a combination of android or ios (we support participants that changed platforms in the middle of your study!). If you have an aware_device table in your database you can set [PLATFORMS]: [multiple] and RAPIDS will infer them automatically.
+
+
+
[LABEL]
+
A string that is used in reports and visualizations.
+
+
+
[START_DATE]
+
A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis
+
+
+
[END_DATE]
+
A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis
+
+
+
+
For [FITBIT]
+
+
+
+
Key
+
Description
+
+
+
+
+
[DEVICE_IDS]
+
An array of the strings that uniquely identify each Fitbit, you can have more than one in case the participant changed devices in the middle of the study, in this case, data from all devices will be joined and relabeled with the last device_id on this list.
+
+
+
[LABEL]
+
A string that is used in reports and visualizations.
+
+
+
[START_DATE]
+
A string with format YYY-MM-DD . Only data collected after this date will be included in the analysis
+
+
+
[END_DATE]
+
A string with format YYY-MM-DD . Only data collected before this date will be included in the analysis
You have two options a) use the aware_device table in your database or b) use a CSV file. In either case, in your config.yaml, set [PHONE_SECTION][ADD] or [FITBIT_SECTION][ADD] to TRUE depending on what devices you used in your study. Set [DEVICE_ID_COLUMN] to the name of the column that uniquely identifies each device and include any device ids you want to ignore in [IGNORED_DEVICE_IDS].
+
+
Set the following keys in your config.yaml
+
CREATE_PARTICIPANT_FILES:
+ SOURCE:
+ TYPE:AWARE_DEVICE_TABLE
+ DATABASE_GROUP:*database_group
+ CSV_FILE_PATH:""
+ TIMEZONE:*timezone
+ PHONE_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:device_id# column name
+ IGNORED_DEVICE_IDS:[]
+ FITBIT_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:fitbit_id# column name
+ IGNORED_DEVICE_IDS:[]
+
+
Then run
+
snakemake -j1 create_participants_files
+
+
+
+
Set the following keys in your config.yaml.
+
CREATE_PARTICIPANT_FILES:
+ SOURCE:
+ TYPE:CSV_FILE
+ DATABASE_GROUP:""
+ CSV_FILE_PATH:"your_path/to_your.csv"
+ TIMEZONE:*timezone
+ PHONE_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:device_id# column name
+ IGNORED_DEVICE_IDS:[]
+ FITBIT_SECTION:
+ ADD:TRUE# or FALSE
+ DEVICE_ID_COLUMN:fitbit_id# column name
+ IGNORED_DEVICE_IDS:[]
+
+Your CSV file ([SOURCE][CSV_FILE_PATH]) should have the following columns but you can omit any values you don’t have on each column:
+
+
+
+
Column
+
Description
+
+
+
+
+
phone device id
+
The name of this column has to match [PHONE_SECTION][DEVICE_ID_COLUMN]. Separate multiple ids with ;
+
+
+
fitbit device id
+
The name of this column has to match [FITBIT_SECTION][DEVICE_ID_COLUMN]. Separate multiple ids with ;
+
+
+
pid
+
Unique identifiers with the format pXXX (your participant files will be named with this string
+
+
+
platform
+
Use android, ios or multiple as explained above, separate values with ;
+
+
+
label
+
A human readable string that is used in reports and visualizations.
Day segments (or epochs) are the time windows on which you want to extract behavioral features. For example, you might want to process data on every day, every morning, or only during weekends. RAPIDS offers three categories of day segments that are flexible enough to cover most use cases: frequency (short time windows every day), periodic (arbitrary time windows on any day), and event (arbitrary time windows around events of interest). See also our examples.
+
+
These segments are computed on every day and all have the same duration (for example 30 minutes). Set the following keys in your config.yaml
These segments can be computed every day, or on specific days of the week, month, quarter, and year. Their minimum duration is 1 minute but they can be as long as you want. Set the following keys in your config.yaml.
+
DAY_SEGMENTS:&day_segments
+ TYPE:PERIODIC
+ FILE:"data/external/your_periodic_segments.csv"
+ INCLUDE_PAST_PERIODIC_SEGMENTS:FALSE# or TRUE
+
+
If [INCLUDE_PAST_PERIODIC_SEGMENTS] is set to TRUE, RAPIDS will consider instances of your segments back enough in the past as to include the first row of data of each participant. For example, if the first row of data from a participant happened on Saturday March 7th 2020 and the requested segment duration is 7 days starting on every Sunday, the first segment to be considered would start on Sunday March 1st if [INCLUDE_PAST_PERIODIC_SEGMENTS] is TRUE or on Sunday March 8th if FALSE.
+
The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows.
+
+
+
+
Column
+
Description
+
+
+
+
+
label
+
A string that is used as a prefix in the name of your day segments. It has to be unique between rows
+
+
+
start_time
+
A string with format HH:MM:SS representing the starting time of this segment on any day
+
+
+
length
+
A string representing the length of this segment.It can have one or more of the following strings XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example 7D 23H 59M 59S
+
+
+
repeats_on
+
One of the follow options every_day, wday, qday, mday, and yday. The last four represent a week, quarter, month and year day
+
+
+
repeats_value
+
An integer complementing repeats_on. If you set repeats_on to every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday, 1-91 represent a qday, and 1-366 represent a yday
This configuration will create five segments instances (daily, morning, afternoon, evening, night) on any given day (every_day set to 0). The daily segment will start at midnight and will last 23:59:59, the other four segments will start at 6am, 12pm, 6pm, and 12am respectively and last for 05:59:59.
+
+
+
+
These segments can be computed before or after an event of interest (defined as any UNIX timestamp). Their minimum duration is 1 minute but they can be as long as you want. The start of each segment can be shifted backwards or forwards from the specified timestamp. Set the following keys in your config.yaml.
+
DAY_SEGMENTS:&day_segments
+ TYPE:EVENT
+ FILE:"data/external/your_event_segments.csv"
+ INCLUDE_PAST_PERIODIC_SEGMENTS:FALSE# or TRUE
+
+
The file pointed by [DAY_SEGMENTS][FILE] should have the following format and can have multiple rows.
+
+
+
+
Column
+
Description
+
+
+
+
+
label
+
A string that is used as a prefix in the name of your day segments. If labels are unique is segment is completely independent, if two segments have the same label their data will be considered together when computing features like the most frequent contact for calls (the most frequent contact will be computed across these segments)
+
+
+
start_time
+
A string with format HH:MM:SS representing the starting time of this segment
+
+
+
length
+
A string representing the length of this segment.It can have one or more of the following XXD XXH XXM XXS to represent days, hours, minutes and seconds. For example `7D 23H 59M 59S
+
+
+
repeats_on
+
One of the follow options every_day, wday, qday, mday, and yday. The last four represent a week, quarter, month and year day
+
+
+
repeats_value
+
An integer complementing repeats_on. If every_day set this to 0, otherwise 1-7 represent a wday starting from Mondays, 1-31 represent a mday, 1-91 represent a qday, and 1-366 represent a yday
This example will create eight segments for a single participant (a748ee1a...), five independent stressX segments with various lengths (1,4,3,7, and 9 hours). Segments stress1, stress3, and stress5 are shifted forwards by 5 minutes and stress2 and stress4 are shifted backwards by 4 hours (that is, if the stress4 event happened on March 15th at 1pm EST (1584291600000), the day segment will start on that day at 9am and end at 4pm).
+
The three mood segments are 1 hour, 1 day and 7 days long and have no shift. In addition, these mood segments are grouped together, meaning that although RAPIDS will compute features on each one of them, some necessary information to compute a few of such features will be extracted from all three segments, for example the phone contact that called a participant the most or the location clusters visited by a participant.
You might need to modify the following config keys in your config.yaml depending on what devices your participants used and where you are storing your data.
+
+
Hint
+
You can ignore [DEVICE_DATA][PHONE] or [DEVICE_DATA][FITBIT] if you are not working with either devices.
+
+
The relevant config.yaml section looks as follows by default:
+
DEVICE_DATA:
+ PHONE:
+ SOURCE:
+ TYPE:DATABASE
+ DATABASE_GROUP:*database_group
+ DEVICE_ID_COLUMN:device_id# column name
+ TIMEZONE:
+ TYPE:SINGLE
+ VALUE:*timezone
+ FITBIT:
+ SOURCE:
+ TYPE:DATABASE# DATABASE or FILES (set each FITBIT_SENSOR TABLE attribute accordingly with a table name or a file path)
+ DATABASE_GROUP:*database_group
+ DEVICE_ID_COLUMN:fitbit_id# column name
+ TIMEZONE:
+ TYPE:SINGLE# Fitbit only supports SINGLE timezones
+ VALUE:*timezone
+
+
For [DEVICE_DATA][PHONE]
+
+
+
+
Key
+
Description
+
+
+
+
+
[SOURCE] [TYPE]
+
Only DATABASE is supported (phone data will be pulled from a database)
Finally, you need to modify the config.yaml of the sensors you want to process. All sensors follow the same naming nomenclature DEVICE_SENSOR and have the following basic attributes (we will use PHONE_MESSAGES as an example).
+
+
Hint
+
Every time you change any sensor parameters, all the necessary files will be updated as soon as you execute RAPIDS. Some sensors will have specific attributes (like MESSAGES_TYPES) so refer to each sensor documentation.
The name of the table in your database that stores this sensor data.
+
+
+
[PROVIDERS]
+
A collection of providers . A provider is an author or group of authors that created specific features for the sensor at hand. The provider for all the features implemented by our team is called RAPIDS but we have also included contributions from other researchers (for example DORYAB for location features).
+
+
+
[PROVIDER][COMPUTE]
+
Set this to TRUE if you want to process features for this provider .
+
+
+
[PROVIDER][FEATURES]
+
A list of all the features available for the provider . Delete those that you don’t want to compute.
+
+
+
[PROVIDER][SRC_LANGUAGE]
+
The programming language ( r or python ) in which the features of this provider are implemented.
+
+
+
[PROVIDER][SRC_FOLDER]
+
The folder where the script(s) to compute the features of this provider are stored. This folder is always inside src/features/[DEVICE_SENSOR]/
After you have installed and configured RAPIDS, use the following command to execute it.
+
./rapids -j1
+
+
+
Info
+
The script ./rapids is a wrapper around Snakemake so you can pass any parameters that Snakemake accepts (e.g. -j1).
+
+
+
Updating RAPIDS output after modifying config.yaml
+
Any changes to the config.yaml file will be applied automatically and only the relevant files will be updated. This means that after modifying the features list for PHONE_MESSAGE for example, RAPIDS will update the output file with the correct features.
+
+
+
Multi-core
+
You can run RAPIDS over multiple cores by modifying the -j argument (e.g. use -j8 to use 8 cores). However, take into account that this means multiple sensor datasets for different participants will be load in memory at the same time. If RAPIDS crashes because it ran out of memory reduce the number of cores and try again.
+
As reference, we have run RAPIDS over 12 cores and 32 Gb of RAM without problems for a study with 200 participants with 14 days of low-frequency smartphone data (no accelerometer, gyroscope, or magnetometer).
+
+
+
Forcing a complete rerun
+
If you want to update your data from your database or rerun the whole pipeline from scratch run one or both of the following commands depending on the devices you are using:
If you want to delete all the output files RAPIDS produces you can execute the following command (the content of these folders will be deleted: data/raw, data/interim, data/processed, reports/figures, and reports/compliance)
This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion.
This step could take several minutes to complete, especially if you have less than 3Gb of RAM or packages need to be compiled from source. Please be patient and let it run until completion.
Julio Vega is a postdoctoral associate at the Mobile Sensing + Health Institute. He is interested in personalized methodologies to monitor chronic conditions that affect daily human behavior using mobile and wearable data.
Meng Li received her Master of Science degree in Information Science from the University of Pittsburgh. She is interested in applying machine learning algorithms to the medical field.
Abhineeth Reddy Kunta is a Senior Software Engineer with the Mobile Sensing + Health Institute. He is experienced in software development and specializes in building solutions using machine learning. Abhineeth likes exploring ways to leverage technology in advancing medicine and education. Previously he worked as a Computer Programmer at Georgia Department of Public Health. He has a master’s degree in Computer Science from George Mason University.
Kwesi Aguillera is currently in his first year at the University of Pittsburgh pursuing a Master of Sciences in Information Science specializing in Big Data Analytics. He received his Bachelor of Science degree in Computer Science and Management from the University of the West Indies. Kwesi considers himself a full stack developer and looks forward to applying this knowledge to big data analysis.
Echhit Joshi is a Masters student at the School of Computing and Information at University of Pittsburgh. His areas of interest are Machine/Deep Learning, Data Mining, and Analytics.
Nicolas is a rising senior studying computer science at the University of Pittsburgh. His academic interests include databases, machine learning, and application development. After completing his undergraduate degree, he plans to attend graduate school for a MS in Computer Science with a focus on Intelligent Systems.
Nik is a graduate student at the University of Pittsburgh pursuing Master of Science in Information Science. He earned his Bachelor of Technology degree in Information Technology from India. He is a Data Enthusiasts and passionate about finding the meaning out of raw data. In a long term, his goal is to create a breakthrough in Data Science and Deep Learning.
Agam is a junior at Carnegie Mellon University studying Statistics and Machine Learning and pursuing an additional major in Computer Science. He is a member of the Data Science team in the Health and Human Performance Lab at CMU and has keen interests in software development and data science. His research interests include ML applications in medicine.
This is a quick guide for creating and running a simple pipeline to extract missing, outgoing, and incoming call features for daily and night epochs of one participant monitored on the US East coast.
+
+
Install RAPIDS and make sure your conda environment is active (see Installation)
+
+
For the Initial Configuration steps do the following and use the example as a guide:
+
+
Things to change on each configuration step
+
1. Setup your database connection credentials in .env. We assume your credentials group is called MY_GROUP.
+
2. America/New_York should be the default timezone
+
3. Create a participant file p01.yaml based on one of your participants and add p01 to [PIDS] in config.yaml
+
4. [DAY_SEGMENTS][TYPE] should be the default PERIODIC. Change [DAY_SEGMENTS][FILE] with the path of a file containing the following lines:
+
5. If you collected data with AWARE you won’t need to modify the attributes of [DEVICE_DATA][PHONE]
+
6. Set [PHONE_CALLS][PROVIDERS][RAPIDS][COMPUTE] to True
+
+
+
Example of the config.yaml sections after the changes outlined above
+
PIDS: [p01]
+
+TIMEZONE: &timezone
+America/New_York
+
+DATABASE_GROUP: &database_group
+MY_GROUP
+
+# ... other irrelevant sections
+
+DAY_SEGMENTS: &day_segments
+ TYPE: PERIODIC
+ FILE: "data/external/daysegments_periodic.csv" # make sure the three lines specified above are in the file
+ INCLUDE_PAST_PERIODIC_SEGMENTS: FALSE
+
+# No need to change this if you collected AWARE data on a database and your credentials are grouped under `MY_GROUP` in `.env`
+DEVICE_DATA:
+ PHONE:
+ SOURCE:
+ TYPE: DATABASE
+ DATABASE_GROUP: *database_group
+ DEVICE_ID_COLUMN: device_id # column name
+ TIMEZONE:
+ TYPE: SINGLE # SINGLE or MULTIPLE
+ VALUE: *timezone
+
+
+############## PHONE ###########################################################
+################################################################################
+
+....
+
+# Communication call features config, TYPES and FEATURES keys need to match
+PHONE_CALLS:
+ TABLE: calls # change if your calls table has a different name
+ PROVIDERS:
+ RAPIDS:
+ COMPUTE: True # set this to True!
+ CALL_TYPES: ...
+
+
+
+
+
Run RAPIDS
+
./rapids -j1
+
+
+
The call features for daily and morning day segments will be in
+
/data/processed/features/p01/phone_calls.csv
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/versions.json b/versions.json
new file mode 100644
index 00000000..f9526d75
--- /dev/null
+++ b/versions.json
@@ -0,0 +1 @@
+[{"version": "0.1", "title": "0.1", "aliases": ["latest"]}]
\ No newline at end of file
+