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!