You Can Build an R Package 🚀

If You Can Write a Function

Dr Rhian Davies

2026-02-25

Welcome 👋

🕓16:00 - 18:00 GMT

🧑‍💻 Code along on your laptop or Posit Cloud

💬 Tell me: Have you built a 📦? Why not?

About me

🧮 NHS Data Scientist

🗣️ Stats communicator

👩‍💻 #RStats educator

💜 Community champion

🔗 rhian.rbind.io

🚣‍♀️ 🚴‍♀️🧗‍♀️ 🏊‍♀️🏃‍♀️🚐🎼 🥁 🧶🏳️‍🌈 she/her

About you 💬

• Have you ever tried to build an R package?
• If not - why not?

What is an R package?

A tool kit 🧰

• Not just any box of random tools
• A kit that someone else should be able to pick up and use immediately without calling you for help.

R packages make it easier to 📦

• run code
• reuse across projects
• share with others
• manage dependencies and versions
• write nice documentation
• add tests

Myths

It doesn’t have to…

• have hundreds of functions
• be useful for anyone else
• do anything fancy
• be on CRAN
• be scary

• Small packages are fine!
• Build on the work of others
• Package warnings are okay!

⚠️ Warning

Building R packages can feel empowering and can be addictive.

What’s inside an R package?

What’s in your toolbox?

biketools/

It’s not just any box of random tools, it’s a kit that someone else should be able to pick up and use immediately without calling you for instructions.

DESCRIPTION

biketools/
├─ DESCRIPTION

It lists the brand name (package name), who built it (author), what it’s for (description), model/version number, and what other kits it needs to work with (dependencies).

Without this, no one knows what kind of work the toolbox is meant for, is it for bikes, plumbing, or electronics?

R/ folder

biketools/
├─ DESCRIPTION
├─ R/
│  ├─ chain-braker.R
│  ├─ multitool.R
│  ├─ pedal-wrench.R
│  ├─ tyre-levers.R

This is where the actual tools (functions) live.

Each tool has a job, each function solves a specific problem.

The better organised and labelled they are, the faster someone can find what they need.

man/ folder

biketools/
├─ DESCRIPTION
├─ R/
│  ├─ chain-braker.R
│  ├─ multitool.R
│  ├─ pedal-wrench.R
│  ├─ tyre-levers.R
├─ man/
│  ├─ chain-braker.Rd
│  ├─ multitool.Rd
│  ├─ pedal-wrench.Rd
│  ├─ tyre-levers.Rd

These tell you what the tool does, how to hold it, and give examples of using it safely.

NAMESPACE

biketools/
├─ DESCRIPTION
├─ R/
│  ├─ chain-braker.R
│  ├─ multitool.R
│  ├─ pedal-wrench.R
│  ├─ tyre-levers.R
├─ man/
│  ├─ chain-braker.Rd
│  ├─ multitool.Rd
│  ├─ pedal-wrench.Rd
│  ├─ tyre-levers.Rd
├─ NAMESPACE

• Some tools are kept in plain sight for anyone to grab (exported functions).

• Others are hidden in a secret compartment only you know about (internal functions).

• Sometimes your toolbox doesn’t have everything — you borrow tools from your friends’ toolboxes (imports).

Extra bits

biketools/
├─ DESCRIPTION
├─ R/
│  ├─ chain-braker.R
│  ├─ multitool.R
│  ├─ pedal-wrench.R
│  ├─ tyre-levers.R
├─ man/
│  ├─ chain-braker.Rd
│  ├─ multitool.Rd
│  ├─ pedal-wrench.Rd
│  ├─ tyre-levers.Rd
├─ NAMESPACE
├─ data/
├─ pkgdown/
├─ tests/
├─ vignettes/
├─ README.md
├─ NEWS.md

• Do my tools work correctly?
• How to do a basic bike service
• Spare bit of chain for trying chain breaker
• Glossy website
• Cool paint job

Let’s build 🛠️

👀 Demo: Create an R package

• Check we’re not in a project
• Initialise the package
• Look at the DESCRIPTION file
• What’s a license?
• Install the package

What makes a good package name?

👩‍💻 Exercise 1

• Run usethis::create_package("sums")¹
• Edit the DESCRIPTION file
• Run usethis::use_mit_license()
• Run devtools::install()

1. If you’re using Posit Cloud - skip this step!

🛠️ Adding functions

What’s a function?

• Has a name
• Takes some inputs
• Does something
• Returns something

 add <- function(x, y) {
  x + y
}

👀 Demo: Add a function

• add the add() function to the package in R/¹
• re-install the package
• does it work?

Need to introduce adding functions without getting hung up on #' @export and NAMESPACE

Could manually edit it FIRST export(hello) and then show later how it’s generated

1. We can’t use subfolders, but we can put multiple functions in one script

install vs load_all()

install()

• installs your package to your R library
• to install “ready” packages

load_all()

• loads all functions and data into your environment
• good for fast developing

👀 Demo: Load all

• Check environment is empty
• Run devtools::load_all()
• Does add.R work now?

👩‍💻 Exercise 2

• Copy the add() function in R/add.R

  add <- function(x, y) {
    x + y
  }

• Run devtools::load_all()

• Try out your function add(3, 4)

Adding documentation 📄

Lending out your tools

• We need to export our function
• Explicitly saying “you can use this”

👀 Demo: Export your function

• Add #' @export tag
• Re-install and check it works
• Inspect the NAMESPACE

Help files

• What happens when you run ?dplyr::slice_head?

Common roxygen tags

• @export: exports the function
• @param: what does an argument do? what are the defaults?
• @returns: what type of object does the function return?
• @examples: show the function in action#

👀 Demo: Document your function

• Add roxygen tags
• Run devtools::document()
• View help files

#' Add together two numbers
#' 
#' @param x A number.
#' @param y A number.
#' @returns A numeric vector.
#' @examples
#' add(1, 1)
#' add(10, 1)
#' @export
add <- function(x, y) {
  x + y
}

👩‍💻 Exercise 3

1. Add some {roxygen2} strings

   #' Add together two numbers
   #' 
   #' @param x A number.
   #' @param y A number.
   #' @returns A numeric vector.
   #' @examples
   #' add(1, 1)
   #' add(10, 1)
   #' @export
   add <- function(x, y) {
     x + y
   }

2. Run devtools::document(); devtools::load_all()

3. View the help file ?add

Checking your package ✅

Inspect your toolbox

• Do all the tools work?
• Does they have instruction manuals?
• Is there anything in there that shouldn’t be in there?
• Is it too heavy?

1 error ✖ | 1 warning ✖ | 2 notes ✖

An inspection before lending the box, ensures all tools are there and safe.

If something fails inspection, you get a report telling you exactly what to fix.

👀 Demo: Package check

• Run devtools::check()
• Inspect the output

👩‍💻 Exercise 4

1. Run devtools::check()

Don’t worry if it doesn’t all pass!

👀 Demo: Borrowing other functions

• Add cli_alert_success("You added two numbers") to add()

• Run check

• Prefix with cli::

• Run check

• Use usethis::use_package("cli") to update Imports:

• Run check

👩‍💻 Exercise 5

1. Add cli::cli_alert_success("You added two numbers") to add()

2. Run check

3. Use usethis::use_package("cli") to update Imports:

4. Run check

You did it! 🥳

Share your package 🔁

• Local install: devtools::install_local("biketools.zip")

• GitHub: devtools::install_github("statsrhian/biketools")

• CRAN: install.packages("biketools")

Bonus stuff 🎁

Use {usethis}

• use_readme_md()

• use_data()

• use_testthat()

• use_vignettes()

• use_pkgdown()

• use_news_md()

• use_github_actions()

Artwork by Allison Horst

Go forth and build! 👷‍♀️

• Remember to make a hex sticker

• Let me know how you get on 📧 @statsRhian