In this lab, we will learn how to write an R package.

Goal: by the end of this lab, you should be able to write an R package.

Creating a package

Note that loading devtools also attaches usethis.

library(devtools)
  1. Use create_tidy_package("FILEPATH/testing") to start a new R package called testing.

FILEPATH should be where you have all your SDS270 RStudio Project folders. Don’t nest this inside another RStudio Project folder. For example

  • macOS: Say your SDS270 materials are in ~/Documents/SDS270, then run create_tidy_package("~/Documents/SDS270/testing")
  • Windows: As Thu pointed out in this Slack message, it will be helpful to change your home/default directory in RStudio:
    • Go to Tools -> Global Options… -> General and under “Default working directory (when not in a project):”
    • Click Browse
    • Choose the directory that you want to set as your home directory (ex Desktop, Documents)
    • Click Apply
    • Click OK
    • Type create_tidy_package("") in the console, put your cursor in between the "", press TAB, find the directory you have your SDS270 materials in, and then add /testing
  1. Delete the FILEPATH/testing/tests/ folder

Within the new "FILEPATH/testing" folder you just created, delete the tests/ subfolder. This is used for unit testing, which is a more advanced topic

  1. Edit the DESCRIPTION file
  • Change the Title of your package
  • In Authors@R: Edit your last name, first name, and email
  1. Set up your package to create help files using roxygen2

Go to “Tools -> Project Options… -> Build Tools” and make sure that:

  • Generate documentation with Roxygen is checked
  • When you click on “Configure…”, “Automatically roxygenize when running: Install and Restart” is checked!
  1. Build your package by going to “Build” panel in RStudio and click “Install package”
  • This “builds” i.e. compiles / constructs your package locally. Build early, build often!
  1. Add a function to your package

Create a new .R R Script file and save it in the R/ folder as functions.R. The R/ folder is where all R functions need to be saved.

add_two_numbers <- function(x, y){
  z <- x + y
  return(z)
}
  1. Add a help file skeleton using roxygen2
  • Click your mouse anywhere inside the add_two_numbers() function, but not the lines that have { or }
  • Go to RStudio menubar -> Code -> Insert Roxygen Skeleton
  1. Test your package!
  • Build your package as indicated above
  • Test your function: add_two_numbers(4, 5)
  • Inspect your (incomplete) help file: ?add_two_numbers
  1. Complete your help file by adding documentation

Go to your add_two_numbers() function and add:

  • A title
  • A longer description
  • Descriptions of the inputs x and y
  • Description of the output that gets returned
  • An example of the functions use

See example on the screen

Added after lecture:

#' Add two numbers
#'
#' This is a braindead function to learn R packages with!
#'
#' @param x number 1
#' @param y number 2
#'
#' @return The sum of x and y
#' @export
#'
#' @examples
#' add_two_numbers(76, 66)
add_two_numbers <- function(x, y){
  z <- x + y
  return(z)
}
  1. Test your package again!
  • Build your package as indicated above
  • Test your function: add_two_numbers(4, 5)
  • Inspect your now help file: ?add_two_numbers
  1. Test that your package passes CRAN standards
  • Run an R CMD check by clicking on the “Check” button under the “Build” tab.
  • Continue until you have fixed all errors, warnings, and notes.
  1. Add dependencies to the Imports field in DESCRIPTION. Rebuild the package.

Under Imports, add each package you want your package to use on a new line, separated by comma’s. Your package should never load a package using library() or require(), rather add it to the DESCRIPTION file.

Imports: 
    dplyr,
    ggplot2
  1. Added after lecture Add a function that calls ggplot()

In your functions.R file, add:

#' Test Graph
#'
#' Tests whether I can use ggplot2
#'
#' @return graph
#' @export
#' @import ggplot2
#' @examples
test_graph <- function() {
  ggplot(data = mtcars, aes(x = wt, y = mpg)) +
    geom_point()
}
  • Note the @import line where we import the ggplot2 package
  • Build the package again
  • Test this function by running test_graph()

Engagement

Prompt: Paste the errors, warnings, or messages that you get from R CMD check to the #questions channel. What questions do you have about what those mean?