ETC5523: Communicating with Data

Workshop 8: Build and document pokemonvgc

Author

Michael Lydeamore

Published

1 August 2001

🎯 Objectives

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

  • distinguish raw data inputs from data shipped in an R package;
  • document and export a package function with roxygen2;
  • replace repeated package::function() calls with selective imports;
  • write a README quick start; and
  • check, install and use a package.

Get the starter package

Clone https://github.com/MikeLydeamore/pokemonvgc and open pokemonvgc.Rproj in Positron or RStudio.

You can clone through the Git: Clone command, or run this in a terminal:

git clone https://github.com/MikeLydeamore/pokemonvgc.git

Install the workshop tools if you do not already have them:

Important

Run the remaining commands with pokemonvgc open as your current project. Do not create another package inside it.

Exercise 8A: Tour the package (5 minutes)

Find each of these components and write one sentence describing its role:

Component Question to answer
R/ What code will be available to package users?
data/ Which objects will be loaded with the package?
data-raw/ Which inputs and scripts produce those objects?
DESCRIPTION What does this tell R and a potential user?
README.Rmd Which reader encounters this document first?

Load the package without installing it:

Use pokemon_elo and recent_champions to answer:

  1. How many rating observations and distinct players are included?
  2. Which recent champion has no rating history in this snapshot?
  3. Can you open ?recent_players yet? Why or why not?

Exercise 8B: Rebuild the package data (7 minutes)

Open data-raw/pokemon-elo.R and follow the data from its prepared inputs to the objects saved by usethis::use_data().

Then run the script from the package root:

The calculation may take several seconds. Confirm that it recreates:

  • data/pokemon_elo.rda; and
  • data/recent_champions.rda.

Discuss with a partner:

  • Why is the match history kept in data-raw/ rather than shipped to users?
  • Why is recent_champions stored as package data rather than embedded in recent_players()?
  • Which file would you edit if the champion lookup changed?

Exercise 8C: Document and export the function (10 minutes)

Open R/recent-players.R. Read the function as evidence before writing its documentation. What does one input row represent? When is a player eligible? What does one output row represent?

Add a roxygen2 block containing:

  • a task-oriented title and short description;
  • @param entries for ratings and min_events;
  • an @return entry stating what one row represents;
  • two runnable @examples, one using a non-default threshold; and
  • @export.

Generate the documentation and reload the package:

Inspect the new files in man/ and NAMESPACE. Do not edit either generated file by hand.

Exercise 8D: Use selective imports (8 minutes)

The first version of the function uses dplyr:: repeatedly. dplyr is already recorded under Imports in DESCRIPTION. Now use roxygen to name only the functions imported into the package namespace.

  1. Add this line to the roxygen block:

    #' @importFrom dplyr filter group_by mutate n slice_max ungroup

  2. Remove the six dplyr:: prefixes from the function body.

  3. Run devtools::document() again.

  4. Inspect the generated NAMESPACE, then run devtools::load_all().

Explain the different jobs performed by:

  • Imports: dplyr in DESCRIPTION;
  • @importFrom dplyr ... in the roxygen block; and
  • importFrom(dplyr, ...) in NAMESPACE.

Exercise 8E: Test from a user’s perspective (5 minutes)

Run the documented function and identify the current top three eligible players:

Check that:

  • the result has one row per player;
  • every returned player has at least 15 observations; and
  • changing min_events changes the eligibility rule.

Ask a partner to use only ?recent_players to explain the events column and the result of changing min_events. Revise the first unclear sentence.

Exercise 8F: Write the README quick start (7 minutes)

Complete the TODOs in README.Rmd. A first-time reader should learn:

  1. what the package helps them do;
  2. how to install it from GitHub;
  3. how to find the latest eligible ratings; and
  4. why the Elo values require care when interpreted.

Use this copyable installation command:

remotes::install_github("MikeLydeamore/pokemonvgc")

Keep the quick start short and runnable. Then regenerate README.md:

Exercise 8G: Check and install (8 minutes)

Check the package as a complete product:

Fix every error and warning. Read every note and decide whether it needs action. When the check passes, install the package:

Restart R, then confirm that the installed package works without devtools::load_all():

Completion check

You have finished when:

  • the data-raw script reproduces both packaged datasets;
  • recent_players() has a useful help page and is exported;
  • DESCRIPTION and generated NAMESPACE record the selective imports;
  • README.md contains a copyable installation command and runnable example;
  • devtools::check() reports no errors or warnings; and
  • the installed package works in a clean R session.