diff --git a/R/REDCapTidieR-package.R b/R/REDCapTidieR-package.R index bb42a6ce..978e6ee3 100644 --- a/R/REDCapTidieR-package.R +++ b/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 diff --git a/R/combine_checkboxes.R b/R/combine_checkboxes.R index a094788b..9a147ece 100644 --- a/R/combine_checkboxes.R +++ b/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 #' ) diff --git a/man/combine_checkboxes.Rd b/man/combine_checkboxes.Rd index 3d78a441..4ba6def4 100644 --- a/man/combine_checkboxes.Rd +++ b/man/combine_checkboxes.Rd @@ -55,26 +55,65 @@ A modified supertibble. \description{ \code{\link[=combine_checkboxes]{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{ -\code{\link[=combine_checkboxes]{combine_checkboxes()}} makes use of the output names of \code{\link[=read_redcap]{read_redcap()}} -data tibbles and metadata tibbles. Changes to checkbox data names or -metadata \code{field_name}s may result in errors. - -Checkbox fields are expanded to be a variable per checkbox option, separated -by underscores. For example, \code{checkbox_var} with 2 options becomes -\code{checkbox_var___1} and \code{checkbox_var___2}. \code{\link[=combine_checkboxes]{combine_checkboxes()}} looks for -these and may give a error if it cannot find them. +\code{\link[=combine_checkboxes]{combine_checkboxes()}} operates on the data and metadata tibbles produced by +the \code{\link[=read_redcap]{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 \code{field_name}s could lead to errors. + +REDCap checkbox fields are typically expanded into separate variables for each +checkbox option, with names formatted as \code{checkbox_var___1}, \code{checkbox_var___2}, +etc. \code{\link[=combine_checkboxes]{combine_checkboxes()}} detects these variables and combines them into a +single column. If the expected variables are not found, an error is returned. } \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 )