In jr-packages/jrPackage: Jumping Rivers: Building an R Package

My first package

RStudio projects

RStudio projects make it straightforward to switch between analyses. You can create an RStudio project:

• in a brand new directory or

• in an existing directory where you already have R code and data or

• by cloning a version control\sidenote{Git or subversion} repository.

\noindent Each project has its own working directory, workspace, history, and source documents. When we create an RStudio package project, this will create a new directory that contains five files.

• .RbuildIgnore: this file contains a list of file names that the R build process should ignore when constructing your package. For example, the .Rproj file.

• DESCRIPTION: an overview of your package\sidenote{\url{http://goo.gl/AXSft}}.

• *.Rproj: an RStudio project file.

• NAMESPACE: a file that contains exported/exposed package functions\sidenote{\url{http://goo.gl/I5yGf8}}.

\noindent Your package directory will also contain two directories:

• man/: documentation directory. When you use the help function in R, the help pages returned live in this directory.

• R/: R file directory. All R functions exported from your package belong in this directory.

Tasks

1. Create a “package” project, via File -> New Project -> New Directory -> R Call the package pkg and select the directory you want to store the package in. Then click Create Project Congratulations - you have just created your first package called pkg.

2. Click Build -> Install and Restart

3. Now type

r library("pkg") hello()

1. Look at the NAMESPACE file. Notice that the function hello() has been exported.

2. The hello() function has also been documented r help("hello") The associated documentation file is in the man/ directory.

The roxygen2 package

Keeping the NAMESPACE file and documentation up-to-date is a painful experience. To ameliorate the process, we use the roxygen2 package to automatically generate the necessary entries. Above function definitions we add roxygen2 tags. The tags are of the form:

#' @export
#' @details
#' @aliases

\noindent Notice the tags are just R comments.

Tasks

1. Check that you have the necessary R packages installed

r library("devtools") library("roxygen2") If you don’t have them installed, then install them in the usual way

r install.packages(c("devtools", "roxygen2"))

1. Click on

Build -> Configure build tools

then select

Generate documentation with Roxygen and click OK. Now when we build our package, RStudio will automatically run

r library("roxygen2") roxygenise(".")

1. In the file R/hello.R add

r #' @export

just above the hello() function, i.e.

r #' @export hello <- function() { print("Hello, world!") }

The export tag above the hello() function indicates that we want to export\sidenote{Export means the users loading this package, can access this function.} this particular function.

1. Now delete the man/ directory and the NAMESPACE file\sidenote{The reason for deleting these is that we will automatically generate them using \textbf{roxygen2} - more details below.}. Select\sidenote{The keyboard shortcut for this is Ctrl + B.}

Build -> Install and Restart \noindent You should now be able to load your package with r library("pkg") \noindent and call the hello function r hello()

1. Open the NAMESPACE file. You should see the entry

r # Generated by roxygen2: do not edit by hand export(hello)

Adding new functions

All R functions that we create in our package are saved in the R/ directory\sidenote{The files can have a \texttt{.R} or \texttt{.r} file extension. Personally, I prefer \texttt{.R}.}. This directory can contain multiple files.

Tasks

1. Create a new file in the R/ directory called basic.R. In this file add the following code

r #' @export add = function(x, y) { return(x + y) } Install and restart your package\sidenote{Remember the keyboard shortcut Ctrl + B} . After reloading your package, the following code should run

r library("pkg") add(1, 2)

1. Create a new function called check_numeric()

r check_numeric = function(x) all(is.numeric(x))

\noindent and save it in the basic.R file.

1. Now use check_numeric() in the add() function

r add = function(x, y) { if (!check_numeric(c(x, y))) stop("Not numeric") x + y } \noindent Rebuild your package and check that the add() function still works.

1. Notice that we haven’t exported the check_numeric() function\sidenote{Remember to export a function, the function name should be in the \texttt{NAMESPACE} file.}, so this will raise an error

r library("pkg") check_numeric(1)

\noindent but we can access any non-exported function in a package using the ::: operator

r pkg:::check_numeric(1)

\noindent We can access\sidenote{The benefit of doing this is that we haven’t loaded the package.} any exported function using ::

r pkg::add(1, 1)

1. Now create a function subtract() and export this function. Rebuild your package and check that this works OK.

\sloppy 6. Delete your package and re-add the functions: add(), check_numeric() and subtract()\sidenote{The purpose of this is to highlight how easy it is to create packages.}.

jr-packages/jrPackage documentation built on Dec. 4, 2020, 8:27 a.m.