add export_checkbox_label

closes #186

Author: wibeasley

R/redcap-read-oneshot.R

@@ -15,7 +15,7 @@
 #' @param events_collapsed A single string, where the desired event names are separated by commas.  Optional.
 #' @param 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'`.
 #' @param raw_or_label_headers A string (either `'raw'` or `'label'` that specifies for the CSV headers whether to export the variable/field names (raw) or the field labels (label).  Default is `'raw'`.
-# exportCheckboxLabel
+#' @param export_checkbox_label specifies the format of checkbox field values specifically when exporting the data as labels.  If `raw_or_label` is `'label'` and `export_checkbox_label` is TRUE, the values will be the text displayed to the users.  Otherwise, the values will be 0/1.
 # returnFormat
 #' @param export_survey_fields A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp') .
 #' @param 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.
@@ -82,7 +82,7 @@ redcap_read_oneshot <- function(
   events                        = NULL, events_collapsed  = "",
   raw_or_label                  = "raw",
   raw_or_label_headers          = "raw",
-  # exportCheckboxLabel
+  export_checkbox_label         = FALSE,   # exportCheckboxLabel
   # returnFormat
   export_survey_fields          = FALSE,
   export_data_access_groups     = FALSE,
@@ -107,7 +107,7 @@ redcap_read_oneshot <- function(
   checkmate::assert_subset(   raw_or_label              , c("raw", "label"))
   checkmate::assert_character(raw_or_label_headers      , any.missing=F, len=1)
   checkmate::assert_subset(   raw_or_label_headers      , c("raw", "label"))
-  # exportCheckboxLabel
+  checkmate::assert_logical(  export_checkbox_label     , any.missing=F, len=1)
   # returnFormat
   checkmate::assert_logical(  export_survey_fields      , any.missing=F, len=1)
   checkmate::assert_logical(  export_data_access_groups , any.missing=F, len=1)
@@ -133,7 +133,9 @@ redcap_read_oneshot <- function(
   if( any(grepl("[A-Z]", fields_collapsed)) )
     warning("The fields passed to REDCap appear to have at least uppercase letter.  REDCap variable names are snake case.")
 
+  export_checkbox_label_string     <- ifelse(export_checkbox_label    , "true", "false")
   export_data_access_groups_string <- ifelse(export_data_access_groups, "true", "false")
+
   export_survey_fields             <- tolower(as.character(export_survey_fields))
 
   post_body <- list(
@@ -143,6 +145,7 @@ redcap_read_oneshot <- function(
     type                    = 'flat',
     rawOrLabel              = raw_or_label,
     rawOrLabelHeaders       = raw_or_label_headers,
+    exportCheckboxLabel     = export_checkbox_label_string,
     exportSurveyFields      = export_survey_fields,
     exportDataAccessGroups  = export_data_access_groups_string,
     # records               = ifelse(nchar(records_collapsed)   > 0, records_collapsed  , NULL),

R/redcap-read.R

@@ -21,7 +21,7 @@
 #' @param events_collapsed A single string, where the desired event names are separated by commas.  Optional.
 #' @param 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'`.
 #' @param raw_or_label_headers A string (either `'raw'` or `'label'` that specifies for the CSV headers whether to export the variable/field names (raw) or the field labels (label).  Default is `'raw'`.
-# exportCheckboxLabel
+#' @param export_checkbox_label specifies the format of checkbox field values specifically when exporting the data as labels.  If `raw_or_label` is `'label'` and `export_checkbox_label` is TRUE, the values will be the text displayed to the users.  Otherwise, the values will be 0/1.
 # returnFormat
 #' @param export_survey_fields A boolean that specifies whether to export the survey identifier field (e.g., 'redcap_survey_identifier') or survey timestamp fields (e.g., instrument+'_timestamp') .
 #' @param 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.
@@ -83,7 +83,7 @@ redcap_read <- function(
   events                        = NULL, events_collapsed  = "",
   raw_or_label                  = "raw",
   raw_or_label_headers          = "raw",
-  # exportCheckboxLabel
+  export_checkbox_label         = FALSE,   # exportCheckboxLabel
   # returnFormat
   export_survey_fields          = FALSE,
   export_data_access_groups     = FALSE,
@@ -105,7 +105,7 @@ redcap_read <- function(
   checkmate::assert_subset(   raw_or_label              , c("raw", "label"))
   checkmate::assert_character(raw_or_label_headers      , any.missing=F, len=1)
   checkmate::assert_subset(   raw_or_label_headers      , c("raw", "label"))
-  # exportCheckboxLabel
+  checkmate::assert_logical(  export_checkbox_label     , any.missing=F, len=1)
   # returnFormat
   # export_survey_fields
   checkmate::assert_logical(  export_data_access_groups , any.missing=F, len=1)
@@ -201,6 +201,7 @@ redcap_read <- function(
       export_data_access_groups   = export_data_access_groups,
       raw_or_label                = raw_or_label,
       raw_or_label_headers        = raw_or_label_headers,
+      export_checkbox_label       = export_checkbox_label,
       guess_type                  = guess_type,
       verbose                     = verbose,
       config_options              = config_options

man/redcap_read.Rd

@@ -400,7 +400,6 @@ test_that("All Records -label", {
   expect_true(returned_object2$fields_collapsed=="", "A subset of fields was not requested.")
   expect_match(returned_object2$outcome_messages, regexp=expected_outcome_message, perl=TRUE)
 })
-
 test_that("All Records -label header", {
   testthat::skip_on_cran()
   expected_data_frame <- structure(list(`Study ID` = c(1, 2, 3, 4, 5), `First Name` = c("Nutmeg",
@@ -488,6 +487,75 @@ test_that("All Records -label header", {
   expect_match(returned_object$outcome_message, regexp=expected_outcome_message, perl=TRUE)
   expect_true(returned_object$success)
 })
+test_that("All Records -export_checkbox_label", {
+  testthat::skip_on_cran()
+  expected_data_frame <- structure(
+    list(record_id = c(1, 2, 3, 4, 5), name_first = c("Nutmeg",
+    "Tumtum", "Marcus", "Trudy", "John Lee"), name_last = c("Nutmouse",
+    "Nutmouse", "Wood", "DAG", "Walker"), address = c("14 Rose Cottage St.\nKenning UK, 323232",
+    "14 Rose Cottage Blvd.\nKenning UK 34243", "243 Hill St.\nGuthrie OK 73402",
+    "342 Elm\nDuncanville TX, 75116", "Hotel Suite\nNew Orleans LA, 70115"
+    ), telephone = c("(405) 321-1111", "(405) 321-2222", "(405) 321-3333",
+    "(405) 321-4444", "(405) 321-5555"), email = c("[email protected]",
+    "[email protected]", "[email protected]", "[email protected]", "[email protected]"
+    ), dob = structure(c(12294, 12121, -13051, -6269, -5375), class = "Date"),
+    age = c(11, 11, 80, 61, 59), sex = c("Female", "Male", "Male",
+    "Female", "Male"), demographics_complete = c("Complete",
+    "Complete", "Complete", "Complete", "Complete"), height = c(7,
+    6, 180, 165, 193.04), weight = c(1, 1, 80, 54, 104), bmi = c(204.1,
+    277.8, 24.7, 19.8, 27.9), comments = c("Character in a book, with some guessing",
+    "A mouse character from a good book", "completely made up",
+    "This record doesn't have a DAG assigned\n\nSo call up Trudy on the telephone\nSend her a letter in the mail",
+    "Had a hand for trouble and a eye for cash\n\nHe had a gold watch chain and a black mustache"
+    ), mugshot = c("[document]", "[document]", "[document]",
+    "[document]", "[document]"), health_complete = c("Unverified",
+    "Incomplete", "Complete", "Complete", "Incomplete"), race___1 = c(NA,
+    NA, NA, NA, "American Indian/Alaska Native"), race___2 = c(NA,
+    NA, NA, "Asian", NA), race___3 = c(NA, "Native Hawaiian or Other Pacific Islander",
+    NA, NA, NA), race___4 = c(NA, NA, "Black or African American",
+    NA, NA), race___5 = c("White", "White", "White", "White",
+    NA), race___6 = c(NA, NA, NA, NA, "Unknown / Not Reported"
+    ), ethnicity = c("NOT Hispanic or Latino", "NOT Hispanic or Latino",
+    "Unknown / Not Reported", "NOT Hispanic or Latino", "Hispanic or Latino"
+    ), race_and_ethnicity_complete = c("Complete", "Incomplete",
+    "Complete", "Complete", "Complete")), .Names = c("record_id",
+    "name_first", "name_last", "address", "telephone", "email", "dob",
+    "age", "sex", "demographics_complete", "height", "weight", "bmi",
+    "comments", "mugshot", "health_complete", "race___1", "race___2",
+    "race___3", "race___4", "race___5", "race___6", "ethnicity",
+    "race_and_ethnicity_complete"), row.names = c(NA, -5L), class = "data.frame"
+  )
+  expected_outcome_message <- "\\d+ records and 24 columns were read from REDCap in \\d+(\\.\\d+\\W|\\W)seconds\\."
+
+  ###########################
+  ## Default Batch size
+  expect_message(
+    regexp            = expected_outcome_message,
+    returned_object1 <- redcap_read(redcap_uri=credential$redcap_uri, token=credential$token, raw_or_label="label", export_checkbox_label=T, verbose=T)
+  )
+  expect_equal(returned_object1$data, expected=expected_data_frame, label="The returned data.frame should be correct") # dput(returned_object1$data)
+  expect_true(returned_object1$success)
+  expect_match(returned_object1$status_codes, regexp="200", perl=TRUE)
+  expect_true(returned_object1$records_collapsed=="", "A subset of records was not requested.")
+  expect_true(returned_object1$fields_collapsed=="", "A subset of fields was not requested.")
+  expect_true(returned_object1$filter_logic=="", "A filter was not specified.")
+  expect_match(returned_object1$outcome_messages, regexp=expected_outcome_message, perl=TRUE)
+
+  ###########################
+  ## Tiny Batch size
+  expect_message(
+    regexp            = expected_outcome_message,
+    returned_object2 <- redcap_read(redcap_uri=credential$redcap_uri, token=credential$token, raw_or_label="label", export_checkbox_label=T, verbose=T, batch_size=2)
+  )
+
+  expect_equal(returned_object2$data, expected=expected_data_frame, label="The returned data.frame should be correct") # dput(returned_object2$data)
+  expect_true(returned_object2$success)
+  expect_match(returned_object2$status_codes, regexp="200", perl=TRUE)
+  expect_true(returned_object2$records_collapsed=="", "A subset of records was not requested.")
+  expect_true(returned_object2$fields_collapsed=="", "A subset of fields was not requested.")
+  expect_match(returned_object2$outcome_messages, regexp=expected_outcome_message, perl=TRUE)
+})
+
 
 test_that("Filter - numeric", {
   testthat::skip_on_cran()