Learn R Programming

REDCapR (version 0.9.3)

redcap_read_oneshot: Read/Export records from a REDCap project.

Description

This function uses REDCap's API to select and return data.

Usage

redcap_read_oneshot(redcap_uri, token, records = NULL, records_collapsed = "", fields = NULL, fields_collapsed = "", events = NULL, events_collapsed = "", export_data_access_groups = FALSE, raw_or_label = "raw", verbose = TRUE, config_options = NULL)

Arguments

redcap_uri
The URI (uniform resource identifier) of the REDCap project. Required.
token
The user-specific string that serves as the password for a project. Required.
records
An array, where each element corresponds to the ID of a desired record. Optional.
records_collapsed
A single string, where the desired ID values are separated by commas. Optional.
fields
An array, where each element corresponds a desired project field. Optional.
fields_collapsed
A single string, where the desired field names are separated by commas. Optional.
events
An array, where each element corresponds a desired project event Optional.
events_collapsed
A single string, where the desired event names are separated by commas. Optional.
export_data_access_groups
A boolean value that specifies whether or not to export the ``redcap_data_access_group'' field when data access groups are utilized in the project. Default is FALSE. See the details below.
raw_or_label
A string (either 'raw' or 'label' that specifies whether to export the raw coded values or the labels for the options of multiple choice fields. Default is 'raw'.
verbose
A boolean value indicating if messages should be printed to the R console during the operation. The verbose output might contain sensitive information (e.g. PHI), so turn this off if the output might be visible somewhere public. Optional.
config_options
A list of options to pass to POST method in the httr package. See the details below. Optional.

Value

Currently, a list is returned with the following elements,
  1. data: An R data.frame of the desired records and columns.
  2. success: A boolean value indicating if the operation was apparently successful.
  3. status_code: The http status code of the operation.
  4. outcome_message: A human readable string indicating the operation's outcome.
  5. records_collapsed: The desired records IDs, collapsed into a single string, separated by commas.
  6. fields_collapsed: The desired field names, collapsed into a single string, separated by commas.
  7. elapsed_seconds: The duration of the function.
  8. raw_text: If an operation is NOT successful, the text returned by REDCap. If an operation is successful, the `raw_text` is returned as an empty string to save RAM.

Details

I like how PyCap creates a `project' object with methods that read and write from REDCap. However this isn't a style that R clients typically use. I like the logic that it's associated with a particular REDCap project that shouldn't change between calls. As a compromise, I think I'll wrap the uri, token, and cert location into a single S4 object that's passed to these methods. It will make these calls take less space.

The full list of configuration options accepted by the httr package is viewable by executing httr::httr_options(). The httr package and documentation is available at http://cran.r-project.org/package=httr.

The `REDCapR' package includes a recent version of the Bundle of CA Root Certificates from the official cURL site. This version is used by default, unless the `config_options` argument is given a value; in this case, the user is responsible for passing the location of the cert file if SSL verification is desired. See the examples below for one example of using a different SSL cert, and one example of avoiding SSL entirely. Avoiding SSL is suggested only for debugging purposes, and not for production code.

If you do not pass in this export_data_access_groups value, it will default to FALSE. The following is from the API help page for version 5.2.3: This flag is only viable if the user whose token is being used to make the API request is *not* in a data access group. If the user is in a group, then this flag will revert to its default value.

References

The official documentation can be found on the `API Help Page` and `API Examples' pages on the REDCap wiki (ie, https://iwg.devguard.com/trac/redcap/wiki/ApiDocumentation and https://iwg.devguard.com/trac/redcap/wiki/ApiExamples). If you do not have an account for the wiki, please ask your campus REDCap administrator to send you the static material.

The official cURL site discusses the process of using SSL to verify the server being connected to.

Examples

Run this code
## Not run: 
# library(REDCapR) #Load the package into the current R session.
# uri <- "https://bbmc.ouhsc.edu/redcap/api/"
# token <- "9A81268476645C4E5F03428B8AC3AA7B"
# #Return all records and all variables.
# ds_all_rows_all_fields <- redcap_read_oneshot(redcap_uri=uri, token=token)$data
# 
# #Return only records with IDs of 1 and 3
# desired_records_v1 <- c(1, 3)
# ds_some_rows_v1 <- redcap_read_oneshot(
#    redcap_uri = uri,
#    token = token,
#    records = desired_records_v1
# )$data
# 
# #Return only the fields record_id, name_first, and age
# desired_fields_v1 <- c("record_id", "name_first", "age")
# ds_some_fields_v1 <- redcap_read_oneshot(
#    redcap_uri = uri,
#    token = token,
#    fields = desired_fields_v1
# )$data
# 
# 
# #Use the SSL cert file that come with the httr package.
# cert_location <- system.file("cacert.pem", package="httr")
# config_options <- list(cainfo=cert_location)
# ds_different_cert_file <- redcap_read_oneshot(
#    redcap_uri = uri,
#    token = token,
#    config_options = config_options
# )$data
# 
# #Force the connection to use SSL=3 (which is not preferred, and possibly insecure).
# config_options <- list(sslversion=3)
# ds_ssl_3 <- redcap_read_oneshot(
#   redcap_uri = uri,
#   token = token,
#   config_options = config_options
# )$data
# 
# config_options <- list(ssl.verifypeer=FALSE)
# ds_no_ssl <- redcap_read_oneshot(
#    redcap_uri = uri,
#    token = token,
#    config_options = config_options
# )$data
# ## End(Not run)

Run the code above in your browser using DataLab