Classes

The meaning of the classes is as follows:

• scalar: an atomic vector of length 1, no tolerance for NAs. Option NA OK allows NA values.

• vector: an atomic vector (vector of list do not fall in this class), tolerance for NAs. Option NO NA throws an error if it contains NAs, named requires the vector to have names.

• matrix: a matrix, tolerance for NAs. Option NO NA throws an error if it contains NAs, square requires the matrix to be square.

• vmatrix: a matrix or vector, tolerance for NAs. Option NO NA throws an error if it contains NAs, square requires the matrix to be square (if a vector, then it must be of length 1).

• data.frame: an object that inherits from data.frame, tolerates NAs. Option No NA throws an error if it contains NAs.

• vdata.frame: an object that inherits from data.frame, or a vector; tolerates NAs. Option No NA throws an error if it contains NAs.

• list: a list. Option named requires it to have names.

• formula: a formula. Option os (resp. ts) requires it to be one-sided (resp. two-sided).

• function: a function.

• charin: a character scalar that must be in a list of choices. Option multi accepts vectors of length greater than 1. You can provide the choices in the argument .choices, or directly in parentheses after the class: charin(value1, value2, etc).

• match: a character scalar that must be in a list of choices after partial matching. Option multi accepts vectors of length greater than 1, strict enables case sensitivity (which is off by default). This class also reassigns the argument after the partial matching. You have three ways to provide the choices: i) in the argument .choices, ii) directly in parentheses after the class: match(value1, value2, etc), or iii) in the argument’s default values, e.g.  fun = function(x = c("value1", "value2", etc)).

• path: a character scalar that should point to a directory or a file. Option dir checks that the path points to a directory. Option read checks that the file exists already and has read permission. Option create creates
  the grand-parent and parent folders in case these do not exist.

• class: an object whose class is listed in parentheses. Example: if class(lm, glm), then only lm or glm arguments will be accepted.

• NA: exactly NA (i.e. an atomic vector of length 1 equal to NA).

Restrictions

Each of these classes supports a set of restrictions, explained in Figure 2.

All atomic classes support sub-type restriction and restrictions based on equality when the sub-type is numeric. The 5 simple sub-types support conversion with the keyword conv, if this keyword is present, then the value is converted to the appropriate type and re-assigned back to the argument.

You can ensure the arguments have the appropriate length, number of row or columns with len(a, b), nrow(a, b) and ncol(a, b). Instead of having hard values, you can enforce the arguments to have a length that depends on the context thanks to the len(data) or len(value) syntax. For instance, let’s say you have an argument weights, you want it to be a vector whose length is equal to the number of observations in argument base, then you can use check_arg(weights, "numeric vector len(data)", .data = base). You could alternatively use check_arg(weights, "numeric vector len(value)", .value = NROW(base)).

For formulas, there is a support for multi-part formulas (package Formula, Zeileis and Croissant 2010), you can restrict the number of parts on the left or right with the left(a, b) and right(a, b) syntax. You can also ensure that all variables contained in the formula are either in the data set provided in the argument .data or in the environment with the var(data, env) syntax.

For functions, you can restrict the number of arguments they have with arg(a, b).

Globals

On top of the types, you also have 8 global keywords that can be anywhere in the type character string. These globals are:

• MBT: requires the user to provide the argument (Must Be There).

• NULL: allows the argument to be NULL.

• NULL{expr}: allows the argument to be NULL, if NULL, then the argument is re-assigned the value of expr.

• safe NULL: allows the argument to be NULL but forbids the argument to be of the type x$a since NULL values in this case are often mistakes–especially useful when the argument is a vector.

• eval: evaluates the argument in a data set given in the argument .data.

• evalset: evaluates the argument in a data set given in the argument .data, then re-assigns the obtained value to the argument.

• dotnames: when checking the ... argument, requires all elements to be named.

check_set_arg

Actually there are two functions to check arguments: check_arg and check_set_arg. The difference between the two is that i) the second allows keywords that re-assigns values to the argument (i.e. the match class, the conv keyword, NULL{expr}, and evalset), and ii) allows to check list elements of list arguments.

Let’s illustrate when to use check_set_arg:

plot_cor = function(x, y = NULL, line.opts = list(), ...){
  # x: numeric vector, must be given by the user
  check_arg(x, "numeric vector mbt")
  # y: 
  #  - numeric vector of the same length as x
  # - if y is NULL, then x with some noise is assigned to it 
  check_set_arg(y, "NULL{x + rnorm(length(x))} numeric vector len(data)", .data = x)
  
  # We ensure line.opts is a list
  check_arg(line.opts, "named list")
  
  # The linear regression + options from ...
  reg = lm(y ~ x, ...)
  
  # plotting the correlation
  plot(x, y)
  
  # The fit, all arguments are in line.opts
  # col:
  # - if not provided => "firebrick"
  # - partially matched to firebrick or darkblue
  # - otherwise, a positive integer or a character scalar
  check_set_arg(line.opts$col, "NULL{'firebrick'} match(firebrick, darkblue) | scalar(integer, character) GE{0}") 
  # lwd:
  # - if not provided => 2
  # - otherwise a positive integer scalar
  check_set_arg(line.opts$lwd, "integer scalar GE{0} NULL{2}") # check + default
  
  line.opts$a = reg
  do.call("abline", line.opts)
}

plot_cor(rnorm(100), line.opts = list(col = "dark"))

Why seperating argument checking in two functions? First, it is because check_set_arg requires (marginally, but still) more processing–so it’s better to always use the faster function when appropriate, and use check_set_arg only when needed. Second, and this is the main reason, it is because dreamerr allows the user to turn off argument checking with setDreamerr_check(FALSE). If a call to a function works, then writting off all check_arg calls would also work. This is not the case for check_set_arg since it re-assigns values to the arguments–and therefore can’t be turned off.

Developer mode

Ironically, to improve perfomance (since its computational footprint should be very low), there is almost no error-handling in check_arg!

But no worries: if you turn the developer mode on with setDreamerr_dev.mode(TRUE), an in-depth check of any call to dreamerr’s functions will be performed. This is especially useful if you are not familiar with the syntax.

Yet beware, this error checking is really in-depth, thus rather computationnally intensive (about half a millisecond). Thus the developer mode should be off the majority of the time.