1 Introduction

1.1 What is a package?

An R package is a collection of functions that are bundled together in a way that lets them be easily shared. Usually these functions are designed to work together to complete a specific task such as analysing a particular kind of data. You are probably familiar with many packages already, for example ggplot2 or data.table.

Packages can take various forms during their life cycle. For example the structure you use when writing package code is not exactly the same as what will be installed by somebody else. While you don’t need to know about these forms in detail to create a package it is useful to be aware of them. For more details have a look at the “What is a package?” section of Hadley Wickham’s “R packages” book (http://r-pkgs.had.co.nz/package.html#package).

1.2 Why write a package?

Packages are the best way to distribute code and documentation, and as we are about to find out they are very simple to make. Even if you never intend to share your package it is useful to have a place to store your commonly used functions. You may have heard the advice that if you find yourself reusing code then you should turn it into a function so that you don’t have to keep rewriting it (along with other benefits). The same applies to functions. If you have some functions you reuse in different projects then it probably makes sense to put those in a package. It’s a bit more effort now but it will save you a lot of time in the long run.

Of course often you will want to share your package, either to let other people use your functions or just so people can see what you have done (for example when you have code and data for a publication). If you are thinking about making a software package for public use there are a few things you should consider first:

  • Is your idea new or is there already a package out there that does something similar?
  • If there is does your package improve on it in some way? For example is it easier to use or does it have better performance?
  • If a similar package exists could you help improve it rather than making a new one? Most package developers are open to collaboration and you may be able to achieve more by working together.

1.2.1 Packages for writing packages

This workshop teaches a modern package development workflow that makes use of packages designed to help with writing packages. The two main packages are devtools and usethis. As you might gather from the name devtools contains functions that will help with development tasks such as checking, building and installing packages. The usethis package contains a range of templates and handy functions for making life easier, many of which were originally in devtools1. All of the core parts of package development can be performed in other ways such as typing commands on the command line or clicking buttons in RStudio but we choose to use these packages because they provide a consistent workflow with sensible defaults. Other packages we will use that will be introduced in the appropriate sections are:

  • roxygen2 for function documentation
  • testthat for writing unit tests
  • knitr for building vignettes

  1. This is important to remember when looking at older tutorials or answers to questions on the internet. If devtools::func() doesn’t seem to exist any more try usethis::func() instead↩