RPR-Debugging

Debugging R

 

Keywords:  Debugging with RStudio; the browser(), debug() and debugonce() commands; setting conditional breakpoints

 

 

 

Abstract

Working effectively with your IDE's debugging tools is a prerequisite for efficient software development.

 

This unit ...

Prerequisites

You need to complete the following units before beginning this one:

• RPR-Introduction (Introduction to R)

 

Objectives

This unit will ...

• ... introduce the R "Browser", the in-built debugging tool;
• ... demonstrate debugging a function.

 

Outcomes

After working through this unit you ...

• ... can invoke the debugger on a function once or multiple times;
• ... can step through code line by line, and examine the values of variables as you are doing so;
• ... are familar with "conditional breakpoints" and know how to set them;
• ... can confidently debug your own functions.

 

Deliverables

• Time management: Before you begin, estimate how long it will take you to complete this unit. Then, record in your course journal: the number of hours you estimated, the number of hours you worked on the unit, and the amount of time that passed between start and completion of this unit.
• Journal: Document your progress in your Course Journal. Some tasks may ask you to include specific items in your journal. Don't overlook these.
• Insights: If you find something particularly noteworthy about this unit, make a note in your insights! page.

 

Evaluation

Evaluation: NA

This unit is not evaluated for course marks.

 

Contents

When something goes wrong in your code, you need to look at intermediate values, as the code executes. Almost always sprinkling print() statements all over your code to retrieve such intermediate values is the least efficient way to isolate problems. But what is worse, you are temporarily modifying your code, and there is a significant risk that that this will create problems later.

Right from the beginning of your programming trajectory, you should make yourself familiar with R's debug functions.

• At first, you may need to pin down approximately where an error occurs. Read the error message carefully, or perhaps do print out some intermediate values from a loop.
• Make sure that it's your code that is at fault, not something else - Google for the error message to get a better idea about what is happeneing.
• Debugging is done by entering a "browser" mode that allows you to step through a function.
• To enter this browser mode ...
  • Call debug(function). When function() is next executed, R will enter the browser mode. Call undebug(function) to clear the debugging flag on your function, or you can use the debugonce(function), which will put the function into browser mode only at the next execution. Note that you don't have to set the debug flag at your top-level function, it could just as well be set on a funcytion that is called by a function which is called by the function that you call when the error occurs. Etc.
  • Alternatively insert a call to browser() into your function code to enter the browser mode. This sets a breakpoint into your function. You can also use if (condition) { browser() } to enter the browser mode only when your function goes into a state of interest - e.g. a loop iteration variable right before the error occurs. This is called a "conditional breakpoint" (or "watchpoint""). A conditional breakpoint is especially useful if the problem occurs only rarely, in a particular context.
• It should go without saying that you need to discover that problems exist in the first place: study the Testing learning unit and test, test, and test again.

 

Here is an example: let's write a rollDice-function, i.e. a function that creates a vector of n integers between 1 and MAX - the number of faces on your die.

rollDice <- function(n = 1, min = 1, max = 6) {
  # Simulating the roll of a fair die
  # Parameters:
  #    n    numeric  the number of rolls that are returned
  #    min  numeric  the minimum value returned
  #    max  numeric  the maximum value returned
  # Value
  #    Integer vector of length n containing the values

  v <- integer(n)
  for (i in 1:n) {
    x <- runif(1, min, max)
    x <- as.integer(x)
    v[i] <- x
  }
  return(v)
}

Lets try running this and see whether the distribution of numbers is fair...

rollDice()
set.seed(112358)
x <- rollDice(10000)
table(x)
hist(x, breaks = seq(0.5, 6.5, by = 1), xlim = c(0, 7), col = "#BBEEFF")

Problem: our "fair" die seems to return "fair" numbers - but it only returns values from 1 to 5. Why? Lets flag the function for debugging...

debug(rollDice)
rollDice(10)

# We switch to the browser interface. You can use the icons to go through the
# code step by step, or execute more of the code. You can also step into the
# next function, if one is being called, or step over it (by default). The
# current expression is highlighted in the code pane.

> debug(rollDice)
> rollDice(10)
debugging in: rollDice(10)
debug at #1: {
    v <- integer(n)
    for (i in 1:n) {
        x <- runif(1, min, max)
        x <- as.integer(x)
        v[i] <- x
    }
    return(v)
}
Browse[2]>
debug at #10: v <- integer(n)
Browse[2]>
debug at #11: for (i in 1:n) {
    x <- runif(1, min, max)
    x <- as.integer(x)
    v[i] <- x
}
Browse[2]>
debug at #12: x <- runif(1, min, max)
Browse[2]>
debug at #13: x <- as.integer(x)
Browse[2]>

# Typing a variable name allows us to examine its current value:

Browse[2]> x
[1] 4.706351

# Note that as.integer() hasn't been called yet. The Browser shows you the
# next statement or block it will execute.

Browse[2]>
debug at #6: v[i] <- x
Browse[2]>x
debug at #4: x <- runif(1, min = MIN, max = MAX)
Browse[2]> v
[1] 4      # Aha: as.integer() truncates values! So all 5.something values
           # get turned into 5 and no 6 is ever returned. So, shall we round()
           # instead?
Browse[2]> Q
undebug(rollDice)

So lets change the function to round instead...

rollDice <- function(n = 1, min = 1, max = 6) {
  # Simulating the roll of a fair die
  # Parameters:
  #    n    numeric  the number of rolls that are returned
  #    min  numeric  the minimum value returned
  #    max  numeric  the maximum value returned
  # Value
  #    Integer vector of length n containing the values

  v <- integer(n)
  for (i in 1:n) {
    x <- runif(1, min, max)
    x <- round(x)     # <<<- changed to round() from as.integer()
    v[i] <- x
  }
  return(v)
}

rollDice()
set.seed(112358)
x <- rollDice(10000)
table(x)   # Good - now all six numbers are there ...
hist(x, breaks = seq(0.5, 6.5, by = 1), xlim = c(0, 7), col = "#BBEEFF")

Ooooo! Wrong thinking. That's even worse - now all the values are there, but our function is no longer fair.

So we actually have to think a bit.

• runif(n, min, max) gives a uniform distribution of numbers. According to the documentation, this is in the interval (min, max), i.e. the actual limit values are not included.
• as.integer() is not safe to use in any case, because it's behaviour is not explicit. Does it round? Does it truncate? Does it round up? We should have used trunc() or round() instead for explicit, predictable behaviour.
• The key problem is that we have cretaed values only in 5 intervals, not six. So what we actually need to do is change the range, by adding 1 to max.

rollDice <- function(n = 1, min = 1, max = 6) {
  # Simulating the roll of a fair die
  # Parameters:
  #    n    numeric  the number of rolls that are returned
  #    min  numeric  the minimum value returned
  #    max  numeric  the maximum value returned
  # Value
  #    Integer vector of length n containing the values

  v <- integer(n)
  for (i in 1:n) {
    x <- runif(1, min, max + 1) # <<<- increase max by one to give correct number of intervals
    x <- trunc(x)               # <<<- changed to trunc() from as.integer()
    v[i] <- x
  }
  return(v)
}

rollDice()
set.seed(112358)
x <- rollDice(10000)
table(x)
hist(x, breaks = seq(0.5, 6.5, by = 1), xlim = c(0, 7), col = "#BBEEFF")

Now the output looks correct.

# Disclaimer
# A base R function exists that does the same thing: sample()

set.seed(112358)
x <- sample(1:6, 10000, replace=TRUE)
table(x)
hist(x, breaks = seq(0.5, 6.5, by = 1), xlim = c(0, 7), col = "#BBEEFF")

# Now if you look at the table() output, you see that these are the EXACT
# same numbers, because sample() does exactly the same as our rollDice()
# function. So why write our own? Because we might want to simulate more
# complex behaviour, like having a loaded die, or a memory effect or something
# and writing the function ourselves gives us detailed control over the
# simulation.

For more on RStudio's debugging interface, see here and here.

For a deeper excursion into R debugging, see this overview by Duncan Murdoch at UWO, and Roger Peng's introduction to R debugging tools.

 

 

Further reading, links and resources

 

Notes

 

Self-evaluation

 

 

---

 

If in doubt, ask! If anything about this learning unit is not clear to you, do not proceed blindly but ask for clarification. Post your question on the course mailing list: others are likely to have similar problems. Or send an email to your instructor.

---

 

About ...
 
Author:

Boris Steipe <boris.steipe@utoronto.ca>

Created:

2017-08-05

Modified:

2017-08-05

Version:

1.0

Version history:

• 1.0 First live version
• 0.1 First stub

---

This copyrighted material is licensed under a Creative Commons Attribution 4.0 International License. Follow the link to learn more.