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 website.

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://redcap-dev-2.ouhsc.edu/redcap/api/ and accessible with the token “9A068C425B1341D69E83064A2D273A70”.

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.

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://redcap-dev-2.ouhsc.edu/redcap/api/","myusername","33","9A068C425B1341D69E83064A2D273A70","simple"
"https://redcap-dev-2.ouhsc.edu/redcap/api/","myusername","34","DA6F2BB23146BD5A7EA3408C1A44A556","longitudinal"
"https://redcap-dev-2.ouhsc.edu/redcap/api/","myusername","36","F9CBFFF78C3D78F641BAE9623F6B7E6A","simple-write"

To retrieve the credentials for the first project listed above, pass the value of “33” to project_id.

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

credential
#> $redcap_uri
#> [1] "https://redcap-dev-2.ouhsc.edu/redcap/api/"
#> 
#> $username
#> [1] "myusername"
#> 
#> $project_id
#> [1] 33
#> 
#> $token
#> [1] "9A068C425B1341D69E83064A2D273A70"
#> 
#> $comment
#> [1] "simple"

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.

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

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

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.