In tkonopka/consonance: Consonance Testing

Overview {#overview}

This section gives a preview of the consonance framework. We will need the following packages.

library(consonance)
library(checkmate)
library(magrittr)

In addition to consonance, we load checkmate as that provides many fast functions designed for checking arguments, which we can use in a consonance suite. The magrittr package provides the piping operator %>%.

For a practical demonstration, let's create a consonance test suite that requires data vectors to be numeric.

suite_1 <- consonance_suite() +
  consonance_assert("numeric vector", assert_numeric)

This definition is a sum of two components. The first is an empty consonance suite created by consonace_suite(). The plus sign and function consonance_assert() augment the suite with a new assertion. Its description, "numeric vector", is meant to distinguish this component from any additional ones. The implementation of the assertion is provided by assert_numeric from the checkmate package.

To use the object, we invoke the validate function. Here are some examples.

# Testing numeric vectors results in quiet execution
validate(c(1, 2), suite_1)
validate(c(1, 2, NA), suite_1)
# Testing a non-numeric vector results in messages
validate(c("a", "b"), suite_1)

All examples provide validate with a data vector and our test suite. The first two lines succeed quietly because their data vectors are composed of numbers. The last line signals that the data is not in agreement, i.e. not in consonance, with the criteria in the suite.

Of course, testing that a vector is numeric can be achieved with one line of code in base R. The consonance suite framework becomes more useful when we combine more conditions. For example, we can check data type and names.

suite_2 <-
  consonance_assert("numeric vec wo NAs", assert_numeric, any.missing=FALSE) +
  consonance_assert("named", assert_named)

The first consonance_assert definition here includes an additional argument. This is passed to the assertion function, i.e. to assert_numeric from the checkmate package. Here, it imposes a constraint that data should not include any missing values.

We can try the suite on some data, this time using the data pipe (%>%) syntax.

# Numeric vectors with names result in quiet execution
c(a=1, a=2) %>% validate(suite_2)
# Numeric vectors without names result in error messages
c(1, 2) %>% validate(suite_2)
# Vectors with missing data result in error messages
c(a=1, b=NA) %>% validate(suite_2)

In each case, the lines containing 'consonance error:' indicate which of the criteria generated the errors. It is worth mentioning that other frameworks (assertr, validate) can provide more granular information, e.g. list the individual elements of the input data triggered failures. However, consonance takes the view that consonance tests should succeed in most situations, and the limited book-keeping helps to make consonance fast (see vignette on performance). At the same time, in situations where the data causes errors, the above messages focus manual debugging while keeping the output succinct.

The convenience of the consonance workflow becomes apparent when performing long series of tests, testing more complex objects like data frames or models, logging output, and toggling strictness of individual requirements.

tkonopka/consonance documentation built on Oct. 9, 2020, 2:09 p.m.