Beiwe Research Administration Website

From Beiwe Wiki
Revision as of 15:38, 15 December 2017 by Msimoneau (talk | contribs)

Jump to: navigation, search

As a Research Collaborator you have the ability to do the following tasks through the study portal website:

  1. Create new Beiwe Patient IDs and temporary passwords to use to register your study participants
  2. Create, edit, and deploy surveys
  3. Create, edit, and deploy audio surveys
  4. Download study data
As illustrated in this diagram, this is the first step to get your study underway.

Logging In

Research collaborators will receive their login credentials from the Onnela Lab Research Administrator.

Please immediately change your password to a secure password of your choice by clicking on the “Manage Credentials” tab. Complete the “Reset Your Password” section, and click on the “Change Password” button.

Setting Up Your Study


Written Surveys

To create or edit a new written survey:

  1. Choose the name of your study from the View Study drop down menu in the top left side of the screen, scroll down under the Patient section and click “Create New Survey” to create a survey. If you have multiple surveys for a study, they will appear in a list.
  2. To add a question to the survey, click the “Add Question” button at the bottom of the page.
  3. To create and edit questions, fill in the appropriate fields in the pop-up, including Question Text, Question Type, and then click the “Save” button.
  4. Edit the timing of the surveys by using the scheduling system and clicking the “Add Time” button to set the time.
  5. After any change, click the “Save and Deploy” button to save the changes.

If you would like the survey to appear when the participant in the study first downloads the app, click the box “Show Survey notification immediately when the user downloads this survey”. If no days/times are scheduled for the survey it will only show once – when the participant first enrolls. (However, if the participant gets a new phone or needs to delete/reinstall Beiwe, if they use the same patient ID, they will see this survey again. You may/may not want to instruct participants to complete it or just skip through the questions and submit so as to delete it.)

If you would like to use the randomized survey functionality, click on the “Randomize” or the “Randomize” without replacement” button on the bottom of the page and specify how many questions you’d like to be included in each survey. “Randomize without replacement” means all questions will be presented before starting over while “randomize” alone will just choose the specified number of questions each time the survey is presented.

Audio Surveys

To create or edit a new audio survey:

  1. Choose the name of your study from the View Study drop down menu in the top left side of the screen, scroll down under the Patient section and click “Create New Audio Survey” to create a survey. If you have multiple surveys for a study, they will appear in a list.
  2. Enter the “Voice Recording Prompt” directly into the Edit Survey section. This will appear on the screen when the participant is directed to the audio survey section from the app notification. Wording for the “Voice Recording Prompt” is completely customizable.
  3. Edit the timing of the surveys by using the scheduling system and clicking the “Add Time” button to set the time.
  4. After any change, click the “Save and Deploy” button to save the changes.

Technical Settings: Researchers should use the “Compressed audio” feature as a default, unless their study has specific needs related to uncompressed audio.

Uncompressed audio recordings sample at a higher rate (16,000, 22,000 or 44,100 Hz) and can reach the quality equivalent to CD quality. However, the cost is excessive data storage. Roughly 5mb of data would be collected for each minute of uncompressed audio at the 44,100 Hz level.

Although uncompressed audio takes up quite a lot of space, compression leads to compromised audio features (even if not audible to a person), and this may have data implications depending on your study aims. Please consult with the Onnela Lab if you would like to discuss this further.

Passive Data Collection

Some settings, including the Passive Data settings, and the consent text, can only be edited by an Onnela Lab member but you will be able to view the settings. Since the Beiwe Research Platform is geared toward collection of research-grade passive sensor data, the app itself is meant to be minimalistic.

When considering the passive data settings and tradeoffs it may be helpful to note that the global positioning system (GPS) sensor setting is more of a battery issue in that this sensor utilizes the phone’s battery capacity while the Accelerometer produces a lot of data, so would impact data storage capacity.

A participant in a study with all data streams turned on could generate about 1 gigabyte of data per month. Most of this is accelerometer data, since every accelerometer datapoint is about 50 bytes of data, and the accelerometer records about 5 to 100 datapoints per second. Other data streams produce less data simply because they record less frequently. This would likely be a worst case scenario as more recently we’ve been limiting the accelerometer data to reduce these numbers.

The Android and Apple iOS phones support different passive data collection items. The Beiwe study settings will be ignored if the phone does not support an enabled setting. Thus, if “Phone calls” is enabled, this data will only be collected from Android phones since Apple does not permit accessing this data.

Allow Data Upload Over Cellular Plan

Beiwe typically relies on a reliable WiFi connection to upload data collected from a study participant. However, for studies that want the data more immediately, or have other specific study aims, a study can be configured for data upload to go over the participant’s cellular plan. As this can be costly, collaborators generally reimburse study participants for the cost of their data plans or only accept participants with unlimited data plans. Study participants will have different providers for their cell phone plans and each provider offers different terms for their data plans and tend to change the terms frequently.

Consent via Apps

While most collaborators choose to consent study participants using the traditional paper-based methods, Beiwe can also be used to provide consent electronically if approved by your IRB. The Android and IPhone have two distinct consent processes. You will need to work with Onnela Lab to set up both to accommodate your study participants. However, the text can be re-used.


The default text for the Android Consent Form is: I have read and understood the information about the study and all of my questions about the study have been answered by the study researchers.

The Researcher will go through the Required Readings with the participant, after which the participant will hit the “I Consent” button, and the app will be activated on the phone.


The iOS Beiwe app offers seven headings in the consent process of which you may use all, some or none. The default set up is that all fields are blank and that none of these screens are shown during registration. However, if you would like to use these screens for sharing information or gaining consent just provide your desired text for one or more of these topics to Onnela Lab.

The seven optional topics are:

  • Welcome
  • Data Gathering
  • Privacy
  • Time Commitment
  • Study Survey
  • Study Tasks
  • Withdrawing

Each topic has two screens. The first screen is designed to give a one or two sentence explanation as shown above and the second screen provides the “learn more” information.

After stepping through each of the topics that are populated with text, the “learn more” text is compiled into one document as shown below and is presented to the participant for review and to ask for their consent to join the study.

Final Checklist before Enrolling Patients

After the IRB is finalized, the study can get underway. Collaborators should meet with the Onnela Lab to ensure the Passive Data Settings are agreed on, for a list of the items that should be provided to the Onnela Lab, visit Items to provide to Onnela Lab.

Adding Participants to Your Study

Research collaborators will enroll new participants in the study by creating and assigning Beiwe Patient IDs.

  1. Click the “Add New Patient” button at the bottom of the screen, and a new 8-character Beiwe ID and temporary password will be generated in a pop-up window.
  2. The new Beiwe ID and temporary password should be given to a study participant to be used when they register for your study from the Beiwe app on their phone.


It is the researcher’s responsibility to keep track of the Beiwe Patient ID and the participant’s identity. In keeping with IRB requirements, the Beiwe app ties all data collected to the Beiwe Participant ID and does not know the participant name or other identifying information.

Downloading Data

Creating Your Data-Download Credentials

The first time you want to download data from, researchers will need to go to the “Manage Credentials” page, and under the “Generate New Data-Download & API Credentials” heading, click the yellow button (“Reset Data-Download API Access Credentials).

Keep these credentials in a secure/password protected area. You will need these credentials to access data each time you want to download data; these will be your same credentials to access data for all the studies you have access to in the system. You only need to generate the data download credentials the first time you access data (you do NOT need to generate new credentials each time you access data). Once you have created and saved your Credentials in the above step, for all future data download needs you can go directly to the step below and use your saved credentials.

Download Data Tab

Go to the Download Data page and enter your access key and secret key and select the study, patient ID, data streams, and date ranges desired. Use CtrA (control all) to select all data types for a particular patient ID. The End Date and Time will default to the current date if not entered.

Click Download Data and a zip of the requested csv files will be created. After downloading data, you will need to refresh the page and re-enter your access and secret keys to download more data. This is how the web page was designed for security purposes.

The format of the data files downloaded will vary by sensor according to the specific data being collected, however, the same metadata is provided for all raw data collected or any event recorded. Specifically, the first two columns for all raw data will provide the Unix timestamp and the UTC time to aid with data analysis. For more information, including an explanation of the sensors and data collected by Beiwe, please see the Beiwe Data Privacy and Security manual.

Download API

A Beiwe API is also available to download data directly to collaborators’ servers and databases. We recommend the API be used for downloading large amounts of data. Please contact Onnela Lab for more information.