Introduction

From release 098.208 the last RStudio IDE comes with a visual debugger. Now debugging with R and RStudio becomes a simple and efficient task.

This short post does not want to be a crash course: “debugging with R” nor can be a full explanation of the RStudio visual debugging capabilities: we guess that all of these will be fully documented as soon as this tool will be officially released.

This post is a simple sharing of something we have learned about R and RStudio.

Finally, thanks to the RStudio team for their presentation at UseR 2013 in Albacete and a special thanks to Jonathan @RStudio for replying at my support questions.

Debugging in R

Normally, debug mode in R is entered by calling debug() or debugonce() on a function.

Therefore, assuming we define a simple function foo():

foo = function(x){ 
  if(x > 0) salutation = "Hello" else
    salutation = "Goodbye"
  salutation
}

Debug mode on foo() can be entered in many ways. Nevertheless, to keep it simple, we only use a call to either debug(foo), or debugonce(foo), as these are our preferred method.

Note that, a call to browser() within the body of function foo() would work exactly the same way except that R would start debugging from the call to browser().

Visual Debugging with RStudio

After debug(foo) is called, RStudio automatically entered “visual debug mode” as soon foo() is called assuming that:

• RStudio is able to match function foo() to a file name say foo.R;
• foo.R was sourced into R, i.e. source(“foo.R”).

Once visual debug mode is entered, several useful features are added to RStudio.

Console

Just below the console bar a new bar appears (Figure 1, see also Figure 5 at the bottom of the post) showing three buttons: Next, Continue, Stop

corresponding to the R commands n, c and Q when R is in debug mode where meaning:

Traceback

On the right hand side of RStudio, in between the lower and the upper panel a new panel named Traceback appears (Figure 2, see also Figure 5 at the bottom of the post).

The content of this panel seems to be the call to the function under debug mode followed by the file where the function was sourced from.

If debug mode on function foo(), sourced from file foo.R, is entered by setting debug(foo), when calling foo(x = 0) the Traceback panel will show

foo(0) at foo.R:2

where :2 refers to the second line of file foo.R, i.e. the line the debugger is now (see also the overall screenshot of Figure 5).

Note that, when called from the R prompt, “traceback() prints the call stack of the last uncaught error, i.e. the sequence of calls that lead to the error”.

Nevertheless, assuming that the last error occurred during a call to function bar() when calling debug(foo) followed by a call to foo() Traceback will show foo() rather than bar().

It seems therefore reasonable to assume that the new middle panel on the right hand side represents the list of functions being debugged rather than the content of .Traceback (traceback() prints the content of .Traceback list).

Environment

The upper panel on the right hand side shows, as usual, a tab named Environment.

When debug mode is not activated, this tab lists the objects existing in the .GlobalEnv.

When debug mode is activated the Environment panel shows the content of the evaluation frame corresponding to the function being debugged (Figure 3, see also Figure 5 at the bottom of the post).

This features is extremely useful as it allows to have the evaluation environments of all functions being debugged clearly displayed just in front of you.

In our simple example, when calling foo(x = 0) the environment panel show the name x associated with its value 0, that is, the value of the argument passed to function foo() associated to its value in the evaluation environment of function foo().

Highlighting

Among all, the most useful features of any visual debugger, is represented by the highlighting of line being debugged at any step.

In order to achieve it, RStudio opens the file corresponding to the function being debugged and, each time the next button is pressed, the evaluator moves to the next line and the highlight moves on the next line too.

As within any visual debugging tool, the RStudio visual debugger helps the developer to immediately visualize what line of the function is evaluated at one time without loosing the overall picture (Figure 4, see also Figure 5 at the bottom of the post).

At present stage of development, the possibility of inserting a breakpoint within the function body while debugging, does not seems to exists, but I am pretty much sure I have seen it during the demos at useR 2013. Therefore, I wouldn’t be surprise if the next RStudio release will be come with this feature too.

myDebug

Given that this is a real helpful tool, especially when intensively developing with R, before a function can be debugged, it requires to be saved to a file and the file itself need to sourced.

In case you need to debug a function not yet saved nor sourced, a simple function like:

myDebug =  function(f){ 
  fname = deparse(substitute(f)) 
  dump(fname, file = "tmp.R") 
  source("tmp.R") 
  do.call("debugonce", args = list(fname), envir = globalenv()) 
  invisible(NULL) 
}

allows to start the visual debugger immediately:

mydebugonce(foo)
foo(x=0)

Overall screenshot

(Figure 5, RStudio overall screenshot)