Make More Packages!

Initial Setup

In order to build a basic package from scratch, you should only need to rely on four different packages that will aid you in setting everything up, building the correct infrastructure, and documenting and testing your functions.

The packages you need:

• devtools
• usethis
• roxygen2
• testthat

devtools is responsible for the majority of the functions you’ll need to build and maintain a package and usethis handles the initial setup of the project, while roxygen2 helps you document your package, and testthat simplifies unit testing.

Functions

Packages are effectively just a way of housing and distributing functions. If you’re making a package, you’ll need some functions! They don’t need to be wildly complex. They just need to work, and ideally they would be reasonably useful too. However, in the absence of useful functions, we’ve got an example of a funny function instead:

check <- function(x){
  if (x %in% c(69, 0.69)){
    print("Nice!")
  } else {
    print("Not very nice.")
  }
}

This is very simple. All it is doing is checking if an object x matches either the number 69 or 0.69. If it does, then it returns “Nice!”, and if it doesn’t, it returns “Not very nice.”. If you’re just looking to build a basic package as a means of learning how to do so, this is all you need! You can build on this iteratively, as you become more confident with package development, or come up with other useful functions your package should include.

I think it is generally best practice to dedicate a different file to each individual function, though it’s not absolutely necessary. If you choose to, you can store all your functions in one file, and this might be a sensible approach if you’re creating a package that contains all your miscellaneous functions. However, for anything a little more meaty than that, I think the best approach is to split out everything into files for each function. That makes it easier for someone (likely including yourself) to navigate the source code.

Documentation

The next step is to document your package, so anyone using it will have some guidance on what they’re doing and why. Documentation doesn’t need to be complicated, though if the function it is documenting is pretty complex, it should probably go into plenty of detail to help anyone trying to use it. In the nice example, the functions are super simple, so there’s no sense in overdoing the docs either.

You need to add comments at the beginning of your function script which explain what the function does, details any of the required parameters for the function to run, and give some examples of usage. In order for roxygen2 to recognise the comments that need to be turned into documentation, you have to add #’ in front of them.

Below is a basic example of what is needed, corresponding to the nice check function above:

#' Checking whether your R output is really nice
#'
#' @keywords nice
#' @export
#' @examples
#' check(69)
#' 

Having done this, devtools will process the documentation so that it all works as expected:

devtools::document()

You can get a look at your documentation by calling ?function like you normally would. In this case, calling ?check returns the documentation for the nice check function.

Testing

In order to reduce the likelihood that your package becomes a mess of errors, it is important to test it. The best way of doing this is automating your tests, to make everything reproducible, and reduce your own opportunities to do anything stupid!

To set up your tests, the following creates a new script for all tests of the particular function(s) you’re working on.

usethis::use_test("name")

An example of a basic test:

test_that("check returns correct type of response", {
  nice <- check(69)
  expect_type(nice, "character")
})

This test is, as it describes, checking that check() is returning the right type of output when it runs. The test creates an object called nice that contains the output from the check() function, when the input it receives is 69. The test expects the object to be of type character, and if that is so, then it will pass the test. If you want to build further tests for this particular function, you could check that the function correctly recognises whether the input is nice or not, and returns the correct response.

This would look as follows:

test_that("check returns correct positive response", {
  nice <- check(69)
  expect_equal(nice, "Nice!")
})

Once you have set up some tests that you want to use to check your functions, you can run those tests by calling on devtools:

devtools::test()

This will run through each test and check that it returns the expected output. If it doesn’t it will show that it has failed, and show you where exactly that failure has occurred, in order to help you fix it. If it has worked, then you’re all good!

Further Reading

This was a very, very quick run-through on how to create a basic package, just to get started, but if you want to make something that is a little more useful than some dumb function to check if your outputs are nice, then there’s plenty of resources for how to take your packages from basics to CRAN and beyond.

The starting point, as is often the case, is Hadley Wickham. Hadley Wickham and Jenny Bryan’s R Packages is an excellent resource for learning to make some killer packages. And if you’re looking to learn how to build the kind of functions that belong in those killer packages, then Hadley Wickham’s Advanced R will get you most of the way there.