Add dateRange options to redcap_read functions

Add dateRangeBegin and dateRangeEnd to redcap-read-oneshot-eav.R, redcap-read-oneshot.R, and R/redcap-read.R
OuhscBbmc · Mar 1, 2021 · da3a6e7 · da3a6e7
1 parent 79b43a8
commit da3a6e7
Show file tree

Hide file tree

Showing 6 changed files with 91 additions and 2 deletions.
diff --git a/R/redcap-read-oneshot-eav.R b/R/redcap-read-oneshot-eav.R
@@ -40,6 +40,14 @@
 #' will only return the records (or record-events, if a longitudinal project)
 #' where the logic evaluates as TRUE.   An blank/empty string returns all
 #' records.
+#' @param dateRangeBegin To return only records that have been created or
+#' modified *after* a given date/time, provide a timestamp in the format
+#' YYYY-MM-DD HH:MM:SS (e.g., '2017-01-01 00:00:00'). If not specified,
+#' it will assume no begin time.
+#' @param dateRangeEnd To return only records that have been created or
+#' modified *before* a given date/time, provide a timestamp in the format
+#' YYYY-MM-DD HH:MM:SS (e.g., '2017-01-01 00:00:00'). If not specified,
+#' it will use the current server time.
 #'
 #' @param verbose A boolean value indicating if `message`s should be printed
 #' to the R console during the operation.  The verbose output might contain
@@ -138,6 +146,8 @@ redcap_read_oneshot_eav <- function(
   # placeholder: export_survey_fields
   export_data_access_groups     = FALSE,
   filter_logic                  = "",
+  dateRangeBegin                = "",
+  dateRangeEnd                  = "",
 
   # placeholder: guess_type
   # placeholder: guess_max
@@ -164,6 +174,8 @@ redcap_read_oneshot_eav <- function(
   # placeholder: export_survey_fields
   checkmate::assert_logical(  export_data_access_groups , any.missing=FALSE, len=1)
   checkmate::assert_character(filter_logic              , any.missing=FALSE, len=1, pattern="^.{0,}$")
+  checkmate::assert_character(dateRangeBegin            , any.missing=TRUE , len=1, pattern="^([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}|)$", null.ok=TRUE)
+  checkmate::assert_character(dateRangeEnd              , any.missing=TRUE , len=1, pattern="^([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}|)$", null.ok=TRUE)
   #
   # placeholder: checkmate::assert_logical(  guess_type                , any.missing=FALSE, len=1)
   # placeholder: checkmate::assert_integerish(guess_max                , any.missing=FALSE, len=1, lower=1)
@@ -192,7 +204,9 @@ redcap_read_oneshot_eav <- function(
     rawOrLabel              = raw_or_label,
     rawOrLabelHeaders       = raw_or_label_headers,
     exportDataAccessGroups  = export_data_access_groups,
-    filterLogic             = filter_logic
+    filterLogic             = filter_logic,
+    dateRangeBegin          = dateRangeBegin,
+    dateRangeEnd            = dateRangeEnd
     # record, fields, forms & events are specified below
   )
 
@@ -340,6 +354,8 @@ redcap_read_oneshot_eav <- function(
     records_collapsed  = records_collapsed,
     fields_collapsed   = fields_collapsed,
     filter_logic       = filter_logic,
+    dateRangeBegin     = dateRangeBegin,
+    dateRangeEnd       = dateRangeEnd,
     events_collapsed   = events_collapsed,
     elapsed_seconds    = kernel$elapsed_seconds,
     raw_text           = kernel$raw_text

diff --git a/R/redcap-read-oneshot.R b/R/redcap-read-oneshot.R
@@ -43,6 +43,14 @@
 #' filtering the data to be returned by this API method, in which the API will
 #' only return the records (or record-events, if a longitudinal project) where
 #' the logic evaluates as TRUE.   An blank/empty string returns all records.
+#' @param dateRangeBegin To return only records that have been created or
+#' modified *after* a given date/time, provide a timestamp in the format
+#' YYYY-MM-DD HH:MM:SS (e.g., '2017-01-01 00:00:00'). If not specified,
+#' it will assume no begin time.
+#' @param dateRangeEnd To return only records that have been created or
+#' modified *before* a given date/time, provide a timestamp in the format
+#' YYYY-MM-DD HH:MM:SS (e.g., '2017-01-01 00:00:00'). If not specified,
+#' it will use the current server time.
 #' @param col_types A [readr::cols()] object passed internally to
 #' [readr::read_csv()].  Optional.
 #' @param guess_type A boolean value indicating if all columns should be
@@ -159,6 +167,8 @@ redcap_read_oneshot <- function(
   export_survey_fields          = FALSE,
   export_data_access_groups     = FALSE,
   filter_logic                  = "",
+  dateRangeBegin                = "",
+  dateRangeEnd                  = "",
 
   col_types                     = NULL,
   guess_type                    = TRUE,
@@ -186,6 +196,8 @@ redcap_read_oneshot <- function(
   checkmate::assert_logical(  export_survey_fields      , any.missing=FALSE, len=1)
   checkmate::assert_logical(  export_data_access_groups , any.missing=FALSE, len=1)
   checkmate::assert_character(filter_logic              , any.missing=FALSE, len=1, pattern="^.{0,}$")
+  checkmate::assert_character(dateRangeBegin            , any.missing=TRUE , len=1, pattern="^([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}|)$", null.ok=TRUE)
+  checkmate::assert_character(dateRangeEnd              , any.missing=TRUE , len=1, pattern="^([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}|)$", null.ok=TRUE)
   #
   checkmate::assert_logical(  guess_type                , any.missing=FALSE, len=1)
   checkmate::assert_integerish(guess_max                , any.missing=FALSE, len=1, lower=1)
@@ -216,7 +228,9 @@ redcap_read_oneshot <- function(
     # placeholder: returnFormat
     exportSurveyFields      = tolower(as.character(export_survey_fields)),
     exportDataAccessGroups  = tolower(as.character(export_data_access_groups)),
-    filterLogic             = filter_logic
+    filterLogic             = filter_logic,
+    dateRangeBegin          = dateRangeBegin,
+    dateRangeEnd            = dateRangeEnd
     # record, fields, forms & events are specified below
   )
 
@@ -316,6 +330,8 @@ redcap_read_oneshot <- function(
     forms_collapsed    = forms_collapsed,
     events_collapsed   = events_collapsed,
     filter_logic       = filter_logic,
+    dateRangeBegin     = dateRangeBegin,
+    dateRangeEnd       = dateRangeEnd,
     elapsed_seconds    = kernel$elapsed_seconds,
     raw_text           = kernel$raw_text
   )

diff --git a/R/redcap-read.R b/R/redcap-read.R
@@ -56,6 +56,14 @@
 #' filtering the data to be returned by this API method, in which the API
 #' will only return the records (or record-events, if a longitudinal project)
 #' where the logic evaluates as TRUE.   An blank/empty string returns all records.
+#' @param dateRangeBegin To return only records that have been created or
+#' modified *after* a given date/time, provide a timestamp in the format
+#' YYYY-MM-DD HH:MM:SS (e.g., '2017-01-01 00:00:00'). If not specified,
+#' it will assume no begin time.
+#' @param dateRangeEnd To return only records that have been created or
+#' modified *before* a given date/time, provide a timestamp in the format
+#' YYYY-MM-DD HH:MM:SS (e.g., '2017-01-01 00:00:00'). If not specified,
+#' it will use the current server time.
 #' @param col_types A [readr::cols()] object passed internally to
 #' [readr::read_csv()].  Optional.
 #' @param guess_type A boolean value indicating if all columns should be
@@ -172,6 +180,8 @@ redcap_read <- function(
   export_survey_fields          = FALSE,
   export_data_access_groups     = FALSE,
   filter_logic                  = "",
+  dateRangeBegin                = "",
+  dateRangeEnd                  = "",
 
   col_types                     = NULL,
   guess_type                    = TRUE,
@@ -199,6 +209,8 @@ redcap_read <- function(
   # placeholder: returnFormat
   checkmate::assert_logical(  export_survey_fields      , any.missing=FALSE,     len=1)
   checkmate::assert_logical(  export_data_access_groups , any.missing=FALSE,     len=1)
+  checkmate::assert_character(dateRangeBegin            , any.missing=TRUE , len=1, pattern="^([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}|)$", null.ok=TRUE)
+  checkmate::assert_character(dateRangeEnd              , any.missing=TRUE , len=1, pattern="^([0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}|)$", null.ok=TRUE)
   #
   checkmate::assert_logical(  guess_type                , any.missing=FALSE,     len=1)
 
@@ -245,6 +257,8 @@ redcap_read <- function(
     forms_collapsed    = forms_collapsed,
     events_collapsed   = events_collapsed,
     filter_logic       = filter_logic,
+    dateRangeBegin     = dateRangeBegin,
+    dateRangeEnd       = dateRangeEnd,
     guess_type         = guess_type,
     verbose            = verbose,
     config_options     = config_options
@@ -261,6 +275,8 @@ redcap_read <- function(
       forms_collapsed       = "failed in initial batch call",
       events_collapsed      = "failed in initial batch call",
       filter_logic          = "failed in initial batch call",
+      dateRangeBegin        = "failed in initial batch call",
+      dateRangeEnd          = "failed in initial batch call",
       elapsed_seconds       = elapsed_seconds,
       status_code           = initial_call$status_code,
       outcome_messages      = outcome_messages,
@@ -308,6 +324,8 @@ redcap_read <- function(
       export_survey_fields        = export_survey_fields,
       export_data_access_groups   = export_data_access_groups,
       filter_logic                = filter_logic,
+      dateRangeBegin              = dateRangeBegin,
+      dateRangeEnd                = dateRangeEnd,
 
       col_types                   = col_types,
       guess_type                  = FALSE,
@@ -368,6 +386,9 @@ redcap_read <- function(
     forms_collapsed     = forms_collapsed,
     events_collapsed    = events_collapsed,
     filter_logic        = filter_logic,
+    dateRangeBegin      = dateRangeBegin,
+    dateRangeEnd        = dateRangeEnd,
+
     elapsed_seconds     = elapsed_seconds
   )
 }

diff --git a/man/redcap_read.Rd b/man/redcap_read.Rd
diff --git a/man/redcap_read_oneshot.Rd b/man/redcap_read_oneshot.Rd
diff --git a/man/redcap_read_oneshot_eav.Rd b/man/redcap_read_oneshot_eav.Rd