Learn how to use the package reprex to create a small reproducible example
Learn how to use specific debugging tools such as browser() and breakpoints
Introduction
Knowing how to debug code is an essential skill, whether one writes an analysis for a paper or develops an R package. This module covers several tools that aim to make the debugging process easier.
library(palaeoverse)data(reefs)reef_counts<-group_apply(occdf =reefs, group ="interval", fun =nrow)# Assign a common time scale based on an interval keyreefs<-look_up(occdf =reefs, early_interval ="interval", late_interval ="interval", int_key =interval_key)reefs<-subset(reefs, interval_max_ma<=541)# Extract Phanerozoic stage-level stages for time binsbins<-time_bins(interval ="Phanerozoic", rank ="stage")bin_time(occdf =reefs, bins =bins, method ="mid")
Error in `[.data.frame`:
! undefined columns selected
We now have an error caused by bin_time(). The first thing we can do is run traceback() to see which call inside bin_time() caused the error:
>traceback()4:stop("undefined columns selected")3:`[.data.frame`(occdf, , max_ma, drop =TRUE)2: occdf[, max_ma, drop =TRUE]1:bin_time(occdf = reefs, bins = bins, method ="mid") at #1
The trace can be read bottom-up: bin_time() failed because of the line occdf[, max_ma, drop = TRUE], which itself failed because of a wrong use of [.
This helps, but the root cause still isn’t very clear. Therefore, we’ll have to do some debugging.
Reducing the problem
The longer the code you try to debug, the more potential causes you have to explore. The first thing to do when you can’t find the bug in your code right away is to build a minimal reproducible example, aka a reprex (this is also known as a MRE, for “Minimal Reproducible Example”). This helps isolate the problem and makes it easier to communicate it to other users and maintainers.
In our example above, we can reduce the problem in two ways: we can reduce the data first, and then reduce the code.
Reduce the size of the data
In the debugging process, we will likely run the code at least a handful of times. Therefore, we want to make sure that it runs as fast as possible so that we don’t lose our focus. The easiest way to do this is to reduce the size of our input data.
In addition to making the error appear faster, it is also easier to compare the actual and expected outputs when the data is as small and simple as possible.
In this example, the dataset we are using has thousands of rows and 14 columns:
# Select the first rows of the datareefs2<-head(reefs)reef_counts<-group_apply(occdf =reefs2, group ="interval", fun =nrow)# Assign a common time scale based on an interval keyreefs2<-look_up(occdf =reefs2, early_interval ="interval", late_interval ="interval", int_key =interval_key)reefs2<-subset(reefs2, interval_max_ma<=541)# Extract Phanerozoic stage-level stages for time binsbins<-time_bins(interval ="Phanerozoic", rank ="stage")bin_time(occdf =reefs2, bins =bins, method ="mid")
Error in `[.data.frame`:
! undefined columns selected
We still see the same error but now we only have 6 rows left (the default provided by head()), much better! Let’s try to reduce that to one row and to remove some columns.
reefs2<-head(reefs, n =1)reefs2<-reefs2[, 1:5]reef_counts<-group_apply(occdf =reefs2, group ="interval", fun =nrow)
Error in `group_apply()`:
! Supplied `group` is not a named column in `occdf`
# Assign a common time scale based on an interval keyreefs2<-look_up(occdf =reefs2, early_interval ="interval", late_interval ="interval", int_key =interval_key)
Error in `look_up()`:
! `early_interval` needs to match a column name of `occdf`
# Extract Phanerozoic stage-level stages for time binsbins<-time_bins(interval ="Phanerozoic", rank ="stage")bin_time(occdf =reefs2, bins =bins, method ="mid")
Error in `[.data.frame`:
! undefined columns selected
Hmm, we don’t have the same error anymore, so we removed too many columns. Let’s try to keep 6 instead of 5:
reefs2<-head(reefs, n =1)reefs2<-reefs2[, 1:6]reef_counts<-group_apply(occdf =reefs2, group ="interval", fun =nrow)# Assign a common time scale based on an interval keyreefs2<-look_up(occdf =reefs2, early_interval ="interval", late_interval ="interval", int_key =interval_key)reefs2<-subset(reefs2, interval_max_ma<=541)# Extract Phanerozoic stage-level stages for time binsbins<-time_bins(interval ="Phanerozoic", rank ="stage")bin_time(occdf =reefs2, bins =bins, method ="mid")
Error in `[.data.frame`:
! undefined columns selected
Bingo! We have the same error as before, but now we only have one row and six columns.
NoteI can’t reduce the size of my data
Here, we were lucky enough that we could drastically reduce the size of the data used. This is not always the case. Maybe the error you are experiencing only appears with large data, in which case you don’t have many options.
Trying to reduce the size of the data is important, no matter what: knowing that the error only appears with large data is key information and might help debug your code.
Let’s now try to reduce the size of the code.
Reduce the size of the code
This is an important process: we want to remove as much code as possible to lower the number of potential causes leading to the error.
Starting from this:
reefs2<-head(reefs, n =1)reefs2<-reefs2[, 1:6]reef_counts<-group_apply(occdf =reefs2, group ="interval", fun =nrow)# Assign a common time scale based on an interval keyreefs2<-look_up(occdf =reefs2, early_interval ="interval", late_interval ="interval", int_key =interval_key)reefs2<-subset(reefs2, interval_max_ma<=541)# Extract Phanerozoic stage-level stages for time binsbins<-time_bins(interval ="Phanerozoic", rank ="stage")bin_time(occdf =reefs2, bins =bins, method ="mid")
Error in `[.data.frame`:
! undefined columns selected
We see that reef_counts is defined but never actually used, so this cannot be the root cause. Let’s remove it.
The subset() call is also suspicious: now that he have only one row left in our test data, does this subset() actually do anything?
Error in `[.data.frame`:
! undefined columns selected
We have removed two out of five function calls, not bad. We still don’t really understand the cause though.
Let’s assume that the documentation also doesn’t give any hint about this error message. If we are completely stuck, then we may want to ask other people, such as package maintainers on GitHub or people on StackOverflow. We have done our best to reduce the size of the problem, making it easier for other people to help us.
Still, we need to ensure that our reprex is correctly made and we must find a nice way to share it, e.g., as an issue on GitHub or with other users.
How to ensure that your reprex actually is a reprex
It seems like we have done everything we can to make the problem easier to reproduce, even for other people (e.g. package developers). However, there is one thing that still needs to be cleaned: our environment.
Our environment may have tons of variables, datasets, and options that were defined before but are not relevant to our problem. Some of those objects may interact in some way with our problematic code, meaning that we need to clean our environment to ensure that we can correctly reproduce the issue.
One way to do this is to restart the R session, but this can easily be forgotten. A more robust solution is to use the package reprex. This package provides a function called reprex() in which we can put all of the code related to our problem. reprex() will start a separate R session in the background to run this code and then report its results. Since this is a completely separate R session, it will error if our code isn’t completely self-contained, and this would indicate that our reproducible example isn’t actually… reproducible.
This is extremely useful to solve the problem yourself, but it is even more useful when reporting a bug to colleagues and package developers: if your example runs in reprex(), then it is almost guaranteed that it can be easily reproduced by other people with different environments.
reefs2<-head(reefs, n =1)#> Error:#> ! object 'reefs' not foundreefs2<-reefs2[, 1:6]#> Error:#> ! object 'reefs2' not foundreefs2<-look_up(occdf =reefs2, early_interval ="interval", late_interval ="interval", int_key =interval_key)#> Error in `look_up()`:#> ! could not find function "look_up"bins<-time_bins(interval ="Phanerozoic", rank ="stage")#> Error in `time_bins()`:#> ! could not find function "time_bins"bin_time(occdf =reefs2, bins =bins, method ="mid")#> Error in `bin_time()`:#> ! could not find function "bin_time"
Our reprex fails, but not with the error we experienced so far! We forgot to add the calls to library() and data(), which is the reason R could not find the functions and data provided by the palaeoverse package.
This is the situation we have so far, so we can now share this output with other people and they should be able to reproduce the issue.
Note that it is good practice to show more information on our session, including the version of packages used. This can be done with the argument session_info in reprex():
You now know how to use reprex()! Note that the steps before actually using it are key: very often, other people will ask you to minimize your issue as much as possible before reporting it. In many cases, you can also find the issue on your own just by reducing it.
Debugging a function
Debugging a function that you wrote (either in a package or as part of a project) can be annoying because an entire (internal) block of code gets executed and you only see the final error.
One solution is to put various print() statements in the function body to see which ones get evaluated (meaning that the code has run fine so far) and which ones don’t because the function errored before.
However, a more robust and convenient approach is to use a function that will stop the evaluation and put us in the evaluating environment: browser(). This allows us to run line by line in the function body, and it is therefore a key tool when you start writing your own functions.
We will use issue #280 in palaeoverse as an example throughout this section.
browser()
The bug report above gives a reprex to reproduce the error (note that at the time you are reading this, this bug has already been fixed):
Error in `bin_space()`:
! object 'secondary' not found
The error happens in bin_space(), which is a long function:
palaeoverse::bin_space#> function (occdf, lng = "lng", lat = "lat", spacing = 100, sub_grid = NULL, #> return = FALSE, plot = FALSE) #> {#> if (!is.data.frame(occdf)) {#> stop("occdf should be of class dataframe")#> }#> #> [ MANUALLY TRUNCATED ]#> #> }
One approach to narrow down the cause of the error would be to add multiple print() statements, so that we can check which messages are printed (indicating that the code ran without error) and which are not because the error occurred before reaching them.
However, it would be way more convenient to be able to execute the internal code line by line so that we can see precisely which line errors. This is the objective of browser(). We can start by putting a browser() at the top, re-loading the function, and executing it again:
function (occdf, lng = "lng", lat = "lat", spacing = 100, sub_grid = NULL, return = FALSE, plot = FALSE) {+ browser() if (!is.data.frame(occdf)) { stop("occdf should be of class dataframe") } [ MANUALLY TRUNCATED ]}
NoteReloading the function
The example above is from an R package, where we can use devtools::load_all() to reload all functions.
If you insert browser() in a standalone function, you need to re-execute this function definition before calling it.
In the video below, running the code with the function that now includes browser() doesn’t error. Instead, it stops the execution at the browser() call:
There are two interesting things in this video:
we have access to the function environment, including the user-provided inputs. Note for instance that sub_grid is NULL by default in the function definition, but printing sub_grid in the console gives 250 because the call that is being inspected contains sub_grid = 250.
We can execute the remaining function body statement by statement by pressing “Enter” in the console. Note that this doesn’t necessarily execute all the code: an if() statement whose condition is FALSE will not be executed. browser() follows exactly the path taken by our code.
Pressing “Esc” or executing Q allows us to exit this “browsing” mode.
Using this approach, we can find the exact source of the error:
Fixing this requires reading all the code prior to this line, but this is beyond the scope of this module.
If you are confident that some lines are irrelevant to the bug, you can move the browser() call past them so that you don’t need to execute them all every time you enter “browsing” mode.
Breakpoints
Breakpoints are a feature directly integrated in the software used to run R (e.g. RStudio or Positron. This is also known as IDE for “Integrated Development Environment”).
They are a way to mimic browser() calls without actually modifying the function. You can add one by clicking on the left of line numbers:
After reloading the package and running the code that is supposed to fail, we end up in almost the same situation as with browser(), except that we haven’t modified the source code at all. We can then follow the same steps to continue our debugging process.
Conclusion
Debugging is an important aspect of programming. This module focused on two essential debugging methods: producing a reproducible example, and using debugging tools such as browser() and breakpoints. Following good debugging practices helps us fix our own code, and it is the essential first step to produce good bug reports. It is also a way to gain experience to recognise potential bugs when reviewing code in the future.