Merge pull request #198 from CHOP-CGTInformatics/combine-checkboxes-d…

…ocumentation

Update documentation, add example

R/REDCapTidieR-package.R

@@ -7,6 +7,7 @@
 #' @importFrom dplyr %>% across bind_rows case_when filter group_by if_any if_else
 #' left_join mutate pull recode relocate rename right_join row_number rowwise
 #' select slice summarise ungroup coalesce cur_column bind_cols first nth n_distinct
+#' first
 #' @importFrom formattable percent
 #' @importFrom lobstr obj_size
 #' @importFrom lubridate is.difftime is.period is.POSIXt is.Date

R/combine_checkboxes.R

@@ -3,18 +3,19 @@
 #' @description
 #' [combine_checkboxes()] consolidates multiple checkbox fields in a REDCap data
 #' tibble into a single column. This transformation simplifies analysis by
-#' combining multiple binary columns into a singular and informative labelled
-#' factor column.
+#' merging several binary columns into one labeled factor column, making the
+#' data more interpretable and easier to analyze.
 #'
 #' @details
-#' [combine_checkboxes()] makes use of the output names of [read_redcap()]
-#' data tibbles and metadata tibbles. Changes to checkbox data names or
-#' metadata `field_name`s may result in errors.
+#' [combine_checkboxes()] operates on the data and metadata tibbles produced by
+#' the [read_redcap()] function. Since it relies on the checkbox field naming
+#' conventions used by REDCap, changes to the checkbox variable names or their
+#' associated metadata `field_name`s could lead to errors.
 #'
-#' Checkbox fields are expanded to be a variable per checkbox option, separated
-#' by underscores. For example, `checkbox_var` with 2 options becomes
-#' `checkbox_var___1` and `checkbox_var___2`. [combine_checkboxes()] looks for
-#' these and may give a error if it cannot find them.
+#' REDCap checkbox fields are typically expanded into separate variables for each
+#' checkbox option, with names formatted as `checkbox_var___1`, `checkbox_var___2`,
+#' etc. [combine_checkboxes()] detects these variables and combines them into a
+#' single column. If the expected variables are not found, an error is returned.
 #'
 #' @param supertbl A supertibble generated by [read_redcap()]. Required.
 #' @param tbl The `redcap_form_name` of the data tibble to extract. Required.
@@ -39,12 +40,50 @@
 #' @return A modified supertibble.
 #'
 #' @examples
+#' # Set up sample data tibble
+#' data_tbl <- tibble::tribble(
+#'   ~"study_id", ~"multi___1", ~"multi___2", ~"multi___3",
+#'   1, TRUE, FALSE, FALSE,
+#'   2, TRUE, TRUE, FALSE,
+#'   3, FALSE, FALSE, FALSE
+#' )
+#'
+#' # Set up sample metadata tibble
+#' metadata_tbl <- tibble::tribble(
+#'   ~"field_name", ~"field_type", ~"select_choices_or_calculations",
+#'   "study_id", "text", NA,
+#'   "multi___1", "checkbox", "1, Red | 2, Yellow | 3, Blue",
+#'   "multi___2", "checkbox", "1, Red | 2, Yellow | 3, Blue",
+#'   "multi___3", "checkbox", "1, Red | 2, Yellow | 3, Blue"
+#' )
+#'
+#' # Create sample supertibble
+#' supertbl <- tibble::tribble(
+#'   ~"redcap_form_name", ~"redcap_data", ~"redcap_metadata",
+#'   "tbl", data_tbl, metadata_tbl
+#' )
+#'
+#' class(supertbl) <- c("redcap_supertbl", class(supertbl))
+#'
+#' # Combine checkboxes under column "multi"
+#' combine_checkboxes(
+#'   supertbl = supertbl,
+#'   tbl = "tbl",
+#'   cols = starts_with("multi")
+#' ) |>
+#'   dplyr::pull(redcap_data) |>
+#'   dplyr::first()
+#'
 #' \dontrun{
+#'
+#' redcap_uri <- Sys.getenv("REDCAP_URI")
+#' token <- Sys.getenv("REDCAP_TOKEN")
+#'
 #' supertbl <- read_redcap(redcap_uri, token)
 #' combine_checkboxes(
 #'   supertbl = supertbl,
-#'   tbl = "demographics",
-#'   cols = starts_with("race"),
+#'   tbl = "tbl",
+#'   cols = starts_with("col"),
 #'   multi_value_label = "Multiple",
 #'   values_fill = NA
 #' )