Build an R package with {usethis}

A black cat lounging across a large wooden table.

Ossie, a Cabinet Office cat (via @cabinetofficeuk)

Coffee packaging

I gave a talk at a Cabinet Office Coffee & Coding session about building R packages. The emphasis was on the {usethis} package, which contains lots of package-setup functions that make your life easier.

Click on the slides embedded below and cycle through with your arrow keys, or you can open them fullscreen in a dedicated browser tab.

I made the slides using Yihui Xie’s {xaringan} implementation of remark.js and I used my own {gdstheme} package for the theme (read the blog or see the source on GitHub).

Talk summary

Basically you can make a minimal R package with only:

  • usethis::create_package() to set up the minimal package structure
  • usethis::create_r() to set up a script for your functions
  • devtools::document() to generate minimal documentation from your files

The {usethis} package also helps you set up internal and long-form documentation, testing, version control, a GitHub repository and more. {pkgdown} even generates a website from your documentation to make it more user-friendly.

Cat-egorise

In the session I live-built a package called {cabinet}. You can:

  • look at the package’s source code on GitHub
  • see the package’s website, made with {pkgdown}
  • install the package yourself with remotes::install_github("matt-dray/cabinet")

The package only has one (very important) function, cabinet_cat(), which checks whether a supplied character string matches the name of either of the Cabinet Office’s cats.

Like:

library(cabinet)
cabinet_cat("Ossie")
## Ossie is a good Cabinet Office kitty.
cabinet_cat("Larry")
## Larry isn't a Cabinet Office cat!
cabinet_cat("Garfield")
## You've much to learn about government cats.

Excellent resources

There are some really good resources out there already. I like the following:

  • Hilary Parker’s post to write a package from scratch (beginner)
  • Tomas Westlake’s update to Hilary’s post (beginner)
  • Emil Hvitfeldt’s post, focusing on {usethis} (beginner/intermediate)
  • Karl Broman’s site, a primer for package developement (intermediate)
  • Hadley Wickham’s book (intermediate/advanced)

Tom’s post is probably the best place to start if you want to create a package with {usethis} from scratch as a beginner.