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.
GitHub | Travis-CI | AppVeyor | Coveralls |
---|---|---|---|
Master | |||
Dev | |||
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 50+ lines of code to contact REDCap and robustly transform the returned CSV into an R data.frame
; it took twice that much 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 redcap_read()
function also accepts values for subsetting/filtering the records and fields. The development version's 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.
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 agedesired_fields <- c("record_id", "name_first", "age")ds_some_fields <- redcap_read( redcap_uri = uri, token = token, fields = desired_fields)$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).
To keep our maintence efforts managable, the package implements only the REDCap API functions that have been requested. If there's a feature that would help your projects, please tell us about it in a new issue in REDCapR's GitHub repository. A troubleshooting document helps diagnose issues with the API.
Our group has benefited 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 checkout the other libraries that 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.
CRAN | Version | Rate | Zenodo | RDocumentation |
---|---|---|---|---|
Latest | ||||
Latest CRAN version | CRAN Downloads | Independently-hosted Archive | HTML Documentation |
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")
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
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 ([email protected]). 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.
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/.
In the future:
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.New Features:
redcap_variables()
.redcap_read_oneshot_eav()
, which can be accessed with a triple colon (ie, REDCapR::redcap_read_oneshot_eav()
).Bug Fixes
New Features:
redcap_read()
and redcap_read_oneshot()
(PR #126)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.Minor Updates:
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)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()
.Minor Updates:
retrieve-token()
tests now account for the (OS X) builds where the RODBC package isn't available.New Features:
curl
package, instead of RCurl
).Minor Updates:
requireNamespace()
instead of require()
.readcap_read()
is being used without 'Full Data Set' export privileges. The problem involves the record IDs are hashed.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 parametersNew Features:
New Features:
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).New Features:
redcap_metadata_read
are tested and public.Minor Updates:
testthat::skip_on_cran()
before any call involving OUHSC's REDCap server.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)verbose==TRUE
. Follows advice of @johnaponte, Benjamin Nutter (@nutterb), and Rollie Parrish (@rparrish). Closes #43.Breaking Changes:
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:
httr
package. 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).New Features:
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:
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).raw_text
value(which was formerly called
raw_csv`) is returned as an empty string to save RAM. It's not really necessary with httr's status message exposed.Bug Fixes:
New Features:
redcap_column_sanitize()
function to address non-ASCII charactersredcap_write
(as an internal function).redcap_project
object reduces repeatedly passing parameters like the server URL, the user token, and the SSL cert location.Updates:
redcap_read_batch
to redcap_read
. These changes reflect our suggestion that reads should typically be batched.redcap_read
to redcap_read_oneshot
redcap_write
to redcap_write_oneshot
(which is an internal function).New Features:
Enhancements: