Typical REDCap Workflow for a Data Analyst

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  tidy    = FALSE
)

The REDCap API facilitates repetitive tasks. If you're sure you'll download and analyze a project only once, then it may make sense to avoid the API and instead download a CSV through the browser.

But that single-shot scenario almost never happens in my life:

  1. the patient dataset is updated with relevant & fresh information daily, or
  2. you run it on a different computer a few months later, or and this is the heart of reproducibility:
  3. you want someone else to be able to unambiguously & effortlessly produce the same analysis.

Instead of telling your students or colleagues "first go to REDCap, then go to project 55, then click "Data Exports", then click "Export Data", then download these files, then move the files to this subdirectory, and finally convert them to this format before you run these models" ...say it with a few lines of R code.

For people running your code on their machines ...the API is so integrated and responsive that they may not even realize their computer is connecting to the outside world. If they're not looking closely, they may think it's a dataset that's included locally in a package they've already installed.

For beginners, most of the work is related to passing security credentials ...which is something that is a reality of working with PHI.

Part 1 - Pre-requisites

Verify REDCapR is installed

First confirm that the REDCapR package is installed on your local machine. If not, the following line will throw the error Loading required namespace: REDCapR. Failed with error: ‘there is no package called ‘REDCapR’’. If this call fails, follow the installation instructions on the REDCapR webpage.

requireNamespace("REDCapR")

# If this fails, run `install.packages("REDCapR")` or `remotes::install_github(repo="OuhscBbmc/REDCapR")`

If you're a workshop attendee, you can use this vignette to copy snippets of code to your local machine to follow along with the examples: https://ouhscbbmc.github.io/REDCapR/articles/workflow-read.html.

Verify REDCap Access

Check with your institution's REDCap administrator to ensure you have

  1. access to the REDCap server,
  2. access to the specific REDCap project, and
  3. an API token with appropriate privileges to the specific REDCap project.

This might be the first time you've ever needed to request a token, and your institution may have a formal process for API approval. Your REDCap admin can help.

For this vignette, we'll use a fake dataset hosted at https://bbmc.ouhsc.edu/redcap/api/ and accessible with the token "9A81268476645C4E5F03428B8AC3AA7B".

Note to REDCap Admins:

For REDCapR::redcap_read() to function properly, the user must have Export permissions for the 'Full Data Set'. Users with only 'De-Identified' export privileges can still use REDCapR::redcap_read_oneshot(). To grant the appropriate permissions:

  • go to 'User Rights' in the REDCap project site,
  • select the desired user, and then select 'Edit User Privileges',
  • in the 'Data Exports' radio buttons, select 'Full Data Set'.

Review Codebook

Before developing any REDCap or analysis code, spend at least 10 minutes to review the codebook, whose link is near the top left corner of the REDCap project page, under the "Project Home and Design" heading. Learning the details will save you time later and improve the quality of the research.

If you're new to the project, meet with the investigator for at least 30 minutes to learn the context, collection process, and idiosyncrasies of the dataset. During that conversation, develop a plan for grooming the dataset to be ready for analysis. This is part of the standard advice that the analyst's involvement should start early in the investigation's life span.

Part 2 - Retrieve Protected Token

The REDCap API token is essentially a combination of a personal password and the ID of the specific project you're requesting data from. Protect it like any other password to PHI (protected health information). For a project with PHI, never hard-code the password directly in an R file. In other words, no PHI project should be accessed with an R file that includes the line

my_secret_token <- "9A81268476645C4E5F03428B8AC3AA7B"

Instead, we suggest storing the token in a location that can be accessed by only you. We have two recommendations.

Security Method 1: Token File

The basic goals are (a) separate the secret values from the R file into a dedicated file and (b) secure the dedicated file. If using a git repository, prevent the file from being committed with an entry in .gitignore. Ask your institution's IT security team for their recommendation.

The retrieve_credential_local() function in the REDCapR package loads relevant information from a csv into R. The plain-text file might look like this:

redcap_uri,username,project_id,token,comment
"https://bbmc.ouhsc.edu/redcap/api/","myusername",153,9A81268476645C4E5F03428B8AC3AA7B,"simple"
"https://bbmc.ouhsc.edu/redcap/api/","myusername",212,0434F0E9CF53ED0587847AB6E51DE762,"longitudinal"
"https://bbmc.ouhsc.edu/redcap/api/","myusername",213,D70F9ACD1EDD6F151C6EA78683944E98,"write data"

To retrieve the credentials for the first project listed above, pass the value of "153" to project_id.

path_credential <- system.file("misc/example.credentials", package = "REDCapR")
credential  <- REDCapR::retrieve_credential_local(
  path_credential = path_credential, 
  project_id      = 153
)

credential

A credential file is already created for this vignette. In your next real project, call create_credential_local() to start a well-formed csv file that can contain tokens.

Compared to the method below, this one is less secure but easier to establish.

Security Method 2: Token Server

Our preferred method involves saving the tokens in a separate database that uses something like Active Directory to authenticate requests. This method is described in detail in the Security Database vignette.

This approach realistically requires someone in your institution to have at least basic database administration experience.

Part 3 - Read Data: Unstructured Approach

The redcap_uri and token fields are the only required arguments of REDCapR::redcap_read(); both are in the credential object created in the previous section.

ds_1 <- 
  REDCapR::redcap_read(
    redcap_uri  = credential$redcap_uri, 
    token       = credential$token
  )$data

At this point, the data.frame ds_1 has everything you need to start analyzing the project.

ds_1

hist(ds_1$weight)

summary(ds_1)

summary(lm(age ~ 1 + sex + bmi, data = ds_1))

Pause here in the workshop for a few minutes. Raise hand if you're having trouble.

Part 4 - Read Data: Choosing Columns and Rows

When you read a dataset for the first time, you probably haven't decided which columns are needed so it makes sense to retrieve everything. As you gain familiarity with the data and with the analytic objectives, consider being more selective with the variables and rows transported from the remote server to your local machine.

Advantages include:

  1. A server is almost always more efficient filtering than a language like R or Python.
  2. REDCap's PHP code retrieves less data from REDCap's database and translates less to a text format (like csv or json).
  3. Fewer bytes are transmitted across your network.
  4. Your local machine will have better performance, because R has a smaller dataset to manage.
  5. Your brain doesn't have to look past unnecessary columns.
  6. Your R code doesn't have filter what the server already removed.
  7. Highly-sensitive PHI columns that are unnecessary for an analysis remain on the server.

Specify Record IDs

The most basic operation to limit rows is passing the exact record identifiers.

# Return only records with IDs of 1 and 4
desired_records <- c(1, 4)
REDCapR::redcap_read(
  redcap_uri  = credential$redcap_uri,
  token       = credential$token,
  records     = desired_records,
  verbose     = FALSE
)$data

Specify Row Filter

A more useful operation to limit rows is passing an expression to filter the records before returning. See your server's documentation for the syntax rules of the filter statements. Remember to enclose your variable names in square brackets. Also be aware of differences between strings and numbers.

# Return only records with a birth date after January 2003
REDCapR::redcap_read(
  redcap_uri    = credential$redcap_uri,
  token         = credential$token,
  filter_logic  = "'2003-01-01' < [dob]",
  verbose       = FALSE
)$data

Specify Column Names

Limit the returned fields by passing a vector of the desired names.

# Return only the fields record_id, name_first, and age
desired_fields <- c("record_id", "name_first", "age")
REDCapR::redcap_read(
  redcap_uri  = credential$redcap_uri,
  token       = credential$token,
  fields      = desired_fields,
  verbose     = FALSE
)$data

Part 5 - Read Data: Structured Approach

As the automation of your scripts matures and institutional resources depend on its output, its output should be stable. One way to make it more predictable is to specify the column names and the column data types. In the previous example, notice that R (specifically readr::read_csv()) made its best guess and reported it in the "Column specification" section.

In the following example, REDCapR passes col_types to readr::read_csv()) as it converts the plain-text output returned from REDCap into an R data.frame.

When readr sees a column with values like 1, 2, 3, and 4, it will make the reasonable guess that the column should be a double precision floating-point data type. However we recommend using the simplest data type reasonable because a simpler data type is less likely contain unintended values and it's typically faster, consumes less memory, and translates more cleanly across platforms. As specifically for identifiers like record_id specify either an integer or character.

Specify Column Names & Types

# Specify the column types.
desired_fields <- c("record_id", "race")
col_types <- readr::cols(
  record_id  = readr::col_integer(),
  race___1   = readr::col_logical(),
  race___2   = readr::col_logical(),
  race___3   = readr::col_logical(),
  race___4   = readr::col_logical(),
  race___5   = readr::col_logical(),
  race___6   = readr::col_logical()
)
REDCapR::redcap_read(
  redcap_uri  = credential$redcap_uri,
  token       = credential$token,
  fields      = desired_fields,
  verbose     = FALSE,
  col_types   = col_types
)$data

Specify Everything is a Character

REDCap internally stores every value as a string. To accept full responsibility of the data types, tell readr::cols() to keep them as strings.

# Specify the column types.
desired_fields <- c("record_id", "race")
col_types <- readr::cols(.default = readr::col_character())
REDCapR::redcap_read(
  redcap_uri  = credential$redcap_uri,
  token       = credential$token,
  fields      = desired_fields,
  verbose     = FALSE,
  col_types   = col_types
)$data

Part 6 - Next Steps

Other REDCapR Resources

In addition to documentation for each function the REDCapR package contains a handful of vignettes including a troubleshooting guide.

Create an Arch for Reuse

When multiple R files use REDCapR call the same REDCap dataset, consider refactoring your scripts so that extraction code is written once, and called by the multiple analysis files. This "arch" pattern is described in slides 9-16 of the 2014 REDCapCon presentation, Literate Programming Patterns and Practices for Continuous Quality Improvement (CQI).

Downstream Reproducible Reports

Once the dataset is in R, take advantage of all the reproducible research tools available. Tomorrow, R/Medicine has a workshop on this topic using the exciting new Quarto program that's similar to R Markdown. Also see the relevant R/Medicine 2020 presentation videos. And of course, any book by Yihui Xie and colleagues.

Batching

By default, REDCapR::redcap_read() requests datasets of 100 patients as a time, and stacks the resulting subsets together before returning a data.frame. This can be adjusted to improve performance; the 'Details' section of REDCapR::redcap_read() discusses the trade offs.

Writing to the Server

Reading record data is only one API capability. REDCapR exposes 20+ API functions, such as reading metadata, retrieving survey links, and writing records back to REDCap. This last operation is relevant in Kenneth McLean's presentation following a five-minute break.

Notes

This vignette was originally designed for a 2021 R/Medicine REDCap workshop with Peter Higgins, Amanda Miller, and Kenneth McLean.

This work was made possible in part by the NIH grant U54GM104938 to the Oklahoma Shared Clinical and Translational Resource).



Try the REDCapR package in your browser

Any scripts or data that you put into this service are public.

REDCapR documentation built on Aug. 10, 2022, 5:06 p.m.