REDCapR

We’ve been using R with REDCap’s API since the Fall 2012 and have developed some functions that we're assembling in an R package: REDCapR. The release version and documentation is on CRAN, while the development site for collaboration is on GitHub.

It was taking us a minimum of 50 lines of code to contact REDCap and robustly transform the returned CSV into an R data.frame. It took more than twice that much code to implement batching. All this can be done in one line of R code with the package's redcap_read() function:

ds <- redcap_read(redcap_uri=uri, token=token)$data

The REDCapR package includes the Bundle of CA Root Certificates from the official cURL site. Your REDCap server's identity is always verified, unless the setting is overridden (or alternative certificates can also be provided).

The redcap_read() function also accepts values for subsetting/filtering the records and fields. The most recent documentation can be found in the GitHub repository. A vignette has also been started. Here's are two examples; the first selects only a portion of the rows, while the second selects only a portion of the columns.

#Return only records with IDs of 1 and 4
desired_records <- c(1, 4)
ds_some_rows <- redcap_read(
   redcap_uri = uri, 
   token = token, 
   records = desired_records
)$data

#Return only the fields record_id, name_first, and age
desired_fields <- c("record_id", "name_first", "age")
ds_some_fields <- redcap_read(
   redcap_uri = uri, 
   token = token, 
   fields = desired_fields
)$data

In the next year, we hope to implement everything exposed by the REDCap API. If there's a feature that would help your projects, feel free to post something here in the forums, or create an issue in REDCapR's GitHub repository. A troubleshooting document helps diagnose issues with the API.

Our group has benefited so much from REDCap and the surrounding community, and we'd like to contribute back. Suggestions, criticisms, and code contributions are welcome. And if anyone is interested in trying a direction that suits them better, we'll be happy to explain the package's internals and help you fork your own version. We have some starting material described in the ./documentation_for_developers/ directory. Also a few other libraries exist for communicating with REDCap: redcapAPI written in R (which is a fork of redcap), RedcapAPI written in Ruby, REDCap_API written in JavaScript, PyCap written in Python, and PhpCap written in PHP. (When you're choosing a library, consider if you need one that's been updated since REDCap's version 6.0.0 changes in Sept 2014).

We'd like to thank the following developers for their advice and code contributions: Rollie Parrish, Scott Burns, Benjamin Nutter, John Aponte, and Andrew Peters.

Thanks, Will Beasley, David Bard, & Thomas Wilson

University of Oklahoma Health Sciences Center, Department of Pediatrics, Biomedical & Behavioral Research Core.

Download and Installation Instructions

All Operating Systems

The release version of REDCapR can be installed from CRAN.

install.packages("REDCapR")

The development version of REDCapR can be installed from GitHub after installing the devtools package.

install.packages("devtools")
devtools::install_github(repo="OuhscBbmc/REDCapR")

Linux

If installing on Linux, the default R CHECK command will try (and fail) to install the (nonvital) RODBC package. While this package isn't available for Windows, isn't necessary to interact with your REDCap server (and thus not necesssary for the core features of REDCapR). To check REDCapR's installation on Linux, run the following R code. Make sure the working directory is set to the root of the REDCapR directory; this will happen automatically when you use RStudio to open the REDCapR.Rproj file.

devtools::check(force_suggests = FALSE)

Alternatively, the RODBC package can be installed from your distribution's repository using the shell. Here are instructions for Ubuntu and Red Hat.

#From Ubuntu terminal
sudo apt-get install r-cran-rodbc

#From Red Hat terminal
sudo yum install R-RODBC

Collaborative Development

We encourage input and collaboration from the overall community. If you're familar with GitHub and R packages, feel free to submit a pull request. If you'd like to report a bug or make a suggestion, please create a GitHub issue; issues are a usually a good place to ask public questions too. However, feel free to email Will (wibeasley@hotmail.com). Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Thanks to Funders

OUHSC CCAN Independent Evaluation of the State of Oklahoma Competitive Maternal, Infant, and Early Childhood Home Visiting (MIECHV) Project.: Evaluates MIECHV expansion and enhancement of Evidence-based Home Visitation programs in four Oklahoma counties. HRSA/ACF D89MC23154.

(So far) the primary developers of REDCapR are the external evaluators for Oklahoma's MIECHV program. See the prelimary CQI reports (many of which use REDCapR) at http://ouhscbbmc.github.io/MReportingPublic/.