How to write an R package

When you see “R package,” you may think "Something to share with other people." But an R package can also be a good way to organize your own work just for yourself. And especially your future self.

R packages give you a consistent structure, so you're more likely to refactor code into functions. And, at least as important: Packages give you a consistent way to document each one of your functions. So, next year, there’s a better chance you’ll remember which parts of your code do what.

System setup

First, you want to set up your system. For easy package development, I suggest making sure you’ve got these libraries installed on your system: devtools, usethis, roxygen2, testthat, knitr, and rmarkdown.

You probably need a little more system setup as well. In Windows, install software called Rtools. That’s actually a software application, not an R package. On a Mac, it is helpful to get Xcode from the App Store.

If you’re not sure whether your system is ready to write packages, devtools has a function called has_devel() that checks if your package development environment is OK. I suggest running that after you’ve got devtools installed.

Sharon Machlis/IDG

Next, you can create a new package in RStudio by going to File > New Project > New Directory and choosing R Package.

You are asked for a package name and whether you want to create a Git repository (which I usually do) and use packrat (which I usually don’t).

At the bottom right panel after creating the package, note that a few files and two directories were created. 

The R subdirectory is where all my R scripts need to live. The man folder is for documentation—specifically, function help files. RStudio also creates a sample hello.R R function.

There are also a couple of important files in the main directory. Explaining NAMESPACE could be an article in itself, but beginners can count on the devtools and usethis packages taking care of that.

DESCRIPTION has some important required metadata about the package, so you need to fill that out. It’s mostly easy things like the package name, author, description, and license. It’s also where package dependencies go.

The usethis package can handle proper package-dependency format for you. For example, if you need the lubridate package for your package, you can load usethis with library(usethis) and then run use_package("lubridate") to add a dependency. You can see how this automatically adds the necessary text to the DESCRIPTION file in the video embedded at the top of this article (or by running similar code on your own system).

Write and document your functions

Next, write any function as usual, and save it as an R script in the R directory. You can name the file anything you want, and you can include one or more functions in the file.

Roxygen offers an easy way to add documentation to a function. Put your cursor anywhere in the function definition and choose the RStudio menu option Code > Insert Roxygen Skeleton.

That gives you some scaffolding to document the function in a way that R understands, such as 

#' Title
#'
#' @param day 
#'
#' @return
#' @export
#'
#' @examples

The Title field is pretty self-explanatory, and you can also add a line for a short description. There is a @param line for each function argument (in this example, the function has one argument called day), @return, and @examples. @param is where you document what data type an argument should be and can give a little description. @return tells what type of object is returned. @examples isn’t required, but you either need to give an example or delete that default @examples.

To turn this scaffolding into an R package help file, run the devtools::document() function.

Now if you look in the man directory, you should have a Markdown help file for your  new function (as well as another one for the default hello function).

Sharon Machlis, IDG

You can build the package using the RStudio Build tab. The Install and Restart option is good for when you’re in the middle of working on your code. When you want to build it for sharing, including getting a source file or binary file, check out the More dropdown in the Build tab.

Run help(package = "yourpackagename") to get the help file for the new function.

If you want to write a package vignette, run the usethis package’s use_vignette() function to set that up. Include the name of the vignette you want as the argument, such as usethis::use_vignette("Intro"). You should see a default vignette, where you can fill in the vignette's title and explainer text.

Hopefully that’s enough to convince you it’s pretty easy to write a basic R package! There’s a lot more you can do, like adding in unit tests with testthat.

If you’d like to learn more about testing, check out my earlier Do More With R post “Test your code with testthat.” And Hadley Wickham has an entire book on writing packages, available free online at r-pkgs.had.co.nz, though it’s a bit out of date now. Jenny Bryan at RStudio is working with Wickham on an update. You can see a bit of the work in progress at r-pkgs.org.