Top 10 tips to make your R package even more awesome

This article is originally published at https://martinctc.github.io/blog/

What this post is about

This post shares top ten tips on how to make your R package even more awesome than it already is. As an R developer, you’ve already put a lot of work into creating and testing your package - so why waste this opportunity to really showcase your work and make it go even further? The tips mentioned in this post can be divided into three main categories:

1. Communicating your package: so others can access your package and try it more easily

2. Wrestling time back from developer chores: so you can spend more time on the important things

3. DevOps best practices: so other fellow R users will feel more confident about using your package, and make it easier for other developers to collaborate or contribute.

This post assumes that you’ve already written an R package, and therefore won’t focus on the coding component of R package development.

Background

Before we begin, shameless plug alert: I’ve written a few tiny R packages. Here are a few of them:

• rwa: you can run Relative Weights Analysis (a.k.a. Key Drivers Analysis) to measure variable importance. This is available on CRAN.

• hkdatasets: contains datasets that relate to Hong Kong, and is used for our own projects at Hong Kong Districts Info. This is also available on CRAN.

• parallaxr: allows you to generate pretty parallax scroll documents with R and Markdown.

• surveytoolbox: this package contains all the ‘convenience’ functions back in the days when I was analysing mostly survey data.

• hkdistrictballs: created for fun, that allows you to generate “country ball” graphics but for the 18 districts of Hong Kong. Makes use of the magick package.

Admittedly, I did not write all these R packages for entirely altruistic reasons. Writing an R package is an exercise that is valuable in itself, as it allows you to put all your most commonly used custom functions into a neat, self-contained package which you can just load at the start of your analysis sessions, instead of copying and pasting snippets of code from GitHub Gists or randomly placed R scripts.

I used to keep a GitHub Gist which contained 1000+ lines of my most used functions, but trust me, you won’t want to do that. Not only does such a maniacal workflow make the likelihood of your future self being able to reproduce your work completely dependent on your organisational or documentation skills, it also represents a potential loss to your colleagues or the R community, as all the work that you have put into writing your custom functions will help nobody else but yourself, as nobody else can access or understand your functions.

However, one big reason why I write all these R packages is because I enjoy the creative process. I believe a significant, but sometimes neglected, part of writing R packages is communicating to your package users on why they should use your package, and how they can use them. Easy to follow examples, reproducible vignettes, documentation that isn’t 100% technical-lingo - all these things help with making an R package easier to use, yet are unrelated with the quality or the implementation of the R code itself. A lot of this is about communication, which is mostly what this post is about (for the code quality aspect, I would recommend resources like Advanced R or R Packages instead).

So here are my top ten recommendations on how to make your R package even more awesome than it currently is. Let’s go!

1. Create a package website with pkgdown

Whilst this tip is quite well-known, it’s place in the top ten is unquestionable. The pkgdown package makes it incredibly easy to create a package website straight from the files that ‘naturally’ exist in your package, such as README.md and DESCRIPTION. This package website will document all the functions in your package, running even all your examples in R scripts (under @examples), and make it incredibly easy for your users to navigate your package and try out its functionalities.

The alternative is to make your users go through the official PDF R package manual - which although is easy enough to generate with devtools::build_manual() - is not the easiest to navigate, does not natively support plot examples, and definitely more likely to put off new R users from using your package.

For an example of the website in action, here is an R package that I’ve recently written for work, which leverages pkgdown to showcase the large number of functions in the package, and to include an “Analyst Guide” to make it easier to explore the package’s features.

The set-up I would recommend is to set up a GitHub Actions that generates the pkgdown website to a separate gh-pages branch every time you push a commit to the main or master branch on GitHub, and set your GitHub Pages to point to gh-pages for hosting.

What this effectively means is that you will a package website that practically “maintains itself”, as the website will update itself as you update your package (like DESCRIPTION or the function documentation) and push the changes onto GitHub. What’s more, this set up is free as it’s hosted on GitHub!

To set all this up, you just need to run:

usethis::use_github_actions("pkgdown")

This line of code will configure a GitHub Actions workflow to build and deploy your pkgdown site whenever you push changes to GitHub. This should be created and saved at .github/workflows/pkgdown.yaml. The only manual step you’ll need to do is to go to Settings in your GitHub repo, go to Options, and scroll down until you see GitHub Pages. For Source, the page site should be set to being built from the root folder of the gh-pages.

Once this is set-up and saved, it should just take a few minutes and you should be able to see your website at https://<YOUR-GITHUB-USERNAME>.github.io/<YOUR-PACKAGE-NAME>. You can also of course use a custom domain if you wish.

If you’d like to customise your website, you may add a _pkgdown.yml file which you can specify things like what to show your navigation bar, Google Analytics tracking code, site theme, social network icons, etc. There are plenty of package sites that are set up this way, so if you’re looking for inspiration you can just take a peek at the _pkgdown.yml file for any pkgdown sites that use this set-up (you can start with the actual pkgdown pkgdown site). The five R packages mentioned at the beginning of this post also uses this set-up.

2. Automated R CMD checks with GitHub Actions

Chances are, if you’ve already written a package, you’ll at least have run a R CMD check, or ran devtools::check() to test for errors in your R package.¹ The R CMD check automatically checks your code for common problems, e.g.:

• whether the package can be successfully installed on different operating systems
• whether there are syntax errors in the script
• whether there are undocumented arguments in your functions, etc.

Now, you can either run this manually on your local machine, OR, you can configure GitHub Actions to run this check automatically whenever push a commit or merge a change to your main/master branch. The bonus with the latter, of course, is that you get a nice fancy badge that you can place in your README.md, like this:

The only thing you have to make sure is that your package passes these checks before you add the badge for the first time, otherwise you’ll get an alarming failing badge on your repo!

The easiest way to add GitHub Actions, again, is to use the usethis package:

usethis::use_github_actions()

Similar to tip #1, this adds a yaml file under .github/workflows called R-CMD-check.yaml. To add a badge, you can then run:

usethis::use_github_actions_badge()

You can check the usethis documentation on the specific details of this function.

Adding automated checks embodies the principles of CI/CD (continuous integration, continuous delivery) coding practice, which prefers regular and frequent code check-ins to version control repositories. Automated checks is a form of continuous testing, which is a condition for CI/CD. As an outcome, the argument goes that this leads to better collaboration due to greater transparency, and higher software quality due to continuous testing. Errors can be identified sooner, plus a ‘passing’ badge helps assure potential users of your package that you have done your homework to make sure that your package is passing all the basic checks.

3. CodeFactor

Speaking of badges, here’s another that you can add to your GitHub!

CodeFactor performs an automated review of your R code for code quality, and returns a grade (just like in school!). As you’ll see, it’s possible to get an A+, but you can also get a few of the following grades:

Instead of checking whether your functions fail or whether your package can be successfully installed, CodeFactor checks for things like:

• Whether you use library() within a function - which is not recommended
• Whether you have arguments which have been defined but never used in function
• Whether you adopt sub-ideal practices like 1:100 (instead of seq_along()) or sapply() (due to return type uncertainty. )
• Using options() directly inside a function instead of withr::with_options()

This is a great way to review your code automatically, instead of badgering a friend who happens to be an experienced R developer to review your package for you.

And speaking of badgers, I highly recommend checking out the badger package, which allows you to generate badges in your README. There are so many other badges that you can add to your package README (e.g. code coverage, number of downloads), but I won’t detail them here as this would turn into a post about badges.

4. Use conventional commits

Write every commit message as if it's part of a PR to your future employer.
- Confucius

— 🐢 Florian (@fistful_of_bass) December 15, 2020

== Need to Learn tidyquant? =====================================================
Business Science offers a 1-hour course - Learning Lab #9: Performance Analysis & Portfolio Optimization with tidyquant!
</> Learn more at: https://university.business-science.io/p/learning-labs-pro </>

.onAttach <- function(libname, pkgname) {
  message <- c("\n Thank you for using the {wpa} R package!",
               "\n \n Our analysts have taken every care to ensure that this package runs smoothly and bug-free.",
               "\n However, if you do happen to encounter any, please email [email protected] to report any issues.",
               "\n \n Happy coding!")
  packageStartupMessage(message)
}

citation('data.table')