ETC5523: Communicating with Data

Tutorial 8

Author

Michael Lydeamore

🎯 Objectives

By the end of this tutorial, you will be able to:

  • create your first R package;
  • prepare and include a dataset reproducibly;
  • document package data with roxygen2; and
  • check, install and use the finished package.

Exercise 8A

Use usethis to create a new package called trashwheeldata.

Edit DESCRIPTION and replace the placeholders with:

  • yourself as the creator and author;
  • a meaningful title and description; and
  • an appropriate version number.

Add an MIT licence, replacing the placeholder name with your own:

usethis::use_mit_license("Your Name")

Exercise 8B

Use usethis to create an R script called trash_collections.R in the data-raw directory of your package.

The data-raw directory holds scripts that generate package data. We will use the Trash Wheel Collection Data published through TidyTuesday and sourced from Baltimore’s Healthy Harbor initiative.

Four semi-autonomous Trash Wheels collect rubbish flowing into Baltimore’s waterways. The data record each dumpster load, including its weight and volume and estimated counts of several kinds of rubbish.

Edit the script to create a long-form dataset in which each row represents one rubbish category from one dumpster collection. Complete the missing cols expression.

url <- paste0(
  "https://raw.githubusercontent.com/rfordatascience/",
  "tidytuesday/main/data/2024/2024-03-05/trashwheel.csv"
)

trash_collections <- readr::read_csv(url, show_col_types = FALSE) |>
  janitor::clean_names() |>
  dplyr::mutate(date = lubridate::mdy(date)) |>
  tidyr::pivot_longer(
    cols = ___,
    names_to = "trash_type",
    values_to = "count"
  )

usethis::use_data(trash_collections, overwrite = TRUE)

Run the completed script from beginning to end.

You should now have a folder called data in your package, with a file called trash_collections.rda.

Tip

The script in data-raw/ is the reproducible source. The .rda file in data/ is the object shipped to users.

How many rows do you expect after pivoting seven rubbish categories? Confirm your prediction with dim(trash_collections).

Exercise 8C

Create an R script in the R directory to document trash_collections.

usethis::use_r("trash_collections")

Modify the script and document the data.

  • Give the dataset a concise title and description.
  • Describe its dimensions and object type.
  • Define every column, including its units.
  • Explain that item counts are estimates and that missing counts are not necessarily zero.
  • Cite both TidyTuesday and the original Healthy Harbor source.
  • Finish the block with the quoted object name, "trash_collections".

Markdown support is enabled by default for packages created with usethis::create_package(). You can confirm or enable it with:

usethis::use_roxygen_md()

Once you’ve finished modifying run

devtools::document()

at the console to build your package documentation.

Exercise 8D

We now have a minimally working package containing a documented dataset. Restart your R session and run:

devtools::load_all()

Confirm that trash_collections is available and that its help page answers the questions below:

trash_collections
?trash_collections
  • What does one row represent?
  • Are the item counts observed exactly or estimated?
  • Does a missing count mean that no items were collected?
  • What units are used for weight and volume?

Then check the complete package:

devtools::check()

Fix every error and warning. Read each note and decide whether it requires action.

Once you have passed the check, install the package locally:

devtools::install()

Restart your R session, load the installed package, and open the help page again.

Completion check

You have finished when:

  • data-raw/trash_collections.R reproduces the packaged data;
  • data/trash_collections.rda exists;
  • devtools::document() creates the help page;
  • DESCRIPTION and the licence contain no placeholders;
  • devtools::check() reports no errors or warnings; and
  • the installed package works in a clean R session.