debug.qmd

# Debug {.unnumbered}

```{r}
#| eval: true 
#| echo: false 
#| include: false
source("_common.R")
library(shinypak)
```

```{r}
#| label: co_box_dev
#| echo: false
#| results: asis
#| eval: true
co_box(
  color = "r", 
  header = "Warning",
  contents = "The contents in this section are under development. Thank you for your patience."
)
```

Expand the callout boxes below to review what we've covered in the last section:

::: {.callout-note collapse='true'}

## [Documentation (Chapter 5)]{style='font-size: 1.35em;'}

In the [Documentation](document.qmd) chapter we covered: 

- @sec-intro-roxygen2  
  - @sec-roxygen2-md-support
  - @sec-roxygen2-title
  - @sec-roxygen2-param-return  
  - @sec-roxygen2-examples 
  
- @sec-document-app-functions  
  - @sec-roxygen2-family 
  - @sec-roxygen2-section 
  - @sec-roxygen2-usage

:::

::: {.callout-note collapse='true'}

## [Dependencies (Chapter 6)]{style='font-size: 1.35em;'}

In [Dependencies](dependencies.qmd), we walked through:

- @sec-depends-exports  
- @sec-depends-imports  

:::

::: {.callout-note collapse='true'}

## [Data (Chapter 7)]{style='font-size: 1.35em;'}

[Data](data.qmd) covered three common locations for storing and documenting data in R packages: 

- @sec-data-data  
  - @sec-document-data
  - @sec-data-system-file

- @sec-data-data-raw  
- @sec-data-inst-extdata  

:::

::: {.callout-note collapse='true'}

## [Launch (Chapter 8)]{style='font-size: 1.35em;'}

[Launch](launch.qmd) describes the differences between Shiny run functions and what to include in the app.R file and standalone app function:

- App functions: 
  - @sec-launch-shiny-app
  - @sec-launch-run-app
  - @sec-launch-shiny-app-dir

- @sec-launch-app-dot-r
  - @sec-launch-standalone-app-function

:::

::: {.callout-note collapse='true'}

## [Resources (Chapter 9)]{style='font-size: 1.35em;'}

[Resources](resources.qmd) covered how to include external files and/or resources in your app (i.e., those previously stored in `www/`): 

- @sec-resources-image-files
    - @sec-resources-add-resource-path 

- Other uses of `inst/`:
    - @sec-resources-inst-dev
    - @sec-resources-inst-quarto
    - @sec-resources-inst-prod

:::

Debugging is the process of identifying, analyzing, and fixing errors in our code.[^debug-define] In Shiny apps, debugging can be challenging because the reactive model involves dynamic interactions and a non-linear flow of execution between inputs, reactive expressions, and outputs. Consider the diagram below that illustrates the function/module tree for our application: 

[^debug-define]: The definition in [this article from AWS](https://aws.amazon.com/what-is/debugging/#:~:text=Debugging) gives a great general overview of debugging. 

```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-cap: 'Debugging'
%%| fig-align: center
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"14px"}}}%%
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"13px"}}}%%
flowchart LR
        subgraph launch_app["launch_app()"]
            display_type["display_type()"]
            subgraph UI["movies_ui()"]
                mod_var_input_ui["mod_var_input_ui()"]
                mod_scatter_display_ui["mod_scatter_display_ui()"]
            end
            subgraph Server["movies_server()"]
                mod_var_input_server["mod_var_input_server()"]
                subgraph mod_scatter_display_server["mod_scatter_display_server()"]
                scatter_plot["scatter_plot()"]
                end
            end
        end


style UI stroke:#333,stroke-width:1px,rx:5,ry:5
style Server stroke:#333,stroke-width:1px,rx:5,ry:5

style mod_var_input_ui color:#000,fill:#f5f5f5,stroke:#333,stroke-width:1px,rx:10,ry:10
style mod_var_input_server color:#000,fill:#f5f5f5,stroke:#333,stroke-width:1px,rx:10,ry:10
style mod_scatter_display_server color:#000,fill:#f5f5f5,stroke:#333,stroke-width:1px,rx:10,ry:10
style mod_scatter_display_ui color:#000,fill:#f5f5f5,stroke:#333,stroke-width:1px,rx:10,ry:10

style display_type color:#FFF,fill:#595959,stroke:#333,stroke-width:1px,rx:25,ry:25
style scatter_plot color:#FFF,fill:#595959,stroke:#333,stroke-width:1px,rx:25,ry:25


```

 
The inputs are collected by the variable input module[^mod_var_input] and passed to the graph display module(as `var_inputs()`),[^mod_scatter_display] where they become `inputs()` to the graph utility function before finally being rendered.[^scatter_plot]

[^mod_var_input]: Our variable input model is in `R/mod_var_input.R`.

[^mod_scatter_display]: The graph display module is in `R/mod_scatter_display.R`.

[^scatter_plot]: The graph utility function is in `R/scatter_plot.R`

```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-cap: 'Reactive flow in Movies App'
%%| fig-align: center
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"13px"}}}%%
flowchart TD
    subgraph Inputs["Inputs"]
        subgraph Variables["Variables"]
        var_input[/"<code>input$x</code><br><code>input$y</code><br><code>input$z</code>"/]
        end
        subgraph Aesthetics["Aesthetics"]
        aes_input[/"<code>input$alpha</code><br><code>input$size</code>"/]
        end
        
    end
    subgraph React["Reactives"]
        var_inputs>"<code>var_inputs()</code> "]
        inputs>"<code>inputs()</code>"]
    end
    subgraph Output["Output"]
        output[\"output$scatterplot"\]
    end


    var_input & aes_input <==> |"UI"|var_inputs 
    var_inputs <==> |"Server"|inputs
    inputs <==> |"UI"|output
    
    style var_input stroke:#333,stroke-width:1px,rx:5,ry:5 
    style aes_input stroke:#333,stroke-width:1px,rx:5,ry:5
```

Our application launches with pre-selected values for the `x`, `y` and `color` graph inputs, along with values for the `size` and opacity (`alpha`) of the points. 

![](images/debug_positron_launch_app.png){width='100%' fig-align='center'}


Users can add a title or change the graph inputs, but by having pre-selected values, we guarantee the graph renders when the application launches.

```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-cap: '*Updating the plot title*'
%%| fig-align: center
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"13px"}}}%%
flowchart TD
    subgraph Inputs["Inputs"]
        subgraph Variables["Variables"]
        var_input[/"<code>input$x</code><br><code>input$y</code><br><code>input$z</code>"/]
        end
        subgraph Aesthetics["Aesthetics"]
        aes_input[/"<code>input$alpha</code><br><code>input$size</code>"/]
        end
        subgraph Title["Title"]
        plot_title[/"<code>input$plot_title</code>"/]
        end
        
    end
    subgraph React["Reactives"]
        var_inputs>"<code>var_inputs()</code> "]
        inputs>"<code>inputs()</code>"]
    end
    subgraph Output["Output"]
        output[\"output$scatterplot"\]
    end


    var_input & aes_input <==> |"UI"|var_inputs 
    plot_title <-.-> |"UI"|var_inputs 
    var_inputs <==> |"Server"|inputs
    inputs <==> |"UI"|output
    
    style var_input stroke:#333,stroke-width:1px,rx:5,ry:5 
    style aes_input stroke:#333,stroke-width:1px,rx:5,ry:5
```

![*The new title is passed with `var_inputs()` to `inputs()` and updates the graph to display the text.*](images/debug_positron_update_launch_app.png){width='100%' fig-align='center'}

### Shiny bugs

Shiny is inherently asynchronous, so bugs can originate from reactive dependencies, execution order, utility functions, hidden states, lazy evaluation, and invalidation (i.e., `reactive()`, `observe()`, `isolate()`, etc.).

For example, we could have an incorrectly defined `inputId`s or `outputId`s in the UI, which causes our graph utility function to fail. We could also have missing parentheses on reactive values in the server. Finally, the bug could be originating from the output/render point.


```{=html}

<style>

.codeStyle span:not(.nodeLabel) {
  font-family: monospace;
  font-size: 1.5em;
  font-weight: bold;
  color: #9753b8 !important;
  background-color: #f6f6f6;
  padding: 0.2em;
}

</style>
```

```{mermaid}
%%| fig-cap: '*Possible locations of bugs in a reactive model*'
%%| fig-align: center
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"13px"}}}%%
flowchart TD
    subgraph Inputs["Inputs"]
        var_input[/"<code>input$x</code>
                   <code>input$y</code> 
                   <code>input$z</code> 
                   <code>input$alpha</code>
                   <code>input$size</code>
                   <code>input$plot_title</code>"/]
    end
    subgraph React["Reactives"]
        var_inputs>"<code>var_inputs()</code> "]
        inputs>"<code>inputs()</code>"]
        
        
        
    end
    subgraph Output["Output"]
        output[\"output$scatterplot"\]
        
    end

    Inputs <==> |"Incorrect <code>inputId</code><br>or <code>outputId</code>"|var_inputs 
    var_inputs <==> |"<code>observe()</code><br>listener error"|inputs
    inputs <==> |"<code>render_*</code><br>function error"|output
    
    style var_input stroke:#333,stroke-width:1px,rx:5,ry:5 
```
 
Understanding the interplay of reactivity, lazy evaluation, asynchronous execution, and hidden states will help us diagnose and resolve bugs in our Shiny app-packages. We have to employ specific strategies and tools to handle Shiny bugs effectively, and some of the traditional debugging approaches can fall short in reactive contexts. The chapters in this section will cover how to adapt common methods for debugging R code to use with our Shiny application.