What is R package

• In R, the fundamental unit of shareable code is the package.
• This huge variety of packages is one of the reasons that R is so successful.
• There is a high chance that someone has already solved a problem that you are working on, and you can benefit from their work by downloading their package.

Install R packages

• from CRAN, 11,611 packages, up to 10/15/2017.

# install.packages("mclust")

• from Bioconductor: 1,383 packages, up to 10/15/2017.

## try http:// if https:// URLs are not supported
source("https://bioconductor.org/biocLite.R")
biocLite("impute")

• .gz.tar zipped file.

install.packages("mclust_5.3.tar",repos=NULL,type="source")

• package folder.

# in R: 
system("R CMD INSTALL mclust")
#command line: R CMD INSTALL mclust

• github.

library(devtools)
install_github("cran/mclust")

Why R package

• Share with others, if your code is in a package, any R user can easily download it, install it and learn how to use it.
• It is about saving yourself time. Organizing code in a package makes your life easier because packages come with conventions.

Use R survival package as an example.

Basic structure of an R Package

• Refer to survival package
  • DESCRIPTION: metadata, basic information, dependency…
  • NAMESPACE: control the imported and exported objects.
  • R: R code
  • man: manual
  • src: other language (c, java…)
  • test: test validity of your functions
  • vignettes: an overall description of your package
  • ToDo: to do list

Play with survival package

• library a package

library(survival)

• help file about the package

help(package = 'survival')

• help file about one function

?coxph

• check out vignettes

browseVignettes("survival")

Structure of R package

• R code: the most important directory is R/
• Package metadata: the DESCRIPTION lets you describe what your package needs to work.
• Documentation: if you want other people (including future-you!) to understand how to use the functions in your package, you’ll need to document them.
• Vignettes: function documentation describes the nit-picky details of every function in your package.
• Vignettes give the big picture. They’re long-form documents that show how to combine multiple parts of your package to solve real problems.
• Tests: to ensure your package works as designed (and continues to work as you make changes), it’s essential to write unit tests which define correct behaviour, and alert you when functions break.
• Namespace: 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.
• External data: the data/ directory allows you to include data with your package.
• Compiled code src/: R code is designed for human efficiency, not computer efficiency, so it’s useful to have a tool in your back pocket that allows you to write fast code.

Simple way to create an R Package – package.skeleton()

• First, have all of your functions saved in sources files or in the workspace.
• Next call the function package.skeleton(). This function automates some of the work needed to make a package. It creates directories, saves functions, data, and R code files to appropriate places, and creates skeleton help files and a Read-and-delete-me file describing further steps in packaging.
• Then complete the documentation files.
• Last, build and check the package.
• If you need to update the package or make changes to the source code you will need to recreate the package.
• ?package.skeleton()

A minimum example

## two functions and two "data sets" :
if(dir.exists("mypkg")){ ## if mypkg folder already exists, delete that folder
  unlink("mypkg", recursive = TRUE)
}
f <- function(x, y) x+y
g <- function(x, y) x-y
d <- data.frame(a = 1, b = 2)
e <- rnorm(1000)

package.skeleton(list = c("f","g","d","e"), name = "mypkg")

Read-and-delete-me

• The Read-and-delete-me file contains instructions for the next steps
  • Edit the help file skeletons in ‘man’, possibly combining help files for multiple functions.
  • Edit the exports in ‘NAMESPACE’, and add necessary imports.
  • Put any C/C++/Fortran code in ‘src’.
  • If you have compiled code, add a useDynLib() directive to ‘NAMESPACE’.
  • Run R CMD build to build the package tarball.
  • Run R CMD check to check the package tarball.

Read “Writing R Extensions” for more information.

DESCRIPTION

The job of the DESCRIPTION file is to store important metadata about your package. Every package must have a DESCRIPTION. In fact, it’s the defining feature of a package.

• LazyLoad, if yes delays the loading of functions until they are required.
• Title and description.
• Author: who are you.
• Dependencies.
• License.
• Version.

DESCRIPTION License

• MIT: This is a simple and permissive license. It lets people use and freely distribute your code subject to only one restriction: the license must always be distributed with the “code”.
• GPL-2/GPL-3: anyone who distributes modified versions of your code (derivative works) must also make the source code available, and also GPL-compatible.
• CC0. It relinquishes all your rights on the code and data so that it can be freely used by anyone for any purpose.
• others

DESCRIPTION Version

Formally, an R package version is a sequence of at least two integers separated by either . or -. For example, 1.0 and 0.9.1-10 are valid versions, but 1 or 1.0-devel are not.

• A released version number consists of three numbers, ... For version number 1.9.2, 1 is the major number, 9 is the minor number, and 2 is the patch number. Never use versions like 1.0, instead always spell out the three components, 1.0.0.

• An in-development package has a fourth component: the development version. This should start at 9000. For example, the first version of the package should be 0.0.0.9000.

Namespace

• You have function a() and b().
• a() depends on b().
• If we only export a(), then b() is not accessible or visable from outside; b() is only accessible by a().
• If users create a function b() in global environment, a() still use b() inside the orignal name space.
• If users create a function a() in global environment, the new a() function will mask the old a() function.

Namespace

Namespaces make your packages self-contained in two ways: the imports and the exports. The imports defines how a function in one package finds a function in another.

nrow

## function (x) 
## dim(x)[1L]
## <bytecode: 0x7ffc2bbfa5c8>
## <environment: namespace:base>

dim(mtcars)

## [1] 32 11

dim <- function(x) c(1, 1)
dim(mtcars)

## [1] 1 1

nrow(mtcars)

## [1] 32

Man

• Documentation is one of the most important aspects of a good package. Without it, users won’t know how to use your package.
• Documentation is also useful for future-you (so you remember what your functions were supposed to do), and for developers extending your package.
• R provides a standard way of documenting the objects in a package: you write .Rd files in the man/ directory. These files use a custom syntax, loosely based on LaTeX, and are rendered to HTML, plain text and pdf for viewing.

Wrap up your package

After editing DESCRIPTION and Man, wrap up your package following the following step

• Check package
  • Need minimum function title
  • also revise the examples

system("R CMD check mypkg")
## system: system invokes the OS command specified by command.
## You may need to revise the Rd files.

• build the package

system("R CMD BUILD mypkg")

• install the package
  • install from R folder

system("R CMD INSTALL mypkg")

• install from R package (.gz.tar)

install.packages("mypkg_1.0.tar.gz",repos=NULL,type="source")

• use the package

library(mypkg)
help(package="mypkg")

Your turn to create a R package using skeleton

• Least square fit https://www.varsitytutors.com/hotmath/hotmath_help/topics/line-of-best-fit

• input: vector x and vector y
• output: least square estimate of slope \(a\) and intercept \(b\)

• Rd: write some contents for your mannual.

Problem with skeleton

• Each time need to manually update Rd files.
• Not easy for maintaining.

Advanced techniques: devtools

• A new pipeline to make R packages.
• More efficient than skeleton.
• More features and reliable.

devtools, starting from sketches. (*) means essential

1. devtools::create() create an new R package*
2. Copy your R code in inside R folder*
3. formatR::tidy dir() clean up the code
4. Add documentation in R code*
5. devtools::document() generate R documentation*
6. devtools::use data() prepare external data
7. devtools::use testthat() prepare test functions
8. devtools::test() preform test
9. devtools::use vignette() generate vignettes
10. devtools::check() check the package
11. devtools::build() build the package*
12. devtools::install() install the package*
13. others

devtools::create() create an new R package (1*)

## set working directory to be Desktop
WD <- '~/Desktop'
setwd(WD)

devtools::create("myPkgDevtool") 
WD2 <- '~/Desktop/myPkgDevtool'

Copy your R code in inside R folder (2*)

### f.R
f <- function(x, y) x + y

### g.R
g <- function(x, y) x - y

formatR::tidy dir() clean up the code (3)

setwd(WD2)
## make the code neat
formatR::tidy_dir("R")

Add documentation in R code, (4*)

• f.R

##' Add up two numbers (Description)
##'
##' We want to add up two numbers, blalala... (Details)
##' @title add two numbers
##' @param x first number
##' @param y second number
##' @return sum of two numbers
##' @author Caleb
##' @export
##' @examples
##' f(1,2)
f <- function(x, y) x + y

• g.R

##' Subtract two numbers (Description)
##'
##' We want to Subtract two numbers, blalala... (Details)
##' @title Subtract two numbers
##' @param x first number
##' @param y second number
##' @return x - y
##' @author Caleb
##' @export
##' @examples
##' g(2,1)
g <- function(x, y) x - y

devtools::document() generate R documentation (5*)

devtools::document() 

Change:

• NAMESPACE is updated
• man folder is created

devtools::use data() prepare external data (6)

xxxx <- sample(1000)
devtools::use_data(xxxx)

Change:

• data folder
• after install the package, do data(xxxx)

Internal data: These objects are only available within the package.

yyyy <- sample(1000)
devtools::use_data(yyyy, internal = TRUE)

devtools::use testthat() prepare test functions (7)

• create test functions

devtools::use_testthat()

• actual test function (e.g. testf.R)

test_that("test if f function is correct", {
    expect_equal(f(1,1), 2)
  }
)

test_that("test if f function is correct", {
    expect_equal(f(1,4), 2)
  }
)

devtools::test() preform test (8)

• perform test

devtools::test()

• Each line represents a test file.
• Each . represents a passed test.
• Each number represents a failed test.

devtools::use_vignette() generate vignettes (9)

• browse all Vignettes

browseVignettes()

• create our own Vignettes

devtools::use_vignette("myPkgDevtool")

devtools::use_vignette()

devtools::check() check the package (10)

• check the package

devtools::check()

devtools::build() build the package (11*)

## build the package
devtools::build()

devtools::install() install the package (12*)

• install the package

devtools::install() ## seems no vignettes

• remove the package

remove.packages("myPkgDevtool")

• install the pacakge again

install.packages("../myPkgDevtool_0.0.0.9000.tar.gz",repos=NULL,type="source") ## with vignettes

others (internal function)

• internal function: you want to use internally but don’t want other people to see it.
• h.R

## h is a internal function for f
h <- function(a,b) a * b

• we do not use ##` @exports and this becomes a internal function

others (depend on other packages)

• DESCRIPTION file Depends: R (>= 3.4.1), survival

• change your function f.R to depend on coxph

References

• http://adv-r.had.co.nz

Generate R code

knitr::purl("Rpackage.rmd", output = "Rpackage.R ", documentation = 2)