Build an R package with {usethis}

Ossie, a Cabinet Office cat (via @cabinetofficeuk on Twitter).

tl;dr

• I gave a talk (slides, source) about creating an R package with helper functions from the {usethis} package.
• In the session I created a new package from scratch called {cabinet} (source, website) for identifying the cats that live in the UK Government’s Cabinet Office.

Coffee packaging

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

The focus is on beginners who may never have written a package before.

Click on the slides embedded below and cycle through with your arrow keys, or you can open them fullscreen in a dedicated browser tab. Press the P button your keyboard to see the presenter notes.

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

install.packages("remotes")  # if not yet installed
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.

Environment

Session info

Last rendered: 2023-07-25 19:13:31 BST

R version 4.3.1 (2023-06-16)
Platform: aarch64-apple-darwin20 (64-bit)
Running under: macOS Ventura 13.2.1

Matrix products: default
BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

time zone: Europe/London
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] cabinet_0.0.0.9000

loaded via a namespace (and not attached):
 [1] digest_0.6.33       fastmap_1.1.1       xfun_0.39          
 [4] glue_1.6.2          knitr_1.43.1        htmltools_0.5.5    
 [7] rmarkdown_2.23      cli_3.6.1           compiler_4.3.1     
[10] rstudioapi_0.15.0   tools_4.3.1         xaringanExtra_0.7.0
[13] evaluate_0.21       yaml_2.3.7          crayon_1.5.2       
[16] rlang_1.1.1         jsonlite_1.8.7      htmlwidgets_1.6.2  

Reuse