Skip to contents

Argument Check

arg_check.Rd

Check expected values of an argument of functions: class, type, mode, length, restricted values panel, kind of numeric values in addition to the distinction between 'integer' and 'double' (proportion only? Inf values authorized? negative values authorized? Integers of type 'double'?)

Usage

arg_check(
  data,
  class = NULL,
  typeof = NULL,
  mode = NULL,
  length = NULL,
  prop = FALSE,
  double_as_integer_allowed = FALSE,
  options = NULL,
  all_options_in_data = FALSE,
  na_contain = FALSE,
  neg_values = TRUE,
  inf_values = TRUE,
  print = FALSE,
  data_name = NULL,
  data_arg = TRUE,
  safer_check = TRUE,
  lib_path = NULL,
  error_text = ""
)

Arguments

data

Object to test.

class

Single character string. Either one of the class() result or "vector" or "ggplot2" (i.e., objects of class c("gg", "ggplot") for R < 4.5 and c("ggplot2::ggplot", "ggplot", "ggplot2::gg", "S7_object", "gg") otherwise) or "ggplot_built" (i.e., objects of class "ggplot_built" for R < 4.5 and c("ggplot2::ggplot_built", "ggplot_built", "ggplot2::gg", "S7_object") otherwise) or NULL. See the warning section below.

typeof

Single character string. Either one of the typeof() result or NULL.

mode

Single character string. Either one of the mode() result (for non-vector object) or NULL.

length

Single numeric value indicating the length of the object. Not considered if NULL.

prop

Single logical value. Are the numeric values between 0 and 1 (proportion)? If TRUE, can be used alone, i.e., without checking the class, mode, etc., of the object to test.

double_as_integer_allowed

Single logical value. If TRUE, no error is reported in the checking message if argument is set to typeof = "integer" or class = "integer", while the reality is typeof == "double" or class == "numeric" but with zero as modulo (reminder of a division). This means that i <- 1, which is typeof(i) == "double" is considered as an integer when setting double_as_integer_allowed = TRUE. Warning: double_as_integer_allowed = TRUE uses data %% 1 == 0L but not isTRUE(all.equal(data %% 1, 0)) is used here because the argument checks for integers stored as double (does not check for decimal numbers that are approximate integers).

options

Vector of character strings or integers indicating all the possible option values for the data argument, or NULL. Numbers of type "double" are accepted if they have a 0 modulo.

all_options_in_data

Single logical value. If TRUE, all of the options of the options argument must be present at least once in the data argument, and nothing else. If FALSE, some or all of the options must be present in the data argument, and nothing else. Ignored if the options argument is NULL.

na_contain

Single logical value. Can the data argument contain NA?

neg_values

Single logical value. Are negative numeric values authorized? Warning: the default setting is TRUE, meaning that, in that case, no check is performed for the presence of negative values. The neg_values argument is activated only when set to FALSE. In addition, (1) neg_values = FALSE can only be used when class, typeof or mode arguments are not NULL, otherwise an error message is returned, (2) the presence of negative values is not checked with neg_values = FALSE if the tested object is a factor. For the latter, a checking message is returned "OBJECT MUST BE MADE OF NON NEGATIVE VALUES BUT IS A FACTOR".

inf_values

Single logical value. Are infinite numeric values authorized (Inf or -Inf)? Same remarks as for the neg_values argument.

print

Single logical value. Print the message if the $problem output is TRUE? Warning: set by default to FALSE, which facilitates the control of the checking message output when using arg_check() inside functions. See the example section.

data_name

Single character string indicating the name of the object to test. If NULL, use what is assigned to the data argument for the returned message.

data_arg

Single logical value. Is the tested object a function argument? If TRUE (default), "ARGUMENT" is written in output messages, otherwise "OBJECT".

safer_check

Single logical value. Perform some "safer" checks? If TRUE, checkings are performed before main code running (see the safer-r project): 1) correct lib_path argument value 2) required functions and related packages effectively present in local R libraries and 3) R classical operators (like "<-") not overwritten by another package because of the R scope. Must be set to FALSE if this function is used inside another "safer" function to avoid pointless multiple checkings.

lib_path

Vector of characters specifying the absolute pathways of the directories containing the required packages for the function, if not in the default directories. Useful when R packages are not installed in the default directories because of lack of admin rights. More precisely, lib_path is passed through the new argument of .libPaths() so that the new library paths are unique(c(new, .Library.site, .Library)). Warning: .libPaths() is restored to the initial paths, after function execution. Ignored if NULL (default) or if the safer_check argument is FALSE: only the pathways specified by the current .libPaths() are used for package calling.

error_text

Single character string used to add information in error messages returned by the function, notably if the function is inside other functions, which is practical for debugging. Example: error_text = " INSIDE <PACKAGE_1>::<FUNCTION_1> INSIDE <PACKAGE_2>::<FUNCTION_2>.". If NULL, converted into "". Of note, in arg_check(), error_text is also used at the end of the string returned when no problem is detected.

Value

A list containing:

  • problem: logical. Is there any problem detected?

  • text: message indicating the details of the problem, or the absence of problem.

  • object.name: value of the data_name argument (i.e., name of the checked object if provided, NULL otherwise).

Details

If options == NULL, then at least class or type or mode or length argument must be non-null.

If options is non-null, then class, type and mode must be NULL, and length can be NULL or specified.

The function tests what is written in its arguments, even if what is written is incoherent. For instance, arg_check(data = factor(1), class = "factor", mode = "character") will return a problem, whatever the object tested in the data argument, because no object can be class "factor" and mode "character" (factors are class "factor" and mode "numeric"). Of note, the length of object of class "environment" is always 0.

If the tested object is NULL, then the function will always return a checking problem.

The argument class can be set to "vector". This means that the object is tested for class(data) returning only "numeric", "integer", "character", "logical", "complex" or "expression". Please, use another value of class (e.g., class = "call" or class = "list") for other types and class of objects.

Since R >= 4.0.0, class(matrix()) returns "matrix" "array", and not "matrix" alone as before. However, use argument class = "matrix" to check for matrix object (of class "matrix" "array" in R >= 4.0.0) and use argument class = "array" to check for array object (of class "array" in R >= 4.0.0).

See more examples here.

See also

match.arg.

Author

Gael Millot

Yushi Han

Haiding Wang

Examples

# Warning: these examples may not work well when using the "Run examples" link 
# because of a particular environment. Please, copy-paste in a local environment.
# See also https://safer-r.github.io/saferDev/articles/arg_check.html
test <- matrix(1:3)
if (FALSE) {
# Example that returns an error
saferDev::arg_check(data = test, print = TRUE, class = "vector", mode = "numeric")  # error: THE test ARGUMENT MUST BE CLASS vector
}
saferDev::arg_check(data = test, print = TRUE, class = "matrix", mode = "numeric")
#> $problem
#> [1] FALSE
#> 
#> $text
#> [1] "NO PROBLEM DETECTED FOR THE test ARGUMENT."
#> 
#> $object.name
#> [1] "test"
#> 
saferDev::arg_check(data = test, print = TRUE, class = "matrix", mode = "numeric", error_text = " using saferDev::arg_check()")
#> $problem
#> [1] FALSE
#> 
#> $text
#> [1] "NO PROBLEM DETECTED FOR THE test ARGUMENT using saferDev::arg_check()"
#> 
#> $object.name
#> [1] "test"
#> 

# See more examples here: https://safer-r.github.io/saferDev/articles/all_args_here.html