Creating an R Package
This tutorial will take you through the steps of creating a new package in R.
There are five primary tasks:
- Create a package skeleton (set of empty files and folders).
- Add your R code to the skeleton directory.
- Create documentation for your package (similar to knitting RMD files).
- Install your new package on your computer and test it out.
- Upload the package to GitHub.
It is recommended to complete this lab in a regular R console, NOT in R Studio. You can do it using RMD docs as well, but some of the steps will be different and it complicates things.
The five steps are explained below, but the entire script you will need will look something like this:
# set your working directory
# if you don't want to create
# the package in your default
# working directory
getwd() # default directory, usually my documents
library(devtools)
# step 1
usethis::create_package( "montyhall" )
# step 2 move R script to montyhall/R folder
# after completing documentation fields
# step 3
setwd( "montyhall" )
devtools::document()
# step 4
setwd( ".." )
devtools::install( "montyhall" )
library( montyhall )
create_game()
# step 5: close R and re-open new console
devtools::install_github( "yourGitHubName/montyhall" )The examples below will walk you through the steps. You will also need to download the Monty Hall Problem functions that we completed during Labs 01 and 02 from the link below. This script contains some roxygen text to get you started with the process of documentation.
Note that you will update this script and place it in the montyhall/R folder after you complete Step 01 and the package skeleton has been created (the working directories for your package are built).
The package code has been provided for you. You just need to complete the documentation and develop the test code for each function (you can adapt these from the unit testing examples in the labs). You place the montyhall.R script directly in the folder. You should not be using RMD files in this assignment.
Install Development Packages
install.packages(c("devtools", "roxygen2","usethis","testthat","knitr"))
# if devtools is not working try
# devtools::build_github_devtools() You can check that you have everything installed and working by running the following code:
## Your system is ready to build packages!Build a Package Skeleton
# devtools::create_package() has been deprecated
# set your directory
# setwd()
usethis::create_package( "montyhall" )What you should see:
# > usethis::create_package( "montyhall" )
# ✔ Creating 'montyhall/'
# ✔ Setting active project to 'C:/Users/jdlecy/Documents/montyhall'
# ✔ Creating 'R/'
# ✔ Writing 'DESCRIPTION'
# Package: montyhall
# Title: What the Package Does (One Line, Title Case)
# Version: 0.0.0.9000
# Authors@R (parsed):
# * First Last <first.last@example.com> [aut, cre] (<https://orcid.org/YOUR-ORCID-ID>)
# Description: What the package does (one paragraph).
# License: What license it uses
# Encoding: UTF-8
# LazyData: true
# ✔ Writing 'NAMESPACE'
# ✔ Writing 'montyhall.Rproj'
# ✔ Adding '.Rproj.user' to '.gitignore'
# ✔ Adding '^montyhall\\.Rproj$', '^\\.Rproj\\.user$' to '.Rbuildignore'
# ✔ Opening 'montyhall/' in new RStudio session
# ✔ Setting active project to '<no active project>'You will now have a directory in your current folder called montyhall. This will contain the files you need for your package.
*Note, some of these files like gitignore are from GitHub - they will appear after completing Step 05. Files may vary by operating system, but you should at the very least have the R folder, a DESCRIPTION file, and a NAMESPACE file.
Document Your Functions
Add your roxygen comments to your R scripts:
#' @title
#' Sum of vector elements.
#'
#' @description
#' `sum(x)` returns the sum of all the values present in its arguments.
#'
#' @details
#' This is a generic function: methods can be defined for it directly
#' or via the [Summary] group generic. For this to work properly,
#' the arguments `...` should be unnamed, and dispatch is on the
#' first argument.
#'
#' @param x Numeric, complex, or logical vectors.
#' @param na.rm A logical scalar. Should missing values (including `NaN`)
#' be removed?
#' @return If all inputs are integer and logical, then the output
#' will be an integer. Otherwise it will be a length-one numeric or
#' complex vector.
#'
#' Zero-length vectors have sum 0 by definition. See
#' <http://en.wikipedia.org/wiki/Empty_sum> for more details.
#'
#' @examples
#' sum(1:10)
#' sum(1:5, 6:10)
#' sum(F, F, F, T, T)
#'
#' sum(.Machine$integer.max, 1L)
#' sum(.Machine$integer.max, 1)
#'
#' \dontrun{
#' sum("a")
#' }
sum <- function(..., na.rm = TRUE) {}Note that good documentation describes all of the arguments needed by the function, including the required data types of each object. And clearly describe what will be returned when the function runs (type of object, what it contains).
Place your documented R scripts into the “R” folder in your package directory, then try:
You should see:
# Updating montyhall documentation
# Updating roxygen version in C:\Users\jdlecy\Documents\montyhall/DESCRIPTION
# Writing NAMESPACE
# Loading montyhall
# Writing create_game.RdYou will see some errors as well if you have not yet finished documenting your functions. Ignore them for now.
Depending upon your OS and your R devtools version you may be required to complete ALL documentation before preceding to the next steps. At the very least each function should have a title.
You will now have a new folder in your montyhall directory called “man”, short for “manuals”. The documentation files have an .Rd (R documentation) extension.
Install Your Package
Go up one level in your directory so you are outside of the package folder, but in the same folder where the package folder lives. Then run the command to install your new package.
If successful you will see messages like this:
# Updating montyhall documentation
# Updating roxygen version in C:\Users\jdlecy\Documents\montyhall/DESCRIPTION
# Writing NAMESPACE
# Loading montyhall
# Writing create_game.Rd
# > getwd()
# [1] "C:/Users/jdlecy/Documents/montyhall"
# > setwd( ".." )
# > devtools::install( "montyhall" )
# √ checking for file 'C:\Users\jdlecy\Documents\montyhall/DESCRIPTION'
# - preparing 'montyhall':
# √ checking DESCRIPTION meta-information ...
# - checking for LF line-endings in source and make files and shell scripts
# - checking for empty or unneeded directories
# - building 'montyhall_0.0.0.9000.tar.gz'
#
# Running "C:/PROGRA~1/R/R-36~1.1/bin/x64/Rcmd.exe" INSTALL \
# "C:\Users\jdlecy\AppData\Local\Temp\RtmpKetkbm/montyhall_0.0.0.9000.tar.gz" --install-tests
# * installing to library 'C:/Users/jdlecy/Documents/R/win-library/3.6'
# * installing *source* package 'montyhall' ...
# ** using staged installation
# ** R
# ** byte-compile and prepare package for lazy loading
# ** help
# *** installing help indices
# 'montyhall'g help for package finding HTML links ...
# done
# -reate_game html
# ** building package indices
# ** testing if installed package can be loaded from temporary location
# *** arch - i386
# *** arch - x64
# ** testing if installed package can be loaded from final location
# *** arch - i386
# *** arch - x64
# ** testing if installed package keeps a record of temporary installation path
# * DONE (montyhall)Check Help Files
You should be able to preview the help files that you created with your roxygen comments.
Update Your Package Description
Navigate to the main “montyhall” package folder on your computer and open the file called “DESCRIPTION” in a text editor (your computer will have a text editor like notebook). You will see something like this:
Package: montyhall
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R:
person(given = "First",
family = "Last",
role = c("aut", "cre"),
email = "first.last@example.com",
comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: What license it uses
Encoding: UTF-8
LazyData: true
RoxygenNote: 6.1.1Since we use dplyr in the package, we need to add another line to import and attach it. Add:
Depends:
dplyrNow complete the rest of the fields from “Title” to “Description”.
Package: montyhall
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R:
person(given = "First",
family = "Last",
role = c("aut", "cre"),
email = "first.last@example.com",
comment = c(ORCID = "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
Depends:
dplyr
License: What license it uses
Encoding: UTF-8
LazyData: true
RoxygenNote: 6.1.1GitHub Hosting
You have a couple of options for sharing your new package with others. You could submit the package to the CRAN so that everyone in the world could install it in R using install.packages(“montyhall”).
We cannot use this option because (1) it’s a homework assignment so we don’t want to burden people with the task of reviewing a new package, (2) package names on the CRAN must be unique so everyone from the class would have to name it something different, and (3) the CRAN requires that the package passes some robustness checks to ensure everything is documented correctly and all of the code is running smoothly.
A simpler option is to host your package on GitHub. Complete the following steps to upload your code to a new repository on GitHub:
- Install the git client on your computer: LINK.
- Install GitHub Desktop application: LINK.
- Open GitHub in a browser and navigate to your profile.
- Create a new repository titled “montyhall”. Check the “Create with README” option.
- Copy the URL for your new repository.
- Open GitHub desktop and select File >> Clone Repository.
- Select the desired location of the folder and paste the URL into the appropriate dialogue.
- Clone your GitHub repo.
- Open the new “montyhall” folder that was just created by GitHub on your machine.
- Transfer all of the files inside of your old “montyhall” folder into the GitHub version.
- You should see the files appear in the GitHub Desktop app. In the “summary” field type something like “initial commit” and at the bottom left select “Commit to master”.
- Now up at the top select “Push origin”.
This last step sends all of the files to GitHub. They sould appear on your repo page shortly.
Now others should be able to install your package by typing:
Additional Resources
These are a few good resources for reference:
A nice tutorial by Fong Chun Chan
The official R Packages book by Hadley Wickham and Jenny Bryant
