20

REDCapR

Interaction Between R and REDCap

Encapsulates functions to streamline calls from R to the REDCap API. REDCap (Research Electronic Data CAPture) is a web application for building and managing online surveys and databases developed at Vanderbilt University. The Application Programming Interface (API) offers an avenue to access and modify data programmatically, improving the capacity for literate and reproducible programming.

GitHubTravis-CIAppVeyorCoveralls
Master
Dev
Ubuntu 12.04 LTSWindows Server 2012Test Coverage

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 SSL certificate retrieved by httr's find_cert_bundle(). 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.

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, which are listed in the REDCap Tools directory.

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

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

CRANVersionRateZenodo
Latest
Latest CRAN versionCRAN DownloadsIndependently-hosted Archive

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 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. unixodbc is necessary for the RODBCext R package to be built.

#From Ubuntu terminal 
sudo apt-get install r-cran-rodbc unixodbc-dev
 
#From Red Hat terminal 
sudo yum install R-RODBC unixODBC-devel

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

Much of this package has been developed to support the needs of the following projects. We appreciate the support.

  • OUHSC CCAN Independent Evaluation of the State of Oklahoma Competitive Maternal, Infant, and Early Childhood Home Visiting (MIECHV) Project. HRSA/ACF D89MC23154. David Bard, PI, OUHSC; 2011-2015.

  • Independent Evaluation of the State of OK MIECHV Evidence Based Home Visitation Project, NIH-sponsored collaboration with OSDH. David Bard, PI, OUHSC; 2015-2017.

  • OSDH ParentPRO Pilot Evaluation, federally-sponsored collaboration with OSDH. David Bard, PI, OUHSC; 2015-2017.

  • Title IV-E Waiver Project, HRSA/MCHB-sponsored collaboration with OKDHS; David Bard, PI, OUHSC; 2014-2017.

  • Integrative Analysis of Longitudinal Studies of Aging (IALSA), sponsored by NIH 5P01AG043362. Scott Hofer, PI, University of Victoria; Will Beasley, PI of site-award, OUHSC; 2013-2018.

  • Oklahoma Shared Clinical and Translational Resources, sponsored by NIH NIGMS; U54 GM104938. Judith A. James, PI, OUHSC; 2013-2018.

  • Additional Insitutional Support from OUHSC Dept of Pediatrics; 2013-2017.

(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/.

News

Upcoming Versions

In the future:

  • When converting REDCap's CSV to R's data.frame, readr::read_csv() is used instead of utils::read.csv() (Issue #127).
  • redcap_read() and redcap_read_oneshot() allows caller to specify data types for columns.

Versions 0.9.4 through 0.9.6 (Developed 2015-08-26 through)

New Features:

  • Support for filtering logic in redcap_read() and redcap_read_oneshot() (PR #126)
  • New functions retrieve_credential_mssql() and retrieve_credential_local(). These transition from storing & retrieving just the token (ie, retrieve_token_mssql()) to storing & retrieving more information. retrieve_credential_local() facilitates a standard way of storing tokens locally, which should make it easier to follow practices of keeping it off the repository.
  • Using parameterized queries with the RODBCext package. (Thanks @nutterb in issues #115 & #116.)
  • Remove line breaks from token (Thanks @haozhu233 in issues #103 & #104)

Minor Updates:

  • When combining batches into a single data.frame, data.table::rbindlist() is used. This should prevent errors with the first batch's data type (for a column) isn't compatible with a later batch. For instance, this occurs when the first batch has only integers for record_id, but a subsequent batch has values like aa-test-aa. The variable for the combined dataset should be a character. (Issue #128 & http://stackoverflow.com/questions/39377370/bind-rows-of-different-data-types; Thanks @arunsrinivasan)
  • Uses the dplyr package instead of plyr. This shouldn't affect callers, because immediately before returning the data, REDCapR::redcap_read() coerces the tibble::tibble (which was formerly called dplyr::tbl_df) back to a vanilla data.frame with as.data.frame().
  • A few more instances of validating input parameters to read functions. (Issue #8).

Versions 0.9.3 (Developed 2015-08-25)

Minor Updates:

  • The retrieve-token() tests now account for the (OS X) builds where the RODBC package isn't available.

Versions 0.9 & 0.8 (Developed 2015-01-15 through 2015-08-14)

New Features:

  • Adapted for version 1.0.0 of httr (which is now based on the curl package, instead of RCurl).

Minor Updates:

  • Uses requireNamespace() instead of require().
  • By default, uses the SSL cert files used by httr, which by default, uses those packaged with R.
  • Added warning if it appears readcap_read() is being used without 'Full Data Set' export privileges. The problem involves the record IDs are hashed.
  • Reconnected code that reads only the id_position in the first stage of batching. The metadata needed to be read before that, after the updates for REDCap Version 6.0.x.
  • retrieve_token_mssql() uses regexes to validate parameters

Version 0.7 (Developed 2014-12-17 through 2014-12-17)

New Features:

  • Updated for Version 6.0.x of REDCap (which introduced a lot of improvements to API behavior).

Version 0.6 (Developed 2014-10-29 through 2014-11-03)

New Features:

  • The config_options in the httr package are exposed to the REDCapR user. See issues #55 & #58; thanks to @rparrish and @nutterb for their contributions (https://github.com/OuhscBbmc/REDCapR/issues/55 & https://github.com/OuhscBbmc/REDCapR/issues/58).

Version 0.5 (Developed 2014-09-20 through 2014-10-19)

New Features:

  • redcap_metadata_read are tested and public.

Minor Updates:

  • Test suite now uses testthat::skip_on_cran() before any call involving OUHSC's REDCap server.
  • Vignette example of subsetting, conditioned on a 2nd variable's value.

Version 0.4 (Developed 2014-09-01 through 2014-09-20)

New Features:

  • redcap_write and redcap_write_oneshot are now tested and public.
  • redcap_write and redcap_write_oneshot are now tested and public.
  • redcap_download_file_oneshot function contributed by John Aponte (@johnaponte; Pull request #35)
  • redcap_upload_file_oneshot function contributed by @johnaponte (Pull request #34)
  • Users can specify if an operation should continue after an error occurs on a batch read or write. Regardless of their choice, more debugging output is written to the console if verbose==TRUE. Follows advice of @johnaponte, Benjamin Nutter (@nutterb), and Rollie Parrish (@rparrish). Closes #43.

Breaking Changes:

  • The records_collapsed default empty value is now an empty string (ie, "") instead of NULL. This applies when records_collapsed is either a parameter, or a returned value.

Updates:

  • By default, the SSL certs come from the httr package. However, REDCapR will continue to maintain a copy in case httr's version on CRAN gets out of date.
  • The tests are split into two collections: one that's run by the CRAN checks, and the other run manually. Thanks, Gabor Csardi. Any test with a dependency outside the package code (especially the REDCap test projects) is run manually so changes to the test databases won't affect the success of building the previous version on CRAN.
  • Corrected typo in redcap_download_file_oneshot() documentation, but Andrew Peters (@ARPeters; Pull request #45).

Version 0.3 (Developed 2014-07-03 through 2014-09-01)

New Features:

  • Relies on the httr package, which provides benefits like the status code message can be captured (eg, 200-OK, 403-Forbidden, 404-NotFound). See https://cran.r-project.org/package=httr.

Updates:

  • Renamed the former status_message to outcome_message. This is because the message associated with http code returned is conventionally called the 'status messages' (eg, OK, Forbidden, Not Found).
  • If an operation is successful, the raw_text value(which was formerly calledraw_csv`) is returned as an empty string to save RAM. It's not really necessary with httr's status message exposed.

Bug Fixes:

  • Correct batch reads with longitudinal schema #27

Version 0.2 (Developed 2014-01-14 through 2014-07-02)

New Features:

  • Added redcap_column_sanitize() function to address non-ASCII characters
  • Added redcap_write (as an internal function).
  • The redcap_project object reduces repeatedly passing parameters like the server URL, the user token, and the SSL cert location.

Updates:

  • New Mozilla SSL Certification Bundles released on cURL (released 2013-12-05; http://curl.haxx.se/ca/cacert.pem)
  • Renamed redcap_read_batch to redcap_read. These changes reflect our suggestion that reads should typically be batched.
  • Renamed redcap_read to redcap_read_oneshot
  • Renamed redcap_write to redcap_write_oneshot (which is an internal function).
  • Small renames to parameters

Version 0.1 (Developed 2013-11-26 through 2014-01-14)

New Features:

  • Introduces redcap_read and redcap_read_batch with documentation
  • SSL verify peer by default, using cert file included in package
  • Initial submission to GitHub

Enhancements:

  • redcap_read takes parameter for raw_or_label (Thanks Rollie Parrish #3)
  • redcap_read takes parameter for export_data_access_groups (Thanks Rollie Parrish #4)

GitHub Commits and Releases

  • For a detailed change log, please see https://github.com/OuhscBbmc/REDCapR/commits/master.
  • For a list of the major releases, please see https://github.com/OuhscBbmc/REDCapR/releases.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("REDCapR")

0.9.8 by Will Beasley, a month ago

https://github.com/OuhscBbmc/REDCapR, http://ouhsc.edu/bbmc/, http://project-redcap.org

Report a bug at https://github.com/OuhscBbmc/REDCapR/issues

Browse source code at https://github.com/cran/REDCapR

Authors: Will Beasley [aut, cre], David Bard [ctb], Thomas Wilson [ctb], John J Aponte [ctb], Rollie Parrish [ctb], Benjamin Nutter [ctb], Andrew Peters [ctb], Hao Zhu [ctb]

Documentation:   PDF Manual  

GPL-2 license

Imports data.table, dplyr, httr, magrittr, methods, readr, tibble, tidyr

Depends on stats

Suggests devtools, kableExtra, knitr, rmarkdown, RODBC, RODBCext, testthat

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug