translate_logic: Translate REDCap branching logic into R expressions

In epicentre-msf/redcap: R Utilities For REDCap

Translate REDCap branching logic into R expressions

Description

Translate REDCap branching logic into expressions evaluable in R. E.g.

Translation step	Example expression
0. Initial REDCap logic	⁠[over_18]='1' and [signed_consent]<>''⁠
1. Translate to R	over_18 == '1' & signed_consent != ''
2. (Optional) Swap values/labels	over_18 == 'Yes' & signed_consent != ''
3. (Optional) Use is.na	over_18 == 'Yes' & !is.na(signed_consent)
4. (Optional) Use %in%	over_18 %in% 'Yes' & !is.na(signed_consent)

Usage

translate_logic(
  x,
  use_value_labs = TRUE,
  use_header_labs = FALSE,
  use_is_na = TRUE,
  use_in = TRUE,
  drop_redundant = FALSE,
  field_nchar_max = 80L,
  meta_factors = NULL,
  meta_dictionary = NULL,
  on_error = "warn"
)

Arguments

x	A character vector of REDCap branching logic statements
use_value_labs	Logical indicating whether to replace factor option values with labels (based on the mapping defined in meta_factors). E.g.: y == '1' becomes y == 'Yes'
use_header_labs	Logical indicating whether to use labels instead of variable names as column names (based on the mapping defined in meta_dictionary). E.g.: age >= 18 becomes "Participant's age" >= 18
use_is_na	Logical indicating whether to replace REDCap-style tests for missingness with is.na. E.g.: y == "" becomes is.na(y) y != "" becomes !is.na(y)
use_in	Logical indicating whether to replace instances of == and != associated with factor-type variables (as defined in meta_factors) with %in%. E.g.: y == 'Yes' becomes y %in% 'Yes' y != 'Yes' becomes !y %in% 'Yes'
drop_redundant	Logical indicating whether to simplify expressions by removing redundant components from expressions that test both for equality and inequality with the same variable. E.g.: var == "X" & var != "" becomes var == "X"
field_nchar_max	Integer indicating the maximum number of characters to allow in field name labels before they are truncated and appended with "...". Defaults to 80L.
meta_factors	A data frame containing variable names (column field_name) and corresponding values (column value) and labels (column label) for factor-type variables. Fetch with meta_factors. Only needed if either use_value_labs or use_in are TRUE.
meta_dictionary	A data frame containing variable names (column field_name) and labels (column field_label). Fetch with meta_dictionary. Only needed if use_header_labs is TRUE.
on_error	What to do if one or more elements of statements can't be translated into valid R expressions? Options are "ignore" (return NA for relevant elements), "warn" (return NA for relevant elements and give warning), or "fail" (throw error). Defaults to "warn".

Value

A character vector of R-style expressions

Examples

# normally would fetch factor metadata with redcap::meta_factors(), but here
# we'll create a simple example by hand
df_factors <- data.frame(
  field_name = c("head_household", "head_household"),
  value = c("0", "1"),
  label = c("No", "Yes"),
  stringsAsFactors = FALSE
)

redcap_logic <- "head_household=1 and age<>\"\""
translate_logic(redcap_logic, meta_factors = df_factors)

epicentre-msf/redcap documentation built on April 13, 2025, 3:27 a.m.