-
Notifications
You must be signed in to change notification settings - Fork 51
[Researchers] Active Data
Customizable per study, the Beiwe app sends notifications to study participants to fill out daily and weekly surveys. Both surveys appear as screens within the app. The app reminds the participant to take a survey by making a notification symbol silently appear in the top bar of the phone’s main screen; tapping on the notification symbol takes the user to the available survey after entering the participant’s password. Additionally, the Apple app displays the arrival of one or more surveys with the appropriate number encircled on the upper right hand corner of the app icon.
The participant does not need to take the survey immediately, and can wait until he or she is in private to do so. The survey reminder will not disappear until the participant completes the survey. Beiwe records not only the participant’s final answer to a survey question, but also the amount of time the participant took to answer each question, and any intermediate answers the participant selected.
Beiwe can be configured with a message that is supplied after completing each survey. For instance, the participant can be reminded that the survey results will not be reviewed by a clinician, so cannot be used to communicate with study staff or to request help. The remainder can also include instructions for reaching his/her clinician if necessary or the research study staff, by pressing the “Call My Clinician” or “Call Research Assistant” buttons within the application. These phone numbers are entered during the registration and study enrollment process by the study research staff. The wording in the text and on the button is customizable per study, so if the study does not involve clinicians, the app can read “Call Study Staff” or “Call Study Researchers."
| timestamp | UTC time | question id | survey id | question type | question text | question answer options | answer | event |
| 1.51E+12 | 2017-10-27T15:32:31.152 | 96259207-bba8-4bf5-80dd-063c188b3080 | 59ea4eb203d3c42e1c0b38dd | radio_button | Little interest or pleasure in doing things | [Not] | present |
The last column 'Event' gives information about what occurred at that time. There are several different options that can be here: present (the survey question was presented to the user), changed (the user selected an answer – can be an original answer or can be a change from a previous answer), unpresent (the subject clicked next/submit on the survey question) and submitted (they submitted the survey). Note that the submission lines in iOS and Android survey timings files differs slightly. On iOS, the submission line has 'submitted' in the event column. On Android, a submission line has 'user hit submit' in the question id column.
| question id | question type | question text | question answer options | answer |
| 88889695-5d99-4fd6-93ea-dab61a2c13b8 | radio_button | Could you currently live alone without any help from another person? This means being able to bathe; use the toilet; shop; prepare or get meals; and manage finances. | [Yes;No] | No |
While both platforms share a similar folder structure, they differ in how they record user interactions. iOS records fine-grained, incremental events (e.g., keystrokes), leading to high row counts, whereas Android records response-level summaries.
| Important Note for Sycamore Users: Analysts using Sycamore to process Beiwe data do not need to re-implement harmonization logic, as the tool already accounts for these platform-specific differences. |
Both platforms utilize a consistent directory structure for data organization:
- survey_answers: Directory containing raw answer values.
- survey_timings: Directory for interaction and timing logs.
- Subfolders: Each directory contains subfolders named by individual survey IDs.
- Files: Individual CSV files are generated for each unique survey instance.
| Feature | iOS | Android |
|---|---|---|
| Shared Columns | timestamp, UTC time, question id, survey id, question type, question text, question answer options, answer | Same |
| Exclusive Columns | event: (present, changed, unpresent, unchanged, submitted) | N/A |
| Event | iOS Logic | Android Logic |
|---|---|---|
| Survey Start | Inferred from the first row where event = present. | Explicit row where question id = "Survey first rendered and displayed to user". |
| Survey Submission | Row where event = submitted (survey id is populated; question fields are empty). | Row where question id = "User hit submit". |
- Android: Logs the completed string once or a few times.
- iOS: Logs answers incrementally; every keystroke generates a new row. The final answer must be inferred from the last meaningful row in the sequence.
- Question Type Naming: iOS uses lowercase_underscore_separated (e.g., free_response), while Android uses Title Case with spaces (e.g., Open Response Question).
- Answer Options: iOS separates options without spaces (Yes;No), whereas Android includes a space (Yes; No).
- Missing Data: Both platforms represent missing values as NaN.
| Category | iOS | Android | Practical Implication |
|---|---|---|---|
| Folder structure | survey_answers, survey_timings | Same | Unified discovery logic. |
| Additional columns | Includes event | None | iOS requires event-aware logic. |
| Survey start | Inferred from first present | Explicit system row | Platform-specific detection needed. |
| Survey submission | event = submitted | question id = User hit submit | Requires normalization. |
| Free-text logging | Incremental (per keystroke) | Final response only | iOS requires reconstruction. |
| Row counts | High | Low | Raw counts are not comparable. |
| Question naming | lowercase_with_underscores | Title Case with spaces | Normalization mapping required. |
| Option spacing | Yes;No | Yes; No | String cleanup needed for matching. |
| Interactions | Available (granular) | Not available | iOS allows deeper UX analysis. |
These differences are critical when working directly with raw Beiwe CSVs. However, Sycamore automatically handles:
- Survey start and submission detection.
- Free-text reconstruction for iOS.
- Question type normalization.
- Row-level aggregation.
| Conclusion: When using Sycamore outputs, survey metrics are already platform-harmonized. Platform-specific handling is only required for custom analyses performed directly on raw survey files. |
The Beiwe app has the ability to record voice samples from participants, similar to the survey functionality described above. The participant is prompted by a notification for an audio sample, which can be scheduled by the research staff, to speak into the phone’s microphone for any amount of time to either describe how he or she is feeling, or read text that is displayed on the application page. Audio formats can be configured as either compressed or uncompressed data depending on the study aims of the collaborator. The participant’s voice is recorded as an MP4 or wav audio file so that researchers can analyze the audio file.
Voice surveys (audio recordings) are encrypted once the recording is complete, and is encrypted in transit and in rest. Voice surveys are stored on the Amazon S3 server. As with all other data collected by the Beiwe app, voice survey data is encrypted on the Amazon server, and can only be decrypted by researchers with the appropriate access credentials as assigned by Jukka-Pekka Onnela and/or authorized Onnela Lab staff.
The app reminds the participant to make a voice recording in the same way that it reminds the participant to take a survey: by making a notification symbol silently appear in the top bar of the phone’s main screen or on the Beiwe app icon on Apple phones. The participant does not need to make an audio sample immediately, and may wait until he or she is in private to do so. The participant can make the audio sample at any time after the notification appears (the notification symbol will not go away until either the participant makes an audio recording or the next audio recording reminder replaces it).
As with survey data, after the recording, a study can be customized to remind participants that a clinician will not listen to their voice recording immediately, so if the participant needs assistance they should use the “Call My Clinician” button or “Call Research Assistant” button within the app.