Outline

• Install R packages
• Inspect a R package
• Build a R package using devtools

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")

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

• ?package.skeleton()
• This is the accient way to build a R package.

Structure of R package

• R/: the most important directory is R/
• DESCRIPTION: basic information, dependency.
• 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.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.
• data/: this directory allows you to include data with your package.
• src/: other programming languages.

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”.
  • Your distribution can be either open source or not open source.
• GPL-2/GPL-3: anyone who distributes modified versions of your code (derivative works) must also make the source code
  • open source,
  • 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.

The namespace file in R package

• You have many functions.
• The Namespace file specifies which functions will be visible to users.
• Other functions are internal funciton, for which you don’t want the users to see and use.
• The namespace file also specifies how to interaction with other programming language (e.g., c++)
• Don’t need to revise the namespace file, will be managed by devtools.

Namespace

• :: to specify namespace

base::dim

• Namespace protect the internal functions being overwritten by functions from other packages/global environment.

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

• variable/function search path

search()

Man (for manual)

• 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.

Devtools, starting from sketches.

Red color indicates essential steps

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

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

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

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

2. Copy your R code in inside R folder

• f.R

##' @export
f <- function(x, y) x + y

• g.R

##' @export
g <- function(x, y) x - y

• h.R

##' @export
h <- function(x, y) f(x,y) * g(x,y)

• all.R

##' @export
all <- function(x, y){
  f0 <- f(x,y)
  g0 <- g(x,y)
  h0 <- h(x,y)
  list(f=f0, g=g0, h=h0)
}

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

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

4. Add documentation in R code

• 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

• h.R

##' Complex operations on two numbers (Description)
##'
##' We want to do some complex operations on two numbers, blalala... (Details)
##' @title Very complex operation of two numbers
##' @param x first number
##' @param y second number
##' @return (x - y)(x + y)
##' @author Caleb
##' @export
##' @examples
##' h(3,2)
h <- function(x, y) f(x,y) * g(x,y)

• all.R

##' Return f,g,h (Description)
##'
##' We want to return f,g,h , blalala... (Details)
##' @title return all
##' @param x first number
##' @param y second number
##' @return A list of f, g, and h.
##' \item{f}{Results for adding}
##' \item{g}{Results for subtracting}
##' \item{h}{Complex Result}
##' @author Caleb
##' @export
##' @examples
##' all(3,2)
all <- function(x, y){
  f0 <- f(x,y)
  g0 <- g(x,y)
  h0 <- h(x,y)
  list(f=f0, g=g0, h=h0)
}

5. devtools::document() generate R documentation

devtools::document() ## default argument is pkg = ".", current working directory

Change:

• NAMESPACE is updated
• man folder is created

6. devtools::use_data() prepare external data

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

Change:

• data folder
• after install the package, do“”

data(xxxx)

6. documenting external data

• no need to export external data

xxxx.R

#' Prices of 50,000 round cut diamonds.
#'
#' A dataset containing the prices and other attributes of almost 54,000
#' diamonds.
#'
#' @format A data frame with 53940 rows and 10 variables:
#' \describe{
#'   \item{price}{price, in US dollars}
#'   \item{carat}{weight of the diamond, in carats}
#'   ...
#' }
#' @source \url{http://www.diamondse.info/}
"xxxx"

6. internal data

• Internal data: These objects are only available within the package.
• Will be saved as sysdata.rda in R/
• No documentation
• Good to put the raw code in data-raw/ for reproducibility purpose

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

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

• create test functions

devtools::use_testthat() ## default argument is pkg = ".", current working directory

• actual test function (e.g. testthat/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)
  }
)

8. devtools::test() preform test

• perform test

devtools::test() ## default argument is pkg = ".", current working directory

9. devtools::use_vignette() generate vignettes

• browse all Vignettes

browseVignettes()

• create our own Vignettes

setwd(WD2)
devtools::use_vignette("Gators", pkg = ".")
## or 
setwd(WD)
devtools::use_vignette("Gators", pkg = "GatorPKG")

10. devtools::check() check the package

• check the package

setwd(WD2)
devtools::check() ## default argument is pkg = ".", current working directory

11. devtools::build() build the package

• build() will generate .tar.gz package

## build the package
devtools::build() ## default argument is pkg = ".", current working directory

12. devtools::install() install the package

• install the package

devtools::install() ## default argument is pkg = ".", current working directory
devtools::install(build_vignettes = TRUE) ## also build the vignettes

• remove the package

remove.packages("GatorPKG")

• install the pacakge again

install.packages(file.path("~/Desktop","GatorPKG_0.0.0.9000.tar.gz"),repos=NULL,type="source") ## directly with vignettes

others (internal function)

• internal function: you want to use internally but don’t want other people to see it.
• we do not use ##` @export 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

others (R package and GitHub)

• GitHub is a great open platform to host R packages
  • Apply for a github acccount
  • https://github.com
• Play with the following git tutorials (HW)
  • https://www.codecademy.com/learn/learn-git

References

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