Checkmate

Intro

As a motivational example, consider you have a function to calculate the faculty of a natural number and the user may choose between using either the stirling approximation or R’s factorial function (which internally uses the gamma function). Thus, you have two arguments, n and method. Argument n must obviously be a positive natural number and method must be either "stirling" or "factorial". Here is a version of all the hoops you need to jump through to ensure that these simple requirements are met:

fact <- function(n, method = "stirling") {
  if (length(n) != 1)
    stop("Argument 'n' must have length 1")
  if (!is.numeric(n))
    stop("Argument 'n' must be numeric")
  if (is.na(n))
    stop("Argument 'n' may not be NA")
  if (is.double(n)) {
    if (is.nan(n))
      stop("Argument 'n' may not be NaN")
    if (is.infinite(n))
      stop("Argument 'n' must be finite")
    if (abs(n - round(n, 0)) > sqrt(.Machine$double.eps))
      stop("Argument 'n' must be an integerish value")
    n <- as.integer(n)
  }
  if (n < 0)
    stop("Argument 'n' must be >= 0")
  if (length(method) != 1)
    stop("Argument 'method' must have length 1")
  if (!is.character(method) || !method %in% c("stirling", "factorial"))
    stop("Argument 'method' must be either 'stirling' or 'factorial'")

  if (method == "factorial")
    factorial(n)
  else
    sqrt(2 * pi * n) * (n / exp(1))^n
}

And for comparison, here is the same function using checkmate:

fact <- function(n, method = "stirling") {
  assertCount(n)
  assertChoice(method, c("stirling", "factorial"))

  if (method == "factorial")
    factorial(n)
  else
    sqrt(2 * pi * n) * (n / exp(1))^n
}

Function overview

All functions come in four flavors, depending on the prefix. If prefixed with assert, an error is thrown if the check fails. Otherwise, TRUE is returned invisibly. The family of functions prefixed with test always return the check result as logical value. Functions starting with check return the error message as a string (or TRUE otherwise) and can be used if you need more control and, e.g., want to grep on the returned error message. The last family of functions is intended to be used with the testthat package. All performed checks are logged into the testthat reported.

In case you miss flexibility

You can use assert to perform multiple checks at once and throw an assertion if all checks fail.

Argument Checks for the Lazy

The following functions allow a special syntax to define argument checks using a special pattern. E.g., qassert(x, "I+") asserts that x is an integer vector with at least one element and no missing values. This provide a completely alternative mini-language (or style) how to perform argument checks. You choose what you like best.

• qassert
• qassertr

checkmate as testthat extension

To extend testthat, use either need to IMPORT, DEPEND or SUGGEST on the checkmate package. If you only SUGGEST checkmate, you need to load the library in you tests/test-all.r file. Here is a minimal example:

library(testthat)
library(checkmate) # for testthat extensions
test_check("checkmate")

Now you are all set and can use more than 30 new expectations in your tests.

test_that("checkmate is a sweet extension for testthat", {
    x = runif(100)
    expect_numeric(x, len = 100, any.missing = FALSE, lower = 0, upper = 1)
})

Speed considerations

In comparison with tediously writing the checks yourself in R (c.f. factorial example at the beginning of the vignette), R is sometimes a tad faster while performing checks on scalars. This seems odd at first, because checkmate is mostly written in C and should be comparably fast. But many of the functions in the base package are not regular functions, but primitives. While primitives jump directly into the C code, checkmate has to employ the considerably slower .Call interface. As a result, checkmate is sometimes slower while checking scalars or small vectors (but you have to invest a some orders of magnitude more time to write these checks yourself).

For larger objects the tide has turned because checkmate avoids many unnecessary intermediate variables. Here is a small unrepresentative benchmark, but also note that this one here has been executed from inside knitr which is often the cause for outliers in the measured execution time. Better try it yourself.

library(ggplot2)
library(microbenchmark)

x = runif(1000)
r = function(x) stopifnot(is.numeric(x) && length(x) == 1000 && all(!is.na(x) & x >= 0 & x <= 1))
cm = function(x) assertNumeric(x, len = 1000, any.missing = FALSE, lower = 0, upper = 1)
mb = microbenchmark(r(x), cm(x))
print(mb)

## Unit: microseconds
##   expr    min      lq     mean   median      uq       max neval
##   r(x) 78.612 106.402 123.7382 127.0025 131.500   206.195   100
##  cm(x) 10.715  12.833 121.4281  17.5925  21.221 10250.385   100

autoplot(mb)