Package Your Research: Why And How To Turn Your Data Into An R Package

Neil Birrell

School of Biological Sciences, Waipapa Taumata Rau

2026-07-02

The guide this talk follows

STAY ON SLIDES for this opening stretch. The whole talk is one free chapter, so nobody needs to scribble notes. Frame it: I’ll build it live with a toy, you can redo it from the written version.

Everything today comes from one free online chapter:

• Data packages, in rstudio4edu: https://rstudio4edu.github.io/rstudio4edu-book/data-pkg.html

If you want the written version to work through later, start there. This talk is a live run at the same workflow.

Go deeper

r-pkgs 2e is the reference for anything package-related. Happy Git is the one to grab the moment Git misbehaves. Point, don’t dwell.

Two books cover the full picture:

• R Packages (2e), Wickham & Bryan: https://r-pkgs.org
• Happy Git with R, Bryan: https://happygitwithr.com

The first is the reference for everything package-related. The second is the one to reach for the moment Git misbehaves.

Who am I?

Twenty seconds. Weevils, museum specimen data. This sets up why the data-sharing problem is a real one for me, not a toy example.

• I’m a researcher working on the taxonomy and ecology of New Zealand weevils.
• I’m based in Tāmaki Makaurau
• I spend a lot of time in museum collections or up mountains looking for weevils

I produce data that is used in different projects

The same specimen table feeds taxonomic revisions, ecological models, and outreach. One dataset, many projects pulling on it.

• A database of specimen records for Anagotus spp. (large flightless weevils, endemic to NZ)
• From many different institutions
• This data gets used in different projects: taxonomic revisions, ecological modelling, outreach, etc.

The problem: one copy, many projects

The pain everyone recognises: copies drift and you lose track of which is the real one. Land this, it is the motivation for the whole talk.

• I started off with the data on my laptop
• Copying the csv file to each project was error-prone
• I wanted a single canonical version of the data, that could be updated and shared easily

The problem: who needs to reach it?

Not only me. Collaborators, reviewers, the public. Dropbox links and email attachments rot.

• How do I make this data easily accessible?
• For my projects
• For collaborators
• For reviewers
• For the wider community

What I tried, and why none of it stuck

Quick and a bit self-deprecating. Each fix broke in its own way, which sets up the package as the thing that finally stuck.

• I tried lots of things:
  • hosting a .csv on Google Drive, Dropbox
  • airtable
  • I tried creating a very complicated github project

The solution

Key line: a data package is just a normal R package that carries data instead of functions. Nothing exotic here.

• A data package
• A standardised way to share data in R
• A data package is a normal R package, but it contains only data and documentation
• Can be hosted on a platform such as github or uploaded to CRAN

Why bundle data into a package?

The three-line install is the hook. somedata is a placeholder; the real package arrives at the very end.

A lot of data ends up shared as a .csv over email, or a Supplementary File on a journal site, or a path that only works on one machine.

A data package does better. Once it exists, anyone gets the data in three lines:

remotes::install_github("user/somedata")
library(somedata)

df_something

What are the benefits?

DOI, built-in docs, types preserved, versioned in Git. These are the payoffs we spend the rest of the talk building toward.

You get:

• One canonical version of the data, citable with a DOI
• Built-in documentation: ?df_something
• Lazy-loaded tibble, fast to read
• Versioned through Git, archived on Zenodo
• Anyone can install it in one line

The mental model: getting a fish ready for sushi

The metaphor that holds the talk together. Raw fish, then the roll, then the menu, then the chef explaining it. Every Part from here maps onto one of these four folders. Illustration is rstudio4edu’s, credited on the slide.

Four folders, four jobs:

• data-raw/ the raw fish: source CSVs and the scripts that clean them
• data/ the sushi roll: one tidy .rda, ready to serve
• R/ the menu: what each column means
• man/ the chef at your table: the help page a user actually reads

Illustration: rstudio4edu, CC BY-NC

Every stage from here maps onto one of these four folders.

The whole pipeline in one picture

If they remember one slide, this is it. One function per arrow, data moving left to right. Point at use_data_raw, use_data, use_r, document as you say them.

Illustration: rstudio4edu, CC BY-NC

Each function moves the data one folder to the right. That is the whole talk.

Mental framework: four folders

Same four folders as a table, mapped to the toy. data-raw and man are the two people trip on: data-raw never ships, man is generated for you.

Folder	Purpose	In our toy mothsurvey.data
data-raw/	Raw CSVs and cleaning scripts (not shipped)	1 source CSV, 1 cleaning script
data/	Cleaned .rda files (shipped)	df_moths.rda
R/	Roxygen-documented .R files	df_moths.R, mothsurvey.data-package.R
man/	Auto-generated .Rd help files	df_moths.Rd, mothsurvey.data-package.Rd

Plus the root: DESCRIPTION, NAMESPACE, LICENSE, README.md.

Raw data → cleaned object → documented object → installable, citable package.

Assumptions

Quick gut-check of the room. A GitHub account and basic Git is the only hard prerequisite. Reassure them the two books cover any gaps.

• A GitHub account and basic Git (clone, commit, push)
• Comfortable in the IDE (e.g., RStudio, VScode, Positron)
• Difference between an .R script and a .qmd or .rmd
• Reading and tidying data with the tidyverse

Tip

If anything above is shaky, the two books from the start of the talk (Happy Git with R and R Packages 2e) are the places to go.

What we’ll build

Set expectations: a tiny five-row moth dataset, deliberately small so the plumbing stays visible. anagotus is the same shape at scale, saved for the end.

We’ll build a small package live: a toy called mothsurvey.data, five rows of light-trap moth counts.

1. Scaffold the package and connect it to GitHub
2. Drop a raw .csv into data-raw/ with a cleaning script
3. Export the cleaned object as .rda in data/
4. Document the dataset with Roxygen → man/
5. Fill in DESCRIPTION, choose a license
6. Document the package itself
7. Build, check, install
8. Ship to others via install_github()

At the end we’ll look at the same workflow at real scale, in my own package anagotus.data.

Part 1 · Get set up

=> SWITCH TO RSTUDIO now, and you stay there through Parts 1 to 6. From here the slides are the map and RStudio is where the work happens. First move: create the empty repo on GitHub, clone it, open it.

Empty repo → package scaffold

Packages you’ll need

=> RSTUDIO. Install and library the four. One breath each: usethis scaffolds, devtools builds, roxygen2 documents, here handles paths. If they are already installed, just library() them to save demo time.

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

library(devtools)
library(usethis)
library(roxygen2)

Three workhorses:

• usethis: scaffolds files and folders
• devtools: builds, checks, documents, installs
• roxygen2: turns #' comments into .Rd help files

Note

Everything that follows should work similarly in Positron. References to the “Build pane” map to Positron’s package commands.

Getting-started workflows

=> RSTUDIO. GitHub-first is cleaner. Empty repo, clone, then create_package(getwd()). Say No when it asks about overwriting. A fresh session opens with the Build tools enabled, use that window.

Recommended: GitHub first

1. Create empty repo on GitHub (no README, no .gitignore)
2. Copy the clone URL
3. IDE → New Project → Version Control → Git
4. Paste URL, click Create
5. In console:

usethis::create_package(getwd())

Choose No when asked about overwriting.

A second IDE session opens with package-building tools enabled. Use that one.

A note on naming

The folder name becomes the package name, so name the repo mothsurvey.data from the start. Dots are allowed, hyphens and underscores are not. The .data suffix signals a data-only package.

The package name is the repo name. Rules:

• Letters, numbers, and . only
• Must start with a letter
• Must not end with .

Our demo package is mothsurvey.data, using the <topic>.data convention: a clear signal that it’s a data-only package. Other patterns you’ll see in the wild:

• nzcarabidae, pollinatortraits: short, no separator
• lepidata, mothdata.nz: topic-first
• weevilSpecimens: camelCase (works but less common)

Hyphens and underscores are not allowed in package names. Dots are.

Part 2 · Clean data

=> RSTUDIO. This is the raw-fish-to-roll step: take a messy CSV and turn it into one clean .rda.

🎣 data-raw/ → 🍣 data/

Scaffold data-raw/

=> RSTUDIO. Run use_data_raw(). Point out it added data-raw to .Rbuildignore, so that folder is your workshop and never ships. Packages you use to clean here do not become dependencies of the package.

usethis::use_data_raw()

This creates:

• data-raw/ (added to .Rbuildignore, so it doesn’t ship)
• A starter script data-raw/DATASET.R

data-raw/ is the messy workspace. Cleaning here can use tidyverse, sf, janitor, lubridate, anything: those packages do not become dependencies of your shipped package.

Drop in the raw data

=> RSTUDIO. Copy moth_counts.csv into data-raw and open it. Show the mess out loud: trailing space, lowercase declana, date stored as text. Ask the room to spot the problems.

Our toy source, data-raw/moth_counts.csv, five nights of light-trap catches:

site,date,species,count
Cascade Kauri,2025-01-12,Declana floccosa,3
Cascade Kauri,2025-01-12,Epiphryne verriculata ,1
Waharau,2025-01-19,declana floccosa,2
Waharau,2025-01-19,Epiphryne verriculata,5
Cascade Kauri,2025-02-02,Declana floccosa,4

Deliberately messy: a trailing space on one species, an inconsistent capital, and dates stored as text. Real data always arrives like this.

One small cleaning script

=> RSTUDIO. Open moth_counts.R and walk the three fixes: squish the space, sentence-case the name, parse the date. Small on purpose. The point is that data-raw is where any tidying lives.

data-raw/moth_counts.R:

library(tidyverse)

df_moths <- readr::read_csv(here::here("data-raw", "moth_counts.csv")) |>
  mutate(
    species = str_squish(species),      # trim the stray space
    species = str_to_sentence(species), # fix the capital
    date    = lubridate::ymd(date)      # text → real date
  )

One read, three small fixes. That’s the whole cleaning step for the toy. The point is that data-raw/ is where arbitrary tidying lives.

Save it, then verify

=> RSTUDIO. use_data writes data/df_moths.rda, the thing that actually ships. Explain load_all: it loads the package as if installed, without installing. If df_moths prints, it worked.

At the end of the script:

usethis::use_data(df_moths, overwrite = TRUE)

Writes data/df_moths.rda, the shipped artefact.

devtools::load_all()

df_moths
#> # A tibble: 5 × 4
#>   site          date       species              count
#>   <chr>         <date>     <chr>                <dbl>
#> 1 Cascade Kauri 2025-01-12 Declana floccosa         3
#> 2 Cascade Kauri 2025-01-12 Epiphryne verriculata    1
#> # … with 3 more rows

If you can call the object by name, it’s in the package.

Why .rda and not .csv?

Brief. It is binary, but fast and type-safe, and the readable CSV stays in data-raw as the source. This question always comes up, so pre-empt it.

• Faster to load than parsing text
• Preserves column types (<chr>, <dbl>, <date>, <fct>) exactly
• Lazy-loaded, available the moment users attach the package
• Compressed by default

The cost: it’s binary. But you keep the source CSV in data-raw/ for diff-friendliness, and the cleaning script is the audit trail.

Part 3 · Check

=> RSTUDIO. Run the check now so the warnings appear, then we fix them. Setting up that warnings on the first pass are normal.

Does R agree this is a package?

Run the check

=> RSTUDIO. check(document = FALSE). Two warnings are expected and healthy: undocumented dataset, and the R version line. We fix both next. Reassure them red text is not failure here.

devtools::check(document = FALSE)

First-time output usually includes:

❯ checking for missing documentation entries ... WARNING
  Undocumented data sets: 'df_moths'

❯ checking data for ASCII and uncompressed saves ... WARNING
  package needs dependence on R (>= 2.10)

Both are expected. The dataset isn’t documented yet, and the dependency line is missing from DESCRIPTION. Fixed next.

Part 4 · Document the dataset

=> RSTUDIO. The menu step: telling users what each column means. Good moment to explain R/ and man/ clearly.

🍣 data/ → 📋 the menu (R/ and man/)

Write the Roxygen block

=> RSTUDIO. use_r makes R/df_moths.R. Context worth saying: R/ is what you write by hand, the #’ roxygen comments. The bare df_moths line at the bottom is what the documentation attaches to. Paste the block.

usethis::use_r("df_moths")

Creates R/df_moths.R. Add the documentation above the dataset name:

#' Light-trap moth counts from two Auckland sites
#'
#' A small toy dataset of nightly light-trap catches, used to
#' demonstrate how to build an R data package.
#'
#' @format A tibble with 5 rows and 4 variables:
#' \describe{
#'   \item{site}{chr Survey site name.}
#'   \item{date}{date Night of the survey.}
#'   \item{species}{chr Moth species (Lepidoptera: Geometridae).}
#'   \item{count}{dbl Number of individuals caught.}
#' }
#' @source Made up for teaching.
"df_moths"

The \describe{} block matters

Slide moment. Every column gets a line. This is the difference between data someone can use and a mystery table. Four variables here, fifteen in the real package.

It’s how a user knows what each column means without opening your code. Document every variable:

• site: where the trap was run
• date: the night of the survey (a real date, not text)
• species: the moth, with its family in brackets
• count: how many came to the light

Four variables here. In a real dataset it might be fifteen, and this block is where future-you (and reviewers) will thank present-you.

Make the docs concrete

=> RSTUDIO. document() turns your roxygen in R/ into .Rd files in man/. Context: man/ is generated, never hand-edit it, your next document() would overwrite it. Then ?df_moths shows a real help page. This is the R/ to man/ arrow on the pipeline.

devtools::document()

Walks every #' block in R/ and writes matching .Rd files into man/.

?df_moths

Returns a real help page, with Format, Source, and the full variable describe block.

Tip

Re-run document() every time you edit Roxygen comments. The man/ folder is generated, never edit it directly.

Part 5 · Package metadata

=> RSTUDIO. The paperwork: who made it, the licence, and the package-level help page.

DESCRIPTION, license, package-level docs

Fill in DESCRIPTION

=> RSTUDIO. Open DESCRIPTION and replace it with this. Depends: R (>= 3.5) clears the second check warning. Authors@R with an ORCID is what makes the package citable.

The toy’s DESCRIPTION:

Package: mothsurvey.data
Title: Toy Light-Trap Moth Counts
Version: 0.1.0
Authors@R:
    person("Neil", "Birrell", email = "nbir012@aucklanduni.ac.nz",
           role = c("aut", "cre"),
           comment = c(ORCID = "0000-0002-7961-1626"))
Description: A tiny toy dataset of light-trap moth counts, used to
    demonstrate how to build an R data package.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
Depends: R (>= 3.5)
Imports: tibble
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.3.3

What each field is doing for you

Slide moment, do not read every line. Call out three: Authors@R makes it citable, Depends fixes the warning, LazyData makes the data available the moment someone runs library().

• Authors@R: with an ORCID, you’re citable
• URL: points to both the repo and the pkgdown site (add these once it’s on GitHub)
• BugReports: wires bug.report() to GitHub issues
• Depends: R (>= 3.5): silences the ASCII/compression warning
• LazyData: true: datasets are available on attach, no data() needed
• Imports: tibble: lets datasets print as tibbles
• Roxygen: list(markdown = TRUE): use markdown in roxygen, not Rd syntax

License

=> RSTUDIO. use_mit_license writes the files. Say the honest bit: unlicensed data is not reusable by default, so pick something. For data, CC-BY or CC0 are also fine choices.

The simplest defensible choice for shared research data is MIT:

usethis::use_mit_license("Neil Birrell")

Writes both LICENSE and LICENSE.md, and updates DESCRIPTION.

For data specifically you may prefer CC-BY or CC0. The principle is the same: pick one, name it in DESCRIPTION, ship the file.

Note

Unlicensed data is, by default, not freely usable. Choose something.

Package-level help page

=> RSTUDIO. use_package_doc makes the landing page you get from ?mothsurvey.data. use_tibble makes the datasets print as tibbles. Then document() once more. This is the fiddliest bit, go slow.

usethis::use_package_doc()

Creates R/mothsurvey.data-package.R. With it open, run:

usethis::use_tibble()

The file ends up as:

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
#' @importFrom tibble tibble
## usethis namespace: end
NULL

Then devtools::document() one more time. Now ?mothsurvey.data shows the package landing page.

Part 6 · Build and install

=> RSTUDIO. Now turn the source into a real installed package and use it like any other.

📋 → 🧑‍🍳 the finished package

Build and install

=> RSTUDIO. install() then restart, or the Build pane button. After the restart, library(mothsurvey.data) and open the help pages. Run check one final time, aim for 0 errors, 0 warnings, 0 notes. This is the payoff, let it land.

Build pane → Install and Restart, or:

devtools::install()

A fresh R session loads. Then:

library(mothsurvey.data)
?mothsurvey.data
?df_moths

df_moths |>
  dplyr::count(site, sort = TRUE)

Note

Run devtools::check(document = FALSE) one final time. Aim for 0 errors, 0 warnings, 0 notes before pushing.

Part 7 · Deliver

=> SWITCH TO BROWSER or TERMINAL. Commit, push, tag a release. Then show the one-line install anyone can run.

Push, tag, share

Deliver

=> Browser or RStudio terminal. Push and tag. The install_github line is the whole point: one command and a collaborator has the data. Zenodo DOI comes from connecting the repo, mention it but do not set it up live.

Commit, push, tag a release on GitHub. From there, anyone installs it in one line:

# install.packages("remotes")
remotes::install_github("nbir012/mothsurvey.data")

library(mothsurvey.data)
df_moths

Tagged releases also trigger a Zenodo deposit (once you’ve connected the repo), giving you a versioned DOI for every release.

Updating workflow

=> BACK TO SLIDES. Reassure them: updating is the same steps, smaller. Edit, re-run, document, check, bump the version, push. The instructions live in the script, not in your head.

When raw data or cleaning logic changes:

1. Edit the CSV and/or the cleaning script
2. Re-run it
3. Update Roxygen if variables changed
4. devtools::document()
5. devtools::check(document = FALSE), aim for clean
6. Build → Install and Restart
7. Bump Version in DESCRIPTION, commit, push, tag release
8. Zenodo mints a new DOI; users re-install for the update

Put these steps in a comment at the bottom of your cleaning script. They live in the repo, not in someone’s head.

The whole build, one screen

=> SLIDES. The recap. Everything they just watched in one screen. Tell them to photograph this one.

# 1. Empty repo on GitHub → clone → open in IDE
usethis::create_package(getwd())

# 2. Raw CSV plus cleaning script go in data-raw/
usethis::use_data_raw()
# (drop moth_counts.csv and moth_counts.R there)

# 3. At the end of the cleaning script:
usethis::use_data(df_moths, overwrite = TRUE)

# 4. Document the dataset
usethis::use_r("df_moths")     # add roxygen comments

# 5. Document the package
usethis::use_package_doc()
usethis::use_tibble()
usethis::use_mit_license("Neil Birrell")

# 6. Build
devtools::document()
devtools::check(document = FALSE)
devtools::install()

# 7. Push to GitHub, tag a release. Done.

The real thing · anagotus.data

=> STAY ON SLIDES for the rest. Toy is done. Now the real package: same shape, more of everything. This is the why-it-was-worth-it section.

From five rows to two thousand

For example: anagotus.data

2,145 records, eight institutions, one DOI. Optional: open ?anagotus.data or the pkgdown site in a browser tab if you have time.

Label data for Anagotus spp. specimens (large flightless weevils, endemic to NZ) housed in museum collections.

• 2,145 specimen records
• 15 variables: institution code, catalog number, collector, date, coordinates, locality, species, etc.
• Collated from 8+ institutions (NZAC, MONZ, NHMUK, ANIC, CMNZ, AK, OMNZ, LUNZ, FRNZ)
• Released in conjunction with the Anagotus taxonomic revision submitted to NZJZ

> df_anagotus
# A tibble: 2,145 × 15
   institution_code catalog_number
   <chr>            <chr>
 1 NZAC             NZAC04094876
 2 NZAC             NZAC04094877
 3 MONZ             AI.041234
 4 NHMUK            010594732
 5 ANIC             32-049981
 # …

DOI: 10.5281/zenodo.19242238

What the real thing looks like

Same four folders, just fuller. Point out it is recognisably the toy grown up, nothing new to learn.

Same four folders, more of everything:

anagotus.data/
├── DESCRIPTION
├── NAMESPACE
├── LICENSE / LICENSE.md
├── README.md
├── _pkgdown.yml          # pkgdown site config
├── renv.lock             # pinned dependencies
├── R/
│   ├── df_anagotus.R              # roxygen for the dataset
│   └── anagotus.data-package.R    # package-level docs
├── data/
│   └── df_anagotus.rda
├── data-raw/
│   ├── run_me.R                   # orchestrator
│   ├── 1_anagotus_data_load.R     # load and clean all sources
│   ├── 2_create_rda.R             # export to data/
│   └── *.csv                      # 8 raw specimen CSVs
├── man/                  # auto-generated .Rd files
└── inst/
    └── CITATION

At scale: eight messy sources

The honest bit: real data is eight messy files and some sf coordinate wrangling. The pattern did not change, only the volume. run_me.R sources the numbered scripts in order.

The toy used one tidy CSV. The real package starts from eight, each with different column names, coordinate systems, and date formats.

data-raw/
├── 1_anagotus_data_load.R   # load and harmonise every source
├── 2_create_rda.R           # use_data() to save to data/
└── run_me.R                 # source the numbered scripts in order

Same folder, same use_data() at the end. The extra work is a run_me.R orchestrator and some sf coordinate wrangling. The pattern does not change, only the volume.

Going further: the extras

Name-drop, do not teach: CITATION, pkgdown site, renv lock, Zenodo DOI, GitHub Actions. Signposts for people who want to go further on their own.

anagotus.data carries a few things the toy skips:

• inst/CITATION: defines what citation("anagotus.data") returns
• _pkgdown.yml: config for the docs site at https://nbir012.github.io/anagotus.data/
• renv.lock: pins the exact package versions used to build the data, for reproducibility
• Zenodo DOI badge in the README: long-term archival and citable releases
• .github/: GitHub Actions for automated R CMD check and pkgdown rebuild on push

The inst/CITATION file

This is what citation(“anagotus.data”) returns. Reviewers and users get a clean reference for free. Optional to show live.

Lives at inst/CITATION (not data-raw/, not the root). The actual file:

bibentry(
  bibtype = "Manual",
  title   = "anagotus.data: Label Data for Anagotus Specimens",
  author  = person("Neil", "Birrell",
                   email = "nbir012@aucklanduni.ac.nz",
                   role  = c("aut", "cre"),
                   comment = c(ORCID = "0000-0002-7961-1626")),
  year    = "2025",
  note    = "R package version 0.1.0",
  url     = "https://nbir012.github.io/anagotus.data/"
)

Users get a properly formatted citation:

citation("anagotus.data")

Install the real one

=> RSTUDIO for a live finish if you like: install_github the real package and print df_anagotus. Same one line as the toy. That symmetry is the closing point.

remotes::install_github("nbir012/anagotus.data")

library(anagotus.data)
df_anagotus

Same one line as the toy. That’s the whole point: a collaborator, student, or reviewer gets the data with a single command, documented and citable.

References

Links are on the slide and they will get the deck. Guide first, then the two books.

• The walkthrough: https://rstudio4edu.github.io/rstudio4edu-book/data-pkg.html
• R Packages (2e): https://r-pkgs.org
• Happy Git with R: https://happygitwithr.com
• usethis: https://usethis.r-lib.org
• devtools: https://devtools.r-lib.org
• anagotus.data: https://github.com/nbir012/anagotus.data

For the large datasets (I mentioned at the end)

• git annex: https://git-annex.branchable.com

with:

• dataLad: https://www.datalad.org/

Ngā mihi

Thanks and questions. Leave the repo link up.

Pātai? Questions?

?anagotus.data

https://github.com/nbir012/anagotus.data