D4: Build Your Own R Package

Practical workshop — bring your laptop

Friday Workshop — ~50 minutes. Bring your laptop with R, RStudio, and the devtools and usethis packages installed. By the end of this session you’ll have a real, installable R package with at least one function in it.

Why Build a Personal R Package?

Every researcher who codes accumulates a collection of helper functions. A function you wrote for your dissertation that loads your data in a standard way. A custom ggplot2 theme that matches your lab’s figures. A function that computes a specialized statistic your field uses. A utility that reformats collaborator spreadsheets.

These functions usually live scattered across project folders — copy-pasted into new scripts every time you need them, gradually drifting out of sync with each other. A personal package solves this:

One library(yourname) loads all your tools
Version controlled in one place
Easy to share with collaborators
Installable on any machine in seconds
Forces you to document your functions properly

It also looks good: a public R package on GitHub is a concrete, verifiable demonstration of programming skill.

What We’ll Build

A minimal package called yourname (replace with your actual name or a project-relevant name) with:

One utility function — something you actually use
Proper documentation with roxygen2
A working DESCRIPTION file
Installable from GitHub with one line

Workshop Steps

1. Setup

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

2. Create the package skeleton

usethis::create_package("~/mypkg")  # creates the folder and opens a new RStudio project

3. Write your first function

Create R/utils.R and add a function — something real and useful:

#' Standard error of the mean
#'
#' @param x A numeric vector (NAs removed automatically)
#' @return A single numeric value
#' @export
se <- function(x) {
  x <- x[!is.na(x)]
  sd(x) / sqrt(length(x))
}

4. Document it

devtools::document()   # generates the man/ pages from roxygen comments

5. Install and test it

devtools::install()
library(mypkg)
se(c(1, 2, 3, 4, NA))
?se

6. Push to GitHub

usethis::use_git()
usethis::use_github()  # requires GitHub PAT — set up at https://github.com/settings/tokens

Now anyone can install your package with:

# install.packages("remotes")
remotes::install_github("yourgithub/mypkg")

Ideas for Your Own Package

What functions do you write over and over? Here are common candidates:

A custom ggplot2 theme: theme_mylab() — saves 10 lines in every script
A read_mydata() function that loads your standard dataset format and does all the cleaning
se(), cv(), cohens_d() — stats utilities base R doesn’t provide
A summary function that outputs a table in the format your PI wants
quick_lm() — fits a model and returns a tidy results table in one call

Resources

R Packages (2nd ed., free online) — Wickham & Bryan. The definitive reference.
usethis documentation — helper functions for every package task
devtools package

Note

You don’t need to publish to CRAN. A GitHub package is completely sufficient for personal use and sharing with collaborators — and it takes 20 minutes to set up.

--- title: "D4: Build Your Own R Package" subtitle: "Practical workshop — bring your laptop" --- ::: {.week-header} **Friday Workshop — ~50 minutes.** Bring your laptop with R, RStudio, and the `devtools` and `usethis` packages installed. By the end of this session you'll have a real, installable R package with at least one function in it. ::: --- ## Why Build a Personal R Package? Every researcher who codes accumulates a collection of helper functions. A function you wrote for your dissertation that loads your data in a standard way. A custom ggplot2 theme that matches your lab's figures. A function that computes a specialized statistic your field uses. A utility that reformats collaborator spreadsheets. These functions usually live scattered across project folders — copy-pasted into new scripts every time you need them, gradually drifting out of sync with each other. A personal package solves this: - One `library(yourname)` loads all your tools - Version controlled in one place - Easy to share with collaborators - Installable on any machine in seconds - Forces you to document your functions properly It also looks good: a public R package on GitHub is a concrete, verifiable demonstration of programming skill. --- ## What We'll Build A minimal package called `yourname` (replace with your actual name or a project-relevant name) with: 1. One utility function — something you actually use 2. Proper documentation with `roxygen2` 3. A working `DESCRIPTION` file 4. Installable from GitHub with one line --- ## Workshop Steps ### 1. Setup ```r install.packages(c("devtools", "usethis", "roxygen2")) ``` ### 2. Create the package skeleton ```r usethis::create_package("~/mypkg") # creates the folder and opens a new RStudio project ``` ### 3. Write your first function Create `R/utils.R` and add a function — something real and useful: ```r #' Standard error of the mean #' #' @param x A numeric vector (NAs removed automatically) #' @return A single numeric value #' @export se <- function(x) { x <- x[!is.na(x)] sd(x) / sqrt(length(x)) } ``` ### 4. Document it ```r devtools::document() # generates the man/ pages from roxygen comments ``` ### 5. Install and test it ```r devtools::install() library(mypkg) se(c(1, 2, 3, 4, NA)) ?se ``` ### 6. Push to GitHub ```r usethis::use_git() usethis::use_github() # requires GitHub PAT — set up at https://github.com/settings/tokens ``` Now anyone can install your package with: ```r # install.packages("remotes") remotes::install_github("yourgithub/mypkg") ``` --- ## Ideas for Your Own Package What functions do you write over and over? Here are common candidates: - A custom ggplot2 theme: `theme_mylab()` — saves 10 lines in every script - A `read_mydata()` function that loads your standard dataset format and does all the cleaning - `se()`, `cv()`, `cohens_d()` — stats utilities base R doesn't provide - A summary function that outputs a table in the format your PI wants - `quick_lm()` — fits a model and returns a tidy results table in one call --- ## Resources - [R Packages (2nd ed., free online)](https://r-pkgs.org) — Wickham & Bryan. The definitive reference. - [usethis documentation](https://usethis.r-lib.org) — helper functions for every package task - [`devtools` package](https://devtools.r-lib.org) --- ::: {.callout-note} You don't need to publish to CRAN. A GitHub package is completely sufficient for personal use and sharing with collaborators — and it takes 20 minutes to set up. :::