Creating R Packages

Creating R PackagesRory WinstonOutlineBasics Creating R PackagesCreating aSimplePackageInterfacing Rory WinstonWith NativeCode February 17, 2011 Rory Winston Melbourne R User Group Creating R Packages

Creating R PackagesRory WinstonOutline 1 OutlineBasicsCreating aSimple 2 BasicsPackageInterfacingWith NativeCode 3 Creating a Simple Package 4 Interfacing With Native Code Rory Winston Melbourne R User Group Creating R Packages

R Packages Creating R PackagesRory WinstonOutlineBasicsCreating a R’s ”jewel in the crown”SimplePackage Almost 3,000 packages on CRANInterfacingWith Native Preferred extension mechanism for RCode Rory Winston Melbourne R User Group Creating R Packages

Why create a Package? Creating R PackagesRory WinstonOutlineBasics Keep frequently-used code and data togetherCreating aSimple Save repetitive typing and analysisPackage Extend base R functionalityInterfacingWith NativeCode Share analysis with others Package reproducible research Rory Winston Melbourne R User Group Creating R Packages

Package Conventions Creating R PackagesRory WinstonOutlineBasics R follows ”convention over conﬁguration”Creating aSimple Flexible packaging structurePackage Sensible defaultsInterfacingWith NativeCode Some pedantry: Note that ’package’ and ’library’ are not strictly equivalent Rory Winston Melbourne R User Group Creating R Packages

Package Structure Creating R PackagesRory Winston Basic package structureOutlineBasics mypackage/Creating a DESCRIPTION # Mandatory package metadataSimple R/ # R source filesPackageInterfacing data/ # Data directoryWith NativeCode 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

Default Loaded Packages Creating R PackagesRory WinstonOutline Not all packages are loaded by defaultBasics A basic subset onlyCreating aSimplePackage Loading many packages can aversely aﬀect performanceInterfacing To see packages loaded by default:With NativeCode > getOption("defaultPackages") [1] "datasets" "utils" "grDevices" [4] "graphics" "stats" "methods" Rory Winston Melbourne R User Group Creating R Packages

Installed Packages Creating R Packages > pkginfo <- installed.packages()Rory Winston > class(pkginfo)Outline [1] "matrix"Basics > dimnames(pkginfo)[1]Creating aSimple [[1]]Package [1] "aplpack" "base"InterfacingWith 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

Installed Packages Creating R PackagesRory WinstonOutline > dimnames(pkginfo)[2]BasicsCreating a [[1]]SimplePackage [1] "Package" "LibPath" "Version"Interfacing [4] "Priority" "Depends" "Imports"With NativeCode [7] "LinkingTo" "Suggests" "Enhances" [10] "OS_type" "License" "Archs" [13] "Built" Rory Winston Melbourne R User Group Creating R Packages

Currently Loaded Packages Creating R PackagesRory WinstonOutlineBasics To see currently loaded packages:Creating aSimple > (.packages())PackageInterfacing [1] "stats" "graphics" "grDevices"With NativeCode [4] "utils" "datasets" "methods" [7] "base" Rory Winston Melbourne R User Group Creating R Packages

Simple Package Example Creating R PackagesRory WinstonOutlineBasics Australian Lotto packageCreating aSimple Some sample data (historical results)Package Simple functionsInterfacingWith NativeCode Help ﬁles Building and checking the package Rory Winston Melbourne R User Group Creating R Packages

Creating the Package Creating R PackagesRory WinstonOutlineBasics Simplest way to create a package in R:Creating aSimplePackage Create a basic set of functions and dataInterfacing Use package.skeleton()With NativeCode Modify and add as required Rory Winston Melbourne R User Group Creating R Packages

The ozlotto Package Creating R PackagesRory WinstonOutlineBasics Let’s download some sample data for our package:Creating aSimple $ curlPackage https://www.tattersalls.com.au/FullResults/TattslottoResults.zipInterfacing > lotto.zipWith NativeCode $ unzip lotto.zip Rory Winston Melbourne R User Group Creating R Packages

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 aSimple + na.strings=c("-"))Package > lotto$date <- as.POSIXct(strptime(lotto$date,InterfacingWith 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

Some Data Creating R PackagesRory Winston > draws <- as.data.frame(lotto[,3:8])Outline > colnames(draws) <- paste("draw", c(1:6))BasicsCreating a > head(draws, 5)SimplePackage draw 1 draw 2 draw 3 draw 4 draw 5 draw 6Interfacing 1 33 8 15 20 25 5With NativeCode 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

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)BasicsCreating aSimple Total Draw FrequencyPackageInterfacingWith Native 200Code 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

What’s In The Environment? Creating R PackagesRory WinstonOutlineBasicsCreating a > sapply(objects(), function(x) (class(get(x))))SimplePackage draws lotto plot.freqsInterfacingWith Native "data.frame" "data.frame" "function"Code Rory Winston Melbourne R User Group Creating R Packages

Creating The Package Skeleton Creating R PackagesRory WinstonOutline > package.skeleton(list=ls(), name="lotto")Basics Creating directories ...Creating a Creating DESCRIPTION ...SimplePackage Creating Read-and-delete-me ...InterfacingWith 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

Editing the DESCRIPTION Creating R PackagesRory WinstonOutlineBasics Mandatory file (very important!)Creating aSimplePackage ”Debian Control File” formatInterfacing Many different fields, see docs for referenceWith NativeCode Dependencies (and licenses) can use version ranges Rory Winston Melbourne R User Group Creating R Packages

Example DESCRIPTION Creating R PackagesRory Winston Package: lottoOutline Type: PackageBasics Title: OzLotto Example PackageCreating a Version: 1.0SimplePackage Date: 2011-02-14Interfacing Author: Rory WinstonWith NativeCode 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

Package Dependencies Creating R PackagesRory WinstonOutline If your package depends on functionality deﬁned in otherBasics packagesCreating aSimple This can be added to the Depends sectionPackageInterfacing Package versions can also be speciﬁedWith NativeCode 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

.RData Files Creating R PackagesRory WinstonOutline Data ﬁles are stored in .rda formatBasicsCreating a This is a portable, (optionally) compressed representationSimplePackage Same as save(lotto, file="lotto.rda")InterfacingWith NativeCode $ file lotto.rda lotto.rda: gzip compressed data Rory Winston Melbourne R User Group Creating R Packages

Help Files - The .Rd Format Creating R PackagesRory Winston Rd is the ”R documentation format”Outline Can be compiled intoBasics LTEX; ACreating a PDF;SimplePackage 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

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 columnsInterfacing 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

Documenting Data Creating R PackagesRory Winston Note that R will generate doc skeletons for package data The data will be inspected and sample docs createdOutlineBasics 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

Sample Generated Manual Creating R Packages Package ‘lotto’ February 15, 2011Rory Winston Type Package Title OzLotto Example PackageOutline Version 1.0Basics Date 2011-02-14Creating a Author Rory WinstonSimple Maintainer Rory Winston <rory@foo.com>Package Description Simple toy packageInterfacing Depends R (>= 2.12.0)With NativeCode 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

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 vectorRory Winston The math markup will be downgraded to ASCII where X4 a numeric vector X5 a numeric vectorOutline appropriate X6 a numeric vector supp1 a numeric vector supp2 a numeric vectorBasics The text deqn{p(x) = frac{1}{b-a}} becomes (in ExamplesCreating a PDF and console): data(lotto) ## maybe str(lotto) ; plot(lotto) ...SimplePackageInterfacing plot.freqs Plotting Number Frequencies Across DrawsWith NativeCode 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

R CMD check Creating R PackagesRory Winston R CMD check is the ﬁrst port of callOutlineBasics Checks documentation, package structure, runs examplesCreating a Produces compiled documentation (e.g. PDF) ifSimplePackage appropriateInterfacingWith Native Basic procedure:Code Run R CMD check <packagename> Check errors in generated <packagename>.Rcheck dir If any errors, ﬁx up rinse and repeat Rory Winston Melbourne R User Group Creating R Packages

Testing The Package Creating R PackagesRory WinstonOutlineBasics The package can be loaded from a working directoryCreating aSimple instance, if we are in the generated lotto.Rcheck dir:PackageInterfacing > library(lib.loc=".", package="lotto")With NativeCode As R CMD check generates a loadable package Rory Winston Melbourne R User Group Creating R Packages

Building The Package Creating R PackagesRory WinstonOutlineBasics A binary package can be built using R CMD buildCreating aSimple <packagename>Package This can be installed to a local libraryInterfacingWith NativeCode > install.packages(c("lotto_1.0.tar.gz"), repos=NULL) Rory Winston Melbourne R User Group Creating R Packages

Things To Be Aware Of Creating R PackagesRory WinstonOutline NamespacesBasics Lazy LoadingCreating aSimplePackage 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

Interfacing With Native Code Creating R PackagesRory WinstonOutline Why go native?Basics SpeedCreating a Functionality otherwise unavailableSimplePackage Some examples:InterfacingWith Native Algorithms in C/C++/Fortran codeCode Speeding up slow R routines Workarounds for R limitations (e.g. shared memory) Rory Winston Melbourne R User Group Creating R Packages

Considerations When Using R and C Creating R Packages R uses many LISP idioms in the C codeRory Winston e.g. PROTECT(ans =Outline FirstArg(CAR(sub),CADR(sub)));Basics R itself has many LISP-like featuresCreating aSimple > ( + ( sum ( ^ (( : (1,10)),2)),Package + ( ^ (( sum ( : (1,10))),2))))InterfacingWith NativeCode [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

Simple Example Creating R Packages R does not have a ’matrix exponentiation’ operatorRory Winston Scalar exponentiation only nOutline x11 x12Basics x21 x22Creating aSimple > X <- matrix(1:4, 2, 2)Package > X^2InterfacingWith 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

Creating a New Operator Creating R PackagesRory WinstonOutlineBasicsCreating a All operators in R are just functionsSimplePackage Binary operators take two argumentsInterfacingWith Native We will create a new operator %^%Code Rory Winston Melbourne R User Group Creating R Packages

The Exponentiation Operator Creating R PackagesRory WinstonOutlineBasicsCreating aSimplePackageInterfacingWith NativeCode Rory Winston Melbourne R User Group Creating R Packages

A Better Way (At Least For C++) Creating R PackagesRory WinstonOutlineBasics Use the Rcpp packageCreating aSimple Lots of examplesPackage Clean, ”modern” C++InterfacingWith NativeCode Manages memory allocation/protection Provides nice syntatic sugar for C++ operations Rory Winston Melbourne R User Group Creating R Packages

Building Windows Packages Creating R PackagesRory WinstonOutline R is reasonably Unix-centricBasics Perl no longer required for most tasksCreating aSimple Some tools support (e.g. LTEX) also assumed APackageInterfacing Packages can be compiled with Visual StudioWith NativeCode 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

Further Reading Creating R PackagesRory WinstonOutlineBasicsCreating a R CMD <command> -helpSimplePackage The R documentationInterfacingWith Native Mailing ListsCode Rory Winston Melbourne R User Group Creating R Packages

http://www.theresearchkitchen.com	730
http://pairach.com	2
http://ams.activemailservice.com	1

Creating R Packages

by Rory Winston

Accessibility

Categories

Upload Details

Usage Rights

3 Embeds 733

Statistics

Creating R Packages Presentation Transcript