util_correct_variable_use {dataquieR}

Check referred variables

Description

This function operates in the environment of its caller (using eval.parent, similar to Function like C-Preprocessor-Macros ). Different from the other utility function that work in the caller's environment (prep_prepare_dataframes), It has no side effects except that the argument of the calling function specified in arg_name is normalized (set to its default or a general default if missing, variable names being all white space replaced by NAs). It expects two objects in the caller's environment: ds1 and meta_data. meta_data is the metadata data frame and ds1 is produced by a preceding call of prep_prepare_dataframes using meta_data and study_data.

Usage

util_correct_variable_use(
  arg_name,
  allow_na,
  allow_more_than_one,
  allow_null,
  allow_all_obs_na,
  allow_any_obs_na,
  min_distinct_values,
  need_type,
  need_scale,
  role = "",
  overwrite = TRUE,
  do_not_stop = FALSE,
  remove_not_found = TRUE
)

util_correct_variable_use2(
  arg_name,
  allow_na,
  allow_more_than_one,
  allow_null,
  allow_all_obs_na,
  allow_any_obs_na,
  min_distinct_values,
  need_type,
  need_scale,
  role = arg_name,
  overwrite = TRUE,
  do_not_stop = FALSE,
  remove_not_found = TRUE
)

Arguments

arg_name

character Name of a function argument of the caller of util_correct_variable_use

allow_na

logical default = FALSE. allow NAs in the variable names argument given in arg_name

allow_more_than_one

logical default = FALSE. allow more than one variable names in arg_name

allow_null

logical default = FALSE. allow an empty variable name vector in the argument arg_name

allow_all_obs_na

logical default = TRUE. check observations for not being all NA

allow_any_obs_na

logical default = TRUE. check observations for being complete without any NA

min_distinct_values

integer Minimum number of distinct observed values of a study variable

need_type

character if not NA, variables must be of data type need_type according to the metadata, can be a pipe (|) separated list of allowed data types. Use ! to exclude a type. See DATA_TYPES for the predefined variable types of the dataquieR concept.

need_scale

character if not NA, variables must be of scale level need_scale according to the metadata, can be a pipe (|) separated list of allowed scale levels. Use ! to exclude a level. See SCALE_LEVELS for the predefined scale levels of the dataquieR concept.

role

character variable-argument role. Set different defaults for all allow-arguments and need_type of this util_correct_variable_use.. If given, it defines the intended use of the verified argument. For typical arguments and typical use cases, roles are predefined in .variable_arg_roles. The role's defaults can be overwritten by the arguments. If role is "" (default), the standards are allow_na = FALSE, allow_more_than_one = FALSE, allow_null = FALSE, allow_all_obs_na = TRUE, allow_any_obs_na = TRUE, and need_type = NA. Use util_correct_variable_use2 for using the arg_name as default for role. See .variable_arg_roles for currently available variable-argument roles.

overwrite

logical overwrite vector of variable names to match the labels given in label_col.

do_not_stop

logical do not throw an error, if one of the variables violates allow_all_obs_na, allow_any_obs_na or min_distinct_values. Instead, the variable will be removed from arg_name in the parent environment with a warning. This is helpful for functions which work with multiple variables.

remove_not_found

TODO: Not yet implemented

Details

util_correct_variable_use and util_correct_variable_use2 differ only in the default of the argument role.

util_correct_variable_use and util_correct_variable_use2 put strong effort on producing compressible error messages to the caller's caller (who is typically an end user of a dataquieR function).

The function ensures, that a specified argument of its caller that refers variable names (one or more as character vector) matches some expectations.

This function accesses the caller's environment!

See Also

.variable_arg_roles

Other robustness_functions: util_as_valid_missing_codes(), util_check_one_unique_value(), util_empty(), util_ensure_character(), util_ensure_in(), util_ensure_suggested(), util_expect_scalar(), util_fix_rstudio_bugs(), util_is_integer(), util_is_numeric_in(), util_is_valid_missing_codes(), util_match_arg(), util_observations_in_subgroups(), util_only_NAs(), util_stop_if_not(), util_warn_unordered()

Other robustness_functions: util_as_valid_missing_codes(), util_check_one_unique_value(), util_empty(), util_ensure_character(), util_ensure_in(), util_ensure_suggested(), util_expect_scalar(), util_fix_rstudio_bugs(), util_is_integer(), util_is_numeric_in(), util_is_valid_missing_codes(), util_match_arg(), util_observations_in_subgroups(), util_only_NAs(), util_stop_if_not(), util_warn_unordered()