R Packages

1. R Packages Davor Cubranic SCARL, Dept. of Statistics

2. Warmup questions • Who here uses packages? • Which ones? • How do you know you’re using a package? • Had to install it • Had to load it • What happens when you load it? • Functions • Data • Help pages

3. So package is a bundle of “stuff” • But, (next slide) • It’s a structured bundle of…

4. What is a package? • Structured, standardized unit of: • R code • documentation • data • external code

5. Why use packages (talking points) • Installation & administration is easy • Finding, installing, compiling, updating… • Validation • Package checks • Distribution mechanisms • CRAN, Bioconductor, Github • Documentation • Bundle examples, demos, tutorials • Organization • Especially useful for the programmers: • Self-contained (names) • Declare and enforce dependencies on other packages

6. Why use packages • Installation & administration • Validation • Distribution • Documentation • Organization

7. Knowing how packages work and how to use them effectively will make you more effective R analyst, even if you don’t develop new packages • But you should consider developing packages even if you don’t write the next ggplot • Packages for your own stuff: • Analyses you frequently repeat and/or share with others • Publication: create a package containing the publication as a vignette, and bundle the code and data with it

8. Handling packages • Load with library(name) • Package-level help: • library(help=name) • Unload with detach(package:name) • You shouldn’t have to do this

9. Handling packages with RStudio • See the packages tab in Rstudio • Checkmark to load • Some are already loaded!! • Click on the name for help

10. What happens when you load a package? • When you start R you have an empty workspace • But there is also all this other “basic” R stuff (matrix, plot) • So it’s more like we have two boxes, your workspace and “core” R • Actually, it’s more like a whole bunch of boxes: see search()

11. So what happens when you load? • New package gets inserted near the front of the list • It can pull additional packages (dependencies) • But notice that each package is its own bundle (box) • We’ll talk how you create these bundles next

12. Structure • What makes package a package is that it follows a prescribed structure of files and directories • If you tell R to treat this as a package, it will • You can create it by hand, but we’ll use a shortcut: package.skeleton()

13. package.skeleton() • Convenient for turning a set of existing functions and scripts into a package • Let’s do it with the anova.mlm code that we wrote earlier

14. New project: • scdemoXX@vscarl1.stat.ubc.ca:~scdemo/pkg • source(‘anova.mlm.R’) • package.skeleton(“anovaMlm”, ls())

15. DESCRIPTION • The only required part of a package • Name, author, license, etc.

16. R/ • Directory for R code • package.skeleton creates one file per function • This is not a rule, you can put as many functions into a single file

17. man/ • Help files

18. NAMESPACE • Defines which objects are visible to the user and other functions • Public vs. private to the package • The default is to make everything visible that starts with a letter

19. Command-line tools • Check • Install • Build

20. INSTALL • Let’s install our package • R CMD INSTALL anova.mlm • Delete the “man” directory • (it’s optional and we’ll recreate it later) • Redo INSTALL • Restart R studio • library(“anova.mlm”)

21. check • Really important!!! • Finds common errors, non-standard parts • CRAN requires no ERRORS or WARNINGS

22. Optional contents • man/: documentation • data/: datasets • demo/: R code for demo purposes • inst/: other files to include in the package (PDFs, vignettes) • tests/: package test files • src/: C, C++, or Fortran source code • NEWS: history of changes to the package • LICENSE or LICENCE: package license

23. DESCRIPTION • Depends: • packages used by this one • and loaded as part of its loading • i.e., visible to the user • Imports: • packages used by this one • but not loaded • i.e, not visible to the user • Suggests: • used in examples or vignettes • non-essential functionality

24. NAMESPACE • exportPattern(“^[[:alpha:]]”) • export(anova.mlm, est.beta) • S3method(print, anova.mlm) • S3method(plot, anova.mlm) • import(MASS) • importFrom(MASS, lda)

25. Documentation • Let’s re-generate the documentation files • promptPackage(“anova.mlm”) • prompt(anova.mlm)

26. anova.mlm.Rd • Description: Compute a (generalized) analysis of variance table for one or more multivariate linear models. • Arguments: • object: an object of class '"mlm”’ • ...: further objects of class '"mlm"’. • force.int: Force intercept • Value: An object of class “anova” inheriting from class “matrix”

27. Help files for methods • \usage{anova.mlm(…)} • For S3 methods: • \usage{\method{print}{anova.mlm}(….)}

28. Vignettes • .rnw extension • Written in Sweave • similar to knitr • Latex + R code • Produces a PDF available in the installed package • vignette() • vignette(‘Sweave’)

29. Help on writing packages • Lots of tutorials on the Web • many of them are not necessarily correct • NAMESPACES, Imports, etc. • Authoritative guide: Writing R Extensions • R-devel mailing list