Building R packages

This practical training will cover the basics of modern package development in R with a focus on the following three aspects: (1) how to turn your code into functions, (2) how to write tests and documentation, and (3) how to share your R package on GitHub..

Andrew MacDonald
2021-05-04

via GIPHY

R packages! they are kind of like cookies:

But most of all: cookies are delicious for what they contain: chocolate chunks, candy, oats, cocoa. However, all cookies share some fundamental ingredients and nearly identical structure. Flour, saturated with fat and sugar hydrated only with an egg, flavoured with vanilla and salt. The basic formula is invariant and admits only slight deviation – otherwise, it becomes something other than a cookie.

This workshop is devoted to the study of cookie dough.

Mise en place : development environment

We’ll explore a few useful packages in this workshop. The first two in particular are very popular tools for modern-day R package development:

install.packages("devtools")
install.packages("usethis")
install.packages("testthat")
install.packages("assertthat")

Building an R package also requires specific tools for compiling the finished package. Run the following line to make sure you have the development environment:

devtools::has_devel()

If you do not have the software to build R packages, you should see a message which will help you find the correct links to download what you need!

Windows will need RTools. First do the check above to see if you are already set up. If not then download the software here.

and Install. After that, open R and run the following:

writeLines('PATH="${RTOOLS40_HOME}\\usr\\bin;${PATH}"', con = "~/.Renviron")

and restart R. Then run the check above once more to confirm

The structure: flour and sugar

No cookies without carbs

An R package is essentially a folder on your computer with specific structure. We will begin by creating an empty R package and taking a tour!

Open your R code editor, and find out where you are:

getwd()

This is to prepare for the next step, where we will choose a location for our R package folder. Please be intentional about where you place your R package! Do not place it in the same space as another package, Rstudio project or other project. Create a new and isolated location for it.

I am working from an existing R project in my typical R Projects folder, so I go up one level:

usethis::create_package("../netwerk")

Let’s run R CMD CHECK right away. We will do this MANY TIMES.

devtools::check()

We should see some warnings! let’s keep these in mind as we continue our tour.

The DESCRIPTION

The most important file to notice is the DESCRIPTION. This gives the general page for the entire package.

Add your name here.

Add a license

usethis::use_mit_license(copyright_holder = "")

note about the different roles taht R package authors can have. Funny ones. but creator and maintainer are the key ones.

Note the R folder. We’ll get much more into that later

keeping notes

create an R file

usethis::use_build_ignore("dev.R")

the docs folder

here we have a very minimal version of an R packages we’re going to be adding to it as the course progresses.

One thing we can do right away is build and check the R package

What exactly is happining here? slide from R package tutorial.

Lots of checkpoints and progress confrimations along the way.

OK so what is that all about? we have compiled the R package and it has gone to where the R packages on our computer go.

There is a natural cycle to how the different steps in an R package workflow proceed – see the documentation for this lesson – we will be following this process (TK another pictures?

Ok so now that we ahve the basic structure, let’s talk about some content for the R package. I received the donation of a little R function already that we can use to create this workflow in a nice way

This R function (explain what the function does)

OK so let’s focus on just one part of this function.

load all – shortcut

how do we do this in VScode?

how to add something to the .Rbuildignore? it would be nice to have a little .dev script as a space to create all the ohter dependencies that are involved in making an R package.

This workshop borrows heavily from some excellent sources:

https://builder.r-hub.io/about.html

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/bios2/bios2.github.io, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".

Citation

For attribution, please cite this work as

MacDonald (2021, May 4). BIOS2 Education resources: Building R packages. Retrieved from https://bios2.github.io/posts/2021-05-04-building-r-packages/

BibTeX citation

@misc{macdonald2021building,
  author = {MacDonald, Andrew},
  title = {BIOS2 Education resources: Building R packages},
  url = {https://bios2.github.io/posts/2021-05-04-building-r-packages/},
  year = {2021}
}