Find pairs of survey iterations with identical response options

Usage

find_matching_pairs(var, vars_df, dicts_df)

Arguments

var

A string specifying the variable (concept) to check. Must be present in the concept column of vars_df.

vars_df

A data frame mapping each survey iteration to the variable name used for the concept. Expected columns:

concept: the concept identifier for each row (matched against var)
variable_<cycle>: one column per iteration to include in the comparison, where <cycle> matches a value in the cycle column of dicts_df; each cell holds the variable name used for the concept in that iteration. At least two variable_<cycle> columns are required.

dicts_df

A nested data frame linking each survey iteration to its data dictionary. Expected columns:

cycle: the survey iteration identifier
dict: a list-column whose elements are iteration-specific data dictionaries (each a data frame)

Each data dictionary should contain the columns:

variable: variable name
name: value code
missing: whether the value is a missing value placeholder
label: value label

Value

A list of the matching iteration pairs. Each element is a length-two character vector giving the two cycle identifiers whose response options are identical. Options are considered identical when the value code-label pairs (name and label) match. Iterations with no matches are omitted, and the list is empty when no two iterations share the same options. It is also empty, with a warning, when the concept appears in fewer than two iterations (nothing to compare). The number of iterations compared is attached as an n_cycles attribute.

Details

While check_response_consistency() returns a single logical value indicating whether every iteration shares the same response options for a given concept, find_matching_pairs() reports which iterations agree with each other. So when the check returns FALSE, the user can refer to this function and see how the response options group together and pinpoint where harmonization is needed prior to downstream analysis.

Examples

vars_df <- data.frame(
  concept = "RET_RTRD",
  variable_COM = "RET_RTRD_COM",
  variable_COF1 = "RET_RTRD_COF1",
  variable_COF2 = "RET_RTRD_COF2"
)

dict_a <- data.frame(
  name = c(1:3, 8, 9),
  missing = c(rep(0, 3), rep(1, 2)),
  label = c(
    "Completely retired",
    "Partially retired",
    "Not retired",
    "[DO NOT READ] Don't know/No answer",
    "[DO NOT READ] Refused"
  )
)

dict_b <- data.frame(name = 4, missing = 0, label = "Never had a job")

dict_COM <- dict_a |> dplyr::mutate(variable = "RET_RTRD_COM")
dict_COF1 <- rbind(dict_a, dict_b) |>
  dplyr::mutate(variable = "RET_RTRD_COF1")
dict_COF2 <- rbind(dict_a, dict_b) |>
  dplyr::mutate(variable = "RET_RTRD_COF2")

# tibble allows list-columns natively
dicts_df <- tibble::tibble(
  cycle = c("COM", "COF1", "COF2"),
  dict = list(dict_COM, dict_COF1, dict_COF2)
)

# COM is missing "Never had a job", so response options are inconsistent --> empty list
check_response_consistency("RET_RTRD", vars_df, dicts_df)
#> [1] FALSE