util_correct_variable_use: Check referred variables

In dataquieR: Data Quality in Epidemiological Research

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 (util_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 util_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,
  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,
  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.
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

dataquieR documentation built on July 26, 2023, 6:10 p.m.