Merge branch 'release/1.19.0'

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: redcapcustodian
 Type: Package
 Title: Data automation for R-centric workflows with a nod towards REDCap
-Version: 1.18.0
+Version: 1.19.0
 Authors@R: c(
   person("Philip", "Chase",
         email = "pbc@ufl.edu",

NAMESPACE

@@ -40,6 +40,8 @@ export(log_job_failure)
 export(log_job_success)
 export(mutate_columns_to_posixct)
 export(quit_non_interactive_run)
+export(read_project_data)
+export(read_project_metadata)
 export(scrape_user_api_tokens)
 export(send_email)
 export(set_package_scope_var)
@@ -57,6 +59,7 @@ export(update_redcap_email_addresses)
 export(write_allocations)
 export(write_error_log_entry)
 export(write_info_log_entry)
+export(write_project_data)
 export(write_summary_metrics)
 export(write_to_sql_db)
 importFrom(magrittr,"%>%")

NEWS.md

@@ -1,3 +1,6 @@
+# redcapcustodian 1.19.0 (released 2024-01-30)
+- Add REDCapR wrapper functions (@ljwoodley, #147, #148)
+
 # redcapcustodian 1.18.0 (released 2024-01-10)
 - Update Dockerfile to verse:4.3.2 (@pbchase)
 

R/read_project_data.R

@@ -0,0 +1,46 @@
+#' read_project_data Read data from a REDCap project
+#'
+#' @param ... parameters to pass on to `REDCapR::redcap_read`
+#' @param conn Connection object to the credentials database
+#' @param project_pid the project PID in the REDCap system.
+#' This string will be used to search through a REDCap custodian
+#' credentials database to locate the `token` and `redcap_uri`
+#' @param server_short_name an optional name of the server that
+#' houses the REDCap project of interest. This will prevent
+#' project PID clashes.
+#'
+#' @return a dataframe of data read from a REDCap project
+#' @export
+#' @importFrom rlang .data
+#' @examples
+#' \dontrun{
+#' library(redcapcustodian)
+#' library(DBI)
+#'
+#' dotenv::load_dot_env("testing.env")
+#' init_etl("dummy")
+#'
+#' support_data <- read_project_data(
+#'   conn = DBI::dbConnect(RSQLite::SQLite(), Sys.getenv("CREDENTIALS_DB")),
+#'   project_pid = Sys.getenv("MY_PROJECT_PID"))
+#' }
+read_project_data <- function(..., conn, project_pid, server_short_name = as.character(NA)) {
+  redcap_credentials <- dplyr::tbl(conn, "credentials") |>
+    dplyr::filter(.data$project_id == project_pid) |>
+    dplyr::filter(is.na(server_short_name) | .data$server_short_name == server_short_name) |>
+    dplyr::collect()
+
+  # Get the data from the REDCap Project
+  data_read <- REDCapR::redcap_read(
+    redcap_uri = redcap_credentials$redcap_uri,
+    token =  redcap_credentials$token,
+    batch_size = 2000,
+    ...
+  )
+
+  if (data_read$success) {
+    data <- data_read$data
+  }
+
+  return(data_read)
+}

R/read_project_metadata.R

@@ -0,0 +1,45 @@
+#' read_project_metadata Read data from a REDCap project
+#'
+#' @param ... parameters to pass on to `REDCapR::redcap_metadata_read`
+#' @param conn Connection object to the credentials database
+#' @param project_pid the project PID in the REDCap system.
+#' This string will be used to search through a REDCap custodian
+#' credentials database to locate the `token` and `redcap_uri`
+#' @param server_short_name an optional name of the server that
+#' houses the REDCap project of interest. This will prevent
+#' project PID clashes.
+#'
+#' @return a dataframe of metadata read from a REDCap project
+#' @export
+#' @importFrom rlang .data
+#' @examples
+#' \dontrun{
+#' library(redcapcustodian)
+#' library(DBI)
+#'
+#' dotenv::load_dot_env("testing.env")
+#' init_etl("dummy")
+#'
+#' support_data <- read_project_metadata(
+#'   conn = DBI::dbConnect(RSQLite::SQLite(), Sys.getenv("CREDENTIALS_DB")),
+#'   project_pid = Sys.getenv("MY_PROJECT_PID"))
+#' }
+read_project_metadata <- function(..., conn, project_pid, server_short_name = as.character(NA)) {
+  redcap_credentials <- dplyr::tbl(conn, "credentials") |>
+    dplyr::filter(.data$project_id == project_pid) |>
+    dplyr::filter(is.na(server_short_name) | .data$server_short_name == server_short_name) |>
+    dplyr::collect()
+
+  # Get the data from the REDCap Project
+  data_read <- REDCapR::redcap_metadata_read (
+    redcap_uri = redcap_credentials$redcap_uri,
+    token =  redcap_credentials$token,
+    ...
+  )
+
+  if (data_read$success) {
+    data <- data_read$data
+  }
+
+  return(data_read)
+}

R/write_project_data.R

@@ -0,0 +1,42 @@
+#' write_project_data Write data from a REDCap project
+#'
+#' @param ... parameters to pass on to `REDCapR::redcap_write`
+#' @param conn Connection object to the credentials database
+#' @param project_pid the project PID in the REDCap system.
+#' This string will be used to search through a REDCap custodian
+#' credentials database to locate the `token` and `redcap_uri`
+#' @param server_short_name an optional name of the server that
+#' houses the REDCap project of interest. This will prevent
+#' project PID clashes.
+#'
+#' @return a dataframe of data write from a REDCap project
+#' @export
+#' @importFrom rlang .data
+#' @examples
+#' \dontrun{
+#' library(redcapcustodian)
+#' library(DBI)
+#'
+#' dotenv::load_dot_env("testing.env")
+#' init_etl("dummy")
+#'
+#' support_data <- write_project_data(
+#'   conn = DBI::dbConnect(RSQLite::SQLite(), Sys.getenv("CREDENTIALS_DB")),
+#'   project_pid = Sys.getenv("MY_PROJECT_PID"))
+#' }
+write_project_data <- function(..., conn, project_pid, server_short_name = as.character(NA)) {
+  redcap_credentials <- dplyr::tbl(conn, "credentials") |>
+    dplyr::filter(.data$project_id == project_pid) |>
+    dplyr::filter(is.na(server_short_name) | .data$server_short_name == server_short_name) |>
+    dplyr::collect()
+
+  # Get the data from the REDCap Project
+  data_write <- REDCapR::redcap_write(
+    redcap_uri = redcap_credentials$redcap_uri,
+    token =  redcap_credentials$token,
+    batch_size = 2000,
+    ...
+  )
+
+  return(data_write)
+}

VERSION

@@ -1 +1 @@
-1.18.0
+1.19.0