Movatterモバイル変換

Interactive overlays on Shiny plots

Description

overshiny provides draggable and resizable rectangular elements thatoverlay plots in Shiny apps. This may be useful in applications where usersneed to define regions on the plot for further input or processing.Currently, the overlays are only designed to move along the x axis of theplot.

Details

The package exports a setup helper (useOverlay()),UI components (overlayToken(),overlayPlotOutput()),a server-side controller (overlayServer()), and a function foraligning overlays to a ggplot2 or base plot (overlayBounds()).

Author(s)

Maintainer: Nick Daviesnicholas.davies@lshtm.ac.uk [copyright holder]

See Also

Useful links:

• https://github.com/nicholasdavies/overshiny

• https://nicholasdavies.github.io/overshiny/

• Report bugs athttps://github.com/nicholasdavies/overshiny/issues

Align overlays with a ggplot2 or base plot

Description

Sets the pixel and coordinate bounds of the overlay area based on aggplot2::ggplot() object or base R plot. This ensures that overlays arepositioned correctly in both visual and coordinate space.

Usage

overlayBounds(ov, plot, xlim = c(NA, NA), ylim = c(NA, NA), row = 1L, col = 1L)

Arguments

Details

Call this function withinshiny::renderPlot(), before returning theggplot object (if using ggplot2) orNULL (if using base R plotting).

Value

The ggplot object (for ggplot2) orNULL (for base R plotting), tobe returned from theshiny::renderPlot() block.

See Also

overlayServer(), for a complete example.

Examples

server <- function(input, output) {    ov <- overlayServer("my_plot", 1, 1)    output$my_plot <- shiny::renderPlot({        plot(1:100, sin(1:100 * 0.1), type = "l")        overlayBounds(ov, "base", xlim = c(1, 100))    })    # further server code here . . .}

Create a plot output element with overlays

Description

Render ashiny::renderPlot() within an application page, with support foroverlays.

Usage

overlayPlotOutput(outputId, width, height)

Arguments

Value

A plot output element that can be added to a UI definition.

See Also

overlayServer(), for a complete example.

Examples

ui <- shiny::fluidPage(    overlayPlotOutput("my_plot", 640, 480)    # further UI elements here . . .)

Add interactive overlays to a Shiny plot

Description

This function sets up server-side infrastructure to support draggable andresizable overlays on a plot. This may be useful in applications where usersneed to define regions on the plot for further input or processing.Currently, the overlays are only designed to move along the x axis of theplot.

Usage

overlayServer(  outputId,  nrect,  width = NULL,  data = NULL,  snap = NULL,  heading = NULL,  select = NULL,  menu = NULL,  colours = overlayColours,  opacity = 0.25,  icon = shiny::icon("gear"),  stagger = 0.045,  style = list(),  debug = FALSE)

Arguments

Details

Call this function once from your server code to initialise a set of overlayrectangles for a specific plot. It creates reactive handlers for move,resize, and dropdown menu actions, and allows adding new overlays bydragging anoverlayToken() onto the plot. The function returns ashiny::reactiveValues() object which you should keep for further use; inthe examples and documentation, this object is typically calledov.

Value

Ashiny::reactiveValues() object with the following named fields:

Note: Fields marked "read-only" above should not be changed. Other fields canbe changed in your reactive code and this will modify the overlays and theirproperties. The fieldspx andpw which specify the pixel coordinates ofeach overlay can be modified, but any modifications should be placed in ashiny::isolate() call, with a call toov$update_cx(i) at the end toupdatecx0 andcx1 and apply snapping. Similarly, the fieldscx0 andcx1 which specify the plot coordinates of each overlay can bemodified, but modifications should be placed in ashiny::isolate() callwith a call toov$update_px(i) at the end to updatepx andpwand apply snapping. Thei parameter to these functions can be left outto apply changes to all overlays, or you can pass in the indices of justthe overlay(s) to be updated.

snap parameter

If you provide your own coordinate snapping function (snap argument), itshould have the signature⁠function(ov, i)⁠ whereov is theshiny::reactiveValues() object defining the overlays and their settings,andi is the set of indices for the rectangles to be updated. When theposition of any of the overlays is changed, the snapping function will beapplied. In this function, you should make sure that allov$cx0[i] andov$cx1[i] are within the coordinate bounds defined by the plot, i.e.constrained byov$bound_cx andov$bound_cw, when the function returns.This means, for example, if you are "rounding down"ov$cx0[i] to somenearest multiple of a number, you should make sure it doesn't become lessthanov$bound_cx. Finally, the snapping function will get triggered whenthe x axis range of the plot changes, so it may be a good idea to provideone if the user might place an overlay onto the plot, but then change the xaxis range of the plot such that the overlay is no longer visible. You candetect this by verifying whether the overlay rectangles are "out of bounds"at the top of your snapping function. See the code forsnapGrid() forideas.

Overlay dropdown menu

Overlays have a little icon in the top-right corner (by default, a gear).When the user clicks on this icon, a dropdown menu appears that allows theuser to remove the overlay. You can also provide additional components forthis dropdown menu by using theheading,select, andmenu parameterstooverlayServer().

heading: This should be a function with the signature⁠function(ov, i)⁠whereov is theshiny::reactiveValues() object defining the overlays andtheir settings, andi is the (single) index for the current overlay. Thefunction should return a character string that will be used as the headingon thedropdown menu. This can be used to e.g. report the precise start andend point of the overlay, which may be useful to your users. The built-infunctionsrangeHeading() anddateHeading() can be used for numericvalues and date values on the x-axis, respectively. Or you can useNULLfor no heading on the dropdown menu.

select: This can beTRUE to provide ashiny::selectInput() widgeton the dropdown menu that users can use to change the type (i.e. label) ofthe current overlay. Or you can provide a character vector to restrict thewidget to specific labels, or useNULL to omit this widget.

menu: This can be a function with the signature⁠function(ov, i)⁠whereov is theshiny::reactiveValues() object defining the overlays andtheir settings, andi is the (single) index for the current overlay. Itshould return UI component(s) (if multiple components, wrapped in alistortagList) that will be inserted into the dropdown menu. If you give theinput widgets special IDs, the user can use those input widgets to directlymodify certain properties of the overlays:

See examples for an illustration of this.

See Also

overlayPlotOutput(),overlayBounds()

Examples

ui <- shiny::fluidPage(    overlayPlotOutput("my_plot", 640, 480),    overlayToken("add", "Raise")    # further UI elements here . . .)server <- function(input, output) {    menu <- function(ov, i) {        sliderInput("my_plot_amount", "Raise amount",               value = ov$data$amount[i], min = 0, max = 1)    }    ov <- overlayServer("my_plot", 4, 1,        data = list(amount = 0.2),        snap = snapGrid(step = 0.1),        heading = rangeHeading(digits = 3),        menu = menu)    output$my_plot <- shiny::renderPlot({        df <- data.frame(x = seq(0, 2 * pi, length.out = 200))        df$y <- (1 + sin(df$x)) / 2        for (i in which(ov$active)) {            xi <- (df$x >= ov$cx0[i] & df$x <= ov$cx1[i])            df$y[xi] <- df$y[xi] + ov$data$amount[i]        }        plot(df, type = "l")        overlayBounds(ov, "base")    })    # further server code here . . .}if (interactive()) {    shiny::shinyApp(ui, server)}

Create an overlay token input control

Description

Create a token that can be dragged onto anoverlay plotto create a new overlay.

Usage

overlayToken(id, name, label = name)

Arguments

Details

Note that the DOM ID of the token will be converted to"overshiny_token_<id>". This transformed ID is important for internalinteraction logic (e.g. for use with JavaScript drag/drop handlers). Whenreferencing the token programmatically (e.g. in CSS selectors or customJavaScript), use the full prefixed ID (see examples).

Value

An overlay token input control that can be added to a UI definition.

See Also

overlayServer(), for a complete example.

Examples

ui <- shiny::fluidPage(    useOverlay(),    overlayToken("add", "Add new overlay", "Overlay"),    # The token's HTML id will be "overshiny_token_add"    shiny::tags$style(shiny::HTML("#overshiny_token_add { cursor: grab; }")))

Headings for overlay dropdown menus

Description

Use a call to one of these functions as theheading parameter ofoverlayServer() to provide a heading on the overlay dropdown menureporting the start and end position of the overlay. For numbers, theheading fromrangeHeading() will be e.g. "1.5 - 3.5". For dates, theheading fromdateHeading() will be e.g. "2025-05-01 - 2025-06-01".

Usage

rangeHeading(..., sep = " - ")dateHeading(format, ..., sep = " - ")

Arguments

Value

A heading function suitable to pass tooverlayServer() as theheading argument.

See Also

overlayServer(), for a complete example.

Examples

server <- function(input, output) {    ov <- overlayServer("my_plot", 8, heading = dateHeading("%b %d"))    # further server code here . . .}

Adjust margins of a ggplot2 plot

Description

To avoid the overlay rectangles moving around when the plot margins change,you can use this function to set specific margins for your plot. You willprobably want to specify a large enough margin so that the axes and legendsdon't go out of the plot area.

Usage

remargin(g, t, r, b, l, unit = "npc")

Arguments

Details

Note that this only works withggplot2 plots. For base plots, you can setthe margins usingpar(plt = c(x1, x2, y1, y2)). Seegraphics::par() fordetails.

Value

Aggplot2 plot with margins adjusted.

Examples

plot1 = ggplot2::ggplot(data.frame(x = rnorm(10), y = rnorm(10))) +    ggplot2::geom_point(ggplot2::aes(x, y))plot2 = remargin(plot1, 0.1, 0.1, 0.1, 0.1) # plot with 10% margins all around

Snap overlays to a grid

Description

Use a call to this function as thesnap parameter ofoverlayServer() toenable a simple snap-to-grid behaviour for your overlay. It will ensure youroverlays stay within the bounds of the plot, and snap both position andwidth of each overlay to the specified grid.

Usage

snapGrid(anchor = 0, step = 1, min_width = NA, max_width = NA)

Arguments

Details

Note that you do not pass justsnapGrid tooverlayServer(), but e.g.snapGrid() orsnapGrid(step = 0.1). The default values snap overlays towhole numbers.

Value

A snapping function suitable to pass tooverlayServer() as thesnap argument.

See Also

overlayServer(), for a complete example.

Examples

server <- function(input, output) {    ov <- overlayServer("my_plot", 8, snap = snapGrid())    # further server code here . . .}

Manually set up a Shiny app to use overshiny

Description

overshiny will set up automatically if you have anoverlayPlotOutput()anywhere in your Shiny UI, which you probably do if you are using thispackage. But if you don't, you can set upovershiny by manually puttinguseOverlay() somewhere in your Shiny app's UI.

Usage

useOverlay()

Details

This also callsshinyjs::useShinyjs(), asovershiny depends onshinyjs.

Value

Returns an HTML dependency that sets up your Shiny app to useovershiny.

See Also

overlayServer(), for a complete example.

Examples

ui <- shiny::fluidPage(    useOverlay() # only needed if no overlayPlotOutput() elements below    # further UI elements here . . .)server <- function(input, output) {    # server code here . . .}if (interactive()) {    shiny::shinyApp(ui, server)}