In RUnit, each test is a function that takes no inputs. Each test compares the actual result of running some code (in this case, calling hypotenuse) to an expected value, using one of the check* functions contained in the package. In this next example we use checkEqualsNumeric, since we are comparing two numbers:

library(RUnit)
test.hypotenuse.3_4.returns_5 <- function()
{
  expected <- 5
  actual <- hypotenuse(3, 4)
  checkEqualsNumeric(expected, actual)
}

Sometimes we want to make sure that a function fails in the correct way. For example, we can test that hypotenuse fails if no inputs are provided:

test.hypotenuse.no_inputs.fails <- function()
{
  checkException(hypotenuse())
}

Many algorithms suffer loss of precision when given very small or very large inputs, so it is good practice to test those conditions. The smallest and largest positive numeric values that R can represent are given by the double.xmin and double.xmax components of the built-in .Machine constant:

.Machine$double.xmin

## [1] 2.225e-308

.Machine$double.xmax

## [1] 1.798e+308

For the small and large tests, we pick values close to these limits. In the case of small numbers, we need to manually tighten the tolerance of the test. By default, checkEqualsNumeric considers its test passed when the actual result is within about 1e-8 of the expected result (it uses absolute, not relative differences). We set this value to be a few orders of magnitude smaller than the inputs to make sure that the test fails appropriately:

test.hypotenuse.very_small_inputs.returns_small_positive <- function()
{
  expected <- sqrt(2) * 1e-300
  actual <- hypotenuse(1e-300, 1e-300)
  checkEqualsNumeric(expected, actual, tolerance = 1e-305)
}
test.hypotenuse.very_large_inputs.returns_large_finite <- function()
{
  expected <- sqrt(2) * 1e300
  actual <- hypotenuse(1e300, 1e300)
  checkEqualsNumeric(expected, actual)
}

There are countless more possible tests; for example, what happens if we pass missing values or NULL or infinite values or character values or vectors or matrices or data frames, or we expect an answer in non-Euclidean space? Thorough testing works your imagination hard. Unleash your inner two-year-old and contemplate breaking stuff. On this occasion, we’ll stop here. Save all your tests into a file; RUnit defaults to looking for files with names that begin with “runit” and have a .R file extension. These tests can be found in the tests directory of the learningr package.

Now that we have some tests, we need to run them. This is a two-step process.

First, we define a test suite with defineTestSuite. This function takes a string for a name (used in its output), and a path to the directory where your tests are contained. If you’ve named your test functions or files in a nonstandard way, you can provide a pattern to identify them:

test_dir <- system.file("tests", package = "learningr")
suite <- defineTestSuite("hypotenuse suite", test_dir)

The second step is to run them with runTestSuite (additional line breaks have been added here as needed, to fit the formatting of the book):

runTestSuite(suite)

##
##
## Executing test function test.hypotenuse.3_4.returns_5  ...
## done successfully.
##
##
##
## Executing test function test.hypotenuse.no_inputs.fails  ...
## done successfully.
##
##
##
## Executing test function
## test.hypotenuse.very_large_inputs.returns_large_finite  ...
## Timing stopped at: 0 0 0 done successfully.
##
##
##
## Executing test function
## test.hypotenuse.very_small_inputs.returns_small_positive  ...
## Timing stopped at: 0 0 0 done successfully.

## Number of test functions: 4
## Number of errors: 0
## Number of failures: 2

This runs each test that it finds and displays whether it passed, failed, or threw an error. In this case, you can see that the small and large input tests failed. So what went wrong?

The problem with our algorithm is that we have to square each input. Squaring big numbers makes them larger than the largest (double-precision) number that R can represent, so the result comes back as infinity. Squaring very small numbers makes them even smaller, so that R thinks they are zero. (There are better algorithms that avoid this problem; see the ?hypotenuse help page for links to a discussion of better algorithms for real-world use.)

RUnit has no built-in checkWarning function to test for warnings. To test that a warning has been thrown, we need a trick: we set the warn option to 2 so that warnings become errors, and then restore it to its original value when the test function exits using on.exit. Recall that code inside on.exit is run when a function exits, regardless of whether it completed successfully or an error was thrown:

test.log.minus1.throws_warning <- function()
{
  old_ops <- options(warn = 2) #warnings become errors
  on.exit(old_ops)             #restore old behavior
  checkException(log(-1))
}

Though testthat has a different syntax, the principles are almost the same. The main difference is that rather than each test being a function, it is a call to one of the expect_* functions in the package. For example, expect_equal is the equivalent of RUnit’s checkEqualsNumeric. The translated tests (also available in the tests directory of the learningr package) look like this:

library(testthat)
expect_equal(hypotenuse(3, 4), 5)
expect_error(hypotenuse())
expect_equal(hypotenuse(1e-300, 1e-300), sqrt(2) * 1e-300, tol = 1e-305)
expect_equal(hypotenuse(1e300, 1e300), sqrt(2) * 1e300)

To run this, we call test_file with the name of the file containing tests, or test_dir with the name of the directory containing the files containing the tests. Since we have only one file, we’ll use test_file:

filename <- system.file(
  "tests",
  "testthat_hypotenuse_tests.R",
  package = "learningr"
)
test_file(filename)

## ..12
##
## 1. Failure: (unknown) -----------------------------------------------------
## learningr::hypotenuse(1e-300, 1e-300) not equal to sqrt(2) * 1e-300
## Mean relative difference: 1
##
## 2. Failure: (unknown) -----------------------------------------------------
## learningr::hypotenuse(1e+300, 1e+300) not equal to sqrt(2) * 1e+300
## Mean relative difference: Inf

There are two variations for running the tests: test_that tests code that you type at the command line (or, more likely, copy and paste), and test_package runs all tests from a package, making it easier to test nonexported functions.

Unlike with RUnit, warnings can be tested for directly via expect_warning:

expect_warning(log(-1))

Whenever you type a line of code at the command line, R has to turn that string into something it understands. Here’s a simple call to the arctangent function:

atan(c(-Inf, -1, 0, 1, Inf))

## [1] -1.5708 -0.7854  0.0000  0.7854  1.5708

We can see what happens to this line of code in slow motion by using the quote function. quote takes a function call like the one in the preceding line, and returns an object of class call, which represents an “unevaluated function call”:

(quoted_r_code <- quote(atan(c(-Inf, -1, 0, 1, Inf))))

## atan(c(-Inf, -1, 0, 1, Inf))

class(quoted_r_code)

## [1] "call"

The next step that R takes is to evaluate that call. We can mimic this step using the eval function:

eval(quoted_r_code)

## [1] -1.5708 -0.7854  0.0000  0.7854  1.5708

The general case, then, is that to execute code that you type, R does something like eval(quote(the stuff you typed at the command line)).

To understand the call type a little better, let’s convert it to a list:

as.list(quoted_r_code)

## [[1]]
## atan
##
## [[2]]
## c(-Inf, -1, 0, 1, Inf)

The first element is the function that was called, and any additional elements contain the arguments that were passed to it.

One important thing to remember is that in R, more or less everything is a function. That’s a slight exaggeration, but operators like +; language constructs like switch, if, and for; and assignment and indexing are functions:

vapply(
  list(`+`, `if`, `for`, `<-`, `[`, `[[`),
  is.function,
  logical(1)
)

## [1] TRUE TRUE TRUE TRUE TRUE TRUE

The upshot of this is that anything that you type at the command line is really a function call, which is why this input is turned into call objects.

All of this was a long-winded way of saying that sometimes we want to take text that is R code and get R to execute it. In fact, we’ve already seen two functions that do exactly that for special cases: assign takes a string and assigns a value to a variable with that name, and its reverse, get, retrieves a variable based upon a string input.

Rather than just limiting ourselves to assigning and retrieving variables, we might occasionally decide that we want to take an arbitrary string of R code and execute it. You may have noticed that when we use the quote function, we just type the R code directly into it, without wrapping it in—ahem—quotes. If our input is a string (as in a character vector of length one), then we have a slightly different problem: we must “parse” the string. Naturally, this is done with the parse function.

parse returns an expression object rather than a call. Before you get frightened, note that an expression is basically just a list of calls.

When we call parse in this way, we must explicitly name the text argument:

parsed_r_code <- parse(text = "atan(c(-Inf, -1, 0, 1, Inf))")
class(parsed_r_code)

## [1] "expression"

Just as with the quoted R code, we use eval to evaluate it:

eval(parsed_r_code)

## [1] -1.5708 -0.7854  0.0000  0.7854  1.5708

There are a few occasions when we want to solve the opposite problem: turning code into a string. The most common reason for this is to use the name of a variable that was passed into a function. The base histogram-drawing function, hist, includes a default title that tells you the name of the data variable:

random_numbers <- rt(1000, 2)
hist(random_numbers)

To replicate this technique ourselves, we need two functions: substitute and deparse. substitute takes some code and returns a language object. That usually means a call, like we would have created using quote, but occasionally it’s a name object, which is a special type that holds variable names. (Don’t worry about the details, this section is called “Magic” for a reason.)

The next step is to turn this language object into a string. This is called deparsing. The technique can be very useful for providing helpful error messages when you check user inputs to functions. Let’s see the deparse-substitute combination in action:

divider <- function(numerator, denominator)
{
  if(denominator == 0)
  {
    denominator_name <- deparse(substitute(denominator))
    warning("The denominator, ", sQuote(denominator_name), ", is zero.")
  }
  numerator / denominator
}
top <- 3
bottom <- 0
divider(top, bottom)

## Warning: The denominator, 'bottom', is zero.

## [1] Inf

substitute has one more trick up its sleeve when used in conjunction with eval. eval lets you pass it an environment or a data frame, so you can tell R where to look to evaluate the expression.

As a simple example, we can use this trick to retrieve the levels of the Gender column of the hafu dataset:

eval(substitute(levels(Gender)), hafu)

## [1] "F" "M"

This is exactly how the with function works:

with(hafu, levels(Gender))

## [1] "F" "M"

In fact, many functions use the technique: subset uses it in several places, and lattice plots use the trick to parse their formulae. There are a few variations on the trick described in Thomas Lumley’s “Standard nonstandard evaluation rules.”

Sometimes we want a function to behave differently depending upon the type of input. A classic example is the print function, which gives a different style of output for different variables. S3 lets us call a different function for printing different kinds of variables, without having to remember the names of each one.

The print function is very simple—just one line, in fact:

print

## function (x, ...)
## UseMethod("print")
## <bytecode: 0x0000000018fad228>
## <environment: namespace:base>

It takes an input, x (and ...; the ellipsis is necessary), and calls UseMethod("print"). UseMethod checks the class of x and looks for another function named print.class_of_x, calling it if it is found. If it can’t find a function of that name, it tries to call print.default.

For example, if we want to print a Date variable, then we can just type:

today <- Sys.Date()
print(today)

## [1] "2013-07-17"

print calls the Date-specific function print.Date:

print.Date

## function (x, max = NULL, ...)
## {
##     if (is.null(max))
##         max <- getOption("max.print", 9999L)
##     if (max < length(x)) {
##         print(format(x[seq_len(max)]), max = max, ...)
##         cat(" [ reached getOption("max.print") -- omitted",
##             length(x) - max, "entries ]
")
##     }
##     else print(format(x), max = max, ...)
##     invisible(x)
## }
## <bytecode: 0x0000000006dc19f0>
## <environment: namespace:base>

Inside print.Date, our date is converted to a character vector (via format), and then print is called again. There is no print.character function, so this time UseMethod delegates to print.default, at which point our date string appears in the console.

You can see all the available methods for a function with the methods function. The print function has over 100 methods, so here we just show the first few:

head(methods(print))

## [1] "print.abbrev"      "print.acf"         "print.AES"
## [4] "print.anova"       "print.Anova"       "print.anova.loglm"

methods(mean)

## [1] mean.Date     mean.default  mean.difftime mean.POSIXct  mean.POSIXlt
## [6] mean.times*   mean.yearmon* mean.yearqtr* mean.zoo*
##
##    Non-visible functions are asterisked

Reference classes are closer to a classical OOP system than S3 and S4, and should be moderately intuitive to anyone who has used classes in C++ or its derivatives.

The setRefClass function creates the template for a class. In R terminology, it’s called a class generator. In some other languages, it would be called a class factory.

Let’s try to build a class for a 2D point as an example. A call to setRefClass looks like this:

my_class_generator <- setRefClass(
  "MyClass",
  fields = list(
    #data variables are defined here
  ),
  methods = list(
    #functions to operate on that data go here
    initialize = function(...)
    {
    #initialize is a special function called
    #when an object is created.
    }
  )
)

Our class needs x and y coordinates to store its location, and we want these to be numeric.

In the following example, we declare x and y to be numeric:

point_generator <- setRefClass(
  "point",
  fields = list(
    x = "numeric",
    y = "numeric"
  ),
  methods = list(
    #TODO
  )
)

This means that if we try to assign them values of another type, an error will be thrown. Purposely restricting user input may sound counterintuitive, but it can save you from having more obscure bugs further down the line.

Next we need to add an initialize method. This is called every time we create a point object. This method takes x and y input numbers and assigns them to our x and y fields. There are three interesting things to note about it:

With the initialize method, our class generator now looks like this:

point_generator <- setRefClass(
  "point",
  fields = list(
    x = "numeric",
    y = "numeric"
  ),
  methods = list(
    initialize = function(x = NA_real_, y = NA_real_)
    {
      "Assign x and y upon object creation."
      x <<- x
      y <<- y
    }
  )
)

Our point class generator is finished, so we can now create a point object. Every generator has a new method for this purpose. The new method calls initialize (if it exists) as part of the object creation process:

(a_point <- point_generator$new(5, 3))

## Reference class object of class "point"
## Field "x":
## [1] 5
## Field "y":
## [1] 3

Generators also have a help method that returns the help string for a method that you specify:

point_generator$help("initialize")

## Call:
## $initialize(x = , y = )
##
##
## Assign x and y upon object creation.

You can provide a more traditional interface to object-oriented code by wrapping class methods inside other functions. This can be useful if you want to distribute your code to other people without having to teach them about OOP:

create_point <- function(x, y)
{
  point_generator$new(x, y)
}

At the moment, the class isn’t very interesting because it doesn’t do anything. Let’s redefine it with some more methods:

point_generator <- setRefClass(
  "point",
  fields  = list(
    x = "numeric",
    y = "numeric"
  ),
  methods = list(
    initialize         = function(x = NA_real_, y = NA_real_)
    {
      "Assign x and y upon object creation."
      x <<- x
      y <<- y
    },
    distanceFromOrigin = function()
    {
      "Euclidean distance from the origin"
      sqrt(x ^ 2 + y ^ 2)
    },
    add                = function(point)
    {
      "Add another point to this point"
      x <<- x + point$x
      y <<- y + point$y
      .self
    }
  )
)

These additional methods belong to point objects, unlike new and help, which belong to the class generator (in OOP terminology, new and help are static methods):

a_point <- create_point(3, 4)
a_point$distanceFromOrigin()

## [1] 5

another_point <- create_point(4, 2)
(a_point$add(another_point))

## Reference class object of class "point"
## Field "x":
## [1] 7
## Field "y":
## [1] 6

As well as new and help, generator classes have a few more methods. fields and methods respectively list the fields and methods of that class, and lock makes a field read-only:

point_generator$fields()

##         x         y
## "numeric" "numeric"

point_generator$methods()

##  [1] "add"                "callSuper"          "copy"
##  [4] "distanceFromOrigin" "export"             "field"
##  [7] "getClass"           "getRefClass"        "import"
## [10] "initFields"         "initialize"         "show"
## [13] "trace"              "untrace"            "usingMethods"

Some other methods can be called either from the generator object or from instance objects. show prints the object, trace and untrace let you use the trace function on a method, export converts the object to another class type, and copy makes a copy.

Reference classes support inheritance, where classes can have children to extend their functionality. For example, we can create a three-dimensional point class that contains our original point class, but includes an extra z coordinate.

A class inherits fields and methods from another class by using the contains argument:

three_d_point_generator <- setRefClass(
  "three_d_point",
  fields   = list(
    z = "numeric"
  ),
  contains = "point",         #this line lets us inherit
  methods  = list(
    initialize = function(x, y, z)
    {
      "Assign x and y upon object creation."
      x <<- x
      y <<- y
      z <<- z
    }
  )
)
a_three_d_point <- three_d_point_generator$new(3, 4, 5)

At the moment, our distanceFromOrigin function is wrong, since it doesn’t take the z dimension into account:

a_three_d_point$distanceFromOrigin() #wrong!

## [1] 5

We need to override it in order for it to make sense in the new class. This is done by adding a method with the same name to the class generator:

three_d_point_generator <- setRefClass(
  "three_d_point",
  fields   = list(
    z = "numeric"
  ),
  contains = "point",
  methods  = list(
    initialize = function(x, y, z)
    {
      "Assign x and y upon object creation."
      x <<- x
      y <<- y
      z <<- z
    },
    distanceFromOrigin = function()
    {
      "Euclidean distance from the origin"
      sqrt(x ^ 2 + y ^ 2 + z ^ 2)
    }
  )
)

To use the updated definition, we need to recreate our point:

a_three_d_point <- three_d_point_generator$new(3, 4, 5)
a_three_d_point$distanceFromOrigin()

## [1] 7.071

Sometimes we want to use methods from the parent class (a.k.a. superclass). The callSuper method does exactly this, so we could have written our 3D distanceFromOrigin (inefficiently) like this:

distanceFromOrigin = function()
{
  "Euclidean distance from the origin"
  two_d_distance <- callSuper()
  sqrt(two_d_distance ^ 2 + z ^ 2)
}

OOP is a big topic, and even limited to reference classes, it’s worth a book in itself. John Chambers (creator of the S language, R Core member, and author of the reference classes code) is currently writing a book on OOP in R. Until that materializes, the ?ReferenceClasses help page is currently the definitive reference-class reference.