index.qmd

---
title: "Debugging"
author: "Shannon Pileggi"
footer:  "[Debugging](https://github.com/rstats-wtf/wtf-debugging-slides)"
logo: "img/wtf-logo-square-transparent.png"
format: 
  revealjs: 
    theme: [night, slides.scss]
    highlight-style: a11y
    transition: fade
    slide-number: true
    chalkboard: true
editor: visual
execute:
  freeze: auto
---

# Agenda

Getting started

Troubleshooting

Moving on

Debugging your code

Debugging in RStudio

Debugging their code

Special cases

Read the source

# Getting started

```{r}
library(countdown)
```

```{r font-awesome-color}
# fill for font awesome icons
fa_fill <- "#C7B41D"
```

## Licensing

<br> <br> This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) (CC BY-SA4.0).

## Checklist

<br>

`r fontawesome::fa("check", fill = fa_fill)` R installed?
Pretty recent?

     Recommended R ≥ 4.2.0

`r fontawesome::fa("check", fill = fa_fill)` RStudio installed?

     I'm on 2022.02.3+492

`r fontawesome::fa("check", fill = fa_fill)` Ready to build packages?

     `devtools::has_devel()`<br>      *Your system is ready to build packages!*

## Additional resources {.smaller}

-   WTF Ch 11 *Debugging R code* <br> <https://rstats.wtf/debugging-r-code.html>

-   Advanced R Ch 22 *Debugging* <br> <https://adv-r.hadley.nz/debugging.html>

-   Jenny Bryan 2020 RStudio Conf Keynote *Object of type closure is not subsettable* <br> <https://github.com/jennybc/debugging#readme>

-   Amanda Gadrow 2018 Webinar *Debugging techniques in RStudio* <br> <https://www.rstudio.com/resources/webinars/debugging-techniques-in-rstudio/>

-   Jim Hester 2019 *Introduction to debugging in R and RStudio* <br> <https://www.jimhester.com/talk/2019-crug-debugging/>

-   Maëlle Salmon 2021 *How to become a better R code detective?* <br> <https://masalmon.eu/2021/07/13/code-detective/>

-   Kara Woo 2019 RStudio Conf *Box plots A case study in debugging and perseverance* <https://www.rstudio.com/resources/rstudioconf-2019/box-plots-a-case-study-in-debugging-and-perseverance/>

::: footer
:::


## Troubleshooting

1. **SEARCH** <br> *Teach Me How To Google*, Samantha Csik (2022) <br> [slides](https://samanthacsik.github.io/teach-me-how-to-google/slides/RLadiesSTL-2022-02-22.html#1), [recording](https://youtu.be/93WsFQUuxvA)

2. **RESET** <br> Restart R, especially when things get weird.

3. **REPREX** <br>  <https://reprex.tidyverse.org/><br> 
*make a reprex..... please*, Sharla Gelfand (2021) <br>
[slides](https://make-a-reprex-please.netlify.app/#1),
[recording](https://www.youtube.com/watch?v=G5Nm-GpmrLw)


## Reset - details

<brshort>

::: r-fit-text
Have you tried turning it `OFF` and `ON` again?
:::

<brshort>


::: columns
::: {.column width="50%"}


`Session -> Restart R` or

-   Ctrl + Shift + F10 (Windows),

-   Cmd + Shift + 0 / Cmd + Shift + F10 (Mac)

:::

::: {.column width="50%"}
`Tools -> Global Options -> Workspace`

![](img/workspace-options.PNG)
:::
:::


## Why reset?

_Which persist after rm(list = ls())?_

| Option                               | Persists?                                      |
|-------------------------------------------------------|-----------------|
| A. library(dplyr)                    | `r fontawesome::fa("check", fill = "#343838")` |
| B. summary \<- head                  | `r fontawesome::fa("xmark", fill = "#343838")` |
| C. options(stringsAsFactors = FALSE) | `r fontawesome::fa("check", fill = "#343838")` |
| D. Sys.setenv(LANGUAGE = "fr")        | `r fontawesome::fa("check", fill = "#343838")` |
| E. x \<- 1:5                         | `r fontawesome::fa("xmark", fill = "#343838")` |
| F. attach(iris)                      | `r fontawesome::fa("check", fill = "#343838")` |

```{r}
countdown(
  minutes = 2
  )
```

## Why reset?

_Which persist after rm(list = ls())?_

| Option                               | Persists?                                    |
|-------------------------------------------------------|-----------------|
| A. library(dplyr)                    | `r fontawesome::fa("check", fill = fa_fill)` |
| B. summary \<- head                  | `r fontawesome::fa("xmark", fill = "white")` |
| C. options(stringsAsFactors = FALSE) | `r fontawesome::fa("check", fill = fa_fill)` |
| D. Sys.setenv(LANGUAGE = "fr")        | `r fontawesome::fa("check", fill = fa_fill)` |
| E. x \<- 1:5                         | `r fontawesome::fa("xmark", fill = "white")` |
| F. attach(iris)                      | `r fontawesome::fa("check", fill = fa_fill)` |




## Your turn, exercise 00

Either on your Posit cloud workspace or your personal computer...


<brshort>

::: question
Set your Workspace options as shown.
:::

`Tools -> Global Options -> Workspace`

::: columns
::: {.column width="50%"}
![](img/workspace-options.PNG)
:::
:::

```{r}
countdown(
  minutes = 2,
  # Fanfare when it's over
  play_sound = TRUE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em",
  )
```



## But what if

![](img/swat-bugs.gif)

::: footer
<https://giphy.com/gifs/TreehouseDirect-agent-binky-8UabbehIqkR0akDt1y>
:::

# Moving on

<br>

::: r-fit-text
from troubleshooting to...
:::

<brshort>

::: r-fit-text
formal `debugging` techniques.
:::

## Key concepts

<br>

`r fontawesome::fa("road", fill = "white")` traceback

   `location` where did the error occur

<br>

`r fontawesome::fa("bug", fill = "white")` interactive debugger

   `context` why did the error occur

<br>

`r fontawesome::fa("magnifying-glass", fill = "white")` your code   vs   `r fontawesome::fa("hat-wizard", fill = "white")` their code

::: notes
interactive debugging: pause the execution of a function and launch environment where you can interactively explore what's happening
:::

## Debugging tools

![](img/debugging_tools.svg)

::: notes
source for image in google slides at

https://docs.google.com/presentation/d/14mqGirw4TnblqSFY0Tk30YrxkAwIrz1xo4nMIwgqk_o/edit?u
sp=sharing
:::

## 

::: r-fit-text
This is a lot.
:::

. . .

<br>

These tools achieve similar objectives slightly differently.

<br>

People don't generally use *all* of these tools at once.
They pick and choose the ones they like.


# Debugging your code

## Debugging your code

![](img/debugging_yours.svg)

## Sourcing

<br>

⚠️ name your script with functions

<brshort>

⚠️ source your script with functions

<brshort>

for the best debugging experience 😎

<br>

![](img/source-marked.jpg)

## Set up

<br>

```{r, echo = TRUE, error = TRUE}
f <- function(x) {
  x + 1
}

g <- function(x) f(x)

g("a")
```




## traceback()

<br>

```{r, eval=FALSE, echo=TRUE, error = TRUE, `code-line-numbers`="3"}
source("demo/my_functions.R")
g("a")
traceback()
```

![](img/traceback.PNG)

<br>

shows the sequence of calls that lead to the error.

::: notes
used interactively in console, called for last error observed
:::

::: footer
the trace back is also known as: <br> call stack, stack trace, & back trace
:::


## Richer traceback

<br>

```{r, eval=FALSE, echo=TRUE, error = TRUE, `code-line-numbers`="5"}
source("demo/my_functions.R")
options(error = rlang::entrace) 
g("a")
rlang::last_trace()
```

![](img/rlang_last-trace.PNG)

<br>

`options(error = rlang::entrace)` <br> could go in your `.Rprofile`

## traceback vs rlang functions

<br>

Numbering and ordering differs between `traceback()` and rlang functions.

<brshort>

![](img/traceback-ordering.PNG)

::: footer
<https://adv-r.hadley.nz/debugging.html#call-stack-ordering>
:::

## browser()

```{r, eval=FALSE, echo=TRUE, `code-line-numbers`="2"}
f <- function(x) {
  browser()
  x + 1
}

g <- function(x) f(x)
```

<br>

`browser()` opens the interactive debugger.

1.  Modify the function by inserting a `browser()` statement.

2.  Source the function.

3.  Execute the function.

## Interactive debugger

![](img/interactive-debugger.PNG)

## Interactive debugger tips

<br>

::: columns
::: {.column width="35%"}
Investigate objects

<br>

<br>

Control execution
:::

::: {.column width="5%"}
:::

::: {.column width="55%"}
`ls()`, `ls.str()`,<br> `str()`, `print()`

<br>

::: small
| command | operation                              |
|---------|----------------------------------------|
| `n`     | next statement                         |
| `c`     | continue (leave interactive debugging) |
| `s`     | step into function call                |
| `f`     | finish loop / function                 |
| `where` | show previous calls                    |
| `Q`     | quit debugger                          |
:::
:::
:::

## Debugging your code

![](img/debugging_yours.svg)

## Your turn, exercise 01

Enter Posit cloud or work locally via 
`usethis::use_course("rstats-wtf/wtf-debugging")`
(<https://github.com/rstats-wtf/wtf-debugging>)

<brshort>

::: question
Complete 01_exercise to practice debugging your own code.
:::

::: small
Check out the `README.md` for some getting started tips!

-   `01_debugging_spartan.R` (directions to explore without suggested code)

-   `01_debugging_comfy.R` (directions to explore with suggested code)

-   `01_debugging_solution.R` (directions to explore with code solutions)
:::

```{r}
countdown(
  minutes = 15,
  # Fanfare when it's over
  play_sound = TRUE,
  # Set timer theme to match solarized colors
  color_border              = "#FFFFFF",
  color_text                = "#7aa81e",
  color_running_background  = "#7aa81e",
  color_running_text        = "#FFFFFF",
  color_finished_background = "#ffa07a",
  color_finished_text       = "#FFFFFF",
  font_size = "2em",
  )
```

::: footer
<https://github.com/rstats-wtf/wtf-debugging>
:::

# Debugging in RStudio

## Debugging in the RStudio IDE

![](img/debugging_ide.svg)

## Editor breakpoints

red circle = breakpoint = `browser()`

(but you don't have to change your code)

![](img/breakpoint.PNG)

. . .

Set / re-set an editor breakpoint:

-   click to the left of the line number in the source file

-   press Shift+F9 with your cursor on the line

## Editor breakpoints

red circle = breakpoint = `browser()`

(but you don't have to change your code)

![](img/breakpoint.PNG)

To activate, either

-   click IDE Source button, or

-   `debugSource(`"demo/my_functions.R"`)`

## Debugging console

![](img/cheatsheet-debug-console.PNG)

::: footer
RStudio IDE cheatsheet

<https://www.rstudio.com/resources/cheatsheets/>
:::

## IDE on error

::: columns
::: {.column width="45%"}
Automatically invoke actions on error.

![](img/IDE_debug_menu_crop.png)
:::

::: {.column .fragment width="55%"}
New set up for demonstration.

```{r, echo=TRUE, eval=TRUE, error=TRUE}
f <- function(x) { strsplit(x, ",") }
g <- function(x) { f(x) }
g("a,b")
```

<br>

::: fragment
```{r, echo=TRUE, eval=TRUE, error=TRUE}
g(factor("a,b"))
```
:::
:::
:::

## IDE message only

<br>

![](img/IDE_message-only.PNG)

## IDE error inspector

<br>

![](img/IDE_error-inspector.PNG)

## IDE break in code

<br>

![](img/IDE_break-in-code.PNG)

## Error inspector

::: columns
::: {.column width="58%"}
```{r, echo=TRUE, eval=FALSE}
# IDE Error Inspector not triggered
f <- function(x) x + 1
g <- function(x) f(x)
g("a")

# IDE Error Inspector not triggered
strsplit(factor("a,b"), ",")

# IDE Error Inspector not triggered
f <- function(x) strsplit(x, ",")
f(factor("a,b"))

# IDE Error Inspector yes triggered
g <- function(x) f(x)
g(factor("a,b"))

```
:::

::: {.column width="5%"}
:::

::: {.column width="35%"}
<br> The error inspector is only invoked if `your` `code` is involved.
:::
:::

::: footer
To have RStudio invoke the debugger on any error,

`Tools -> Global Options -> General -> Advanced -> Debugging`

*uncheck* `Use debug error handler only when my code contains errors.`
:::

## Debugging in the RStudio IDE

![](img/debugging_ide.svg)

## Your turn, exercise 02

<br>

::: question
Complete 02_exercise to practice debugging a slightly different version of your own code, using features from the RStudio IDE.
:::

```{r}
countdown(
  minutes = 7
  )
```

::: footer
<https://github.com/rstats-wtf/wtf-debugging>
:::

# Debugging their code

## Debugging their code

![](img/debugging_theirs.svg)

## debug()

`debug()` = `browser()`/ `breakpoint` in first line of function

```{r, eval=FALSE, echo=TRUE,`code-line-numbers`="4,7"}
# source if code is yours, otherwise not necessary
source("demo/my_functions.R")
# set debugging flag
debug("g")
g("a")
# turn off debugging flag
undebug("g")
```

. . .

-   interactive debugger is initiated every time `g()` is executed, until `undebug("g")`

-   depending on function internals, this can...
    trap you in the debugger 😬

## debugonce()

`debugonce()` = `browser()`/ `breakpoint` in first line of function

```{r, eval=FALSE, echo=TRUE,`code-line-numbers`="4"}
# source if code is yours, otherwise not necessary
source("demo/my_functions.R")
# set debugging flag
debugonce("g")
g("a")
```

-   one time only!

-   interactive debugger initiated a **single** time when `g()` is executed

## options(error = recover)

`r fontawesome::fa("check", fill = fa_fill)` we already discussed <br> `options(error = rlang::entrace)`<br> for a richer traceback on error

<br>

🤠 `options(error = recover)`

1.  displays an interactive prompt with frames

2.  you select the frame to enter the debugger

## recover example

```{r, eval=FALSE, echo=TRUE,`code-line-numbers`="2"}
source("demo/my_functions.R")
options(error = recover)
g("a")
options(error = NULL)
```

<br>

![](img/options-error-recover.PNG)

## trace() overview

`trace(what = fun, tracer = browser)` <br> is equivalent to

-   inserting `browser()` in first line of function

-   `debug(fun)`

. . .

you an also insert *any* code at *any* location in function

-   `trace(what = fun, tracer = browser, at = 2)` <br>inserts `browser()` at second step of `fun`

. . .

`untrace(fun)` cancels the tracing

::: notes
`trace()` is a more flexible version of `debug()`

⚠️ `trace()` requires `{` in function definition
:::

## trace() without a specified step

<br>

```{r, eval=FALSE, echo=TRUE,`code-line-numbers`="1,4"}
trace(what = colSums, tracer = browser)
colSums(1:3)
# ls.str() in browser
untrace(colSums)
```

<br>

`trace(what = colSums, tracer = browser)` <br> is equivalent to

-   inserting `browser()` in first line of `colSums` <br> if we had the source code

-   `debug(colSums)`

## navigating function steps

<br>

investigate 🧐 the function with `as.list()` + `body()`

<brshort>

```{r, eval=FALSE, echo=TRUE}
x <- as.list(body(colSums))
View(x)
```

<brshort>

. . .

::: columns
::: {.column width="40%"}
![](img/colSums-body.png)
:::

::: {.column width="2%"}
:::

::: {.column width="58%"}
![](img/colSums-list.PNG)
:::
:::

## identify function step

![](img/colSums-list-investigate.PNG)

## trace() at specified step

<br>

```{r, eval=FALSE, echo=TRUE,`code-line-numbers`="7,12"}
# identify spot to insert code
as.list(x[[3]][[1]])
# equivalent notation
as.list(x[[c(3, 1)]])

# insert browser at step 3.1
trace(colSums, browser, at = list(c(3, 1)))
# execute function
colSums(1:3)
# ls.str() handy in browser
# cancel tracing
untrace(colSums)
```

## Debugging their code

![](img/debugging_theirs.svg)

## Your turn, exercise 03

<br>

```{r, eval=FALSE, echo=TRUE}
# already installed in the Posit Cloud work space
# install.packages("devtools")
# devtools::install_github("rstats-wtf/wtfdbg")
```

<br>

::: question
Complete 03_exercise to practice debugging others' code.
:::

```{r}
countdown(
  minutes = 10
  )
```

::: footer
<https://github.com/rstats-wtf/wtf-debugging>
:::


# Special cases

## Rmarkdown {.smaller}

<br>

#### Troubleshooting:

1.  rmarkdown chunk option `error = TRUE` enables knitting with errors

2.  insert `knitr::knit_exit()` and interactively work through .Rmd

. . .

<br>

#### Debugging:

1.  Adv R Ch 22.5.3 RMarkdown <https://adv-r.hadley.nz/debugging.html#rmarkdown>

2.  WTF Ch 11.4 Debugging in Rmarkdown documents <https://rstats.wtf/debugging-r-code.html#debugging-in-r-markdown-documents>

## Piped expressions

<br>

tracebacks can be verbose with pipes

. . .

<br>

```{r, eval=FALSE, echo=TRUE}
options(error = rlang::entrace, rlang_backtrace_on_error = "branch")
```

gives trimmed tracebacks when using pipes

. . .

<br>

-   more [contributed answers on RStudio Community](https://community.rstudio.com/t/whats-currently-the-recommended-way-to-debug-pipe-chains/14724/3)

-   Matt Dray 2019 blog post [Fix leaky pipes in R](https://www.rostrum.blog/2019/04/07/fix-leaky-pipes/)

## Warnings

<br>

If you want to dig deeper into a warning, you can convert them to errors to initiate debugging tools.

<brshort>

```{r, eval=FALSE, echo=TRUE}
?options
options(warn = 0) # default, stores warnings until top-level function returns
options(warn = 1) # warnings are printed as they occur
options(warn = 2) # upgrades warnings to errors


# initiate recover on warning
options(warn = 2, error = recover)
# restore original settings
options(warn = 0, error = NULL)

```

## Debugging special cases

![](img/debugging_special.svg)

# Wrap up

## Pick your favorite

![](img/debugging_pick.svg)


## Go forth, <br> and learn from your bugs!

::: columns
::: {.column width="53%"}
![](img/butterflies.gif){fig-align="center"}
:::

::: {.column width="2%"}
:::

::: {.column width="45%"}

`r fontawesome::fa("road", fill = "white")` traceback

<br>

`r fontawesome::fa("bug", fill = "white")` interactive debugger

<br>

`r fontawesome::fa("magnifying-glass", fill = "white")` your code   vs   <br> `r fontawesome::fa("hat-wizard", fill = "white")` their code
:::
:::

::: footer
<https://giphy.com/gifs/TreehouseDirect-max-and-ruby-maxandruby-maxruby-S3qtrEqiU5OuwAtg5Z>
:::