arg_test

Test combinations of argument values of a function.

Usage

arg_test(
  fun,
  arg,
  val,
  expect_error = NULL,
  parall = FALSE,
  thread_nb = NULL,
  print_count = 10,
  plot_fun = FALSE,
  export = FALSE,
  res_path = ".",
  safer_check = TRUE,
  lib_path = NULL,
  error_text = ""
)

Arguments

fun: Single character string indicating the name of the function tested (without brackets).
arg: Vector of character strings of arguments of fun. At least arguments that do not have default values must be present in this vector.
val: List with number of compartments equal to the length of arg, each compartment containing values of the corresponding argument in arg. Each different value must be in a list or in a vector. For instance, argument 3 in arg is a logical argument (values accepted TRUE, FALSE, NA). Thus, compartment 3 of val can be either list(TRUE, FALSE, NA), or c(TRUE, FALSE, NA). NULL value alone must be written list(NULL).
expect_error: List of exactly the same structure as val argument, but containing FALSE or TRUE, depending on whether error is expected (TRUE) or not (FALSE) for each corresponding value of val. A message is returned depending on discrepancies between the expected and observed errors. See the examples below. BEWARE: not always possible to write the expected errors for all the combination of argument values. Ignored if NULL.
parall: Single logical value. Force parallelization ?
thread_nb: Single numeric integer indicating the number of threads to use if ever parallelization is required. If NULL, all the available threads will be used. Ignored if parall is FALSE.
print_count: Single interger value. Print a working progress message every print_count during loops. BEWARE: can increase substentially the time to complete the process if using a small integer value, like 10 for instance. Use Inf if no loop message desired.
plot_fun: Single logical value. Plot the plotting function tested for each test? Ignored if the tested function is not a graphic function.
export: Single logical value. Export the results into a .RData file and into a .tsv file? If FALSE, return a list into the console (see below). BEWARE: will be automatically set to TRUE if parall is TRUE. This means that when using parallelization, the results are systematically exported, not returned into the console.
res_path: Single character string indicating the absolute pathway of the folder where the txt results and pdfs, containing all the plots, will be saved (by default into the working directory). Several txt and pdf, one per thread, if parallelization. Ignored if export is FALSE. Must be specified if parall is TRUE or if export is TRUE.
safer_check: Single logical value. Perform some "safer" checks? If TRUE, checkings are performed before main code running (see https://github.com/safer-r): 1) correct lib_path argument value 2) required functions and related packages effectively present in local R lybraries and 3) R classical operators (like "<-") not overwritten by another package because of the R scope. Must be set to FALSE if this fonction 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 package 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 "".

Value

One or several pdf if a plotting function is tested and if the plot_fun argument is TRUE.

And then, if export is FALSE a list containing:

- $fun: the tested function.

- $ini: the initial input values.

- $data: a data frame of all the combination tested, containing the following columns:

# the different values tested, named by arguments - $kind: a vector of character strings indicating the kind of test result: either "ERROR", or "WARNING", or "OK". - $problem: a logical vector indicating if error or not.

- $expected.error: optional logical vector indicating the expected error specified in the expect_error argument. - $message: either NULL if $kind is always "OK", or the messages.

- $sys.info: system and packages info.

If export is TRUE:

- the same list object into a .RData file.

- also the $data data frame into a .tsv file.

- if expect_error is non NULL and if any discrepancy, the $data data frame into a .tsv file but containing only the rows with discrepancies between expected and observed errors.

Details

Limited to 43 arguments with at least 2 values each. The total number of arguments tested can be more if the additional arguments have a single value. The limit is due to nested "for" loops (https://stat.ethz.ch/pipermail/r-help/2008-March/157341.html), but this limitation is away from the number of tests performed that would be 2^43.

Author

Gael Millot

Yushi Han

Haiding Wang

Examples