10 January 2018

R / RStudio / CRAN

R / RStudio / CRAN

R Package Documentation

What is an R package?

Definition

Quite tricky to answer! I would say:

a set of files that passes the R CMD install

Examples

Many packages

Why would you create an R package?

Action

Create your R package without RStudio

Create your R package with RStudio

Package architecture

  • DESCRIPTION: meta data of your package (name, version, …)
  • NAMESPACE: import / export / dynlab
  • R: R functions
  • man: documentation (.Rd files)

Package architecture

  • data: R objects stored as RData (.rda)
  • vignettes: documentation
  • src: file in other programming language
  • test: tests for you package
  • inst: CITATION / non-R scripts / external-data…
  • .Rbuildignore
  • .Rinstignore

Session 2

Remember

  • DESCRIPTION: meta data of your package (name, version, …)
  • NAMESPACE: import / export / dynlab
  • R: R functions
  • man: documentation (.Rd files)
  • test: tests (.R files)
  • data: data (.Rda files)

Hadley’s package collection for package development

  • R packages
  • Devtools: install.packages('devtools')
  • Roxygen: to document package
  • Testhat: to test your package
  • Rmarkdown: to build vignettes

Basic workflow with devtools

  • create a function load_all()
  • document the function document()
  • test the function test()

load_all()

First, create a function. For instance I’ve created:

getDigits <- function(x, collapse = NULL) {
    out <- strsplit(x, split = "\\D") %>% lapply(function(x) x[x != ""])
    if (!is.null(collapse))
        out <- lapply(out, paste, collapse = collapse)
    out
}

in R/getDigits.R file.

load_all()

Additional tools to improve your workflow

Versioning and Licence

Extra notes

Imports / Suggests and Enhances

https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Package-Dependencies

The ‘Suggests’ field uses the same syntax as ‘Depends’ and lists packages that are not necessarily needed. This includes packages used only in examples, tests or vignettes (see Writing package vignettes), and packages loaded in the body of functions. E.g., suppose an example11 from package foo uses a dataset from package bar. Then it is not necessary to have bar use foo unless one wants to execute all the examples/tests/vignettes: it is useful to have bar, but not necessary. Version requirements can be specified but should be checked by the code which uses the package.

Finally, the ‘Enhances’ field lists packages “enhanced” by the package at hand, e.g., by providing methods for classes from these packages, or ways to handle objects from these packages (so several packages have ‘Enhances: chron’ because they can handle datetime objects from chron even though they prefer R’s native datetime functions). Version requirements can be specified, but are currently not used. Such packages cannot be required to check the package: any tests which use them must be conditional on the presence of the package. (If your tests use e.g. a dataset from another package it should be in ‘Suggests’ and not ‘Enhances’.)