How to Create a Package in R (Example) | RStudio Tutorial for Your Own Library

Creating your own R package is easier than you may think if you haven’t done it before, and can be fun!

This tutorial shows why you should create your own packages and how to create them in RStudio.

The table of contents looks like this:

Note: This article was created in collaboration with Wolf Riepl. Wolf is an expert on topics such as R programming, statistical computing, and data analysis. You may find more information about Wolf and his other tutorials on his profile page.

Why and When Should You Create Your Own R Package?

Before we dive into the How, let’s take a moment to think about the Why and When.

• When you find yourself re-using functions across projects
• When you want to organize code in a central place
• To make use of R’s built-in functionality for documentation (help pages), rather than forcing yourself and others to read scripts and comments to understand your code
• When you want to organize and share data in a central place – mainly useful if this data doesn’t change often, e.g. a specific data structure you need to showcase your code
• Also, it feels cool and may increase your confidence as an R developer!

A First Package in 2 Minutes in RStudio

In RStudio, you can create a simple example package with the basic file structure literally in 2 minutes or less, just with a few clicks. Packages are projects in RStudio, so you can get started by clicking the down button in the top right corner, below the “X” to close RStudio, open the menu, and select the first entry New Project. The New Project Wizard opens.

It is recommended to start in a New Directory. Don’t create a project inside another project. Select R Package. (For packages beyond this minimal example, I recommend selecting R Package using devtools, which has some useful settings, and starts empty.)

RStudio creates a simple package with the basic required file structure. There are two folders: “R” contains the R script (there could be many; here it is just “hello.R”); “man” contains the documentation. The R script contains a simple function hello() that prints the famous words “Hello World” to the console. Luckily, we don’t need to write code like the one in “hello.Rd” manually – there are cool helper functions in the roxygen2 package that do that for us, as we’ll see later.

The DESCRIPTION contains some meta data; it is a plain text file that can be edited manually. The .Rproj file is an RStudio-internal file that manages the project – no need to edit that. .Rbuildignore can be used to specify files that you need during development (e.g. R script templates, or a PDF documentation), but that shall not be part of your published package.

It is recommended to not edit that by hand, but use convenience functions from the usethis package instead. The NAMESPACE can also be handled by helper functions (roxygen2 package); it describes which functions shall be accessible to the end user (“exported” functions).

Next to the Environment, History and Connections pane in RStudio, there is now a new tab Build. We can simply click on Install and Restart to install our package. After a few moments, RStudio starts a new session and loads the package. We can test the function by typing hello() in the console. It should print “Hello World”. Note that the hello() function should not appear in the Global Environment – it should only live in a protected space called package namespace. You can try out ?hello to see the function documentation.

A Second Example: A Package from Scratch, Including Function Documentation

Again we start a new RStudio project by using the drop down menu in the top right corner, below the “X”: New Project – New Directory – R Package using devtools. (You may need to install devtools first:

install.packages("devtools")

This time the package should be empty, i.e. there is an R subfolder, but it does not contain any R script (note that basic files like the .Rproj file, DESCRIPTION and NAMESPACE etc., as described above, will be there.)

library(devtools)    # loads usethis as well
use_r("my_calc.R")

This way we can open a script, which is conveniently saved in the R/ subfolder. We can add a basic function in that script, e.g. like this:

my_calc < function(x, f) {
   f(x)
}

It takes a numeric vector and a function as inputs, then applies the function to the numeric vector. To make the function available, we can click on the Build tab and navigate to More – Load All, or use the keyboard shortcut Ctrl + Shift + L, or type devtools::load_all() in the console. The the function can be applied e.g. like this:

my_calc(1:10, mean)
# 5.5

So far, so good, but the function is not documented yet.

Documenting a Function Using Roxygen Tags

RStudio can help: We place the cursor inside the function, then navigate to the RStudio menu Code and select Insert Roxygen Skeleton. It should look similar to this:

#' Title
#'
#' @param x 
#' @param f 
#'
#' @return Result of calculation
#' @export
#'
#' @examples my_calc(1:10, mean)
 
my_calc < function(x, f) {
f(x)
}

The so-called roxygen tags are marked by an @ symbol. We can fill in information for the parameters (@param) and add a title and a description, e.g. like this:

#' my_calc: Apply function to numeric vector
#'
#' Applies a function of your choice to a numeric vector.
#'
#' @param x A numeric vector for calculation
#' @param f A function to be applied to x
#'
#' @return Result of calculation
#' @export
#'
#' @examples my_calc(1:10, mean)
 
my_calc < function(x, f) {
f(x)
}

The roxygen2 package creates the documentation from this information. This is great, and an improvement to former times, when the separate .Rd file was edited, because now code and documentation are in one place, and we are less likely to forget to update our documentation as our code evolves. roxygen2 can help us, e.g. remind us of undocumented parameters.

To have a look at the help page corresponding to this code, we can navigate to Build – More and select Document, or click Ctrl + Shift + D. It is a good idea to also load the function again, Build – More – Load All or Ctrl + Shift + L. If you don’t see the Document option, you may need to navigate to Tools – Project Options – Build Tools and activate Use devtools functions and Generate documentation with Roxygen. (This should be enabled by default when you start the project using R Package using devtools).

If you want to learn more, have a look at the great R Packages book by Hadley Wickham and Jenny Bryan, which is luckily available online for free (don’t buy the first edition – a lot has happened since), or check out my YouTube playlist here. If you enjoy reading in German, you can find out more here.

In case you want to learn more on the examples of this tutorial, you may also have a look at the following video on the Statistics Globe YouTube channel. The video explains the examples of this page in some more detail:

Have fun creating your own packages!