it-ebooks - R packages

From: http://r-pkgs.had.co.nz/

In R, the fundamental unit of shareable code is the package. A package bundles together code, data, documentation, and tests, and is easy to share with others. As of January 2015, there were over 6,000 packages available on the Comprehensive RArchive Network, or CRAN, the public clearing house for R packages. This huge variety of packages is one of the reasons that R is so successful: the chances are that someone has already solved a problem that youre working on, and you can benefit from their work by downloading their package.

If youre reading this book, you already know how to use packages:

• You install them from CRAN with install.packages("x").
• You use them in R with library("x").
• You get help on them with package?x and help(package = "x").

The goal of this book is to teach you how to develop packages so that you can write your own, not just use other peoples. Why write a package? One compelling reason is that you have code that you want to share with others. Bundling your code into a package makes it easy for other people to use it, because like you, they already know how to use packages. If your code is in a package, any R user can easily download it, install it and learn how to use it.

But packages are useful even if you never share your code. As Hilary Parker says in her introduction to packages: Seriously, it doesnt have to be about sharing your code (although that is an added benefit!). It is about saving yourself time. Organising code in a package makes your life easier because packages come with conventions. For example, you put R code in R/, you put tests in tests/ and you put data in data/. These conventions are helpful because:

• They save you time you dont need to think about the best way to organise a project, you can just follow a template.

• Standardised conventions lead to standardised tools if you buy into Rs package conventions, you get many tools for free.

Its even possible to use packages to structure your data analyses, as Robert M Flight discusses in a series of blog posts.

This book espouses my philosophy of package development: anything that can be automated, should be automated. Do as little as possible by hand. Do as much as possible with functions. The goal is to spend your time thinking about what you want your package to do rather than thinking about the minutiae of package structure.

This philosophy is realised primarily through the devtools package, a suite of R functions that I wrote to automate common development tasks. The goal of devtools is to make package development as painless as possible. It does this by encapsulating all of the best practices of package development that Ive learned over the years. Devtools protects you from many potential mistakes, so you can focus on the problem youre interested in, not on developing a package.

Devtools works hand-in-hand with RStudio, which I believe is the best development environment for most R users. The only real competitor is ESS, emacs speaks statistics, which is a rewarding environment if youre willing to put in the time to learn emacs and customise it to your needs. The history of ESS stretches back over 20 years (predating R!), but its still actively developed and many of the workflows described in this book are also available there.

Together, devtools and RStudio insulate you from the low-level details of how packages are built. As you start to develop more packages, I highly recommend that you learn more about those details. The best resource for the official details of package development is always the official writing R extensions manual. However, this manual can be hard to understand if youre not already familiar with the basics of packages. Its also exhaustive, covering every possible package component, rather than focussing on the most common and useful components, as this book does. Writing R extensions is a useful resource once youve mastered the basics and want to learn whats going on under the hood.

Youll start by learning about the basic structure of a package, and the forms it can take, in . Then each of the next ten chapters of the book goes into more details about each component. Theyre roughly organised in order of importance:

• : the most important directory is R/, where your R code lives. A package with just this directory is still a useful package. (And indeed, if you stop reading the book after this chapter, youll have still learned some useful new skills.)

• : the DESCRIPTION lets you describe what your package needs to work. If youre sharing your package, youll also use the DESCRIPTION to describe what it does, who can use it (the license) and who to contact if things go wrong.

• : if you want other people (including future-you!) to understand how to use the functions in your package, youll need to document them. Ill show you how to use roxygen2 to document your functions. I recommend roxygen2 because it lets you write code and documentation together while continuing to produce Rs standard documentation format.

• : function documentation describes the nit-picky details of every function in your package. Vignettes give the big picture. Theyre long-form documents that show how to combine multiple parts of your package to solve real problems. Ill show you how to use Rmarkdown and knitr to create vignettes with a minimum of fuss.

• : to ensure your package works as designed (and continues to work as you make changes), its essential to write unit tests which define correct behaviour, and alert you when functions break. In this chapter, Ill teach you how to use the testthat package to convert the informal interactive tests that youre already doing to formal, automated tests.

• : to play nicely with others, your package needs to define what functions it makes available to other packages and what functions it requires from other packages. This is the job of the NAMESPACE file and Ill show you how to use roxygen2 to generate it for you. The NAMESPACE is one of the more challenging parts of developing an R package but its critical to master if you want your package to work reliably.

• : the data/ directory allows you to include data with your package. You might do this to bundle data in a way thats easy for R users to access, or just to provide compelling examples in your documentation.

• : R code is designed for human efficiency, not computer efficiency, so its useful to have a tool in your back pocket that allows you to write fast code. The src/ directory allows you to include speedy compiled C and C++ code to solve performance bottlenecks in your package.

• : this chapter documents the handful of other components that are rarely needed: demo/, exec/, po/ and tools/.

The final three chapters describe general best practices not specifically tied to one directory:

• : mastering a version control system is vital to easily collaborate with others, and is useful even for solo work because it allows you to easily undo mistakes. In this chapter, youll learn how to use the popular git and GitHub combo with RStudio.

• : R provides very useful automated quality checks in the form of R CMD check. Running them regularly is a great way to avoid many common mistakes. The results can sometimes be a bit cryptic, so I provide a comprehensive cheatsheet to help you convert warnings to actionable insight.