Skip to content

[Researchers] Beiwe Research Administration Manual

olsenje edited this page Apr 4, 2022 · 12 revisions

Welcome to the Beiwe Research Platform Administration Guide for Collaborators. This manual reviews how collaborators will utilize the Beiwe Research Platform’s backend or “Study Portal” ( to setup and review your study, add participants to your study and download your data. You will use throughout the course of your research.

As a Beiwe user, 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 written surveys
  3. Create, edit, and deploy audio surveys
  4. Download study data

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 list on the "Manage Studies" screen or click "View Study" in the top left side of the screen. Scroll down past the Patient section to the "Surveys" 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 Display Logic. Then, click the "Add Question" button.
  4. Edit the timing of the surveys by using the scheduling system under the Schedule section. Click 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.

Absolute and Relative Survey Scheduling

New survey scheduling features are available on the new versions of the Beiwe app for both Android and iOS. These features include relative survey scheduling, absolute survey scheduling, and setting the time zone of a study.

Relative Survey

Relative schedules send surveys a specified number of days before or after a date and time that is specific to each participant, which is known as an intervention. Surveys arrive at the designated date and time in the designated study-wide time zone.

  1. Create an intervention a. On the study’s page, click the “Edit Interventions” button under Study Configuration to navigate to the Interventions page. b. Create a new intervention by typing in a name and clicking “Add New Intervention”. c. Back on the study page, the new intervention will appear as a column in the Participants section. d. Click on each Patient ID to set the value of the intervention for each participant.
  2. Create a new survey. On the survey page, navigate to the “Relative” tab. Create a timing for the absolute survey using the options on that tab, relative to the selected intervention. Options include “Day of”, “Days After” and “Days Before”.

Absolute Survey

Absolute schedules send out surveys to participants at an exact date and time. Surveys arrive at the designated date and time in the designated study-wide time zone. If a patient registers after the date of the absolute survey, it will be delivered upon registration.

  1. Create a new survey. On the survey page, navigate to the “Absolute” tab. Create a timing for the absolute survey using the options on that tab.

Set the time zone of a survey

Set the time zone for a survey, on which all surveys will be sent out. Note: It is important to set the time zone at the beginning of the study and do not change it after sending surveys to participants, as this will cause surveys to be reset.

  1. From the study page, click “Edit Study” in the upper left side of the screen
  2. Scroll down until you see the option to “Set Study Timezone.” Select the appropriate time zone and click “Update Timezone”.

Survey Branching

Any questions that you would like to use to determine branching logic must have a definitive answer, thus must use the following question types:

  • slider questions
  • radio button questions, and
  • numeric open response questions

Beiwe’s remaining question types, such as information or checkbox, do not result in a unique outcome thus cannot be used for branching decisions. However, they can be used in the normal flow of your surveys without being referred to later. Set up your questions as you always have:

  • Enter your question text
  • Choose a question type (as noted above, depending on how you’re using the question)
  • Add your answer choices.
  • Press “Add Question” to save

Questions in surveys are now designated as “Always Displayed” or “Conditionally Displayed.”

As you add your answer choices to a radio button survey question, note that a number is now noted to the left of your list of the choices, as shown in the screenshot below. If you’ll be using this question for survey branching, take note of these numbers to use later on when you set up your branching logic.

If you’re using a slider or numeric open response question type, the specific number entered on either can be used for your subsequent conditional questions.

“Always Displayed” and “Conditionally Displayed” questions can be used as the basis for survey branching. To set up the conditions for displaying a “Conditionally Displayed” question, the following four operator blocks are available:

  • Add “NOT” block
  • Add “OR” block
  • Add “AND” block
  • Add Conditional

One or more of the operators can be configured to implement your branching logic. Click on one or more of these new buttons in the Edit Question screen to get started. “Add Conditional” is a single operator.

The NOT, OR and AND blocks can be configured with multiple conditional statements and can be nested within each other. See an example in the following screenshot. Remember to click the “Add Question” button to save your questions and the “Save and Deploy” button to save the survey when you’re done and as you’re adding new questions. Add your survey delivery times as normal before your final Save and Deploy.

Questions that use the conditional operators and thus are displayed conditionally can use any question type and therefore can be used to ask additional questions. In the example below, if Yes is answered to the “Always Displayed” question, a follow-on question is asked for quantity while if No is answered, an informational box with advice is provided. Additional conditional questions could be set up using the answers from Questions 1 and/or 2 since either result in a unique answer.

When will I get an error when entering branching logic?

  • You won't get errors when you save contradictory logic, like the expression "((Q1 == 0) AND (Q1 == 1))". You will have to correct logic errors like this on your own when you notice a survey is not giving you the results you’re expecting. Errors only appear when Beiwe can't parse the logic, for example, if you're referencing a question that doesn't exist anymore (e.g., if you referenced Q5 and then deleted it, even if there's a new Q5) or if you're referencing a question that doesn't have a numeric answer (like a checkbox question or alphanumeric response). If the logical expression can be parsed, even if the logical expression always evaluates to False, it won't show any errors when you click "Save and Deploy".

What happens to questions that aren't displayed?

  • If any comparative operator (<, <=, ==, >=, or >) references a question that wasn't answered, the expression should evaluate as False. For example, if you're evaluating (Q3 < 1) AND (4 > 3) and Q3 wasn't answered, it should evaluate as (False) AND (4 > 3). If you're evaluating NOT(Q3 == 1) and Q3 wasn't answered, that should evaluate as NOT(False), which equals True.

  • If Q3 never displayed, it cannot have been answered. If Q3 displayed, and the participant answered it, and then the participant went back in the survey and changed a previous answer so that Q3 shouldn't have displayed, the answer to Q3 is still there to be operated on. So if you want Q4 to never display if Q3 didn't display either, you could add a copy of the Q3 display logic to Q4's display logic inside an AND block.

Entering long text responses: How to write responses so the app shows a new line.

  • You need to use two newlines when entering your text in the “Question Text” box in order to get a paragraph break to display in the app. A single newline is ignored.

Beiwe Randomize feature

  • Beiwe’s randomize feature does not work with survey branching. If you click the “Randomize” box when configuring your survey, it will disable any branching questions in the survey.

Special Characters in Surveys (Unicode)

Beiwe allows for unicode characters to be added to questions to allow for surveys in other languages. However, at this time the hardcoded language in Beiwe is only available in English.

Audio Surveys

Audio surveys are created and scheduled in the same way that surveys are scheduled. To create or edit a new audio survey:

  1. Scroll down past the Participants 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 would like 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 or discuss with the Onnela Lab to ensure the Passive Data Settings are agreed on.

Prior to the kick off of your Beiwe study please provide the following items to the Onnela Lab:

  • Title for Project
  • PI should send team's names and email addresses that will need access to the Beiwe study
  • Copy of the IRB approval
  • Copy of the IRB materials
  • Text for consent -- Android, if applicable
  • Text for consent -- Apple, if applicable
  • Text for the app's "Call My Clinician" button
  • Approximate number of patients/study participants anticipated in study
  • Approximate duration of the study
  • "Allow Data Upload Over Cellular Plan" Setting

Adding Participants to Your Study

Research collaborators will enroll new participants in the study by creating and assigning Beiwe Patient IDs.You have the option to create on new patient ID or many.

To create one patient ID:

  1. Click the "Add New Participant" button at the top of the study screen, and a new 8-character Beiwe ID and temporary password will be generated at the top of the screen.
  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.

To create many patient IDs:

  1. Click the "Add Many New Participants" button on the study screen, and a window will pop up asking the number of patient IDs you would like to generate and the name of the file you would like the IDs to export to.
  2. Fill in those fields and click Create New Patient IDs.
  3. The new Beiwe IDs and temporary passwords will be downloaded into a .csv file (can be opened using Microsoft Excel) and can be given to participants 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, researchers will need to go to the "Manage Credentials" page, and under the "Generate New Data-Download API Access 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

Log into the Beiwe backend. Go to the "Download Data" page and enter your access key and secret key and select the study, patient ID, data types, 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 Beiwe Data Privacy and Security and Beiwe Passive Data.

We recommend downloading 1GB of data or less at a time. If your computer times out or the download doesn't complete, try downloading less data. Note, while the amount of data depends on your study settings, the typical Onnela Lab study settings generates approximately 1GB of raw data per subject-month.

Note : The Download Data tab has two options: “Download Raw/Chunked Data” or “Download Processed (Pipeline Output) Data”. Please use the former “Download Raw/Chunked Data”. The second option is currently only for Onnela Lab use. Open source users can find more information here.

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. More information is available here:.

Clone this wiki locally