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.
|Ubuntu 12.04 LTS||Windows Server 2012||Test Coverage|
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
ds <- redcap_read(redcap_uri=uri, token=token)$data
REDCapR package includes the SSL certificate retrieved by
find_cert_bundle(). Your REDCap server's identity is always verified, unless the setting is overridden (or alternative certificates can also be provided).
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 agedesired_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.
Thanks, Will Beasley, David Bard, & Thomas Wilson
|Latest CRAN version||CRAN Downloads||Independently-hosted Archive|
The release version of REDCapR can be installed from CRAN.
The development version of REDCapR can be installed from GitHub after installing the
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
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 terminalsudo apt-get install r-cran-rodbc unixodbc-dev#From Red Hat terminalsudo yum install R-RODBC unixODBC-devel
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 (firstname.lastname@example.org). 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.
Much of this package has been developed to support the needs of the following projects. We appreciate the support.
OSDH ParentPRO Pilot Evaluation, federally-sponsored collaboration with OSDH. David Bard, PI, OUHSC; 2015-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/.
In the future:
readr::read_csv()is used instead of
redcap_read_oneshot()allows caller to specify data types for columns.
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.
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)
dplyrpackage instead of
plyr. This shouldn't affect callers, because immediately before returning the data,
tibble::tibble(which was formerly called
dplyr::tbl_df) back to a vanilla
retrieve-token()tests now account for the (OS X) builds where the RODBC package isn't available.
curlpackage, instead of
readcap_read()is being used without 'Full Data Set' export privileges. The problem involves the record IDs are hashed.
id_positionin 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
httrpackage 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).
redcap_metadata_readare tested and public.
testthat::skip_on_cran()before any call involving OUHSC's REDCap server.
redcap_write_oneshotare now tested and public.
redcap_write_oneshotare now tested and public.
redcap_download_file_oneshotfunction contributed by John Aponte (@johnaponte; Pull request #35)
redcap_upload_file_oneshotfunction contributed by @johnaponte (Pull request #34)
verbose==TRUE. Follows advice of @johnaponte, Benjamin Nutter (@nutterb), and Rollie Parrish (@rparrish). Closes #43.
records_collapseddefault empty value is now an empty string (ie, "") instead of NULL. This applies when
records_collapsedis either a parameter, or a returned value.
httrpackage. However, REDCapR will continue to maintain a copy in case httr's version on CRAN gets out of date.
redcap_download_file_oneshot()documentation, but Andrew Peters (@ARPeters; Pull request #45).
httrpackage, 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.
outcome_message. This is because the message associated with http code returned is conventionally called the 'status messages' (eg, OK, Forbidden, Not Found).
(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.
redcap_column_sanitize()function to address non-ASCII characters
redcap_write(as an internal function).
redcap_projectobject reduces repeatedly passing parameters like the server URL, the user token, and the SSL cert location.
redcap_read. These changes reflect our suggestion that reads should typically be batched.
redcap_write_oneshot(which is an internal function).