Build your own toolbox 🧰

R package development

Dr Rhian Davies

2025-09-03

Set-up 👩‍💻

• Welcome! We’ll start the workshop shortly

• If you want to code along with me, please follow the set-up instructions ⬇️

statsrhian.github.io/build-r-pkg/set-up

• If you’d prefer to just want to sit back and watch, that’s fine too 😊

• WiFi: RSS edin2025

Welcome

What is an R package?

Why build one?

• Reproducible
• Reusability across projects
• Testing is easier
• Dependency management
• Easy to use documentation
• It’s fun and empowering
• Sharing is caring

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!

Your personal toolbox

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.

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 🛠️

👀 Create an R package

👩‍💻 Create an R package

• Run usethis::create_package("sums")
• Open the DESCRIPTION file and customise it
• Run usethis::use_mit_license()
• Run devtools::install()

👀 Add a function

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

👩‍💻 Add a function

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

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

• Add export(add) to NAMESPACE

• Run devtools::load_all()

• Try out your function add(3, 4)

👀 Document your function

#' 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
}

👩‍💻 Document your function

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

Package check

Inspect your toolbox before lending it out

• 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?

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.

👀 Package check

👩‍💻 Package check

1. Run devtools::check()

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

👀 Using other functions

👩‍💻 Using other functions

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

2. Run check

3. Prefix with cli::

4. Run check

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

6. Run check

Usethis

• use_readme_md()

• use_roxygen_md()

• use_news_md()

• use_github_actions()

• use_data()

• use_testthat()

• use_vignettes()

• use_pkgdown()

Developer process 🔄

Editing code

1. Make code changes
2. devtools::load_all()

Add new function

1. Create and @export
2. devtools::document()
3. devtools::load_all()

Editing docs

1. Edit function docs
2. devtools::document()

All changes ready

1. devtools::check()
2. devtools::install()
3. Publish code

Share your package

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

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

• CRAN: install.packages("biketools.zip")

Go forth and build! 👷‍♀️

• Remember to make a hex sticker

• Let me know how you get on 📧 @statsRhian