Skip to content

[Researchers] Using Beiwe for Open Source Users

Eli Jones edited this page Sep 27, 2021 · 1 revision

Under Construction

This documentation is a work in progress. Before releasing Beiwe as Open Source, the Onnela Lab setup all studies without developing any documentation and our developer similarly worked without documentation such as when configuring the Beiwe backend administrators. We will add salient information like this for Open Source Users here.

Here’s a quick video showing how we set up Beiwe studies

https://www.dropbox.com/s/qvm9es35jtg8que/Beiwe%20Study%20Creation_2019.mov?dl=0

Recommended setting: Test data

From the setup screen:

This study involves:

Test data: researchers will be able to download raw data and processed data output from the Data Analysis Pipeline. Use this setting for testing and debugging.

Production data: researchers will only be able to download processed data output from the Data Analysis Pipeline. This setting is higher security. Use this setting if your study will involve actual patient data.

While the ultimate goal is to configure studies as production data so that potentially identifyable GPS data isn't downloadable, the Onnela Lab continues to use the raw data for methods development. If you have the data analysis pipeline set up then it may be reasonable to use the production data setting. We developed the production data setting for future use.

Please check here for more information: https://github.com/onnela-lab/beiwe-backend/issues/54#issuecomment-474930689

Sample Study Settings

Sample Study Settings

Beiwe data collection is configurable in order to tailor it for your particular research. Study settings are configured in seconds. For example, sensors are configured for on/off intervals in seconds. And, if you configure the upload data files frequency for 3600 seconds, data will be uploaded every hour from your study participants' phones.

Some items of note:

Allow data upload over a cellular data plan

Recommended setting: Leave unchecked.

This is typically NOT checked as it is potentially costly to study participants. Alternatively, if you plan to reimburse study participants for data use, using the cell data plan may be a reasonable approach. This is likely dictated by your Institutional Review Board (IRB).

Use anonymized phone number and MAC address encryption

Recommended setting: Check

This should be checked for all studies after 2018. The original implementation of phone number and MAC address hashing was found to be potentially vulnerable to a brute force attack. The box may be unchecked indicating an old study.

Please explain on/off durations for sensors.

Here's an example:

GPS on duration: 90

GPS off duration:810

This means that Beiwe turns on the GPS sensor and collects the GPS data for 90 seconds then turns it off for 810 seconds (13.5 min) and then pings the GPS again for 90 seconds, etc… meaning it’d be about 4 times an hour or so.

Does the wifi sensor record the name of the wireless networks nearby?

Yes, we collect wifi mac addresses which are permanently encrypted into a 64 digit string so they are not identifiable. An individual MAC address will be always be transformed into the same string for consistency.

How does the Bluetooth sensor work?

The Bluetooth feature isn’t working at the moment due to changes in the Bluetooth protocol, so that’s not an option.

Excessive Sentry errors from an Android PID

We saw this when a study was configured incorrectly. On the Beiwe backend, the wifi data stream was mistakenly set to a frequency of 0 seconds, causing the device to generate literally hundreds of thousands of wifi log files. It looks like the Android app somehow lost its encryption key (maybe something broke during installation), and it keeps trying to write data, crashing, restarting, trying to write data, and crashing again.

Fix the study in the backend (the default frequency for collecting wifi logs, for instance, is every 900 seconds). Ask any enrolled study participants to uninstall and reinstall their apps and re-register since the survey settings are set permanently when a study participant registers.

There's no need to assign a new patient ID; just the act of uninstalling and reinstalling (with the same patient ID) should generate a new encryption key for them.

Where's the documentation for the Beiwe ios_log file?

https://github.com/onnela-lab/beiwe-ios/wiki

This log file can be used for troubleshooting any Beiwe iOS app problems. For instance, when the sequence number is 0 it shows that Beiwe rebooted. Apple doesn't guarantee it will keep an app running so Beiwe could be shut down for any number of reasons. See https://github.com/onnela-lab/beiwe-backend/wiki/[Researchers]-FAQs-and-Beiwe-Troubleshooting/ for more information.

Clone this wiki locally