index.qmd

---
title: "Debugging"
author: "Shannon Pileggi"
footer:  "[Debugging](https://github.com/shannonpileggi/iterating-well-with-purrr)"
logo: "img/wtf-logo-square-transparent.png"
format: 
  revealjs: 
    theme: [night, slides.scss]
    highlight-style: a11y
    transition: fade
    slide-number: true
    chalkboard: true
editor: source
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"
```

## About

**Licensing**

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).

<br> <br>

**Material**

This material was originally developed as part of the 2-day RStudio Conference
["What They Forgot To Teach You About R"](https://rstats-wtf.github.io/wtf-2022-rsc/){target="_blank"} workshop.

## 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
:::

## 

```{r, out.width="20%"}
#| fig.alt: > 
#|   A cartoon of a fuzzy round monster face showing 10 different emotions experienced during the process of debugging code. The 
#|   progression goes from (1) “I got this” - looking determined and optimistic; (2) “Huh. Really thought that was it.” - looking a bit
#|   baffled; (3) “...” - looking up at the ceiling in thought; (4) “Fine. Restarting.” - looking a bit annoyed; (5) “OH WTF.” Looking very
#|   frazzled and frustrated; (6) “Zombie meltdown.” - looking like a full meltdown; (7) (blank) - sleeping; (8) “A NEW HOPE!” - a happy
#|   looking monster with a lightbulb above; (9) “insert awesome theme song” - looking determined and typing away; (10) “I love coding” -
#|   arms raised in victory with a big smile, with confetti falling.
knitr::include_graphics("img/debugging.jpg")
```

::: footer
Artwork by [\@allison_horst](https://twitter.com/allison_horst).

<https://github.com/allisonhorst/stats-illustrations>
:::

# Troubleshooting

## 1. Search

<br>

-   Google *exact* error message

-   keyword search on [RStudio community](https://community.rstudio.com/)

-   keyword search on [stackoverflow](https://stackoverflow.com/), `[r]` tag

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

## 2. Reset {.smaller}

<brshort>

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

. . .

<brshort>

::: r-fit-text
Restart R, especially when things get weird.
:::

. . .

::: 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)
:::
:::

::: footer
:::


## Your turn, exercise 00

[Click here to open the NHS-R RStudio Cloud debugging work space.](https://rstudio.cloud/spaces/293870/join?access_code=5lSkhQedDhpg6X-KDU0j433JgYYpIsz1YZaLGXBU){target="_blank"}


<brshort>

::: question
In RStudio Cloud, set your Workspace options as shown.
:::

`Tools -> Global Options -> Workspace`

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

```{r}
countdown(
  minutes = 3,
  # 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",
  )
```

## 3. Reprex

::: r-fit-text
minimum `repr`oducible `ex`ample
:::

::: columns
::: {.column width="45%"}
![](img/reprex-logo.png)
:::

::: {.column width="55%"}
<br> <br> <https://reprex.tidyverse.org/>
:::
:::

<brshort>

::: footer
*make a reprex..... please* by Sharla Gelfand (2021)

slides: <https://make-a-reprex-please.netlify.app/#1>

recording: <https://www.youtube.com/watch?v=G5Nm-GpmrLw>
:::

## minimum

![](img/haystack.PNG){fig-align="center"}

::: footer
Jenny Bryan (2020) *Object of type closure is not subsettable*

<https://github.com/jennybc/debugging>
:::

::: notes
MINIMAL: Don't wring hands and speculate.
Work a small concrete example that reveals, confirms, or eliminates something.
:::

## `repr`oducible `ex`ample

![](img/say_do.PNG){fig-align="center"}

::: footer
Jenny Bryan (2020) *Object of type closure is not subsettable*

<https://github.com/jennybc/debugging>
:::

::: notes
Reproducible example: No reliance on hidden state
:::

## why reprex

![](img/reprex-why.PNG){fig-align="center"}

::: footer
Jenny Bryan (2020) *Object of type closure is not subsettable*

<https://github.com/jennybc/debugging>
:::

## Review

<br>

Troubleshooting strategies:

<br>

1.  Search

2.  Reset

3.  Reprex

## 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.

## 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")
```

# Debugging your code

## print()

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

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

```{r, eval=TRUE, echo=TRUE, error=TRUE, `code-line-numbers`="2"}
g("a")
```

::: notes
Insert numerous print statements to precisely locate the problem, and see the values of important variables.

Print debugging is slow and primitive, but it always works.

Can provide location by inserting print statements in different places, can provide context by seeing values.

can assess `location` by where `print` statement is inserted

can assess `context` by value printed

`non-interactive` debugging

good for `your code`
:::

## cat()

```{r, eval=TRUE, echo=TRUE, error=TRUE, `code-line-numbers`="2-3"}
f <- function(x) {
  cat("f()\n")
  cat("x =", x, "\n")
  x + 1
}

g <- function(x) f(x)

g("a")
```

::: notes
can assess `location` by where `print` statement is inserted

can assess `context` by value printed

`non-interactive` debugging

good for `your code`

print is handy to see full object; cat is handy to create smaller messages
:::

## 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`="2,4"}
source("demo/my_functions.R")
options(error = rlang::entrace) 
g("a")
rlang::last_error()
```

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

## 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_error()
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

[Click here to open the NHS-R RStudio Cloud debugging work space.](https://rstudio.cloud/spaces/293870/join?access_code=5lSkhQedDhpg6X-KDU0j433JgYYpIsz1YZaLGXBU){target="_blank"}


<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

## 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`

*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

## 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 your RStudio 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>
:::

## Pick your favorite

![](img/debugging_pick.svg)

# 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)

# Read the source

##  {background-image="img/read-the-source-luke.PNG"}

## (almost) all source on GitHub

<br>

| Link                                                       | Description                                   |
|----------------------------------------|--------------------------------|
| [github.com/search](https://github.com/search)             | All of GitHub! Can do advanced searches, too. |
| [github.com/cran](https://github.com/cran)                 | CRAN packages                                 |
| [github.com/wch/r-source](https://github.com/wch/r-source) | R core                                        |

: {tbl-colwidths="\[50,50\]"}

<br>

[About searching on GitHub](https://docs.github.com/en/search-github/getting-started-with-searching-on-github/about-searching-on-github)

## google: cran pkgname

<br>

![](img/usethis-cran-markup.png)

::: footer
<https://cran.r-project.org/web/packages/usethis/index.html>
:::

## [github.com/cran](https://github.com/cran)

![](img/package-structure.PNG)

::: columns
::: {.column width="25%"}
In R console
:::

::: {.column width="75%"}
`pkg::fnc` to see exported functions

`pkg:::fnc` to see non-exported functions
:::
:::

::: footer
From *Package development with devtools* RStudio cheatsheet <br> <https://www.rstudio.com/resources/cheatsheets/>
:::

## Your turn, investigating a CRAN package

<br>

::: question
At a high level, <br> how does readr::read_lines() work?
:::

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

## [github.com/wch/r-source](https://github.com/wch/r-source)

<br>

| Location                                                               | Item                        |
|--------------------------------------------------|----------------------|
| [src/main](https://github.com/wch/r-source/tree/trunk/src/main)        | base R                      |
| [src/library/](https://github.com/wch/r-source/tree/trunk/src/library) | packages included in base R |
| [doc/manual](https://github.com/wch/r-source/tree/trunk/doc/manual)    | R manuals & documentation   |

## Your turn, investigating source code

<br>

::: question
1.  When was the trimws() function added to base R?

2.  How does is.na() work?
:::

*Hints on next slides.*

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

## Investigating source code hints

::: question
1.  When was the trimws() function added to base R?
:::

Try restricting search to only commit messages in [github.com/wch/r-source](https://github.com/wch/r-source/).

## Investigating source code hints

::: question
2.  How does is.na() work?
:::

1.  Look at the function.

```{r, eval=TRUE, echo=TRUE}
is.na
```

2.  Look in [github.com/wch/r-source/src/main/names.c](https://github.com/wch/r-source/blob/trunk/src/main/names.c) to find the name of the [internal function](https://github.com/wch/r-source/blob/4a73802c7d6de8670cfe8b9301232cbf2b63a201/src/main/names.c#L615).
    Or in GitHub search bar: `is.na filename:names.c`.

3.  In GitHub search bar: `"do_isna" language:c`

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

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

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

::: {.column width="40%"}
<br> <br>

Troubleshoot

Debug

Read the source
:::
:::

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