Making Packages in R

Overview

Teaching: 30 min
Exercises: 0 min
Questions
  • How do I collect my code together so I can reuse it and share it?

  • How do I make my own packages?

Objectives
  • Describe the required structure of R packages.

  • Create the required structure of a simple R package.

  • Write documentation comments that can be automatically compiled to R’s native help and documentation format.

Why should you make your own R packages?

Reproducible research!

An R package is the basic unit of reusable code. If you want to reuse code later or want others to be able to use your code, you should put it in a package.

An R package requires four components:

There are other optional components. Go here for much more information.

DESCRIPTION file

Package: Package name
Title: Brief package description
Description: Longer package description
Version: Version number(major.minor.patch)
Author: Name and email of package creator
Maintainer: Name and email of package maintainer (who to contact with issues)
License: Abbreviation for an open source license

The package name can only contain letters and numbers and has to start with a letter.

.R files

Functions don’t all have to be in one file or each in separate files. How you organize them is up to you. Suggestion: organize in a logical manner so that you know which file holds which functions.

Making your first R package

Let’s turn our temperature conversion functions into an R package.

fahrenheit_to_kelvin <- function(temp_F) {
    #Converts Fahrenheit to Kelvin
    temp_K <- ((temp_F - 32) * (5/9)) + 273.15
    temp_K
}
kelvin_to_celsius <- function(temp_K) {
  #Converts Kelvin to Celsius
  temp_C <- temp_K - 273.15
  temp_C
}
fahrenheit_to_celsius <- function(temp_F) {
  #Converts Fahrenheit to Celsius using fahrenheit_to_kelvin() and kelvin_to_celsius()
  temp_K <- fahrenheit_to_kelvin(temp_F)
	temp_C <- kelvin_to_celsius(temp_K)
  temp_C
}

We will use the [devtools][devtools] and [roxygen2][roxygen2] packages, which make creating packages in R relatively simple. Both can be installed from CRAN like this:

install.packages(c("devtools", "roxygen2"))  # installations can be `c`ombined
library("devtools")
library("roxygen2")

Set your working directory, and then use the create function to start making your package. Keep the name simple and unique.

setwd(parentDirectory)
create("tempConvert")

Add our functions to the R directory. Place each function into a separate R script and add documentation like this:

#' Converts Fahrenheit to Kelvin
#'
#' This function converts input temperatures in Fahrenheit to Kelvin.
#' @param temp_F The temperature in Fahrenheit.
#' @return The temperature in Kelvin.
#' @export
#' @examples
#' fahrenheit_to_kelvin(32)

fahrenheit_to_kelvin <- function(temp_F) {
  temp_K <- ((temp_F - 32) * (5/9)) + 273.15
  temp_K
}

The roxygen2 package reads lines that begin with #' as comments to create the documentation for your package. Descriptive tags are preceded with the @ symbol. For example, @param has information about the input parameters for the function. Now, we will use roxygen2 to convert our documentation to the standard R format.

setwd("./tempConvert")
document()

Take a look at the package directory now. The /man directory has a .Rd file for each .R file with properly formatted documentation.

Overall, your package directory should look something like this:

R Package Structure

Now, let’s load the package and take a look at the documentation.

setwd("..")
install("tempConvert")

?fahrenheit_to_kelvin

Notice there is now a tempConvert environment that is the parent environment to the global environment.

search()

Now that our package is loaded, let’s try out some of the functions.

fahrenheit_to_celsius(32)
[1] 0
fahrenheit_to_kelvin(212)
[1] 373.15
kelvin_to_celsius(273.15)
[1] 0

Creating a Package for Distribution

  1. Create some new functions for your tempConvert package to convert from Kelvin to Fahrenheit or from Celsius to Kelvin or Fahrenheit.
  2. Create a package for our analyze function so that it will be easy to load when more data arrives.

Key Points

  • A package is the basic unit of reusability in R.

  • Every package must have a DESCRIPTION file and an R directory containing code. These are created by us.

  • A NAMESPACE file is needed as well, and a man directory containing documentation, but both can be autogenerated.