Closed Captioning Closed captioning available on our YouTube channel

How to write your own R package

InfoWorld | Mar 5, 2019

When you hear “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

Similar
Hi. I’m Sharon Machlis at IDG Communications, here with Do More With R episode 22: Write Your Own R package.
When you hear “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 refactor code into functions. And, maybe even more important, a consistent way to document each one of those functions. So, next year there’s a better chance you’ll remember which parts of your code do what.
Let’s get started.
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’ll probably need a little more system setup as well. On Windows, install software called Rtools. That’s actually a software application, not an R package. You should be able to find it on any CRAN mirror, or Google Rtools. And on a Mac, it will be 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. So do run that after you’ve got devtools installed.
Next, you can create a new package in RStudio by going to File > New Project > New Directory and selecting R package.
I’m then asked for a package name, and whether I want to create a git repository (which I usually do) and use packrat (which I usually don’t).
Let’s take a look at what happens.
If you look at the bottom right panel, you’ll see that a few files and 2 directories were created. We can ignore the .gitignore and .Rbuildignore files for now – one is for my git repo; the other is to list local files that I don’t want in the final package when I build it.
The R subdirectory is where all my R scripts need to live. The man folder is for documentation – specifically, function help files. You see that RStudio generated a sample “hello” R script.
There are also a couple of important files in the main directory. I don’t have enough time to go into NAMESPACE, but devtools and usethis should take care of that for us.
DESCRIPTION has some important required meta data about the package, so we need to fill that out. It’s mostly easy things like the package name, author, description, license. It’s also where package dependencies go. Fortunately, the usethis package takes care of the proper format for you. Say I need the lubridate and dplyr packages for my package. I can run use_package() to add a dependency. First I’ll load my libraries. Then I’ll run use_package()in the console with the DESCRIPTION file open so you can see what happens.
You see that sets up the proper DESCRIPTION package dependency.
Next, I’ll write an R function for my package. More specifically, I’ll use one that I found on Stack Overflow, by Columbia University assistant professor James Curley, to get the most recent date for any day of the week. It answers questions like: “What was the date of the most recent Monday?”
It’s a little hard to know what that “day” input argument should be, though. That’s where my documentation will come in. An easy way to write package documentation is with Roxygen. If I put my cursor anywhere in the function definition and choose the RStudio menu option Code > Insert Roxygen Skeleton
That gives me some scaffolding to document my function in a way that R understands. Title is pretty self explanatory. I can also use a second line for a description. There is a @param line for each function argument. That’s where you document what data type an argument should be, and give a little description. @return says what type of object is returned. @examples isn’t required, but you either need to give an example or delete that default @examples.
To save you having to watch me type all that, I’ll copy it from a file I already prepared.
See I gave an example here
To turn this scaffolding into an R package help file, you run the devtools document() function.
Now if I look in the man directory, I’ve got a Markdown help file for the function (as well as another one for the default hello function).
If you want to solve that NAMESPACE warning, just delete the default NAMESPACE file that RStudio created and run document() again.
Now I can build my 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, those options are in the More dropdown. .
Run help, and there should be a 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
And you’ve got a default vignette, where I can fill in title and text.
Hopefully that’s enough to convince you it’s pretty easy to write a simple basic package. There’s tons more you can do, like adding in unit tests with testthat. Hadley Wickham has an entire book on writing packages, available free online at r-pkgs.had.co.nz.
It’s a bit out of date now. Jenny Bryan at RStudio is working with Hadley on an update. You can see a bit of the work in progress at r-pkgs.org.
That’s it for this episode, thanks for watching! For more R tips, head to the Do More With R page at https go dot infoworld dot com slash more with R, all lowercase except for the R. You can also find the Do More With R playlist on YouTube. Hope to see you next episode!
Popular
Featured videos from IDG.tv