![A black cat lounging across a large wooden table.](/post/2019-11-01-usethis-for-easeir-r-package-building_files/ossie.jpeg)
Ossie, a Cabinet Office cat (via @cabinetofficeuk)
tl;dr
- I gave a talk about creating an R package with helper functions from the {usethis} package
- In the session I created a new package from scratch called {cabinet} for identifying the cats that live in the UK Government’s Cabinet Office
- See the slides in a dedicated window or view their source
- See the {cabinet} package source and its website
- Jump to a list of other materials
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 structureusethis::create_r()
to set up a script for your functionsdevtools::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-06-07"
## ─ Session info ───────────────────────────────────────────────────────────────
## setting value
## version R version 4.0.0 (2020-04-24)
## os macOS Mojave 10.14.6
## system x86_64, darwin17.0
## ui X11
## language (EN)
## collate en_GB.UTF-8
## ctype en_GB.UTF-8
## tz Europe/London
## date 2020-06-07
##
## ─ Packages ───────────────────────────────────────────────────────────────────
## package * version date lib source
## assertthat 0.2.1 2019-03-21 [1] CRAN (R 4.0.0)
## blogdown 0.19 2020-05-22 [1] CRAN (R 4.0.0)
## bookdown 0.19 2020-05-15 [1] CRAN (R 4.0.0)
## cabinet * 0.0.0.9000 2020-06-07 [1] Github (matt-dray/cabinet@441b227)
## cli 2.0.2 2020-02-28 [1] CRAN (R 4.0.0)
## crayon 1.3.4 2017-09-16 [1] CRAN (R 4.0.0)
## digest 0.6.25 2020-02-23 [1] CRAN (R 4.0.0)
## evaluate 0.14 2019-05-28 [1] CRAN (R 4.0.0)
## fansi 0.4.1 2020-01-08 [1] CRAN (R 4.0.0)
## glue 1.4.1 2020-05-13 [1] CRAN (R 4.0.0)
## htmltools 0.4.0 2019-10-04 [1] CRAN (R 4.0.0)
## knitr 1.28 2020-02-06 [1] CRAN (R 4.0.0)
## magrittr 1.5 2014-11-22 [1] CRAN (R 4.0.0)
## Rcpp 1.0.4.6 2020-04-09 [1] CRAN (R 4.0.0)
## rlang 0.4.6 2020-05-02 [1] CRAN (R 4.0.0)
## rmarkdown 2.1 2020-01-20 [1] CRAN (R 4.0.0)
## sessioninfo 1.1.1 2018-11-05 [1] CRAN (R 4.0.0)
## stringi 1.4.6 2020-02-17 [1] CRAN (R 4.0.0)
## stringr 1.4.0 2019-02-10 [1] CRAN (R 4.0.0)
## withr 2.2.0 2020-04-20 [1] CRAN (R 4.0.0)
## xfun 0.14 2020-05-20 [1] CRAN (R 4.0.0)
## yaml 2.2.1 2020-02-01 [1] CRAN (R 4.0.0)
##
## [1] /Library/Frameworks/R.framework/Versions/4.0/Resources/library