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
debugonce() on a function.
Therefore, assuming we define a simple function
Debug mode on
foo() can be entered in many ways. Nevertheless, to keep it simple, we only use a call to either
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
Visual Debugging with RStudio
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.
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:
|Next||n||Advance to the next step.|
|Continue||c||Continue to the end of the current context.|
|Stop||Q||Exit debug mode.|
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
: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
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() prints the content of
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
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
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.
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:
allows to start the visual debugger immediately:
(Figure 5, RStudio overall screenshot)