http://stat545-ubc.github.io What is an R package? Where does it live? How do I make one?
Lecture slides from UBC STAT545 2015 are usually intended as complement to, e.g., a hands-on activity.
Laboratories University of British Columbia [email protected] https://github.com/jennybc http://www.stat.ubc.ca/~jenny/ @JennyBryan ← personal, professional Twitter https://github.com/STAT545-UBC http://stat545-ubc.github.io @STAT545 ← Twitter as lead instructor of this course
the package the first moment I thought about it, and then use all the saved time to watch cat videos because that really would have been more productive. http://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/
a companion to 3 hours of hands-on activity in which we actually write an R package. Our attention bounced between these Big Ideas + technical details and hands-on work.
packages - functions in these pkgs are what you think of as “base R” 15 Recommended packages - ship w/ all binary dist’ns of R; no need to install - use via, e.g., library(lattice) CRAN has > 6K more packages - e.g., install.packages(“dplyr”) - e.g., library(dplyr) And then there’s Github ... - e.g., devtools::install_github(“hadley/dplyr”) - e.g., library(dplyr)
datasets for use Why better than just source()ing functions, read.table()ing data? - standard structure facilitates distribution - help pages, vignettes - optionally, incorporate non-R code - tests to ensure code works and stays that way - checking package as a whole What are R scripts good for? - e.g., executing a series of data manipulations You will need both in your data analytical life. Up ‘til now in this course, we’ve focused on writing our own R scripts and using packages developed by other people. NOW we’ll talk about developing our own R packages.
[1] "/Users/jenny/resources/R/library" [2] “/Library/Frameworks/R.framework/Versions/3.2/Resources/library" > readLines("~/.Renviron") [1] "R_LIBS=~/resources/R/library" [2] “GITHUB_TOKEN=??????????????????????????????????????” [3] “GITHUB_PAT=????????????????????????????????????????” [4] "NOT_CRAN=true" Get to know your R installation * your set up is probably different from mine symlinked
[1] "/Users/jenny/resources/R/library" ... functions like old.packages(), install.packages(), update.packages(), library() operate, by default, on the first library listed in .libPaths() = your default library for you, probably same as .Library
class Systematically compare the files and directories of the package when it exists in ... source form vs installed form consult GitHub or CRAN for source consult your local library for installed form
do installed packages get into memory? So far, you’ve only put packages into memory - that are already installed - that live in your default library - using the library()function
- write package source - document, test, check it - install it, load it, use it - several times in a day The devtools package reduces the agony of this. RStudio has good (and constantly improving) integration with devtools.
More > Document wrapper that uses roxygen2 to make formal documentation and NAMESPACE RStudio Build and Reload allow you to use your package and see how things are going devtools::load_all() RStudio > Build> More > Load All Your first devtools.
it interactively ... then ... load_all() to quickly emulate building and installing ... oops, something is broken! ... more editing to fix the code, etc ... then ... Build and Reload
be doing other crucial work • keep DESCRIPTION and the documentation in the #’ roxygen comments up-to-date • periodically run devtools::document() to regenerate help files and NAMESPACE • periodically run R CMD check to see if your package would pass muster with CRAN • write and run formal unit tests • write one or more vignettes
at least, in our recommended devtools driven workflow let devtools::document() and devtools:: build_vignettes() author these files for you inst/doc/VIGNETTE.[Rmd | html | R ]
More > Document wrapper that uses roxygen2 to make formal documentation and NAMESPACE RStudio > Build and Reload devtools::load_all() RStudio > Build> More > Load All devtools::use_vignette() devtools:build_vignettes() sets up and renders vignettes, respectively R CMD check devtools::check() RStudio > Check see if your package would pass muster with CRAN devtools::test() RStudio > Build> More > Test Package wrapper that uses testthat to run formal unit tests