An output that explains where its number came from

whenceOutput() shows a single value. The viewer can click the value (or press Enter or Space on it) to open a panel. The panel shows how many rows each step of the pipeline removed, and the code that makes the value again. A button in the panel shows the rows that make the value.

Usage

whenceOutput(outputId, label = NULL)

renderWhence(
  expr,
  format = NULL,
  env = parent.frame(),
  quoted = FALSE,
  outputArgs = list()
)

Arguments

outputId

The output id.

label

Text to show before the value, or NULL for none. The panel uses it in its heading too.

expr

A pipeline that ends in a single value.

format

A function that takes the value and gives the text to show. A formatter of 'scales' works, for example scales::label_dollar(), and so does function(x) paste0(round(x), " kg"). With NULL, a number gets a comma for each thousand, and any other value goes through as.character().

env

The environment in which to evaluate expr.

quoted

Is expr already quoted? Use TRUE when you give an expression made with quote().

outputArgs

A list of arguments for whenceOutput(), such as label, when the render is used in an R Markdown document with runtime: shiny.

Value

whenceOutput() gives an HTML tag for the UI. renderWhence() gives a render function for the server.

Details

renderWhence() makes the value. Give it a pipeline that ends in a single value, as for whence_trace(). The pipeline can be inside braces, as in renderWhence({ ... }).

The panel

The panel is a popover next to the value. On a screen narrower than 576 pixels it is a sheet at the bottom of the screen. Escape and a click outside it close it, and the focus then goes back to the value. The panel and the waterfall have no colours of their own: they use currentColor and the variables of the Bootstrap theme.

These CSS classes are stable, and you can style them: .whence-value (the value), .whence-panel (the panel), .whence-backdrop, .whence-waterfall (the list of steps), .whence-delta (a count of removed rows) and .whence-code (the reproduce code).

Reactivity

Each step runs in the environment of the render. It reads inputs and reactive values as the full expression would, so the output updates when they change. format runs on the server too, so it can read inputs, for example to choose a currency.

Examples

whenceOutput("total", label = "Total revenue")
#> <div id="total" class="whence-output" data-label="Total revenue">
#>   <span class="whence-label">Total revenue</span>
#>   <span class="whence-slot"></span>
#> </div>

if (interactive() && requireNamespace("dplyr", quietly = TRUE)) {
  library(shiny)
  library(dplyr, warn.conflicts = FALSE)

  ui <- fluidPage(
    selectInput("cyl", "Cylinders", c(4, 6, 8)),
    whenceOutput("mean_mpg", label = "Mean mpg")
  )
  server <- function(input, output, session) {
    output$mean_mpg <- renderWhence(
      mtcars |>
        filter(cyl == input$cyl) |>
        summarise(mpg = mean(mpg)),
      format = function(x) paste(round(x, 1), "mpg")
    )
  }
  shinyApp(ui, server)
}