The goal of REDCapExporter is to provide a simple and relatively secure way to download and format data from a REDCap project.
While REDCap (Research Electronic Data Capture) is a fantastic tool for data capture, dissemination of the collected data in a format that multiple data analysts can easily access and share can be improved. The REDCapExporter package provides tools for easy access to REDCap data via the REDCap API with two aims:
- Scripting functions to allow for easy access to, and formatting of, a data set within a REDCap project.
- Producing a skeleton R data package to house, document, archive, and disseminate a data set.
Why is REDCapExporter needed?
If you are familiar with REDCap then you know that exporting the data from the
web interface is straightforward, easy to use, and powerful. However, there is
a fair amount of (meta) data that could be valuable to data analysis which is
not included in the export. REDCapExporter aims to report and cross-link
the metadata, collected data, and (expanded) documentation in one location.
The resulting .tar.gz data package is easy to disseminate.
Version control of data is difficult. Small data files can easily be added to git repositories, and larger files using git-lfs. Subversion can handle larger data sets with its own pros and cons. However, adding the data to multiple repositories will consume a lot of disk space unnecessarily, and there are issues with sensitive data being versioned while using public repository hosts. An R data package will provide implicit versioning of data while keeping only one copy of the data on the local disk.
Install the released version from CRAN:
install.packages("REDCapExporter", repos = "https://cran.rstudio.com")You can install the development version of REDCapExporter from GitHub with:
# install.packages("pak")
pak::pak("dewittpe/REDCapExporter")You have multiple REDCap projects and you have an API token for each project allowing for data download.
There are several ways to do this. A simple way is based on the keyring package.
library(REDCapExporter)
# Check if a file-based keyring called "REDCapExporter" exists and create one if
# not.
REDCapExporter_keyring_check()
# Add, or verify existence of, an API token for PROJECT1
REDCapExporter_add_api_token("PROJECT1")
# Add, or verify existence of, an API token for PROJECT2
REDCapExporter_add_api_token("PROJECT2")To set the token to use for the current session,
set an environment variable and use
REDCapExporter_get_api_token to retrieve the token from the keyring.
Sys.setenv(REDCap_API_TOKEN = REDCapExporter_get_api_token("PROJECT1"))You may set one more environment variable, or specify it explicitly in the call
to export_core. It is recommended to set the environment variable for ease
of use.
Sys.setenv(REDCap_API_URI = "https://<your-redcap-domain>/api/")Export the data from REDCap and format it, based on the metadata of the REDCap project via:
project1_redcap_core <- export_core()
project1 <- format_record(project1_redcap_core)The example data provided in this package are statistics from the 2000-2001 National Hockey League Stanley Cup Champion Colorado Avalanche. The data was transcribed from Hockey Reference into a REDCap project hosted at the University of Colorado Denver.
The data set avs_raw_core was generated via the following, after setting up my
keyring and token as described above.
library(REDCapExporter)
Sys.setenv(REDCap_API_URI = "https://redcap.ucdenver.edu/api/")
Sys.setenv(REDCap_API_TOKEN = REDCapExporter_get_api_token("2000_2001_Avalanche"))
avs_raw_core <- export_core()
#> Getting Project Info
#> Getting project metadata
#> Getting user data
#> Getting project record
avsDF <- format_record(avs_raw_core)A simple summary statistic from the data set: the number of goals scored by position:
aggregate(goals ~ position, data = avsDF, FUN = sum)
#> position goals
#> 1 Goal 0
#> 2 Left Wing 71
#> 3 Right Wing 72
#> 4 Center 93
#> 5 Defence 34