Advanced REDCapR Operations

This vignette covers the the less-typical uses of REDCapR to interact with REDCap through its API.

report_render_start_time <- Sys.time()


  comment = "#>", 
  # collapse = TRUE, 
  tidy    = FALSE

# knitr::opts_chunk$set(comment = "#>", collapse = TRUE) = function(x, ...) {
  # Adapted from

  x %>% 
    # rmarkdown::print.paged_df() %>% 
      col.names = gsub("_", " ", colnames(.)),
      format = "html"
    ) %>%
      bootstrap_options = c("striped", "hover", "condensed", "responsive"),
      full_width        = FALSE
    ) %>%
    c("", "", .) %>%
    paste(collapse = "\n") %>%


Next Steps {#nextsteps .emphasized}

Set project-wide values.

There is some information that is specific to a REDCap project, as opposed to an individual operation. This includes the (1) uri of the server, and the (2) token for the user's project. This is hosted on a machine used in REDCapR's public test suite, so you can run this example from any computer. Unless tests are running.

library(REDCapR) #Load the package into the current R session.
uri                   <- ""
token_simple          <- "9A81268476645C4E5F03428B8AC3AA7B"
token_longitudinal    <- "0434F0E9CF53ED0587847AB6E51DE762"

Converting from tall/long to wide

Disclaimer: Occasionally we're asked for a longitudinal dataset to be converted from a "long/tall format" (where typically each row is one observation for a participant) to a "wide format" (where each row is on participant). Usually we advise against it. Besides all the database benefits of a long structure, a wide structure restricts your options with the stat routine. No modern longitudinal analysis procedures (eg, growth curve models or multilevel/hierarchical models) accept wide. You're pretty much stuck with repeated measures anova, which is very inflexible for real-world medical-ish analyses. It requires a patient to have a measurement at every time point; otherwise the anova excludes the patient entirely.

However we like going wide to produce visual tables for publications, and here's one way to do it in R. First retrieve the dataset from REDCap.

events_to_retain  <- c("dose_1_arm_1", "visit_1_arm_1", "dose_2_arm_1", "visit_2_arm_1")

ds_long <- REDCapR::redcap_read_oneshot(redcap_uri=uri, token=token_longitudinal)$data
ds_long %>% 
  dplyr::select(study_id, redcap_event_name, pmq1, pmq2, pmq3, pmq4)

When widening only one variable (eg, pmq1), the code's pretty simple:

ds_wide <- ds_long %>% 
  dplyr::select(study_id, redcap_event_name, pmq1) %>% 
  dplyr::filter(redcap_event_name %in% events_to_retain) %>% 
  tidyr::spread(key=redcap_event_name, value=pmq1)

When widening more than one variable (eg, pmq1 - pmq4), it's usually easiest to go even longer/taller (eg, ds_eav) before reversing direction and going wide:

pattern <- "^(\\w+?)_arm_(\\d)$"

ds_eav <- ds_long %>% 
  dplyr::select(study_id, redcap_event_name, pmq1, pmq2, pmq3, pmq4) %>% 
    event      = sub(pattern, "\\1", redcap_event_name),
    arm        = as.integer(sub(pattern, "\\2", redcap_event_name))
  ) %>% 
  dplyr::select(study_id, event, arm, pmq1, pmq2, pmq3, pmq4) %>% 
  tidyr::gather(key=key, value=value, pmq1, pmq2, pmq3, pmq4) %>% 
  dplyr::filter(!(event %in% c(
    "enrollment", "final_visit", "deadline_to_return", "deadline_to_opt_ou")
  )) %>% 
  dplyr::mutate( # Simulate correcting for mismatched names across arms:
    event = dplyr::recode(event, "first_dose"="dose_1", "first_visit"="visit_1"),
    key = paste0(event, "_", key)
  ) %>% 

# Show the first 10 rows of the EAV table.
ds_eav %>% 

# Spread the EAV to wide.
ds_wide <- ds_eav %>% 
  tidyr::spread(key=key, value=value)

SSL Options

The official cURL site discusses the process of using SSL to verify the server being connected to.

Use the SSL cert file that come with the openssl package.

cert_location <- system.file("cacert.pem", package="openssl")
if( file.exists(cert_location) ) {
  config_options         <- list(cainfo=cert_location)
  ds_different_cert_file <- redcap_read_oneshot(
    redcap_uri     = uri,
    token          = token_simple,
    config_options = config_options

Force the connection to use SSL=3 (which is not preferred, and possibly insecure).

config_options <- list(sslversion=3)
ds_ssl_3 <- redcap_read_oneshot(
  redcap_uri     = uri,
  token          = token_simple,
  config_options = config_options

config_options <- list(ssl.verifypeer=FALSE)
ds_no_ssl <- redcap_read_oneshot(
   redcap_uri     = uri,
   token          = token_simple,
   config_options = config_options

Session Information

For the sake of documentation and reproducibility, the current report was rendered in the following environment. Click the line below to expand.


if( requireNamespace("devtools", quietly = TRUE) ) {
} else {

report_render_duration_in_seconds <- round(as.numeric(difftime(Sys.time(), report_render_start_time, units="secs")))

Report rendered by r["user"] at r strftime(Sys.time(), "%Y-%m-%d, %H:%M %z") in r report_render_duration_in_seconds seconds.

Try the REDCapR package in your browser

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

REDCapR documentation built on May 29, 2017, 9:24 a.m.