REDCapTidieR (version 1.2.2)

combine_checkboxes: Combine Checkbox Fields into a Single Column

Description

combine_checkboxes() consolidates multiple checkbox fields in a REDCap data tibble into a single column. This transformation simplifies analysis by merging several binary columns into one labeled factor column, making the data more interpretable and easier to analyze.

Usage

combine_checkboxes(
  supertbl,
  tbl,
  cols,
  names_prefix = "",
  names_sep = "_",
  names_glue = NULL,
  names_repair = "check_unique",
  multi_value_label = "Multiple",
  values_fill = NA,
  raw_or_label = "label",
  keep = TRUE
)

Value

A modified supertibble.

Arguments

supertbl

A supertibble generated by read_redcap(). Required.

tbl

The redcap_form_name of the data tibble to extract. Required.

cols

Checkbox columns to combine to single column. Required.

names_prefix

String added to the start of every variable name.

names_sep

String to separate new column names from names_prefix.

names_glue

Instead of names_sep and names_prefix, you can supply a glue specification and the unique .value to create custom column names.

names_repair

What happens if the output has invalid column names? The default, "check_unique" is to error if the columns are duplicated. Use "minimal" to allow duplicates in the output, or "unique" to de-duplicated by adding numeric suffixes. See vctrs::vec_as_names() for more options.

multi_value_label

A string specifying the value to be used when multiple checkbox fields are selected. Default "Multiple".

values_fill

Value to use when no checkboxes are selected. Default NA.

raw_or_label

Either 'raw' or 'label' to specify whether to use raw coded values or labels for the options. Default 'label'.

keep

Logical indicating whether to keep the original checkbox fields in the output. Default TRUE.

Details

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_names could lead to errors.

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.

Examples

library(dplyr)
# 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()

if (FALSE) {

redcap_uri <- Sys.getenv("REDCAP_URI")
token <- Sys.getenv("REDCAP_TOKEN")

supertbl <- read_redcap(redcap_uri, token)
combine_checkboxes(
  supertbl = supertbl,
  tbl = "tbl",
  cols = starts_with("col"),
  multi_value_label = "Multiple",
  values_fill = NA
)
}