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.

Preparation

Exercise 8A

Use usethis to create a new package called trashwheeldata.

Solution

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.

Solution

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)

Solution

The seven item-count columns run from plastic_bottles to sports_balls:

trash_collections <- readr::read_csv(url, show_col_types = FALSE) |>
  janitor::clean_names() |>
  dplyr::mutate(date = lubridate::mdy(date)) |>
  tidyr::pivot_longer(
    cols = plastic_bottles:sports_balls,
    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).

Solution

The source has 993 dumpster collections. Pivoting seven categories produces \(993 \times 7 = 6{,}951\) rows and 11 columns.

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.

Solution

One possible documentation block is:

#' Rubbish collected by Baltimore's Trash Wheel family
#'
#' Dumpster collections from four Trash Wheels operating in Baltimore's
#' waterways. Each row describes one rubbish category in one collection.
#' Item counts are estimated using samples taken during collection.
#'
#' @format A data frame with 6,951 rows and 11 variables:
#' \describe{
#'   \item{id}{Short identifier for the Trash Wheel.}
#'   \item{name}{Name of the Trash Wheel.}
#'   \item{dumpster}{Dumpster collection number.}
#'   \item{month}{Month of collection.}
#'   \item{year}{Year of collection.}
#'   \item{date}{Date of collection.}
#'   \item{weight}{Weight of collected rubbish, in US tons.}
#'   \item{volume}{Volume of collected rubbish, in cubic yards.}
#'   \item{homes_powered}{Source estimate of homes that could be powered
#'     using energy generated from the collected rubbish.}
#'   \item{trash_type}{Category of rubbish counted.}
#'   \item{count}{Estimated item count; missing when not reported.}
#' }
#' @source TidyTuesday,
#'   \url{https://github.com/rfordatascience/tidytuesday/tree/main/data/2024/2024-03-05};
#'   original data from Baltimore Healthy Harbor,
#'   \url{https://www.mrtrashwheel.com/}.
"trash_collections"

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.

Solution

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.