An R package is the basic unit of reusable code. You need to master the art of making R packages if you want others to use your code. At their heart, packages are quite simple and only have two essential components:
DESCRIPTIONfile that describes the package, what it does, who's allowed to use it (the license) and who to contact if you need help
Rdirectory that contains your R code.
If you want to distribute R code to someone else, there's no excuse not to use a simple package: it's a standard structure, and you can easily expand on it by adding documentation, data and tests.
This document explains how to get started, with a description of package structure, tips for naming your package, and more details about the
The most accurate resource for up-to-date details on package development is always the official writing R extensions guide. However, it's rather hard to read and follow if you're not already familiar with the basics of packages. It's also exhaustive, covering every possible package component, rather than focussing on the most common and useful components as this package does. Once you are familiar with the content here, you should find R extensions a little easier to read.
As mentioned above, there are only two elements that you must have:
DESCRIPTIONfile, which provides metadata about the package, and is described in the following section.
R/directory where your R code lives (in
If you don't want to create this by hand, you can use
devtools::create which initialises the directory structure and includes a few other files that most packages have.
Almost all R packages also have:
man/directory where your [[function documentation|documenting-functions]]. In the style of package development described in this book, you'll never personally touch the files in this directory. Instead, they will be automatically generated from comments in your source code using the
After the code and function documentation, the most important optional components of an R package help your users learn how to use your package. The following files and directories are described in more detail in [[documenting packages]].
NEWSfile describes the changes in each version of the package. Using the standard R format will allow you to take advantage of many automated tools for displaying changes between versions.
READMEfile gives a general overview of your package, including why it's important. This text should be included in any package announcement, to help others understand why they might want to use your package.
inst/CITATIONfile describes how to cite your package. If you have published a peer reviewed article which you'd like people to cite when they use your software, this is the place to put it.
demo/directory contains larger scale demos, that use many features of the package.
inst/doc/directory is used for larger scale documentation, like vignettes, long-form documents which show how to combine multiple parts of your package to solve problems.
Other optional files and directories are part of good development practice:
NAMESPACEfile describes which functions are part of the formal API of the package and are available for others to use. See [[namespaces]] for more details.
inst/tests/contains [[unit tests|testing]] which ensure that your package is operating as designed. In this book, we'll focus on the
testthatpackage for writing tests.
.rdatafiles, used to include sample datasets (or other R objects) with your package.
There are other directories that we won't cover. You might see these in other packages you download from CRAN, but these topics are outside the scope of this book.
src/: C, C++ and fortran source code
exec/: executable scripts
po/: translation files
When creating a package the first thing (and sometimes the most difficult) is to come up with a name for it. There's only one formal requirement:
- The package name can only consist of letters and numbers, and must start with a letter.
But I have a few additional recommendations:
Make the package name googleable, so that if you google the name you can easily find it. This makes it easy for potential users to find your package, and it's also useful for you, because it makes it easier to find out who is using it.
Avoid using both upper and lower case letters: they make the package name hard to type and hard to remember. For example, I can never remember if it's
Some strategies I've used in the past to create packages names:
lvplot(letter value plots),
meifly(models explored interactively)
Add an extra R:
helpr(alternative documentation view)
Find a name evocative of the problem and modify it so that it's unique:
plyr(generalisation of apply tools),
lubridate(makes dates and times easier),
classifly(high-dimensional views of classification)
Once you have a name, create a directory with that name, and inside that create an
R subdirectory and a
DESCRIPTION file (note that there's no extension, and the file name must be all upper case).
R/ directory contains all your R code, so copy in any existing code.
It's up to you how you arrange your functions into files. There are two possible extremes: all functions in one file, and each function in its own file. I think these are both too extreme, and I suggest grouping related functions into a single file. My rule of thumb is that if I can't remember which file a function lives in, I probably need to split them up into more files: having only one function in a file is perfectly reasonable, particularly if the functions are large or have a lot of documentation. As you'll see in the next chapter, often the code for the function is small compared to its documentation (it's much easier to do something than it is to explain to someone else how to do it.)
The next step is to create a
DESCRIPTION file that defines package metadata.
A minimal description file (this one is taken from an early version of plyr) looks like this:
Package: plyr Title: Tools for splitting, applying and combining data Description: Version: 0.1 Author: Hadley Wickham <email@example.com> Maintainer: Hadley Wickham <firstname.lastname@example.org> License: MIT
This is the critical subset of package metadata: what it's called (
Package), what it does (
Description), who's allowed to use and distribute it (
License), who wrote it (
Author), and who to contact if you have problems (
Maintainer). Here I've left the
Description blank to illustrate that if you haven't decided what the correct value is yet, it's ok to leave it blank.
Again, the six required elements are:
Package: name of the package. Should be the same as the directory name.
Title: a one line description of the package.
Description: a more detailed paragraph-length description.
Version: the version number, which should be of the the form
?package_versionfor more details on the package version formats. I recommended following the principles of semantic versioning.
Maintainer: a single name and email address for the person responsible for package maintenance.
License: a standard abbreviation for an open source license, like
BSD. A complete list of possibilities can be found by running
file.show(file.path(R.home(), "share/licenses/license.db")). If you are using a non-standard license, put
file LICENSEand then include the full text of the license in a
A more complete
DESCRIPTION (this one from a more recent version of
plyr) looks like this:
Package: plyr Title: Tools for splitting, applying and combining data Description: plyr is a set of tools that solves a common set of problems: you need to break a big problem down into manageable pieces, operate on each pieces and then put all the pieces back together. For example, you might want to fit a model to each spatial location or time point in your study, summarise data by panels or collapse high-dimensional arrays to simpler summary statistics. The development of plyr has been generously supported by BD (Becton Dickinson). URL: http://had.co.nz/plyr Version: 1.3 Maintainer: Hadley Wickham <email@example.com> Author: Hadley Wickham <firstname.lastname@example.org> Depends: R (>= 2.11.0) Suggests: abind, testthat (>= 0.2), tcltk, foreach Imports: itertools, iterators License: MIT
DESCRIPTION includes other components that are optional, but still important:
Enhancesdescribe which packages this package needs. They are described in more detail in [[namespaces]].
URL: a url to the package website. Multiple urls can be separated with a comma or whitespace.
Author, you can
Authors@R, which takes a vector of
person() elements. Each person object specifies the name of the person and their role in creating the package:
aut: full authors who have contributed much to the package
ctb: people who have made smaller contributions, like patches.
cre: the package creator/maintainer, the person you should bother if you have problems
Other roles are listed in the help for person. Using
Authors@R is useful when your package gets bigger and you have multiple contributors that you want to acknowledge appropriately. The equivalent
Authors@R syntax for plyr would be:
Authors@R: person("Hadley", "Wickham", role = c("aut", "cre"))
There are a number of other less commonly used fields like
Language. A complete list of the
DESCRIPTION fields that R understands can be found in the R extensions manual.
Source, binary and bundled packages
So far we've just described the structure of a source package: the development version of a package that lives on your computer. There are also two other types of package: bundled packages and binary packages.
A package bundle is a compressed version of a package in a single file. By convention, package bundles in R use the extension
.tar.gz. This is Linux convention indicating multiple files have been collapsed into a single file (
.tar) and then compressed using gzip (
.gz). The package bundle is useful if you want to manually distribute your package to another R package developer. It is not OS specific. You can use
devtools::build() to make a package bundle.
If you want to distribute your package to another R user (i.e. someone who doesn't necessarily have the development tools installed) you need to make a binary package. Like a package bundle, a binary package is a single file, but if you uncompress it, you'll see that the internal structure is a little different to a source package:
Meta/directory contains a number of
Rdsfiles. These contain cached metadata about the package, like what topics the help files cover and parsed versions of the
DESCRIPTIONfiles. (If you want to look at what's in these files you can use
html/directory contains some files needed for the HTML help.
there are no
.Rfiles in the
R/directory - instead there are three files that store the parsed functions in an efficient format. This is basically the result of loading all the R code and then saving the functions with
save, but with a little extra metadata to make things as fast as possible.
If you had any code in the
src/directory there will now be a
libs/directory that contains the results of compiling that code for 32 bit (
i386/) and 64 bit (
Binary packages are platform specific: you can't install a Windows binary package on a Mac or vice versa. You can use
devtools::build(binary = TRUE) to make a package bundle.
An installed package is just a binary package that's been uncompressed into a package library, described next.
A library is a collection of installed packages. You can have multiple libraries on your computer and most people have at least two: one for the recommended packages that come with a base R install (like
stats etc), and one library where the packages you've installed live. The default is to make that directory dependent on which version of R you have installed - that's why you normally lose all your packages when you reinstall R. If you want to avoid this behaviour, you can manually set the
R_LIBS environmental variable to point somewhere else.
.libPaths() tells you where your current libraries live.
When you use
library(pkg) to load a package, R looks through each path in
.libPaths() to see if a directory called
Package installation is the process whereby a source package gets converted into a binary package and then installed into your local package library. There are a number of tools that automate this process:
install.packages()installs a package from CRAN. Here CRAN takes care of making the binary package and so installation from CRAN basically is equivalent to downloading the binary package value and unzipping it in
.libPaths()(but you should never do this by hand because the process also does other checks)
devtools::install()installs a source package from a directory on your computer.
devtools::install_github()installs a package that someone has published on their github account. There are a number of similar functions that make it easy to install packages from other internet locations:
install_bitbucket, and so on.
(to be integrated throughout the chapter)
Go to CRAN and download the source and binary for XXX. Unzip and compare. How do they differ?
Download the source packages for XXX, YYY, ZZZ. What directories do they contain?
Where is your default library? What happens if you install a new package from CRAN?