Title: Adding REDCap fields to Flywheel metadata
Date: 17-04-2020
A real example demonstrating how to access REDCap through PyCap, how to search and view the data, and how to add the data to the appropriate flywheel container



REDCap is an online tool for acquiring questionnaire style data, typically on subjects, though the range of uses is virtually limitless. For example, one REDCap site could provide subjects with a series of questions to answer over the course of a study. Another REDCap site could simply contain one form for each subject to fill, possibly some kind of enrollment data. Another REDCap site could be made with a series of forms designed to track the progress of a project. Because of the diverse possibilities of REDCap implementations, there is no single script that can be designed to run for all cases. The purpose of this notebook is to introduce you to the tools required to integrate REDCap and Flywheel. Using these tools, a custom script will have to be created based on your specific use case.

WARNING: Before getting started, download and install all required libraries. It's also highly recommended that you read the PyCap quickstart and Documentation to familiarize yourself with the tools.

REDCap vs Flywheel Organization:

Flywheel Hierarchy

Flywheel and REDCap both organize their data slightly differently. Flywheel has a straightforward hierarchy:

This Hierarchy is strictly enforced (you will never find an acquisition containing a subject, and a subject cannot have an acquisition without also having a session).

Each Project can have multiple subjects.
Each Subject can have multiple sessions.
Each Session can have multiple acquisitions.

REDCap Hierarchy

REDCap follows a similar pattern:

Although REDCap has a similar structure, it does not rigidly enforce how this hierarchy is utilized. Here we provide a common use case, but different studies may utilize different strategies:

Each Project can have multiple arms.
Each arm can have multiple events.
Each event can have multiple forms.
Each form can have multiple fields.

Integrating REDCap into Flywheel

Because of the differences between the hierarchies, and the flexibility that REDCap users have with how they structure their data, the exact method for extracting redcap data and mapping it to the Flywheel project will require intimate knowledge of both the structure of your flywheel project, as well as the REDCap project.

Matching Subjects/Sessions from REDCap to Flywheel

The first and most obvious problem to address for REDCap integration is "Where should the data go?".
For example, if a subject comes to the testing center, fills out REDCap forms, then gets a scan, how do we match that REDCap data to our flywheel data?

Subject Matching

First, REDCap assigns a unique ID (record ID) to each subject, but this might not match what the researcher is using for the subject ID in Flywheel. One way to match the two datasets would be to include a field like "flywheel subject ID" in the enrollment data. That way, this field could be used to determine which Flywheel subject to attach the REDCap data to. For legacy data, a lookup table can be made, with REDCap ID's in one column, and the corresponding Flywheel ID in the other.

Session Matching

Second, the REDCap form will be part of a specific REDCap event, and that scan will be part of a specific Flywheel session. In this case, it would make sense that we would like to add that event data to the session's metadata. One possible way to do this would be to have the researcher add a field to the form called "flywheel session name", where the session name (Set in the scan terminal) would be entered. If this field matches the flywheel session name, then we can use that field when we query the REDCap data to determine which session to add the REDCap data to. For legacy data, a lookup table can be made, with REDCap event names in one column, and Flywheel session names in the other.

Environment Setup

This section will download the necessary packages and setup our python environment

Initialize Flywheel

We will first initialize our flywheel SDK, which entails the following steps:

  1. Enter your flywheel API key
  2. Access the flywheel SDK client at your flywheel instance
  3. Access the flywheel project we're interested in working with
  4. Examine the subjects/sessions within the project


Before starting off, we want to check your permission on the Flywheel Instance in order to proceed in this notebook.

Tip: Group ID and Project Label can be found on top of the Project page on the Flywheel Instance as shown in the snippet below.

check_user_permission will return True if both the group and project meet the minimum requirement, else a compatible list will be printed.

Initialize Flywheel Project

Initialize PyCap

We will now initialize PyCap , which entails the following steps:

  1. Enter your REDCap API url
  2. Entering your REDCap API key
  3. Access the REDCap information we're interested in working with
  4. Examine the arms/events/forms within the project

Upload REDCap Enrollment data to Flywheel

We will now examine the REDCap data to best determine how to interface with Flywheel. This will involve:

  1. Determine which field REDCap is using to store unique REDCap subject ID's
  2. The flywheel subject ID is stored in a field in the enrollment_log form. We will access this field to determine which subject to upload the data to.
  3. Determine exactly which event to upload the data from
  4. upload the data to the "Subject" container in flywheel

Upload REDCap Questionnaire data to Flywheel

We will now upload questionnaire data to a specific session in flyhweel. For the enrollment data, we were able to use the field "subject_fw_id" to determine which subject to attach the data to. Now, we need to upload the data to a specific session. Since this data has no "session_fw_id" tag, we will use a lookup table to match events to sessions. This will involve:

  1. Match events to sessions using a lookup table.
  2. upload the data to the "Session" container in flywheel