rstudio_debugging.qmd

---
title: "Debugging in RStudio"
---

## Scope: Global vs. Local Environment

All variables in a program may not be accessible at all locations in that program. This depends on where you have declared a variable.

Variables that are defined inside a function body have a local scope, and those defined outside have a global scope.

This means that local variables can be only be accessed inside the function in which they are declared. Thus, any ordinary assignments done within the function are local and temporary and are lost after exit from the function; whereas global variables can be accessed throughout the program body by all functions.

### Challenge

Try to predict what will be outputted by the following:

```{r scope 1, eval=FALSE}
foo <- function() {
    bar <- 1
    return(bar)
}
```

```{r scope 2, eval=FALSE}
bar <- 2
foo <- function() {
    bar <- 1
    return(bar)
}
```

```{r scope 3, eval=FALSE}
foo <- function() {
    bar <<- 1  #hein?!
    return(bar)
}
```

Although `<<-` is a specificity of R, the general concept of global and local scope is valid for Python and others.


### One last one
```{r scope 4, eval=FALSE}
foo <- function() {
    bar <- bar + 1
    return(bar)
}
```


## Debugging

*This section is adapted from the more detailed material available on the RStudio website: <https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio>* 

Debugging is a broad topic that can be approached in many ways. Generically, at some point you will likely attempt to execute a script in R, receive errors and not know exactly what caused the errors. One approach would be to run your code line by line, but RStudio has some useful [built-in debugging features](https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio). 

*One basic approach* to debugging is to create a breakpoint in your code -- this forces your code to "stop" executing when it reaches some certain function or line number in your code, allowing you then to examine the state of various variables, etc. The easiest way to do this is to set the breakpoint by manually clicking next to the desired line number in the code panel, [per this web example](https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-the-RStudio-IDE#entering-debug-mode-stopping):

![https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio#stopping-on-a-line](img/SetBreakPointR.png)


Setting this **editor breakpoint** creates tracing code associated with the R function object. You can remove the breakpoint by clicking on the red dot by the line number. Also note the Debug toolbar has an option to clear all breakpoints.

*Note*: keep in mind that you can't set breakpoints anywhere. In general, you want to insert breakpoints at [top-level expressions or simple, named functions.](https://support.rstudio.com/hc/en-us/articles/200534337-Breakpoint-Troubleshooting)

An alternative way to set breakpoints is with the `browser()` function. This must be typed into your code, [per this web example](https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio):

![https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio](img/browser-breakpoint.png)

(image source: <https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio#stopping-on-a-line>)

### The debugging interface

Once your code hits a breakpoint, RStudio enters debugging mode. Details on the debugging interface [can be found here](https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio), but we summarize the main points below:

The **Environment** tab will display the objects in the environment of the currently executing function (i.e., the function's defined arguments)

The **Traceback** literally traces back how you arrived at the currently executing function (latest executed command is at the top of the list). This is analagous to the "call stack" in other programming languages.

The **Code window** highlights the currently executing function and may create a new tab, named *Source Viewer*, when the current function the debugger is stepping through is not in the main R script.

The **Console** retains most of its normal functionality in debugging mode, but contains some additional buttons that appear at the top to facilitate moving through code lines (see below).

![Debugging buttons on the console](img/RStudio_debugging_console.png)

### Challenge

1. Start a new R Script
2. Write a function that computes the percentage of a number: `n*p/100`
3. Add a ratio factor as an argument so we can also use your function to compute 1/1000
4. Add a break point inside the function and use it to inspect local variables of your function


## Further Reading

- Functional programming in R: http://adv-r.had.co.nz/Functional-programming.html#functional-programming
- Scoping in R: http://adv-r.had.co.nz/Functions.html