document & test timezones

ref #410

R/redcap-project-info-read.R

@@ -36,6 +36,21 @@
 #' unsuccessful operation, it should contain diagnostic information.
 #' * `elapsed_seconds`: The duration of the function.
 #'
+#' @details
+#' Several datetime variables are returned, such as the project's
+#' `creation_time`.  For the time to be meaningful, you'll need to set
+#' the time zone because this function uses [readr::read_csv()],
+#' which assigns
+#' [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time)
+#' if no timezone is specified.  Find your server's location listed in
+#' [base::OlsonNames()], and pass it to readr's [readr::locale()] function,
+#' and then pass that to `redcap_project_info_read()`.  See the examples below
+#'
+#' For more timezone details see the
+#' ["Timezones"](https://readr.tidyverse.org/articles/locales.html#timezones)
+#' section of readr's
+#' [locales](https://readr.tidyverse.org/articles/locales.html) vignette.
+#'
 #' @author Will Beasley, Stephan Kadauke
 #' @references The official documentation can be found on the 'API Help Page'
 #' and 'API Examples' pages on the REDCap wiki (*i.e.*,
@@ -47,19 +62,36 @@
 #'
 #' @examples
 #' \dontrun{
+#' # Specify your project uri and token(s).
 #' uri                  <- "https://bbmc.ouhsc.edu/redcap/api/"
 #' token_simple         <- "9A81268476645C4E5F03428B8AC3AA7B"
 #' token_longitudinal   <- "0434F0E9CF53ED0587847AB6E51DE762"
 #'
+#' # ---- Simple examples
 #' d1 <- REDCapR::redcap_project_info_read(uri, token_simple      )$data
 #' View(d1)
 #'
 #' d2 <- REDCapR::redcap_project_info_read(uri, token_longitudinal)$data
 #' View(d2)
 #'
+#' # ---- Specify timezone
+#' # Specify the server's timezone, for example, US Central
+#' server_locale <- readr::locale(tz = "America/Chicago")
+#' d3 <-
+#'   REDCapR::redcap_project_info_read(
+#'     uri,
+#'     token_simple,
+#'     locale     = server_locale
+#'   )$data
+#' d3$creation_time
+#'
+#' # Alternatively, set timezone to the client's location.
+#' client_locale <- readr::locale(tz = Sys.timezone())
 #'
-#' # Stack all the projects on top of each other in a (nested) tibble
-#' #   (starting from a csv of REDCapR test projects).
+#' # ---- Inspect multiple projects in the same tibble
+#' # Stack all the projects on top of each other in a (nested) tibble,
+#' #   starting from a csv of REDCapR test projects.
+#' # The native pipes in this snippet require R 4.1+.
 #' d_all <-
 #'   system.file("misc/example.credentials", package = "REDCapR") |>
 #'   readr::read_csv(
@@ -68,7 +100,7 @@
 #'     col_types   = readr::cols(.default = readr::col_character())
 #'   ) |>
 #'   dplyr::filter(32L == nchar(token)) |>
-#'   purrr::pmap_dfr(REDCapR::redcap_project_info_read)
+#'   purrr::pmap_dfr(REDCapR::redcap_project_info_read, locale = server_locale)
 #'
 #' # Inspect values stored on the server.
 #' View(d_all$data)

inst/test-data/specific-redcapr/project-info-read/chicago.R

@@ -0,0 +1,42 @@
+structure(list(project_id = 153L, project_title = "REDCapR Target Simple Static -see https://github.com/OuhscBbmc/REDCapR", 
+    creation_time = structure(1385762300, class = c("POSIXct", 
+    "POSIXt"), tzone = "America/Chicago"), production_time = structure(NA_real_, class = c("POSIXct", 
+    "POSIXt"), tzone = "America/Chicago"), in_production = FALSE, 
+    project_language = "English", purpose = 0L, purpose_other = NA_character_, 
+    project_notes = NA_character_, custom_record_label = NA, 
+    secondary_unique_field = NA, is_longitudinal = FALSE, has_repeating_instruments_or_events = FALSE, 
+    surveys_enabled = FALSE, scheduling_enabled = FALSE, record_autonumbering_enabled = TRUE, 
+    randomization_enabled = FALSE, ddp_enabled = FALSE, project_irb_number = NA, 
+    project_grant_number = NA, project_pi_firstname = NA, project_pi_lastname = NA, 
+    display_today_now_button = TRUE, missing_data_codes = NA, 
+    external_modules = "cross_project_piping,date_validation_action_tags,form_status_tweaks", 
+    bypass_branching_erase_field_prompt = FALSE), row.names = c(NA, 
+-1L), spec = structure(list(cols = list(project_id = structure(list(), class = c("collector_integer", 
+"collector")), project_title = structure(list(), class = c("collector_character", 
+"collector")), creation_time = structure(list(format = ""), class = c("collector_datetime", 
+"collector")), production_time = structure(list(format = ""), class = c("collector_datetime", 
+"collector")), in_production = structure(list(), class = c("collector_logical", 
+"collector")), project_language = structure(list(), class = c("collector_character", 
+"collector")), purpose = structure(list(), class = c("collector_integer", 
+"collector")), purpose_other = structure(list(), class = c("collector_character", 
+"collector")), project_notes = structure(list(), class = c("collector_character", 
+"collector")), custom_record_label = structure(list(), class = c("collector_logical", 
+"collector")), secondary_unique_field = structure(list(), class = c("collector_logical", 
+"collector")), is_longitudinal = structure(list(), class = c("collector_logical", 
+"collector")), has_repeating_instruments_or_events = structure(list(), class = c("collector_logical", 
+"collector")), surveys_enabled = structure(list(), class = c("collector_logical", 
+"collector")), scheduling_enabled = structure(list(), class = c("collector_logical", 
+"collector")), record_autonumbering_enabled = structure(list(), class = c("collector_logical", 
+"collector")), randomization_enabled = structure(list(), class = c("collector_logical", 
+"collector")), ddp_enabled = structure(list(), class = c("collector_logical", 
+"collector")), project_irb_number = structure(list(), class = c("collector_logical", 
+"collector")), project_grant_number = structure(list(), class = c("collector_logical", 
+"collector")), project_pi_firstname = structure(list(), class = c("collector_logical", 
+"collector")), project_pi_lastname = structure(list(), class = c("collector_logical", 
+"collector")), display_today_now_button = structure(list(), class = c("collector_logical", 
+"collector")), missing_data_codes = structure(list(), class = c("collector_logical", 
+"collector")), external_modules = structure(list(), class = c("collector_character", 
+"collector")), bypass_branching_erase_field_prompt = structure(list(), class = c("collector_logical", 
+"collector"))), default = structure(list(), class = c("collector_guess", 
+"collector")), delim = ","), class = "col_spec"), class = c("spec_tbl_df", 
+"tbl_df", "tbl", "data.frame"))

tests/testthat/test-project-info-read.R

@@ -41,4 +41,34 @@ test_that("simple", {
   expect_true( returned_object$success)
 })
 
+test_that("chicago", {
+  testthat::skip_on_cran()
+  path_expected <- "test-data/specific-redcapr/project-info-read/chicago.R"
+  expected_outcome_message <- "\\d+ rows were read from REDCap in \\d+(\\.\\d+\\W|\\W)seconds\\."
+
+  server_locale <- readr::locale(tz = "America/Chicago")
+
+  expect_message(
+    regexp          = expected_outcome_message,
+    returned_object <-
+      redcap_project_info_read(
+        redcap_uri    = credential$redcap_uri,
+        token         = credential$token,
+        locale        = server_locale
+      )
+  )
+
+  if (update_expectation) {
+    attr(returned_object$data, which = "problems") <- NULL
+    save_expected(returned_object$data, path_expected)
+  }
+  expected_data_frame <- retrieve_expected(path_expected)
+
+  expect_equal(returned_object$data, expected=expected_data_frame, label="The returned data.frame should be correct", ignore_attr = TRUE) # dput(returned_object$data)
+  expect_equal(returned_object$status_code, expected=200L)
+  expect_equal(returned_object$raw_text, expected="", ignore_attr = TRUE) # dput(returned_object$raw_text)
+  expect_match(returned_object$outcome_message, regexp=expected_outcome_message, perl=TRUE)
+  expect_true( returned_object$success)
+})
+
 rm(credential)