Getting Help with R

Writing reproducible examples and debugging errors with R.
Author

Michael McCarthy

Published

January 24, 2023

Writing reproducible examples

If you need help solving a problem, the first step is to create a reproducible example. The goal of a reproducible example is to make it easier for others to help you, or for you to help yourself, by packaging your problematic code in such a way that anyone can exactly reproduce your problem. A good reproducible example is:

  • Self-contained: Your code includes everything needed to reproduce your problem
  • Minimal: Your example only includes code directly related to your problem

The work you put into writing a good reproducible example usually pays for itself:

  • Often you will solve your own problem in the process of writing a reproducible example
  • You improve your chances of getting help when your problem is easy to understand and reproduce

For tips on writing good reproducible examples, see:

Create an R project for writing reproducible examples

Because reproducible examples are self-contained and minimal, it’s good practice to create them separately from the project that inspired your problem. A nice way to do this is to create a new reprex R project that contains empty files where you can write reproducible examples like:

reprex/
├─reprex.Rproj
├─reprex.R
├─reprex.Rmd
├─reprex.qmd

The contents of these files are meant to be ephemeral. After you write a reproducible example and share it, it’s safe to delete the contents of the file or overwrite it in the future. If you do want to save the reproducible example somewhere, consider turning it into a gist on GitHub or a question on Stack Overflow, Cross Validated, or the Posit forum.

Sharing reproducible examples

Use the reprex R package to test, render, and copy your reproducible examples to your clipboard. Then share them when asking for help on:

Debugging interactively

See Debugging with the RStudio IDE by Jonathan McPherson and the Debugging chapter in Advanced R by Hadley Wickham.

R package versions and debugging

Sometimes the bugs you run into aren’t caused by your code, but rather the internal code of the package(s) you’re using. If you’re encountering a bug that’s associated with a package that has a newer version available, updating the package might be the only thing you need to do to fix the bug.

Debugging targets pipelines

See the Debugging chapter in the targets R package user manual

Debugging GitHub Actions workflows

If you encounter problems in a GitHub Actions workflow but not locally, good luck. GitHub provides monitoring and troubleshooting documentation to get you started, but the lack of an interactive debugger can make debugging difficult. The typical approach to debugging GitHub Actions workflows is to:

  1. View which step caused the failure in the workflow’s logs
  2. Guess what caused the problem and commit the changes attempting to fix it
  3. Push those changes to trigger the workflow
  4. Hope the workflows succeeds (or repeat the process until it does)

This isn’t great. But there are a few things you can do to make it somewhat better:

  • Debug the workflow in a Pull Request so you don’t make a mess of your commit history
  • Use act to run GitHub Actions workflows locally in Docker containers
  • Use tmate to access a workflow’s runner with SSH or Web shell for interactive debugging