Writing R Packages

Logistics

• Final Exam
  • Shorter than homeworks (will be cumulative)
  • work by yourself, can only ask for help interpreting the questions
  • 5% extra credit on Final Exam if \(>80\%\) of the class fills out FCEs
  • more details Monday
• Last week schedule
  • Monday & Tuesday like normal.
  • Wednesday Lecture: Tidyverse Advance: Split-Apply-Combine, Parallel Computing, and Deep Learning (?) -> Optional
  • Thursday: open work session (no need to attend)
  • Friday: Either a “lecture” where I bring in other phd students who talk about how they use computing in their research, or nothing…

Last time: Version control

• version control (git) creates “snapshots” of your code with a message to help for future you
• Github is an example of a “centralized” version control tool (allows for easy sharing and collaboration.)
• “Github First” is the approach of making a github repo first before creating a directory on your computer (in Rstudio followed with making a project connected to the repo)
• commits allow you to take a “snapshot” relative to new lines, modified lines, and deleted lines
• push/pull sends the snap shots on your computer to github or brings the snap shots from github to your computer (respectively)

Why make an R Package?

• Packages are the “fundamental units of shareable code”
• Organization, standardized tools
• Fulfillment, building something

“… from user to programmer to contributor, in the gradual progress that R encourages.”

~ John Chambers (Software for Data Analysis: Programming with R)

R package: Goals

• Build a minimal working package
• Understand how devtools/ usethis can facilitate this process
• Develop a better understanding of how R packages work

What is an R Package?

• Collection of files, organized in a specific way
• When installed by R, can be used in R sessions
• Packages are installed into libraries: see yours using .libPaths()
• Attached to the session using the library() function.

library(tidyverse)
search()

##  [1] ".GlobalEnv"        "package:forcats"   "package:stringr"  
##  [4] "package:dplyr"     "package:purrr"     "package:readr"    
##  [7] "package:tidyr"     "package:tibble"    "package:ggplot2"  
## [10] "package:tidyverse" "package:stats"     "package:graphics" 
## [13] "package:grDevices" "package:utils"     "package:datasets" 
## [16] "package:methods"   "Autoloads"         "package:base"

The 5 stages of an R package

R provides tools (R CMD INSTALL, R CMD BUILD, R CMD CHECK, etc…) to move to different stages

Packages to help with developing an R package

library(devtools)
library(usethis)
# documentation
library(roxygen2) 
# tests
library(testthat)

devtools and usethis allows us to get our package up an running

“The goal of devtools is to make package development as painless as possible”

~ Hadley Wickham (R Packages)

  install.packages("devtools")
  library("devtools")

• Provides a suite of functions which automate the higher level package details, which come with R itself

Devtools serves as a wrapper to many other useful packages

usethis focuses on automating repetitive tasks in building packages

  install.packages("usethis")
  library("usethis")

“usethis is a workflow package: it automates repetitive tasks that arise during project setup and development, both for R packages and non-package projects.”

~ usethis package description

Step 0: Setting up your github (“Github First”)

Just like in the version control we are going to us the “Github First” Approach. Here are the reminder of the steps:

In GitHub, do the following:

• go to the top-level directory (i.e., github.com/<your user name>)

• click on “+” at top right, and select “New repository”

• name the repository (e.g., “tartan”)

• provide a short description of the repository (don’t leave completely blank!)

• keep the repository public (as students you have access to free private repos https://education.github.com/pack, but for purposes of this lab keep the repo public)

• click on “Initialize this repository with a README” and select the R option in “Add .gitignore”… there is no need to “Add a license”

• click on “Create Repository”

---

…then RStudio

In RStudio, do the following:

• click on File > New Project…

• click on “Version Control”, then on “Git”

• provide the full address for the “Repository URL” (including the https, etc.; by default, this will provide the name of your local repository)

• make sure “Create project as subdirectory of:” points to where you want to point it

• click on “Create Project” (in this example we will be calling our package tartan)

Step 1: Create the minimal source package

An R (source) package is just files in a directory, formatted in a specific way.

To create the bare bones R package, just type:

usethis::create_package("tartan") 

• if in the tartan project, may need to do setwd("../"), run the above line and then do setwd("tartan").

---

This should give us:

1. Directory R/
2. Directory man/
3. NAMESPACE file
4. DESCRIPTION file
5. tartan.Rproj file (if using RStudio)

and anything else you included from intializing your git repo (.gitignore, LICENSE, etc)

The description file contains package meta-data