Creating an R Package

R Café @ TU Delft

Icebreaker

Who attended Part 1?

Who has started creating their own package?

What is your favourite R package?

Part 1

Why?

There are benefits (beyond sharing) to bundling your code as an R package:

  • sharing with others is convenient
  • it’s a common template that R users will recognise
  • there are many useful tools and resources for developing R packages
  • it will help you understand the structure of an R package

You can also bundle your research project as an R package!

R Cafe package

We need your help!

Your mission, should you choose to accept, is to help create a communidefaultnaming-things/):

  • Is the package name hard to say?
  • Is the package name hard to spell?
  • Can you remember the name of the package?
  • Does the package name evoke the task it does, or perhaps fit into some sort of larger pun or story?

R package: naming

Ideas:

Check if the name is already in use

available::available("name")

R package: in practice

Most of the process can be achieved with the {devtools} and {usethis} packages

install.packages(c("devtools", "usethis"))



Important

Windows users will have to install Rtools

R package: in practice

library(usethis)
create_package("<path/to/packagename>")

This creates the following files:

<packagename>
├── .Rbuildignore
├── .gitignore
├── DESCRIPTION
├── NAMESPACE # DO NOT EDIT
├── R
└── <packagename>.Rproj

R package: functions

Main part of the R package

Tasks:

  • enter new event into a scheduler
  • create a calendar event (.ics)
  • send emails for communication

Useful for participants:

  • retrieve info on upcoming sessions
    • date, time, room, topic, speaker, registration link
  • retrieve resources from previous sessions

R package: functions

(Code-along) Extract information on upcoming session

R package: load functions

Whenever you create or modify a function, it needs to be (re-)loaded

This can be done with the load_all() function from {devtools}

devtools::load_all()

Add dependencies to DESCRIPTION

usethis::use_package("packagename")

This will make sure packagename is installed on a user’s system when your package is installed.

R package: making functions accessible

If you install the package now, the functions will be missing

They need to be exported

this can be done by adding

#' @export
function_name <- function(){
  # function body
}

Then run

devtools::document()

to modify NAMESPACE (don’t modify manually!)

Your turn!

R package: contributors

Add yourself as a contributor to the DESCRIPTION under Authors@R

Authors@R: c(
    person("Example", "Person1", email = "ex1@example.com", role = c("aut", "cre"),
           comment = c(ORCID = "0000-0001-2345-6789")),
    person("Example", "Person2", role = "aut",
           comment = c(ORCID = "0000-0002-2345-6789"))
  )

abbreviations:

  • aut = author
  • cre = creator (maintainer)
  • ctb = contributor

Note

The DESCRIPTION file format is that of a version of a ‘Debian Control File’ (https://www.debian.org/doc/debian-policy/ch-controlfields.html)

R package: build and distribute

Package states:

  • source
  • bundled
  • binary
  • installed
  • in-memory

R Packages (2e)

R package: build and distribute

Package locations

Official: CRAN install.packages("packagename")

Development: GitHub (mostly) devtools::install_github("username/packagename")

Part 2

R Package: summary

Naming

  • Is the package name hard to say?
  • Is the package name hard to spell?
  • Can you remember the name of the package?
  • Does the package name evoke the task it does, or perhaps fit into some sort of larger pun or story?

R Package: summary

Functions

  • core part of the package
  • (re-)load when modified devtools::load_all()
  • need to be exported #' @export

Documentation

  • create documentation for functions and data
  • incorporate documentation devtools::document()

R Package: summary

We created a package!

Download the binary from the R console:

# To download the binary
devtools::install_github("delft-rcafe/tudrcafe")

Or clone the git repo to get the source:

# To download the source
git clone git@github.com:Delft-RCafe/tudrcafe.git

R package: testing

A good way to catch issues is the {testthat} package

which you can apply to your package with… you guessed it, {usethis}

usethis::use_testthat()

it creates

tests
├── testthat
└── testthat.R # DO NOT EDIT

R package: testing

Add a testing script

usethis::use_test("functions") # name of test file

Then add a test to run:

test_that("multiplication works", {
  expect_equal(2 * 2, 4)
  expect_false(2 * 2 == 6)
})
Test passed 🎊

This is just a generic example; ideally you should include statements about functions in the package

Run tests when you modify functions

devtools::test()

Testing is also part of check()

R package: checking

Check that your package meets criteria for a functional R package

devtools::check()

This function will tell you about issues with your package

  • errors: Your package won’t work
  • warnings: your package will work but breaks some important conventions
  • notes: your package will work but could benefit from minor modifications

R package: workflow

Here is a typical workflow when working on package development:

  • Edit one or more files below R/.default
  • document() (if you’ve made any changes that impact help files or NAMESPACE)
  • load_all()
  • Run some examples interactively.
  • test() (or test_active_file())
  • check()

To do for tudrcafe

  • More testing
  • More functionality
    • R Cafe schedule (spreadsheet)
  • README
  • Contributing guidelines

Resources

Official CRAN documentation

R Packages book

usethis package documentation

testthat package documentation

Upcoming sessions

22nd March - Topic: TBD
26th April - Topic: APIs (featuring Sofia Gil Clavel)
24th May - Topic: TBD

delft-rcafe.github.io/home/
rcafe-lib@tudelft.nl
delft-rcafe