BST430 Lecture 14

.title[
# BST430 Lecture 14
]
.subtitle[
## Functions (iii), testing and debugging
]
.author[
### Don Harrington, based on the course by Andrew McDavid
]
.institute[
### U of Rochester
]
.date[
### 2021-10-13 (updated: 2024-10-23 by TL)
]

---

# Agenda

1.  Functions and generics
2.  Knitr tricks
3.  Debugging

Here's the [R code in this lecture](l14/l14-debugging.R)

---

#  Functions and generics

Have you ever wondered how does R knows to display a data.frame specially compared to a list?  (The `typeof` both is `list`, but a `data.frame` has a different class...)
Consider:
1.  When you input an object to the Console and hit "enter", R calls `print(object)`

``` r
my_list = list(A = 1:4, B = rnorm(4), C = stringr::fruit[1:4])
my_list
```

```
## $A
## [1] 1 2 3 4
## 
## $B
## [1] -1.2070657  0.2774292  1.0844412 -2.3456977
## 
## $C
## [1] "apple"   "apricot" "avocado" "banana"
```

---

``` r
print(my_list)
```

```
## $A
## [1] 1 2 3 4
## 
## $B
## [1] -1.2070657  0.2774292  1.0844412 -2.3456977
## 
## $C
## [1] "apple"   "apricot" "avocado" "banana"
```

---

### Print

Let's look at the source of `print`:

``` r
print
```

```
## function (x, ...) 
## UseMethod("print")
## <bytecode: 0x00000234596875d8>
## <environment: namespace:base>
```

Huh, that's not helpful.

---

### R classes and generics

Unlike most other languages, a `class` in R can belong to a set of `generics`.  The generics are akin to a method<sup>1</sup>. Let's spend a moment thinking about more ordinary languages before we return to R:

---

### C++ classes and methods

``` c
#include <iostream>

class Person {
 public:
  void Print() const;

private:
  std::string name_;
  int age_ = 5;
};

void Person::Print() const {
  std::cout << name_ << ':' << age_ << '\n';
}
```

This C++ class implements the `Person` class, which contains two members -- `name_` and `age_`.  It implements one method: `Print()`.  Note that the `print` method is defined in, and belongs to the class.

---
class: code70

### The R `print` methods
.pull-left[
In contrast, in R there is a `print` generic, and each class can choose to implement its own method for the generic.  We can see all the different ways this generic has been implemented with `methods`.  
.font50[[1] Using the S3 object orientation system, which is the original and most commonly used system.  Base R also contains two other systems: S4 and refClasses (R5).  S4 is like S3 but with stronger class typing guarantees. R5 behaves like "ordinary" object oriented languages.  There are also several commonly used external implementation of object orientation in R... 🤯]
]
.pull-right[
Behold the print methods:
<div class="datatables html-widget html-fill-item" id="htmlwidget-84a58f836166d559454e" style="width:100%;height:auto;"></div>
<script type="application/json" data-for="htmlwidget-84a58f836166d559454e">{"x":{"filter":"none","vertical":false,"data":[["1","2","3","4","5","6","7","8","9","10","11","12","13","14","15","16","17","18","19","20","21","22","23","24","25","26","27","28","29","30","31","32","33","34","35","36","37","38","39","40","41","42","43","44","45","46","47","48","49","50","51","52","53","54","55","56","57","58","59","60","61","62","63","64","65","66","67","68","69","70","71","72","73","74","75","76","77","78","79","80","81","82","83","84","85","86","87","88","89","90","91","92","93","94","95","96","97","98","99","100","101","102","103","104","105","106","107","108","109","110","111","112","113","114","115","116","117","118","119","120","121","122","123","124","125","126","127","128","129","130","131","132","133","134","135","136","137","138","139","140","141","142","143","144","145","146","147","148","149","150","151","152","153","154","155","156","157","158","159","160","161","162","163","164","165","166","167","168","169","170","171","172","173","174","175","176","177","178","179","180","181","182","183","184","185","186","187","188","189","190","191","192","193","194","195","196","197","198","199","200","201","202","203","204","205","206","207","208","209","210","211","212","213","214","215","216","217","218","219","220","221","222","223","224","225","226","227","228","229","230","231","232","233","234","235","236","237","238","239","240","241","242","243","244","245","246","247","248","249","250","251","252","253","254","255","256","257","258","259","260","261","262","263","264","265","266","267","268","269","270","271","272","273","274","275","276","277","278","279","280","281","282","283","284","285","286","287","288","289","290","291","292","293","294","295","296","297","298","299","300","301","302","303","304","305","306","307","308","309","310","311","312","313","314","315","316","317","318","319","320","321","322","323","324","325","326","327","328","329","330"],["print.acf","print.activeConcordance","print.AES","print.all_vars","print.anova","print.any_vars","print.aov","print.aovlist","print.ar","print.Arima","print.arima0","print.AsIs","print.aspell","print.aspell_inspect_context","print.bibentry","print.Bibtex","print.browseVignettes","print.bslib_breakpoints","print.bslib_fragment","print.bslib_page","print.bslib_showcase_layout","print.bslib_value_box_theme","print.by","print.cachem","print.changedFiles","print.check_bogus_return","print.check_code_usage_in_package","print.check_compiled_code","print.check_demo_index","print.check_depdef","print.check_details","print.check_details_changes","print.check_doi_db","print.check_dotInternal","print.check_make_vars","print.check_nonAPI_calls","print.check_package_code_assign_to_globalenv","print.check_package_code_attach","print.check_package_code_data_into_globalenv","print.check_package_code_startup_functions","print.check_package_code_syntax","print.check_package_code_unload_functions","print.check_package_compact_datasets","print.check_package_CRAN_incoming","print.check_package_datalist","print.check_package_datasets","print.check_package_depends","print.check_package_description","print.check_package_description_encoding","print.check_package_license","print.check_packages_in_dir","print.check_packages_used","print.check_po_files","print.check_pragmas","print.check_Rd_line_widths","print.check_Rd_metadata","print.check_Rd_xrefs","print.check_RegSym_calls","print.check_S3_methods_needing_delayed_registration","print.check_so_symbols","print.check_T_and_F","print.check_url_db","print.check_vignette_index","print.checkDocFiles","print.checkDocStyle","print.checkFF","print.checkRd","print.checkRdContents","print.checkReplaceFuns","print.checkS3methods","print.checkTnF","print.checkVignettes","print.citation","print.cli_ansi_html_style","print.cli_ansi_string","print.cli_ansi_style","print.cli_boxx","print.cli_diff_chr","print.cli_doc","print.cli_progress_demo","print.cli_rule","print.cli_sitrep","print.cli_spark","print.cli_spinner","print.cli_tree","print.clock","print.codoc","print.codocClasses","print.codocData","print.col_spec","print.collector","print.colorConverter","print.compactPDF","print.condition","print.conflict_report","print.connection","print.CRAN_package_reverse_dependencies_and_views","print.crayon","print.css","print.data.frame","print.Date","print.date_names","print.default","print.dendrogram","print.density","print.diamond","print.difftime","print.dist","print.Dlist","print.DLLInfo","print.DLLInfoList","print.DLLRegisteredRoutines","print.document_context","print.document_position","print.document_range","print.document_selection","print.dplyr_join_by","print.dplyr_sel_vars","print.dummy_coef","print.dummy_coef_list","print.ecdf","print.eigen","print.element","print.emoji","print.emoji_completion","print.factanal","print.factor","print.family","print.fileSnapshot","print.findLineNumResult","print.fisher_alphabet","print.flag","print.flatGridListing","print.fontawesome","print.formula","print.fseq","print.ftable","print.fun_list","print.function","print.getAnywhere","print.ggplot","print.ggplot2_bins","print.ggproto","print.ggproto_method","print.gList","print.glm","print.glue","print.gpar","print.GridCoords","print.GridGrobCoords","print.GridGTreeCoords","print.grob","print.gtable","print.hashtab","print.hcl_palettes","print.hclust","print.help_files_with_topic","print.hexmode","print.hms","print.HoltWinters","print.hsearch","print.hsearch_db","print.htest","print.html","print.html_dependency","print.htmltools.selector","print.htmltools.selector.list","print.htmlwidget","print.infl","print.integrate","print.isoreg","print.json","print.key_missing","print.keycap","print.kmeans","print.knitr_kable","print.last_dplyr_warnings","print.Latex","print.LaTeX","print.libraryIQR","print.lifecycle_warnings","print.listof","print.lm","print.loadings","print.locale","print.loess","print.logLik","print.ls_str","print.medal","print.medpolish","print.memoised","print.MethodsFunction","print.moon","print.mtable","print.NativeRoutineList","print.news_db","print.nls","print.noquote","print.numeric_version","print.object_size","print.octmode","print.packageDescription","print.packageInfo","print.packageIQR","print.packageStatus","print.paged_df","print.pairwise.htest","print.path","print.person","print.pillar","print.pillar_1e","print.pillar_colonnade","print.pillar_ornament","print.pillar_shaft","print.pillar_squeezed_colonnade","print.pillar_tbl_format_setup","print.pillar_vctr","print.pillar_vctr_attr","print.POSIXct","print.POSIXlt","print.power.htest","print.ppr","print.prcomp","print.princomp","print.proc_time","print.purrr_function_compose","print.purrr_function_partial","print.purrr_rate_backoff","print.purrr_rate_delay","print.quosure","print.quosures","print.R6","print.R6ClassGenerator","print.raster","print.Rconcordance","print.Rd","print.recordedplot","print.rel","print.restart","print.RGBcolorConverter","print.RGlyphFont","print.rlang:::list_of_conditions","print.rlang_box_done","print.rlang_box_splice","print.rlang_data_pronoun","print.rlang_dict","print.rlang_dyn_array","print.rlang_envs","print.rlang_error","print.rlang_fake_data_pronoun","print.rlang_lambda_function","print.rlang_message","print.rlang_trace","print.rlang_warning","print.rlang_zap","print.rle","print.rlib_bytes","print.rlib_error_3_0","print.rlib_trace_3_0","print.roman","print.sass","print.sass_bundle","print.sass_layer","print.SavedPlots","print.scalar","print.sessionInfo","print.shiny.tag","print.shiny.tag.env","print.shiny.tag.list","print.shiny.tag.query","print.simple.list","print.smooth.spline","print.socket","print.square","print.src","print.srcfile","print.srcref","print.stepfun","print.stl","print.stringr_view","print.StructTS","print.subdir_tests","print.summarize_CRAN_check_status","print.summary.aov","print.summary.aovlist","print.summary.ecdf","print.summary.glm","print.summary.lm","print.summary.loess","print.summary.manova","print.summary.nls","print.summary.packageStatus","print.summary.ppr","print.summary.prcomp","print.summary.princomp","print.summary.table","print.summary.warnings","print.summaryDefault","print.suppress_viewer","print.table","print.tables_aov","print.tbl","print.terms","print.theme","print.tidyverse_conflicts","print.tidyverse_logo","print.transform","print.trunc_mat","print.ts","print.tskernel","print.TukeyHSD","print.tukeyline","print.tukeysmooth","print.undoc","print.uneval","print.unit","print.vctrs_bytes","print.vctrs_sclr","print.vctrs_unspecified","print.vctrs_vctr","print.viewport","print.vignette","print.warnings","print.xfun_raw_string","print.xfun_record_results","print.xfun_rename_seq","print.xfun_strict_list","print.xgettext","print.xngettext","print.xtabs"]],"container":"<table class=\"display\">\n  <thead>\n    <tr>\n      <th> <\/th>\n      <th>method<\/th>\n    <\/tr>\n  <\/thead>\n<\/table>","options":{"columnDefs":[{"orderable":false,"targets":0},{"name":" ","targets":0},{"name":"method","targets":1}],"order":[],"autoWidth":false,"orderClasses":false}},"evals":[],"jsHooks":[]}</script>
]

---
class: code50

### Inspecting R methods

Let's look at data frame's print method:

``` r
base:::print.data.frame
```

```
## function (x, ..., digits = NULL, quote = FALSE, right = TRUE, 
##     row.names = TRUE, max = NULL) 
## {
##     n <- length(row.names(x))
##     if (length(x) == 0L) {
##         cat(sprintf(ngettext(n, "data frame with 0 columns and %d row", 
##             "data frame with 0 columns and %d rows"), n), "\n", 
##             sep = "")
##     }
##     else if (n == 0L) {
##         print.default(names(x), quote = FALSE)
##         cat(gettext("<0 rows> (or 0-length row.names)\n"))
##     }
##     else {
##         if (is.null(max)) 
...
```

To do this, I figured out in what package the `data.frame` class was defined, and used `:::` to access a private member from the namespace of that package.  Can also use `getS3method`.

---

### Implementing a print generic

So we want to make our own class, and have it print specially we need to do two things:

1.  Set the class attribute on the object
2.  Implement the generic by defining a function called `generic.<class>`

---

``` r
class(my_list) = 'dr_awesome'
print.dr_awesome = function(x, ...){
  type = class(x)
  len = length(x)
  cat(glue::glue("An object of type {type} and length {len}.
  Andrew drools, Dr. Awesome Rules!"))
}
```

``` r
print(my_list)
```

```
## An object of type dr_awesome and length 3.
## Andrew drools, Dr. Awesome Rules!
```

---

### S3 Generics and functions summary

May you live a long and prosperous life without implmenting your own object-oriented code in R.  But, to debug issues in other people's code, you will want to take to heart:

*  some functionality in R is hidden behind generics and methods.  
*  Sometimes, to understand what code is being run, you will need to determine the class of your object, and examine its methods with `package:::generic.class` or `getS3method`.

If you work with S4 objects, or what to implement your own objects and methods, you need want to do [some more reading](https://adv-r.hadley.nz/oo.html).

---

# a few rmarkdown tricks

---

### Using the cache

As your markdown scripts become longer and longer, you will become impatient to have to run every line in the script what some small change does towards the bottom.  To combat this, turn on the cache by inserting this somewhere near the top of your rmarkdown:

``` r
knitr::opts_chunk$set(cache = TRUE, autodep = TRUE)
```

Now, every chunk after this will be rerun only if its source code changes, or if it references objects modified in chunks whose source code changes

---

### cache caveats

1.  To determine chunk dependencies, knitr does some sort of static code analysis, and sometimes misses induced changes in objects.
2.  The cache can sometimes [fail to capture](https://yihui.org/knitr/demo/cache/) some types of side-effects (e.g. printing stuff to Console or displaying a plot.
3.  When in doubt, throw it out--click "Knit" -> "Clear knitr cache" to delete the cache and start again.

---

### Evaluating rmarkdown in the global environment

We have seen that clicking the "knit" button does not affect the state of the global environment in the Console -- instead you have to click "run chunk" or "run all chunks" button.  However, if you enter

``` r
rmarkdown::render("<path to my document>") 
```

in the console, your document will be knit, and all the chunks will be evaluated in the global environment, so you can start working interactively with the objects defined therein.

---

### `knit_exit()` and `eval = FALSE`

This can be combined usefully with `knit_exit()`, which terminates a rmarkdown document early.  Place this somewhere in your markdown and execution will stop at that point.  Then you can knit your document exit out at the point the function is called.

*  You can also set `eval = FALSE` as a chunk option to effectively skip a chunk.
````markdown
```{r, eval = FALSE}
object = object %>% mutate(not_evaluated = TRUE)
```
````

*  Note that rmarkdown chunks can contain arbitrary R code and objects, so you could also set `eval = debugging` to run a chunk only if the R object is defined earlier and `TRUE`.

---

# debugging

---

## Debugging what

Informally, we use a process of differential diagnosis:

0. Reproduce the error: can you make the bug reappear?
1. Characterize the error: what can you see that is going wrong?
2. Localize the error: where in the code does the mistake originate?
3. Modify the code: did you eliminate the error? Did you add new ones?

---
## Debugging how

To debug code efficiently you need a develop both your

*  **Mindset**: enumerate your assumptions, test these assumptions, look for contradictions.
*  **Toolset**: understand error reporting in R, and how to pause and inject yourself interactively into code.

---

## Mindset

My code isn't working -- why?  Step one (often skipped, at your peril!) is to list your assumptions about what the code is supposed to do.  Try to answer

1.  What unit of code is involved?
1.  What preconditions need to hold on the input to this code?
2.  What do I think this code does?
3.  What would cause this code to fail?
4.  How would it report a failure?

Hint:  .alert[unit tests] are a great way to both list and test your assumptions.

---

### What unit of code?

This is often the hardest part. But the first step is to reproduce the bug.

- Can we produce it repeatedly when re-running the same code, with the same input values? 
- And if we run the same code in a .alert[clean copy] of R, does the same thing happen?

---

### Localizing can be easy or hard

Sometimes error messages are easier to decode, sometimes they're harder; this can make locating the bug easier or harder

``` r
base_plot = function(x, y, list_data = NULL) {
  if (!is.null(list_data)) 
    plot(list_data, main="A plot from list_data!")
  else
    plot(x, y, main="A plot from x, y!")
}
```

---

``` r
base_plot(list_data=list(x=-10:10, y=(-10:10)^3))
```

---

``` r
base_plot() # Easy to understand error message
```

```
## Error in base_plot(): argument "x" is missing, with no default
```

``` r
base_plot(list_data=list(x=-10:10, Y=(-10:10)^3)) # Not as clear
```

```
## Error in xy.coords(x, y, xlabel, ylabel, log): 'x' is a list, but does not have components 'x' and 'y'
```

Who called `xy.coords()`? (Not us, at least not explicitly!) And why is it saying 'x' is a list? (We never set it to be so!)

---

### `traceback()`

Calling `traceback()`, after an error: traces back through all the function calls leading to the error

- Start your attention at the "bottom", where you recognize the function you called
- Read your way up to the "top", which is the lowest-level function that produces the error
- Often the most useful bit is somewhere in the middle

---

If you run `base_plot(list_data=list(x=-10:10, Y=(-10:10)^3))` in the console, then call `traceback()`, you'll see:

```
> traceback()
5: stop("'x' is a list, but does not have components 'x' and 'y'")
4: xy.coords(x, y, xlabel, ylabel, log)
3: plot.default(list_data, main = "A plot from list_data!")
2: plot(list_data, main = "A plot from list_data!") at #4
1: base_plot(list_data = list(x = -10:10, Y = (-10:10)^3))
```

We can see that `base_plot()` is calling `plot()` is calling `plot.default()` is calling `xy.coords()`, and this last function is throwing the error

Why? Its first argument `x` is being set to `list_data`, which is OK, but then it's expecting this list to have components named `x` and `y` (ours are named `x` and `Y`)

---

## Test assumptions and look for contradictions

*  Now try running your code in a way that satisfies the assumed preconditions and see if you can find a contradiction between the assumed and observed output
*  It should be clear, that smaller and more modular the functions are, the easier it is to test for contradictions.

*  If you are losing your mind about a bug, set it aside for a few hours or day, and try again later.  Or do some [rubber duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging) debugging.

---

## Toolset

But sometimes code is monolithic, and there's nothing we can do about it.  To debug in this case, we need to turn to our toolset.

*  break up pipelines and nested expressions
*  inspect manually
*  inspect with printf 

*  inspect with `browser()` (set a breakpoint)
*  step through with `debug`
*  inspect with `options(error = recover)`

---

### Break up pipelines (and inspect manually)

``` r
flights %>% 
  mutate(hourf = as.factor(hour), day_of_week = weekdays(ymd(glue::glue("{year}-month-{day}")))) %>%
  group_by(hourf, day_of_week, .drop = FALSE) %>%
  summarize(cancel_rate = mean(is.na(arr_time))) %>%
  ggplot(aes(x = hour, y = day_of_week, fill = cancel_rate)) + 
    geom_tile() + 
    scale_fill_distiller(palette = 'PuBu', direction = 1)
```

```
## Warning: There was 1 warning in `mutate()`.
## ℹ In argument: `day_of_week =
##   weekdays(ymd(glue::glue("{year}-month-{day}")))`.
## Caused by warning:
## ! All formats failed to parse. No formats found.
```

```
## Error in `geom_tile()`:
## ! Problem while computing aesthetics.
## ℹ Error occurred in the 1st layer.
## Caused by error in `compute_aesthetics()`:
## ! Aesthetics are not valid data columns.
## ✖ The following aesthetics are invalid:
## ✖ `x = hour`
## ℹ Did you mistype the name of a data column or forget to add
##   `after_stat()`?
```
]
.panel[.panel-name[Plot]

---

### After (bug fixed)

``` r
cancellation = flights %>% 
  mutate(hourf = as.factor(hour), day_of_week = weekdays(ymd(glue::glue("{year}-{month}-{day}")))) %>%
  group_by(hourf, day_of_week, .drop = FALSE) %>%
  summarize(cancel_rate = mean(is.na(arr_time)), n_flights =  n()) %>%
  filter(n_flights > 500)

cancellation %>%
  ggplot(aes(x = hourf, y = day_of_week, fill = cancel_rate)) + 
    geom_tile() + 
    scale_fill_distiller(palette = 'PuBu', direction = 1)
```
]
.panel[.panel-name[Plot]
<img src="l14-debugging_files/figure-html/unnamed-chunk-17-1.png" width="60%" style="display: block; margin: auto;" />
]]

---

### `browser()`

One of the simplest but most powerful built-in debugging tools: `browser()`. Place a call to `browser()` at any point in your function that you want to debug. As in:

```
fun = function(arg1, arg2, arg3) {
  # Some initial code 
  browser()
  # Some final code
}
```

Then redefine the function in the console, and run it. Once execution gets to the line with `browser()`, you'll enter an interactive debug mode

---

### Things to do while browsing

While in the interactive debug mode granted to you by `browser()`, you can type any normal R code into the console, to be executed within in the function environment, so you can, e.g., investigate the values of variables defined in the function

---

You can also type:

- "n" (or simply return) to execute the next command
- "s" to step into the next function
- "f" to finish the current loop or function
- "c" to continue execution normally
- "Q" to stop the function and return to the console

(To print any variables named `n`, `s`, `f`, `c`, or `Q`, defined in the function environment, use `print(n)`, `print(s)`, etc.)

---

### Browsing in R Studio

You have buttons to click that do the same thing as "n", "s", "f", "c", "Q" in the "Console" panel; you can see the locally defined variables in the "Environment" panel; the traceback in the "Traceback" panel

---

### Knitting and debugging

As with `cat()`, `print()`, `traceback()`, used for debugging, you should only run `browser()` in the Console, never in an Rmd code chunk that is supposed to be evaluated when knitting. See more [here](https://support.rstudio.com/hc/en-us/articles/205612627-Debugging-with-RStudio#debugging-in-r-markdown-documents)

But, to keep track of your debugging code (that you'll run in the console), you can still use code chunks in Rmd, you just have to specify `eval=FALSE`

``` r
# As an example, here's a code chunk that we can keep around in this Rmd doc,
# but that will never be evaluated (because eval=FALSE) in the Rmd file, take 
# a look at it!
mat = matrix(rnorm(1000)^3, 1000, 1000)
mat
# Note that the output of mat is not printed to the console, and also
# that mat was never actually created! (This code was not evaluated)
```

---

### More ways to inspect code without modifying it

*  Instrument a function with `debug()` -- this will let you step through execution line by line
```
debug(<FUNCTION>)
<FUNCTION>(<BUGGY ARGUMENTS...>)
```

*  Set `options(error = recover)` to open a debugger after an error occurs.

As with `browser()` these cannot be run by knitting a chunk or a document.

---

# Acknowledgments

Some materials from Ryan Tibshirani Stat 18 on [debugging and testing](https://www.stat.cmu.edu/~ryantibs/statcomp-S18/lectures/debugging.html)

### Caveats for debugging rmarkdown

https://rstats.wtf/debugging-r-code.html#debugging-in-r-markdown-documents

https://adv-r.hadley.nz/debugging.html