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:

# remotes::install_github("matt-dray/cabinet)
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.


Session info

## [1] "Last updated 2020-01-02"
## ─ Session info ───────────────────────────────────────────────────────────────
##  setting  value                       
##  version  R version 3.6.1 (2019-07-05)
##  os       macOS Sierra 10.12.6        
##  system   x86_64, darwin15.6.0        
##  ui       X11                         
##  language (EN)                        
##  collate  en_GB.UTF-8                 
##  ctype    en_GB.UTF-8                 
##  tz       Europe/London               
##  date     2020-01-02                  
## 
## ─ Packages ───────────────────────────────────────────────────────────────────
##  package     * version    date       lib source                            
##  assertthat    0.2.1      2019-03-21 [1] CRAN (R 3.6.0)                    
##  blogdown      0.17       2019-11-13 [1] CRAN (R 3.6.0)                    
##  bookdown      0.16       2019-11-22 [1] CRAN (R 3.6.0)                    
##  cabinet     * 0.0.0.9000 2020-01-02 [1] Github (matt-dray/cabinet@ae03e11)
##  cli           2.0.0      2019-12-09 [1] CRAN (R 3.6.1)                    
##  crayon        1.3.4      2017-09-16 [1] CRAN (R 3.6.0)                    
##  digest        0.6.23     2019-11-23 [1] CRAN (R 3.6.0)                    
##  evaluate      0.14       2019-05-28 [1] CRAN (R 3.6.0)                    
##  fansi         0.4.0      2018-10-05 [1] CRAN (R 3.6.0)                    
##  glue          1.3.1      2019-03-12 [1] CRAN (R 3.6.0)                    
##  htmltools     0.4.0      2019-10-04 [1] CRAN (R 3.6.0)                    
##  knitr         1.26       2019-11-12 [1] CRAN (R 3.6.0)                    
##  magrittr      1.5        2014-11-22 [1] CRAN (R 3.6.0)                    
##  Rcpp          1.0.3      2019-11-08 [1] CRAN (R 3.6.0)                    
##  rlang         0.4.2      2019-11-23 [1] CRAN (R 3.6.0)                    
##  rmarkdown     2.0        2019-12-12 [1] CRAN (R 3.6.0)                    
##  sessioninfo   1.1.1      2018-11-05 [1] CRAN (R 3.6.0)                    
##  stringi       1.4.3      2019-03-12 [1] CRAN (R 3.6.0)                    
##  stringr       1.4.0      2019-02-10 [1] CRAN (R 3.6.0)                    
##  withr         2.1.2      2018-03-15 [1] CRAN (R 3.6.0)                    
##  xfun          0.11       2019-11-12 [1] CRAN (R 3.6.0)                    
##  yaml          2.2.0      2018-07-25 [1] CRAN (R 3.6.0)                    
## 
## [1] /Users/matt.dray/Library/R/3.6/library
## [2] /Library/Frameworks/R.framework/Versions/3.6/Resources/library