ResearchStack Tutorial: Getting Started

In April of 2016, Open mHealth announced the release of ResearchStack, an open-source SDK for building research study apps on Android.

This opens up exciting possibilities for researchers looking to roll out large-scale studies to Android users.

One of ResearchStack’s primary goals is to make it easy to port existing iOS apps using Apple’s ResearchKit. Since its release, ResearchKit apps have reached thousands of users to help study conditions ranging from melanoma to autism.

In this ResearchStack tutorial, you will duplicate the functionality in the excellent ResearchKit tutorial written by Matt Luedke. Along the way you will learn:

• How to set up a new ResearchStack project from scratch.
• How to translate key ResearchKit concepts to ResearchStack.
• How to create consent, survey and active tasks.

If you are beginning Android Development, you’ll want to work through the Beginning Android Development Tutorial Series to get familiar with the basic concepts and development tools.

Getting Started

In this tutorial, you are going to take the very important research collected by Matt’s ResearchKit app and open it up to the world of Android users.

This research study attempts to answer the following question: “Does one’s name, quest, or favorite color affect vocal chord variations?”. Don’t worry, as with the iOS version, participants are not asked the airspeed velocity of an unladen swallow. :]

To begin, download the starter project and open with Android Studio. Take a minute to look through the project files.

To verify that everything compiles, build and run the app. You will see three buttons labeled Consent, Survey and Microphone.

ResearchStack Modules

There are two primary modules for building ResearchStack apps:

1. Backbone: The core ResearchStack API. This includes Tasks, Steps, Results, Consent, File/Database Storage and Encryption.
2. Skin: Built on top of Backbone, this provides a way to build ResearchStack apps with minimal Android knowledge. This is mostly compatible with ResearchKit’s AppCore template engine and works with minor changes to AppCore resources.

This tutorial focuses on teaching the core Backbone components. The sample asthma app provides a good way to get more familiar with using Skin.

Application Setup

First, you need to include ResearchStack in the project.

Open the app build.gradle file and add the following to the dependencies section:

compile 'org.researchstack:backbone:1.1.1'

Open the project build.gradle file and add the following to the repositories section under jcenter():

maven { url "https://jitpack.io" }

Sync the gradle changes, then build the app. If your build succeeds, you’re ready to start using ResearchStack!

Custom Application class

Next, you need to initialize the Backbone StorageAccess component. Even though you will not be using the storage engine in this tutorial, Backbone will not run without this initialization.

Open CamelotApplication.java and add the following code at the bottom of OnCreate():

PinCodeConfig pinCodeConfig = new PinCodeConfig();

EncryptionProvider encryptionProvider = new UnencryptedProvider();

FileAccess fileAccess = new SimpleFileAccess();

AppDatabase database = new DatabaseHelper(this,
    DatabaseHelper.DEFAULT_NAME,
    null,
    DatabaseHelper.DEFAULT_VERSION);

StorageAccess.getInstance().init(pinCodeConfig, encryptionProvider, fileAccess, database);

Here you construct PinCodeConfig, UnencryptedProvider, SimpleFileAccess and DatabaseHelper objects and pass them into the StorageAccess singleton object. For more advanced apps, you may provide custom versions of any of these objects.

Note: Throughout this tutorial, you may see errors with resolving names after typing in or pasting blocks of code. If this happens, you can resolve the imports manually or turn on the option in Android Studio preferences to Insert imports on paste and Optimize imports on the fly under Editor\General\Auto Import.

You are now ready to create the first part of the research study!

Informed Consent

The first step in any research study is to get consent from the test subject. ResearchStack’s consent features are designed to let you easily present the study’s goals and requirements and get signed consent from the subject.

The consent section of your ResearchKit app breaks down into four main steps:

1. Create a consent document.
2. Create consent steps for the consent document.
3. Create a consent task from the consent steps.
4. Display the consent task.

Start by creating a ConsentDocument object. The consent document holds all the information necessary to inform the user and get their consent. This is analogous to ORKConsentDocument in ResearchKit.

Open MainActivity.java and add the following method:

private ConsentDocument createConsentDocument() {

  ConsentDocument document = new ConsentDocument();

  document.setTitle("Demo Consent");
  document.setSignaturePageTitle(R.string.rsb_consent);
  
  return document;
}

This creates a new ConsentDocument and assigns a main title and a signature page title. Note that R.string.rsb_consent comes from the ResearchStack backbone (rsb) library. You will find such references in other code snippets as well.

Consent Document Contents

You can now add ConsentSections to the consent document. Each ConsentSection will show as a new screen with a built-in graphic illustration. ResearchStack has a comprehensive list of section types defined by the ConsentSection.Type enum. This is comparable to the ORKConsentSectionType enum from ResearchKit.

You have several ContentSections to create, so start by adding the following helper method to MainActivity.java:

private ConsentSection createSection(ConsentSection.Type type, String summary, String content) {

  ConsentSection section = new ConsentSection(type);
  section.setSummary(summary);
  section.setHtmlContent(content);

  return section;
}

This method creates and returns a new ConsentSection based on the passed in type, summary and content parameters.

Add the following before return document; in createConsentDocument():

List<ConsentSection> sections = new ArrayList<>();

sections.add(createSection(ConsentSection.Type.Overview, "Overview Info", "<h1>Read " +
    "This!</h1><p>Some " +
    "really <strong>important</strong> information you should know about this step"));
sections.add(createSection(ConsentSection.Type.DataGathering, "Data Gathering Info", ""));
sections.add(createSection(ConsentSection.Type.Privacy, "Privacy Info", ""));
sections.add(createSection(ConsentSection.Type.DataUse, "Data Use Info", ""));
sections.add(createSection(ConsentSection.Type.TimeCommitment, "Time Commitment Info", ""));
sections.add(createSection(ConsentSection.Type.StudySurvey, "Study Survey Info", ""));
sections.add(createSection(ConsentSection.Type.StudyTasks, "Study Task Info", ""));
sections.add(createSection(ConsentSection.Type.Withdrawing, "Withdrawing Info", "Some detailed steps " +
    "to withdrawal from this study. <ul><li>Step 1</li><li>Step 2</li></ul>"));

document.setSections(sections);

Here you start by creating a new ArrayList named sections to hold the consent sections. Next, you call createSection() for each section and add it to the sections list. Finally, you add the sections to document.

In your own research app, you will likely choose a subset of section types. You will also provide detailed information for each section.