MATH167R: Debugging

Peter Gao

Overview of today

Debugging (based on Jennifer Bryan and Jim Hester’s What they Forgot to Teach You About R - Debugging R Code)

What to do when your code doesn’t work

Step 1: Look online

When you see an error code you don’t understand, search for it!

Search for the exact text of your error message (except for any references to filepaths, etc.).

R has millions of users and an incredibly active online community. If you encounter any error message, chances are someone has had to debug that exact error in the past.

Step 2: Reset

Many, many issues will be solved by closing and re-opening R.

Sometimes, things get weird with your global environment, and you just need to start with a clean slate. It can be frustrating, because you don’t know what was causing the issue, but also a relief, because it will be fixed.

Resetting will:

Clear your workspace (better than rm(list = ls()!)
Reset your options to their defaults (an easy one to miss!)
Clear your search path (the order R looks for things)

Step 3: Repeat

When you encounter a bug, try to repeat it. Likely, it came about for a reason.

When you do repeat it, you should repeat it with a minimal reproducible example. This means you should remove as much code and simplify as much data as possible.

Small and simple inputs
No extraneous packages or function calls

Example: did your function break with a large data matrix of real-world data stored within a package? How about if you just use a \(3\times 3\) matrix of \(1\)’s?

For more guidelines, see StackOverflow’s guide to creating minimal reproducible examples.

Step 4: Locate

If you weren’t able to fix a bug the “easy” way (found the solution online or just needed a reset), and you have a minimal reproducible example demonstrating your bug, then you are ready for the really hard part: finding the bug.

Often (not always), once you find a bug, it is rather easy to fix.

`traceback()`: call stack

Sometimes functions(in functions(in functions(in functions(…)))) can get complicated.

Exercise: What will the following code return?

f <- function(x) x + 1
g <- function(x) f(x)
g("a")

Error in x + 1: non-numeric argument to binary operator

`traceback()`: call stack

If you call the traceback() function immediately after triggering an error, the console will print out a summary of how your program reached that error. This summary is called a call stack.

f <- function(x) x + 1
g <- function(x) f(x)
g("a")

Error in x + 1: non-numeric argument to binary operator

traceback()

2: f(x) at #1
1: g("a")

`traceback()`: call stack

Exercise: What will the following code return?

f <- function(a) g(a)
g <- function(b) h(b)
h <- function(c) i(c)
i <- function(d) {
  d + 10
}
f(5)

[1] 15

`traceback()`: call stack

What about this code?

f <- function(a) g(a)
g <- function(b) h(b)
h <- function(c) i(c)
i <- function(d) {
  d + 10
}
f(1:3)

[1] 11 12 13

`traceback()`: call stack

What about this code?

f <- function(a) g(a)
g <- function(b) h(b)
h <- function(c) i(c)
i <- function(d) {
  d + 10
}
f("a")

Error in d + 10: non-numeric argument to binary operator

Why doesn’t it say error in a + 10?

`traceback()`: call stack

traceback()

5: stop("`d` must be numeric", call. = FALSE) 
4: i(c) 
3: h(b) 
2: g(a) 
1: f("a")

`traceback()`: call stack

Read from bottom to top:

First call was to f("a")
Second call was g(a)
Third call was h(b)
Fourth call was i(c)
Fifth and last call was our error message, so we know i(c) triggered our error.

We now know that our error occurred within i(c), but we don’t know where within i(c) our error occurred.

`traceback()`: call stack

Note this is done in your Console, not your Editor pane. This is typically not a part of your reproducible workflow, this is you figuring out your own problems until you fix what actually belongs in your workflow.

Once you have the bug fixed, then put the debugged code in your Editor pane. In general, most debugging will be done through the Console.

`print(), cat(), str()`: messages

Use print() statements to test out print() statements to see the values used during execution.

i <- function(d) {
  print(d)
  d + 10
}
f("a")

[1] "a"

Error in d + 10: non-numeric argument to binary operator

This is a quick and easy way to find bugs quickly and should be probably your first step when manually debugging.

`print(), cat(), str()`: messages

Take your function and throw in a cat() statement to see what the function is seeing.

i <- function(d) {
  cat("The value of input parameter d is:", d, "\n")
  cat("The class of input parameter d is:", class(d), "\n")
  d + 10
}
f("a")

The value of input parameter d is: a 
The class of input parameter d is: character

Error in d + 10: non-numeric argument to binary operator

`print(), cat(), str()`: messages

We can similarly use str():

i <- function(d) {
  str(d)
  d + 10
}
f("a")

 chr "a"

Error in d + 10: non-numeric argument to binary operator

More specifically, str() can be used to see the structure of what the function is seeing. This can often be more informative if the structure is not what you expect (a common source of bugs).

`print(), cat(), str()`: messages

The main downside to these approaches is that it can get messy quickly if you use multiple print statements, and you cannot further investigate the object. However, many bugs come down to typos or other trivial errors, and print statements are often all you need.

`browser()`: Interactive debugger

Sometimes, it may not be enough to just use print statements and locate a bug. You can get more information and interact with that information using browser(), an interactive debugger.

Within RStudio, you can also get right to an interactive debugger by clicking Rerun with Debug.

`browser()`: Interactive debugger

Alternatively, we can plug browser() into our function, as with the print statements.

i <- function(d) {
  browser()
  d + 10
}
f("a")

Called from: i(c)
debug at <text>#3: d + 10

Error in d + 10: non-numeric argument to binary operator

`browser()`: Interactive debugger

After you run a function with browser(), you will be inside of your function with an interactive debugger.

You will know it worked if you see a special prompt: Browse[1]>.

We can see:

The environment within the function using the Environment pane
The call stack using the new Traceback pane
Special interactive debugging commands

Interactive debugging commands

Next, n: executes the next step in the function. (If you have a variable named n, use print(n) to display its value.)
Step into, s, works like next, but if the next step is a function, it will step into that function so you can explore it interactively. (Easy to get lost!)
Finish, or f: finishes execution of the current loop or function. Useful to skip over long for loops you don’t need to interact with.
Continue, c: leaves the debugger and continues execution of the function. Useful if you’ve fixed the bad state and want to check that the function proceeds correctly.
Stop, Q: exits the debugger and returns to the R prompt.

Interactive debugging commands

Enter (no text): repeat the previous interactive debugging command. Defaults to Next n if you haven’t used any debugging commands yet.
where: prints stack trace of active calls (the interactive equivalent of traceback).

Other useful things to do

ls(): List the current environment. You can use this to browse everything that the function is able to see at that moment.
str(), print(): examine objects as the function sees them.

A warning

If you execute the step of a function where the error occurs, you will exit interactive debugging mode, the error message will print, and you will be returned to the R prompt.

This can get annoying, because it stops you from interacting right when you hit the bug.

A warning

Strategy:

Call browser() and execute until you hit the error. Remember exactly where it occurs.
Call browser() again and execute again, stopping just before triggering the error.
You can copy and paste the next line of code into the Browse console to trigger the error without exiting the interactive debugger.

Tips

Within the debugging section, you are interacting with the exact environment R is using before the error is triggered.
Examine each object one-by-one in the environment to make sure the structure matches expectations.
If you still can’t figure it out, s “Step into” the next function and repeat this process.

Example

create_p_norm <- function(p = 2) {
  return(
    function(x) return(sum(abs(x) ^ p) ^ (1 / p))
  )
}
calculate_p_norm <- function(x, p) {
  # browser()
  norm_fn <- create_p_norm(p)
  return(norm_fn(x))
}
calculate_p_norm(1:5, 1)

[1] 15

Within an interactive debugging environment, you can use as.list(environment()) to see what is in the environment.

Example

loop_fun <- function(x) {
  # browser()
  n <- length(x)
  y <- rep(NA, n)
  z <- rep(NA, n)
  for (i in 1:n) {
    y[i] <- x[i] * 2
    z[i] <- y[i] * 2
  }
  return(list("y" = y, "z" = z))
}
loop_fun(1:5)

$y
[1]  2  4  6  8 10

$z
[1]  4  8 12 16 20

loop_fun(diag(1:5))

$y
 [1]  2  0  0  0  0  0  4  0  0  0  0  0  6  0  0  0  0  0  8  0  0  0  0  0 10

$z
 [1]  4  0  0  0  0  0  8  0  0  0  0  0 12  0  0  0  0  0 16  0  0  0  0  0 20

Breakpoints

In RStudio, you may also use breakpoints by writing your code in an R file. A breakpoint is like a browser() call, but you avoid having to change your code.

loop_fun <- function(x) {
  # browser()
  n <- length(x)
  y <- rep(NA, n)
  z <- rep(NA, n)
  for (i in 1:n) {
    y[i] <- x[i] * 2
    z[i] <- y[i] * 2
  }
  return(list("y" = y, "z" = z))
}
loop_fun(c("a", "b", "c"))

Error in x[i] * 2: non-numeric argument to binary operator

Debugging Summary

Search online.
Reset.
Repeat.
Locate:

Call stack: traceback()
Non-interactive messages: print(), cat(), str()
Interactive debugging: browser(), debug(), debugonce(), trace()

Debugging Resources

Debugging exercise

A number is a palindrome if it is the same when the digits are reversed (ex. 484). Can you fix the following code to print numbers between 1 and 1000 that are both prime and palindromes?

Debugging exercise

is_prime <- function(x) {
  if (x == 2) {
    return(TRUE)
  } else if (any(x %% 2:(x-1) == 0)) {
    return(FALSE)
  } else {
    return(TRUE)
  }
}
is_palindrome <- function(x) {
  x_char <- as.character(x)
  x_char <- stringr::str_split(x_char, "")[[1]]
  x_rev <- rev(x_char)
  return(x_char == x_rev)
}
for (i in 1:1000) {
  if (is_prime(i) & is_palindrome(i)) {
    print(i)
  }
}

[1] 2
[1] 3
[1] 5
[1] 7

Error in if (is_prime(i) & is_palindrome(i)) {: the condition has length > 1

MATH167R: Debugging

Overview of today

What to do when your code doesn’t work

Step 1: Look online

Step 2: Reset

Step 3: Repeat

Step 4: Locate

traceback(): call stack

traceback(): call stack

traceback(): call stack

traceback(): call stack

traceback(): call stack

traceback(): call stack

traceback(): call stack

traceback(): call stack

print(), cat(), str(): messages

print(), cat(), str(): messages

print(), cat(), str(): messages

print(), cat(), str(): messages

browser(): Interactive debugger

browser(): Interactive debugger

browser(): Interactive debugger

Interactive debugging commands

Interactive debugging commands

Other useful things to do

A warning

A warning

Tips

Example

Example

Breakpoints

Debugging Summary

Debugging Resources

Debugging exercise

Debugging exercise

`traceback()`: call stack

`traceback()`: call stack

`traceback()`: call stack

`traceback()`: call stack

`traceback()`: call stack

`traceback()`: call stack

`traceback()`: call stack

`traceback()`: call stack

`print(), cat(), str()`: messages

`print(), cat(), str()`: messages

`print(), cat(), str()`: messages

`print(), cat(), str()`: messages

`browser()`: Interactive debugger

`browser()`: Interactive debugger

`browser()`: Interactive debugger