The purpose of this vignette is to show examples of exporting elements of a REDCap project via the REDCap (Research Electronic Data Capture) API. The examples in this vignette rely on use of a API token which cannot be divulged and thus the end users will not be able to reproduce the following examples exactly, but hopefully will be able to use these examples as a guide for their own use.
The raw return from the API calls has been provided and can be used as the input for examples the end users can evaluate.
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](https://www.hockey-reference.com/teams/COL/2001.html} into a REDCap Project hosed at the University of Colorado Denver.
This vignette is focused on the API and the general export functions. To learn more about automated building of a R data package from the exported contents of a REDCap project please see
vignette(topic = "export2package", package = "REDCapExporter")You will need to have API export rights for the REDCap project you are looking to export into an R data package. Contact the project owner, system admin, or go through your institution’s REDCap webpage to acquire an API token.
Remember, your API token is the equivalent of a username/password combination. Thus, you must treat the token with the same, or more, level of security you would treat any username/password combination. DO NOT PUT THE TOKEN IN PLAIN TEXT!
We suggest the reader set up a vault with their API token as a secret. via the secret package. We encourage the reader to read the “secrets” vignette in R via: vignette(topic = "secrets", package = "secret") for details on the use of the secret package.
There are two system environment variables we recommend setting to make the API calls simple.
Sys.setenv(REDCap_API_URI = "https://redcap.ucdenver.edu/api/")
Sys.setenv(REDCap_API_TOKEN = secret::get_secret("2000_2001_Avalanche"))A third environmental variables is the format for data to be returned in. Possible values for the API are ‘csv’, ‘xml’, or ‘json’. However, within the REDCapExporter package methods have been built to support csv or json; xml is not yet supported. csv is the default format.
Sys.getenv("REDCap_API_format")First, let’s load and attach the REDCapExporter namespace
library(REDCapExporter)Methods which will call REDCap API are export_content and export_core.
The specific behavior and results of these functions will depended on your institution’s REDCap instance and the user access permissions associated with the token used to access the project.
The next subsections provide details on these methods.
The export_content method has five arguments:
args(export_content)
## function (content, uri = NULL, token = NULL, format = NULL, ...)
## NULLThe uri, token, and format arguments are set to NULL by default. If the value is NULL then the system environmental variable values are used. The end user need only define the content argument. Additional arguments, if needed, are passed to RCurl::postForm via the ellipsis.
content return specific parts of the REDCap project.
content = “metadata” returns the data dictionary
content = “record” returns the records for a project. Note about export rights: Please be aware that Data Export user rights will be applied to this API request. For example, if you have ‘No Access’ data export rights in the project, then the API data export will fail and return an error. And if you have ‘De-Identified’ or ‘Remove all tagged Identifier fields’ data export rights, then some data fields might be removed and filtered out of the data set returned from the API. To make sure that no data is unnecessarily filtered out of your API request, you should have ‘Full Data Set’ export rights in the project.
content = “project” exports some of the basic attributes of the given REDCap project, such as the project’s title, if it is longitudinal, if surveys are enabled, the time the project was created and moved to production, etc.
content = “user” exports the list of users for a project, including their user privileges and also email address, first name, and last name. Note: if the user has been assigned to a user role, it will return the user with the role’s defined privileges.
Check the API documentation for your host for specific additional options. The likely uri is redcap.
An example: the metadata, i.e., data dictionary, for the 2000-2001 Colorado Avalanche data set could be retrieved via
avs_raw_metadata <- export_content(content = "metadata")Since the reader does not have the API token needed to actively evaluate the above code, the avs_raw_metadata object is available as a data set.
ls()
## character(0)
data(avs_raw_metadata)
ls()
## [1] "avs_raw_metadata"
str(avs_raw_metadata)
## 'rcer_raw_metadata' chr "field_name,form_name,section_header,field_type,field_label,select_choices_or_calculations,field_note,text_valid"| __truncated__
## - attr(*, "Content-Type")= Named chr [1:2] "text/csv" "utf-8"
## ..- attr(*, "names")= chr [1:2] "" "charset"
## - attr(*, "accessed")= POSIXct[1:1], format: "2019-12-17 12:42:20"Using the as.data.frame methods will help you get the return from REDCap into a usable form:
avs_metadata <- as.data.frame(avs_raw_metadata)
str(avs_metadata)
## Classes 'rcer_metadata' and 'data.frame': 64 obs. of 18 variables:
## $ field_name : chr "record_id" "uniform_number" "firstname" "lastname" ...
## $ form_name : chr "roster" "roster" "roster" "roster" ...
## $ section_header : chr "" "" "" "" ...
## $ field_type : chr "text" "text" "text" "text" ...
## $ field_label : chr "Record ID" "Uniform Number" "First name" "Last name" ...
## $ select_choices_or_calculations : chr "" "" "" "" ...
## $ field_note : chr "" "" "" "" ...
## $ text_validation_type_or_show_slider_number: chr "" "" "" "" ...
## $ text_validation_min : chr "" "" "" "" ...
## $ text_validation_max : chr "" "" "" "" ...
## $ identifier : chr "" "" "y" "y" ...
## $ branching_logic : chr "" "" "" "" ...
## $ required_field : chr "" "" "y" "y" ...
## $ custom_alignment : chr "" "" "" "" ...
## $ question_number : chr "" "" "" "" ...
## $ matrix_group_name : chr "" "" "" "" ...
## $ matrix_ranking : chr "" "" "" "" ...
## $ field_annotation : chr "" "" "" "" ...With one call to export_core Will call the API several times and download several elements of a REDCap project. The return is a list and is the expected object class to be used as the basis for building a R data package. An example of the return from this method below. It is a list of several rcer_raw_* objects.
data(avs_raw_core)
lapply(avs_raw_core, class)
## $project_raw
## [1] "rcer_raw_project" "character"
##
## $metadata_raw
## [1] "rcer_raw_metadata" "character"
##
## $user_raw
## [1] "rcer_raw_user" "character"
##
## $record_raw
## [1] "rcer_raw_record" "character"print(sessionInfo(), local = FALSE)