vetR - Trust, but Verify

Easily

When you write functions that operate on S3 or unclassed objects you can either trust that your inputs will be structured as expected, or tediously check that they are.

vetr takes the tedium out of structure verification so that you can trust, but verify. It lets you express structural requirements declaratively with templates, and it auto-generates human-friendly error messages as needed.

Quickly

vetr is written in C to minimize overhead from parameter checks in your functions. It has no dependencies.

Templates

Declare a template that an object should conform to, and let vetr take care of the rest:

library(vetr)
tpl <- numeric(1L)
vet(tpl, 1:3)

[1] "`length(1:3)` should be 1 (is 3)"

vet(tpl, "hello")

[1] "`\"hello\"` should be type \"numeric\" (is \"character\")"

vet(tpl, 42)

[1] TRUE

The template concept is based on vapply, but generalizes to all S3 objects and adds some special features to facilitate comparison. For example, zero length templates match any length:

tpl <- integer()
vet(tpl, 1L:3L)

[1] TRUE

vet(tpl, 1L)

[1] TRUE

And for convenience short (<= 100 length) integer-like numerics are considered integer:

tpl <- integer(1L)
vet(tpl, 1)       # this is a numeric, not an integer

[1] TRUE

vet(tpl, 1.0001)

[1] "`1.0001` should be type \"integer-like\" (is \"double\")"

vetr can compare recursive objects such as lists, or data.frames:

tpl.iris <- iris[0, ]      # 0 row DF matches any number of rows in object
iris.fake <- iris
levels(iris.fake$Species)[3] <- "sibirica"   # tweak levels

vet(tpl.iris, iris)

[1] TRUE

vet(tpl.iris, iris.fake)

[1] "`levels(iris.fake$Species)[3]` should be \"virginica\" (is \"sibirica\")"

From our declared template iris[0, ], vetr infers all the required checks. In this case, vet(iris[0, ], iris.fake, stop=TRUE) is equivalent to:

stopifnot_iris <- function(x) {
  stopifnot(
    is.data.frame(x),
    is.list(x),
    length(x) == length(iris),
    identical(lapply(x, class), lapply(iris, class)),
    is.integer(attr(x, 'row.names')),
    identical(names(x), names(iris)),
    identical(typeof(x$Species), "integer"),
    identical(levels(x$Species), levels(iris$Species))
  )
}
stopifnot_iris(iris.fake)

Error in stopifnot_iris(iris.fake): identical(levels(x$Species), levels(iris$Species)) is not TRUE

vetr saved us typing, and the time and thought needed to come up with what needs to be compared.

You could just as easily have created templates for nested lists, or data frames in lists. Templates are compared to objects with the alike function. For a thorough description of templates and how they work see the alike vignette. For template examples see example(alike).

Auto-Generated Error Messages

Let’s revisit the error message:

vet(tpl.iris, iris.fake)

[1] "`levels(iris.fake$Species)[3]` should be \"virginica\" (is \"sibirica\")"

It tells us:

• The reason for the failure
• What structure would be acceptable instead
• The location of failure levels(iris.fake$Species)[3]

vetr does what it can to reduce the time from error to resolution. The location of failure is generated such that you can easily copy it in part or full to the R prompt for further examination.

Introduction

You can combine templates with && / ||:

vet(numeric(1L) || NULL, NULL)

[1] TRUE

vet(numeric(1L) || NULL, 42)

[1] TRUE

vet(numeric(1L) || NULL, "foo")

[1] "`\"foo\"` should be `NULL`, or type \"numeric\" (is \"character\")"

Templates only check structure. When you need to check values use . to refer to the object:

vet(numeric(1L) && . > 0, -42)  # strictly positive scalar numeric

[1] "`-42 > 0` is not TRUE (FALSE)"

vet(numeric(1L) && . > 0, 42)

[1] TRUE

If you do use the . symbol in your vetting expressions in your packages, you will need to include utils::globalVariables(".") as a top-level call to avoid the “no visible binding for global variable ‘.’” R CMD check NOTE.

You can compose vetting expressions as language objects and combine them:

scalar.num.pos <- quote(numeric(1L) && . > 0)
foo.or.bar <- quote(character(1L) && . %in% c('foo', 'bar'))
vet.exp <- quote(scalar.num.pos || foo.or.bar)

vet(vet.exp, 42)

[1] TRUE

vet(vet.exp, "foo")

[1] TRUE

vet(vet.exp, "baz")

[1] "At least one of these should pass:"                         
[2] "  - `\"baz\" %in% c(\"foo\", \"bar\")` is not TRUE (FALSE)" 
[3] "  - `\"baz\"` should be type \"numeric\" (is \"character\")"

all_bw is available for value range checks (~10x faster than isTRUE(all(. >= x & . <= y)) for large vectors):

vet(all_bw(., 0, 1), runif(5) + 1)

[1] "`all_bw(runif(5) + 1, 0, 1)` is not TRUE (is chr: \"`1.017089` at index 1 not in `[0,1]`\")"

There are a number of predefined vetting tokens you can use in your vetting expressions such as:

vet(NUM.POS, -runif(5))    # positive numeric; see `?vet_token` for others

[1] "`-runif(5)` should contain only positive values, but has negatives"

Vetting expressions are designed to be intuitive to use, but their implementation is complex. We recommend you look at example(vet) for usage ideas, or at the “Non Standard Evaluation” section of the vignette for the gory details.

Non Standard Evaluation

vet(. > 0, 1:3)

a <- quote(integer() && . > 0)
b <- quote(logical(1L) && !is.na(.))
c <- quote(a || b)

vet(c, 1:3)

vet((integer() && . > 0) || (logical(1L) && !is.na(.)), 1:3)

vet(quote(x + y), my.call)       # notice `quote`

tpl.call <- quote(quote(x + y))  # notice `quote(quote(...))`
vet(tpl.call, my.call)

logical(1) || (numeric(1) && (. > 0 & . < 1))

vet(. > 0, 1:3)

[1] TRUE

vet(logical(1) || (numeric(1) && (. > 0 & . < 1)), 42)
# becomes:
alike(logical(1L), 42) || (alike(numeric(1L), 42) && all(42 > 0 & 42 < 1))
# becomes:
FALSE || (TRUE && FALSE)
# becomes:
FALSE

vet(logical(1) || (numeric(1) && (. > 0 & . < 1)), 42)

[1] "At least one of these should pass:"                 
[2] "  - `42 > 0 & 42 < 1` is not TRUE (FALSE)"          
[3] "  - `42` should be type \"logical\" (is \"double\")"

Special Cases

If you need to reference a literal dot (.) in a token, you can escape it by adding another dot so that . becomes ... If you want to reference ... you’ll need to use ..... If you have a standard token that does not reference the vetting object (i.e. does not use .) you can mark it as a standard token by wrapping it in .() (if you want to use a literal .() you can use ..()).

If you need && or || to be interpreted literally you can wrap the call in I to tell vet to treat the entire call as a single token:

I(length(a) == length(b) && . %in% 0:1)

vet will stop searching for tokens at the first call to a function other than (, &&, and ||. The use of I here is just an example of this behavior and convenient since I does not change the meaning of the vetting token. An implication of this is you should not nest template tokens inside functions as vet will not identify them as template tokens and you may get unexpected results. For example:

I(logical(1L) && my_special_fun(.))

will always fail because logical(1L) is part of a standard token and is evaluated as FALSE rather than used a template token for a scalar logical.

Benchmarks

vetr is written primarily in C to minimize the performance impact of adding validation checks to your functions. Performance should be faster than using stopifnot except for the most trivial of checks. The vetr function itself carries some additional overhead from matching arguments, but it should still be faster than stopifnot except in the simplest of cases. Here we run our checks on valid iris objects we used to illustrate declarative checks:

vetr_iris <- function(x) vetr(tpl.iris)

bench_mark(times=1e4,
  vet(tpl.iris, iris),
  vetr_iris(iris),
  stopifnot_iris(iris)   # defined in "Templates" section
)

Mean eval time from 10000 iterations, in microseconds:
  vet(tpl.iris, iris)   ~  12.0
  vetr_iris(iris)       ~  15.9
  stopifnot_iris(iris)  ~  27.1

Performance is optimized for the success case. Failure cases should still perform reasonably well, but will be slower than most success cases.

Templates and Performance

Complex templates will be slower to evaluate than simple ones, particularly for lists with lots of nested elements. Note however that the cost of the vetting expression is a function of the complexity of the template, not that of the value being vetted.

We recommend that you predefine templates in your package and not in the validation expression since some seemingly innocuous template creation expressions carry substantial overhead:

bench_mark(data.frame(a=numeric()))

Mean eval time from 1000 iterations, in microseconds:
  data.frame(a = numeric())  ~  80

In this case the data.frame call alone take over 100us. In your package code you could use:

df.tpl <- data.frame(a=numeric())

my_fun <- function(x) {
  vetr(x=df.tpl)
  TRUE    # do work
}

This way the template is created once on package load and re-used each time your function is called.