Retrieve REDCap Data in R

Version 1: Pull from reports created in REDCap

1. Get API access in REDCap
2. Generate a token in REDCap
3. Create a system level environmental variable in Windows
   • Search “Edit the system environment variables”
   • Environment Variables …
   • New under the system portion of the window
   • Set the Variable name to something related to the project name e.g. “PROJ_pt_demo”
   • Set the Variable value to the token
   • Click OK and exit out of the windows
4. In REDCap create a report of the events/fields/instruments of interest, and take note of the report id
5. Use the following code to pull data, replacing the .token, url, and report_id values
   • Modify rawOrLabel and rawOrLabelHeaders to download numeric (raw) values or character(label) values
   • Could also download both in separate data frames to use a mixture

.token <- Sys.getenv("PROJ_pt_demo")

url <- "https://redcap.institution.edu/api/"

formData <- list(token = .token, 
                 content = "report",
                 format = "csv",
                 report_id = "REPORT_ID",    # Replace with report_id of interest
                 csvDelimiter = "",
                 rawOrLabel = "raw",
                 rawOrLabelHeaders = "raw",
                 exportCheckboxLabel = "false",
                 returnFormat = "csv")

response <- httr::POST(url, body = formData, encode = "form")

data <- httr::content(response)

Version 2: Pull the entire data set

Create a credentials file

1. Install the REDCapR pacakge
2. Create a credentials files with the credential_create() command

install.packages("REDCapR")

REDCapR::credential_create()

3. Fill out the file with the corresponding information including the project id and API token.

redcap_uri,username,project_id,token,comment
"https://redcap.[institution].edu/api/","[user_name]","[project_id]","[token]","[optional comment to name the project]"

4. Save the file in a location that will not be tracked and potentially uploaded to GitHub by Git.

5. The following commands will pull all data from a REDCap project

credential <- REDCapR::retrieve_credential_local(
  path_credential = path_to_credential,
  project_id = the_project_id_of_interest
)
  
data <- REDCapR::redcap_read(
  redcap_uri = credential$redcap_uri,
  token = credential$token
)$data

Create a function using a project_id (pid) as an input

#' Retrieve REDCap data using user-specific credentials
#'
#' This function pulls data from a REDCap project using a locally stored 
#' credentials file. It is designed to be used in environments where 
#' REDCap credentials are stored in a fixed directory path with a user-specific
#' component (e.g., `C:/Users/<username>/path/to/redcap_credentials/credentials`).
#'
#' @param pid Integer. The REDCap project ID.
#'
#' @return A `data.frame` containing the REDCap project data retrieved using
#' the API token and URI stored in the credential file.
#'
#' @details This function requires the `REDCapR` package and assumes that the
#' local credentials file has been created using `REDCapR::credential_create()` 
#' or similar method. The file path is dynamically generated using the system
#' username and a fixed relative path.
#'
#' @examples
#' \dontrun{
#'   df <- get_redcap_data(pid = 12345)
#'   head(df)
#' }
#'
#' @importFrom REDCapR retrieve_credential_local redcap_read
#' @export
get_redcap_data <- function(pid) {
  # Set path to credentials file -----------------------------------------------
  prefix <- "C:/Users/"
  user <- Sys.getenv("USERNAME")
  docs <- "/path/to/redcap_credentials/credentials"
  
  path_credential <- paste0(prefix, user, docs)
  
  # Retrieve credential object -------------------------------------------------
  credential <- REDCapR::retrieve_credential_local(
    path_credential = path_credential,
    project_id = pid
  )
  
  # Read data ------------------------------------------------------------------
  data <- REDCapR::redcap_read(
    redcap_uri = credential$redcap_uri,
    token = credential$token
  )$data
  
  return(data)
}