Presentation on creating R packages (including native code integration). Presented at the Melbourne R User Group in 2011.

1. Creating R
Packages
Rory Winston
Outline
Basics Creating R Packages
Creating a
Simple
Package
Interfacing Rory Winston
With Native
Code
February 17, 2011
Rory Winston Melbourne R User Group
Creating R Packages

2. Creating R
Packages
Rory Winston
Outline
1 Outline
Basics
Creating a
Simple
2 Basics
Package
Interfacing
With Native
Code
3 Creating a Simple Package
4 Interfacing With Native Code
Rory Winston Melbourne R User Group
Creating R Packages

3. R Packages
Creating R
Packages
Rory Winston
Outline
Basics
Creating a R’s ”jewel in the crown”
Simple
Package Almost 3,000 packages on CRAN
Interfacing
With Native Preferred extension mechanism for R
Code
Rory Winston Melbourne R User Group
Creating R Packages

4. Why create a Package?
Creating R
Packages
Rory Winston
Outline
Basics Keep frequently-used code and data together
Creating a
Simple
Save repetitive typing and analysis
Package
Extend base R functionality
Interfacing
With Native
Code
Share analysis with others
Package reproducible research
Rory Winston Melbourne R User Group
Creating R Packages

5. Package Conventions
Creating R
Packages
Rory Winston
Outline
Basics R follows ”convention over configuration”
Creating a
Simple Flexible packaging structure
Package
Sensible defaults
Interfacing
With Native
Code
Some pedantry: Note that ’package’ and ’library’ are not
strictly equivalent
Rory Winston Melbourne R User Group
Creating R Packages

6. Package Structure
Creating R
Packages
Rory Winston Basic package structure
Outline
Basics
mypackage/
Creating a
DESCRIPTION # Mandatory package metadata
Simple R/ # R source files
Package
Interfacing
data/ # Data directory
With Native
Code
demo/ # Demo code
man/ # Package docs (.Rd)
po/ # i18n
src/ # Native (compiled) code
tests/ # Unit tests
Rory Winston Melbourne R User Group
Creating R Packages

7. Default Loaded Packages
Creating R
Packages
Rory Winston
Outline Not all packages are loaded by default
Basics
A basic subset only
Creating a
Simple
Package
Loading many packages can aversely affect performance
Interfacing To see packages loaded by default:
With Native
Code > getOption("defaultPackages")
[1] "datasets" "utils" "grDevices"
[4] "graphics" "stats" "methods"
Rory Winston Melbourne R User Group
Creating R Packages

8. Installed Packages
Creating R
Packages > pkginfo <- installed.packages()
Rory Winston > class(pkginfo)
Outline
[1] "matrix"
Basics > dimnames(pkginfo)[1]
Creating a
Simple
[[1]]
Package [1] "aplpack" "base"
Interfacing
With Native
[3] "boot" "caret"
Code [5] "codetools" "datasets"
[7] "distr" "e1071"
[9] "fortunes" "graphics"
[11] "grDevices" "grid"
[13] "highlight" "inline"
[15] "IPSUR" "iterators"
[17] "itertools" "lotto"
Rory Winston [19] "methods" "neuralnet" Melbourne R User Group
Creating R Packages

9. Installed Packages
Creating R
Packages
Rory Winston
Outline
> dimnames(pkginfo)[2]
Basics
Creating a [[1]]
Simple
Package [1] "Package" "LibPath" "Version"
Interfacing [4] "Priority" "Depends" "Imports"
With Native
Code [7] "LinkingTo" "Suggests" "Enhances"
[10] "OS_type" "License" "Archs"
[13] "Built"
Rory Winston Melbourne R User Group
Creating R Packages

10. Currently Loaded Packages
Creating R
Packages
Rory Winston
Outline
Basics To see currently loaded packages:
Creating a
Simple > (.packages())
Package
Interfacing [1] "stats" "graphics" "grDevices"
With Native
Code [4] "utils" "datasets" "methods"
[7] "base"
Rory Winston Melbourne R User Group
Creating R Packages

11. Simple Package Example
Creating R
Packages
Rory Winston
Outline
Basics Australian Lotto package
Creating a
Simple
Some sample data (historical results)
Package
Simple functions
Interfacing
With Native
Code
Help files
Building and checking the package
Rory Winston Melbourne R User Group
Creating R Packages

12. Creating the Package
Creating R
Packages
Rory Winston
Outline
Basics
Simplest way to create a package in R:
Creating a
Simple
Package
Create a basic set of functions and data
Interfacing Use package.skeleton()
With Native
Code Modify and add as required
Rory Winston Melbourne R User Group
Creating R Packages

13. The ozlotto Package
Creating R
Packages
Rory Winston
Outline
Basics
Let’s download some sample data for our package:
Creating a
Simple
$ curl
Package https://www.tattersalls.com.au/FullResults/TattslottoResults.zip
Interfacing > lotto.zip
With Native
Code $ unzip lotto.zip
Rory Winston Melbourne R User Group
Creating R Packages

14. Load The Data
Creating R
Packages
Load the data into R:
Rory Winston > lotto<-read.table("Tattslotto.txt", sep = ",",
+ fill = TRUE, header = TRUE,
Outline
+ col.names = c("number", "date",
Basics
+ c(1:6), "supp1", "supp2"),
Creating a
Simple + na.strings=c("-"))
Package
> lotto$date <- as.POSIXct(strptime(lotto$date,
Interfacing
With Native + "%Y%m%d"))
Code
> head(lotto,4)
number date X1 X2 X3 X4 X5 X6 supp1 supp2
1 101 1981-03-07 33 8 15 20 25 5 11 NA
2 102 1981-03-14 1 32 18 19 37 38 4 NA
3 103 1981-03-21 20 12 17 1 19 39 2 NA
4 104 1981-03-28 34 14 2 18 26 15 4 NA
Rory Winston Melbourne R User Group
Creating R Packages

15. Some Data
Creating R
Packages
Rory Winston
> draws <- as.data.frame(lotto[,3:8])
Outline
> colnames(draws) <- paste("draw", c(1:6))
Basics
Creating a
> head(draws, 5)
Simple
Package draw 1 draw 2 draw 3 draw 4 draw 5 draw 6
Interfacing 1 33 8 15 20 25 5
With Native
Code 2 1 32 18 19 37 38
3 20 12 17 1 19 39
4 34 14 2 18 26 15
5 14 29 7 18 2 16
Rory Winston Melbourne R User Group
Creating R Packages

16. Some Functions
Creating R
Packages > plot.freqs <- function(x) barplot(cex.names=.6,
Rory Winston + table(unlist(x)), col="lightblue",
+ las=2, main="Total Draw Frequency")
Outline
> plot.freqs(draws)
Basics
Creating a
Simple Total Draw Frequency
Package
Interfacing
With Native 200
Code
150
100
50
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
Rory Winston Melbourne R User Group
Creating R Packages

17. What’s In The Environment?
Creating R
Packages
Rory Winston
Outline
Basics
Creating a > sapply(objects(), function(x) (class(get(x))))
Simple
Package
draws lotto plot.freqs
Interfacing
With Native "data.frame" "data.frame" "function"
Code
Rory Winston Melbourne R User Group
Creating R Packages

18. Creating The Package Skeleton
Creating R
Packages
Rory Winston
Outline > package.skeleton(list=ls(), name="lotto")
Basics Creating directories ...
Creating a Creating DESCRIPTION ...
Simple
Package Creating Read-and-delete-me ...
Interfacing
With Native
Saving functions and data ...
Code
Making help files ...
Done.
Further steps are described in './lotto/Read-and-delet
Rory Winston Melbourne R User Group
Creating R Packages

19. What’s In The Package?
Creating R
Packages
lotto/
Rory Winston
|~data/
Outline | |-draws.rda
Basics | |-lotto.rda
Creating a
Simple
|~man/
Package
| |-draws.Rd
Interfacing
With Native | |-lotto-package.Rd
Code
| |-lotto.Rd
| |-plot.freqs.Rd
|~R/
| |-plot.freqs.R
|-DESCRIPTION
|-Read-and-delete-me
Rory Winston Melbourne R User Group
Creating R Packages

20. Editing the DESCRIPTION
Creating R
Packages
Rory Winston
Outline
Basics
Mandatory file (very important!)
Creating a
Simple
Package
”Debian Control File” format
Interfacing Many different fields, see docs for reference
With Native
Code Dependencies (and licenses) can use version ranges
Rory Winston Melbourne R User Group
Creating R Packages

21. Example DESCRIPTION
Creating R
Packages
Rory Winston
Package: lotto
Outline Type: Package
Basics Title: OzLotto Example Package
Creating a Version: 1.0
Simple
Package Date: 2011-02-14
Interfacing Author: Rory Winston
With Native
Code Maintainer: Rory Winston <rory@foo.com>
Description: Simple toy package
Depends: R (>= 2.12.0)
License: GPL (>=2) | BSD
LazyLoad: yes
Rory Winston Melbourne R User Group
Creating R Packages

22. Package Dependencies
Creating R
Packages
Rory Winston
Outline If your package depends on functionality defined in other
Basics packages
Creating a
Simple This can be added to the Depends section
Package
Interfacing
Package versions can also be specified
With Native
Code Example from the highlight package:
Depends: R (>= 2.11.0), tools, codetools, utils, parser (>= 0.0-10)
Rory Winston Melbourne R User Group
Creating R Packages

23. .RData Files
Creating R
Packages
Rory Winston
Outline
Data files are stored in .rda format
Basics
Creating a This is a portable, (optionally) compressed representation
Simple
Package Same as save(lotto, file="lotto.rda")
Interfacing
With Native
Code $ file lotto.rda
lotto.rda: gzip compressed data
Rory Winston Melbourne R User Group
Creating R Packages

24. Help Files - The .Rd Format
Creating R
Packages
Rory Winston Rd is the ”R documentation format”
Outline Can be compiled into
Basics LTEX;
A
Creating a PDF;
Simple
Package
HTML;
Interfacing
ASCII text;
With Native HTML Help;
Code
etc.
Functions and data can be documented;
Uses a TEX-like markup
Many, many options
Rory Winston Melbourne R User Group
Creating R Packages

25. Sample Documentation for a Function
Creating R
Packages
name{plot.freqs}
Rory Winston alias{plot.freqs}
title{Plotting Number Frequencies Across Draws}
description{
Outline This function produces a bar plot of number
frequencies across all six-number draws.
Basics
}
Creating a usage{plot.freqs(x)}
Simple arguments{item{x}{
Package A code{data.frame} where each row corresponds
to a separate lottery draw and the columns
Interfacing represent the numbers drawn in that event, in order.}}
With Native author{Rory Winston}
Code seealso{
See code{link{draws}}
Also see code{link[graphics]{hist}}
}
examples{
random.draw <- function() sapply(45:(45-6),
function(x) sample(1:x, 1))
draws <- t(replicate(random.draw(), n=1000))
plot.freqs( draws )
}
Rory Winston Melbourne R User Group
Creating R Packages

26. Documenting Data
Creating R
Packages
Rory Winston
Note that R will generate doc skeletons for package data
The data will be inspected and sample docs created
Outline
Basics
For example:
Creating a
format{
Simple
A data frame with 1620 observations on the following 10 variables.
Package
describe{
Interfacing item{code{number}}{a numeric vector}
With Native item{code{date}}{a POSIXct}
Code item{code{X1}}{a numeric vector}
item{code{X2}}{a numeric vector}
item{code{X3}}{a numeric vector}
item{code{X4}}{a numeric vector}
item{code{X5}}{a numeric vector}
item{code{X6}}{a numeric vector}
item{code{supp1}}{a numeric vector}
item{code{supp2}}{a numeric vector}
}
}
Rory Winston Melbourne R User Group
Creating R Packages

27. Sample Generated Manual
Creating R
Packages
Package ‘lotto’
February 15, 2011
Rory Winston
Type Package
Title OzLotto Example Package
Outline
Version 1.0
Basics
Date 2011-02-14
Creating a Author Rory Winston
Simple
Maintainer Rory Winston <rory@foo.com>
Package
Description Simple toy package
Interfacing
Depends R (>= 2.12.0)
With Native
Code License GPL (>=2) | BSD
LazyLoad yes
R topics documented:
lotto-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
draws . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
lotto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
plot.freqs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Index 5
lotto-package Simple Oz Lotto Package
Rory Winston Melbourne R User Group
Creating R Packages Description

28. Usage
Math in Rd Docs data(lotto)
Format
A data frame with 1620 observations on the following 10 variables.
number a numeric vector
date a POSIXct
Creating R X1 a numeric vector
Packages Note that Rd supports TEX-like math markup
X2 a numeric vector
X3 a numeric vector
Rory Winston The math markup will be downgraded to ASCII where
X4 a numeric vector
X5 a numeric vector
Outline
appropriate X6 a numeric vector
supp1 a numeric vector
supp2 a numeric vector
Basics The text deqn{p(x) = frac{1}{b-a}} becomes (in
Examples
Creating a PDF and console): data(lotto)
## maybe str(lotto) ; plot(lotto) ...
Simple
Package
Interfacing plot.freqs Plotting Number Frequencies Across Draws
With Native
Code Description
This function produces a bar plot of number frequencies across all six-number draws. The uniform
distribution is commonly notated as
1
p(x) =
b−a
Usage
plot.freqs(x)
Arguments
This function produces xa bar plot data.frame where frequencies toacross all and the
A
of number each row corresponds a separate lottery draw
columns represent the numbers drawn in that event, in order.
six-number draws. The uniform distribution is commonly notated as
p(x) = frac{1}{b-a}
Rory Winston Melbourne R User Group
Creating R Packages

29. R CMD check
Creating R
Packages
Rory Winston
R CMD check is the first port of call
Outline
Basics Checks documentation, package structure, runs examples
Creating a Produces compiled documentation (e.g. PDF) if
Simple
Package appropriate
Interfacing
With Native
Basic procedure:
Code
Run R CMD check <packagename>
Check errors in generated <packagename>.Rcheck dir
If any errors, fix up
rinse and repeat
Rory Winston Melbourne R User Group
Creating R Packages

30. Testing The Package
Creating R
Packages
Rory Winston
Outline
Basics
The package can be loaded from a working directory
Creating a
Simple instance, if we are in the generated lotto.Rcheck dir:
Package
Interfacing > library(lib.loc=".", package="lotto")
With Native
Code As R CMD check generates a loadable package
Rory Winston Melbourne R User Group
Creating R Packages

31. Building The Package
Creating R
Packages
Rory Winston
Outline
Basics A binary package can be built using R CMD build
Creating a
Simple
<packagename>
Package
This can be installed to a local library
Interfacing
With Native
Code
> install.packages(c("lotto_1.0.tar.gz"),
repos=NULL)
Rory Winston Melbourne R User Group
Creating R Packages

32. Things To Be Aware Of
Creating R
Packages
Rory Winston
Outline Namespaces
Basics
Lazy Loading
Creating a
Simple
Package
What does the following mean:
Interfacing > suppressWarnings(dump("AirPassengers",
With Native + "", evaluate=FALSE))
Code
AirPassengers <-
<promise: lazyLoadDBfetch(c(0L, 367L), datafile, compressed,
envhook)>
Rory Winston Melbourne R User Group
Creating R Packages

33. Interfacing With Native Code
Creating R
Packages
Rory Winston
Outline Why go native?
Basics Speed
Creating a Functionality otherwise unavailable
Simple
Package
Some examples:
Interfacing
With Native Algorithms in C/C++/Fortran code
Code
Speeding up slow R routines
Workarounds for R limitations (e.g. shared memory)
Rory Winston Melbourne R User Group
Creating R Packages

34. Considerations When Using R and C
Creating R
Packages
R uses many LISP idioms in the C code
Rory Winston
e.g. PROTECT(ans =
Outline FirstArg(CAR(sub),CADR(sub)));
Basics R itself has many LISP-like features
Creating a
Simple
> ( + ( sum ( ^ (( : (1,10)),2)),
Package
+ ( ^ (( sum ( : (1,10))),2))))
Interfacing
With Native
Code
[1] 3410
> sum((1:10)^2) + (sum(1:10))^2
[1] 3410
Garbage collection is also an issue
Frequent source of error (even for the R team)
Rory Winston Melbourne R User Group
Creating R Packages

35. Simple Example
Creating R
Packages R does not have a ’matrix exponentiation’ operator
Rory Winston Scalar exponentiation only
n
Outline
x11 x12
Basics x21 x22
Creating a
Simple
> X <- matrix(1:4, 2, 2)
Package > X^2
Interfacing
With Native [,1] [,2]
Code
[1,] 1 9
[2,] 4 16
> X %*% X
[,1] [,2]
[1,] 7 15
[2,] 10 22
Rory Winston Melbourne R User Group
Creating R Packages

36. Creating a New Operator
Creating R
Packages
Rory Winston
Outline
Basics
Creating a All operators in R are just functions
Simple
Package Binary operators take two arguments
Interfacing
With Native We will create a new operator %^%
Code
Rory Winston Melbourne R User Group
Creating R Packages

37. The Exponentiation Operator
Creating R
Packages
Rory Winston
Outline
Basics
Creating a
Simple
Package
Interfacing
With Native
Code
Rory Winston Melbourne R User Group
Creating R Packages

38. A Better Way (At Least For C++)
Creating R
Packages
Rory Winston
Outline
Basics Use the Rcpp package
Creating a
Simple
Lots of examples
Package
Clean, ”modern” C++
Interfacing
With Native
Code
Manages memory allocation/protection
Provides nice syntatic sugar for C++ operations
Rory Winston Melbourne R User Group
Creating R Packages

39. Building Windows Packages
Creating R
Packages
Rory Winston
Outline R is reasonably Unix-centric
Basics Perl no longer required for most tasks
Creating a
Simple Some tools support (e.g. LTEX) also assumed
A
Package
Interfacing
Packages can be compiled with Visual Studio
With Native
Code The mingw compiler and other supporting tools can be
downloaded from:
http://www.murdoch-sutherland.com/Rtools/
Rory Winston Melbourne R User Group
Creating R Packages

40. Further Reading
Creating R
Packages
Rory Winston
Outline
Basics
Creating a R CMD <command> -help
Simple
Package The R documentation
Interfacing
With Native Mailing Lists
Code
Rory Winston Melbourne R User Group
Creating R Packages