Package Development: : CHEAT SHEET

Package Structure Setup (# DESCRIPTION)

A package is a convention for organizing files into directories. The # DESCRIPTION file describes your work, sets up how your Package: mypackage
package will work with other packages, and applies a copyright. Title: Title of Package
This sheet shows how to work with the 7 most common parts of Version: 0.1.0
an R package: ! You must have a DESCRIPTION file Authors@R: person("Hadley", "Wickham", email =
"hadley@me.com", role = c("aut", "cre"))
Add the packages that yours relies on with
% Package ! devtools::use_package()
Description: What the package does (one paragraph)
Depends: R (>= 3.1.0)
Import packages that your package
# DESCRIPTION SETUP License: GPL-2
must have to work. R will install them
Adds a package to the Imports or Suggests field LazyData: true
" R/ WRITE CODE Imports: when it installs your package.
" tests/ TEST CC0 MIT GPL-2 dplyr (>= 0.4.0),
ggvis (>= 0.2) Suggest packages that are not very
" man/ DOCUMENT No strings attached. MIT license applies to GPL-2 license applies to your
Suggests: essential to yours. Users can install
your code if re-shared. code, and all code anyone
" vignettes/ TEACH knitr (>= 0.1.0) them manually, or not, as they like.
bundles with it, if re-shared.
" data/ ADD DATA
# NAMESPACE ORGANIZE
Write Code ( " R/) Test ( " tests/)
The contents of a package can be stored on disk as a:
All of the R code in your package goes in " R/. A package with just Use " tests/ to store tests that will alert you if your code breaks.
• source - a directory with sub-directories (as above) an R/ directory is still a very useful package.
• bundle - a single compressed file (.tar.gz)
• binary - a single compressed file optimized for a specific OS ! Create a new package project with
! Add a tests/ directory
devtools::create("path/to/name")
Or installed into an R library (loaded into memory during an R
session) or archived online in a repository. Use the functions Create a template to develop into a package. ! Import testthat with devtools::use_testthat(), which
sets up package to use automated tests with testthat
below to move between these states.
! Save your code in " R/ as scripts (extension .R)
! Write tests with context(), test(), and expect statements
Repository

In memory

! Save your tests as .R files in tests/testthat/

Installed

WORKFLOW
Bundle
Source

Binary

1. Edit your code. WORKFLOW

install.packages()
install.packages(type =
"source")
R CMD install
devtools::install()
devtools::build()
devtools::install_github( github
)
devtools::load_all()
Build & Reload (RStudio)
CRAN ○ 2. Load your code with one of 1. Modify your code or tests.
Example Test
CRAN ○ devtools::load_all() 2. Test your code with one of
context("Arithmetic")
○ ○ Re-loads all saved files in " R/ into memory. devtools::test()
○ ○ Ctrl/Cmd + Shift + L (keyboard shortcut) Runs all tests in " tests/ test_that("Math works", {
expect_equal(1 + 1, 2)
○ ○ Saves all open files then calls load_all(). Ctrl/Cmd + Shift + T expect_equal(1 + 2, 3)
○ (keyboard shortcut) expect_equal(1 + 3, 4)
3. Experiment in the console. })
○ ○ 3. Repeat until all tests pass
4. Repeat.
○ Expect statement Tests
○ ○ • Use consistent style with r-pkgs.had.co.nz/r.html#style expect_equal() is equal within small numerical tolerance?
○ ○ ○ • Click on a function and press F2 to open its definition expect_identical() is exactly equal?

library() • Search for a function with Ctrl + . expect_match() matches specified string or regular
○ ○ expression?
expect_output() prints specified output?
Internet On disk library memory
Visit r-pkgs.had.co.nz to expect_message() displays specified message?
devtools::use_build_ignore("file") learn much more about expect_warning() displays specified warning?
Adds file to .Rbuildignore, a list of files that will not be included writing and publishing expect_error() throws specified error?
packages for R expect_is() output inherits from certain class?
when package is built.
expect_false() returns FALSE?
expect_true() returns TRUE?

RStudio® is a trademark of RStudio, Inc. • CC BY SA RStudio • info@rstudio.com • 844-448-1212 • rstudio.com • Learn more at http://r-pkgs.had.co.nz/ • devtools 1.5.1 • Updated: 2015-01
Document (" man/) Add Data (" data/)
" man/ contains the documentation for your functions, the help The " data/ directory allows you to
pages in your package. ROXYGEN2 include data with your package.

Use roxygen comments to document each function The roxygen2 package lets you write
! beside its definition documentation inline in your .R files with a ! Save data as .Rdata files (suggested)
shorthand syntax. devtools implements Store data in one of data/, R/Sysdata.rda, inst/extdata
! Document the name of each exported data set roxygen2 to make documentation. ! Always use LazyData: true in your DESCRIPTION file.
! Include helpful examples for each function • Add roxygen documentation as comment lines !
that begin with #’.
devtools::use_data()
WORKFLOW • Place comment lines directly above the code that defines the Adds a data object to data/
object documented.
(R/Sysdata.rda if internal = TRUE)
1. Add roxygen comments in your .R files • Place a roxygen @ tag (right) after #’ to supply a specific
2. Convert roxygen comments into documentation with one of: section of documentation. devtools::use_data_raw()
Adds an R Script used to clean a data set to data-raw/.
devtools::document() • Untagged lines will be used to generate a title, description, Includes data-raw/ on .Rbuildignore.
Converts roxygen comments to .Rd files and places and details section (in that order)
them in " man/. Builds NAMESPACE.
Store data in
#' Add together two numbers.
Ctrl/Cmd + Shift + D (Keyboard Shortcut) #' • data/ to make data available to package users
3. Open help pages with ? to preview documentation
#' @param x A number. • R/sysdata.rda to keep data internal for use by your
#' @param y A number. functions.
4. Repeat #' @return The sum of \code{x} and \code{y}.
#' @examples
• inst/extdata to make raw data available for loading and
#' add(1, 1) parsing examples. Access this data with system.file()
.Rd FORMATTING TAGS #' @export
add <- function(x, y) {
\emph{italic text} \email{name@@foo.com} x + y
\strong{bold text}
\code{function(args)}
\href{url}{display}
\url{url}
}
Organize (# NAMESPACE)
\pkg{package}
\link[=dest]{display} COMMON ROXYGEN TAGS The # NAMESPACE file helps you make your package self-
contained: it won’t interfere with other packages, and other
\dontrun{code} \linkS4class{class} @aliases @inheritParams @seealso packages won’t interfere with it.
\dontshow{code} \code{\link{function}}
@concepts @keywords @format
\donttest{code} \code{\link[package]{function}}
@describeIn @param @source data Export functions for users by placing @export in their
\deqn{a + b (block)} \tabular{lcr}{ @examples @rdname @include
! roxygen comments
\eqn{a + b (inline)} left \tab centered \tab right \cr @export @return @slot S4 Import objects from other packages with

}
cell \tab cell \tab cell \cr @family @section @field RC ! package::object (recommended) or @import,
@importFrom, @importClassesFrom,
@importMethodsFrom (not always recommended)
Teach (" vignettes/)
" vignettes/ holds documents that teach your users how to solve real problems with your tools.
WORKFLOW
! Create a " vignettes/ directory and a template vignette with
devtools::use_vignette()
---
title: "Vignette Title" 1. Modify your code or tests.
author: "Vignette Author"
2. Document your package (devtools::document())
Adds template vignette as vignettes/my-vignette.Rmd. date: "`r Sys.Date()`"
output: rmarkdown::html_vignette 3. Check NAMESPACE
! Append YAML headers to your vignettes (like right)
vignette: > 4. Repeat until NAMESPACE is correct
! Write the body of your vignettes in R Markdown
(rmarkdown.rstudio.com)
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc} SUBMIT YOUR PACKAGE
--- r-pkgs.had.co.nz/release.html

RStudio® is a trademark of RStudio, Inc. • CC BY SA RStudio • info@rstudio.com • 844-448-1212 • rstudio.com • Learn more at http://r-pkgs.had.co.nz/ • devtools 1.5.1 • Updated: 2015-01