Creating R Packages

5,432 views
5,359 views

Published on

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

Published in: Technology
1 Comment
4 Likes
Statistics
Notes
No Downloads
Views
Total views
5,432
On SlideShare
0
From Embeds
0
Number of Embeds
1,634
Actions
Shares
0
Downloads
135
Comments
1
Likes
4
Embeds 0
No embeds

No notes for slide

Creating R Packages

  1. 1. Creating R PackagesRory WinstonOutlineBasics Creating R PackagesCreating aSimplePackageInterfacing Rory WinstonWith NativeCode February 17, 2011 Rory Winston Melbourne R User Group Creating R Packages
  2. 2. 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
  3. 3. 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
  4. 4. 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
  5. 5. Package Conventions Creating R PackagesRory WinstonOutlineBasics R follows ”convention over configuration”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
  6. 6. 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
  7. 7. Default Loaded Packages Creating R PackagesRory WinstonOutline Not all packages are loaded by defaultBasics A basic subset onlyCreating aSimplePackage Loading many packages can aversely affect 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
  8. 8. 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
  9. 9. 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
  10. 10. 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
  11. 11. Simple Package Example Creating R PackagesRory WinstonOutlineBasics Australian Lotto packageCreating aSimple Some sample data (historical results)Package Simple functionsInterfacingWith NativeCode Help files Building and checking the package Rory Winston Melbourne R User Group Creating R Packages
  12. 12. 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
  13. 13. 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
  14. 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 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
  15. 15. 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
  16. 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)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
  17. 17. 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
  18. 18. 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
  19. 19. What’s In The Package? Creating R Packages lotto/Rory Winston |~data/Outline | |-draws.rdaBasics | |-lotto.rdaCreating aSimple |~man/Package | |-draws.RdInterfacingWith Native | |-lotto-package.RdCode | |-lotto.Rd | |-plot.freqs.Rd |~R/ | |-plot.freqs.R |-DESCRIPTION |-Read-and-delete-me Rory Winston Melbourne R User Group Creating R Packages
  20. 20. 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
  21. 21. 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
  22. 22. Package Dependencies Creating R PackagesRory WinstonOutline If your package depends on functionality defined in otherBasics packagesCreating aSimple This can be added to the Depends sectionPackageInterfacing Package versions can also be specifiedWith 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
  23. 23. .RData Files Creating R PackagesRory WinstonOutline Data files 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
  24. 24. 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
  25. 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 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
  26. 26. 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
  27. 27. 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
  28. 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 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
  29. 29. R CMD check Creating R PackagesRory Winston R CMD check is the first 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, fix up rinse and repeat Rory Winston Melbourne R User Group Creating R Packages
  30. 30. 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
  31. 31. 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
  32. 32. 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
  33. 33. 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
  34. 34. 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
  35. 35. 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
  36. 36. 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
  37. 37. The Exponentiation Operator Creating R PackagesRory WinstonOutlineBasicsCreating aSimplePackageInterfacingWith NativeCode Rory Winston Melbourne R User Group Creating R Packages
  38. 38. 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
  39. 39. 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
  40. 40. 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

×