downsampler {shinyHugePlot}

R6 class for down-sampling data

Description

A class for down-sampling data with a large number of samples. An instance contains (the reference of) original data, layout of the figure, and options for aggregating the original data. An interactive plot for displaying large-sized data can be obtained using the figure, down-sampler and its options included in the instance, while making the plot using shiny_hugeplot function is easier (see examples). See the super class (plotly_datahandler) to find more members to handle the data in plotly.

Format

An R6::R6Class object

Super class

shinyHugePlot::plotly_datahandler -> downsampler

Active bindings

downsample_options

Options for aggregating (down-sampling) data registered in this instance.

n_out_default

Default sample size.

aggregator_default

Default aggregator instance.

Methods

Public methods

• downsampler$new()

• downsampler$add_trace()

• downsampler$update_trace()

• downsampler$set_downsample_options()

• downsampler$clone()

Inherited methods

• shinyHugePlot::plotly_datahandler$plotly_data_to_df()
• shinyHugePlot::plotly_datahandler$set_trace_data()

Method new()

To construct an instance, original data, layout of the figure, and options for aggregating the original data are necessary. The original data and the layout of the figure can be given by providing a plotly object (figure argument). The options for aggregating the original data can be given by providing an aggregator (aggregator argument) and the number of samples (n_out argument). See the constructor of the plotly_datahandler class for more information on other arguments.

Usage

downsampler$new(
  figure = NULL,
  n_out = 1000L,
  aggregator = min_max_aggregator$new(),
  tz = Sys.timezone(),
  use_light_build = TRUE,
  legend_options = list(name_prefix = "<b style=\"color:sandybrown\">[S]</b> ",
    name_suffix = "", xdiff_prefix = "<i style=\"color:#fc9944\"> ~", xdiff_suffix =
    "</i>"),
  verbose = F
)

Arguments

figure, legend_options, tz, use_light_build

Arguments passed to plotly_datahandler$new.

n_out

Integer or numeric. The number of samples shown after down-sampling. By default 1000.

aggregator

An instance of an R6 class for aggregation. Select an aggregation function. The list of the functions are obtained using list_aggregators. By default, min_max_aggregator$new().

verbose

Boolean. Whether detailed messages to check the procedures are shown. By default, FALSE.

Method add_trace()

Add a new series to the data registered in the instance. If a data frame (traces_df argument) compliant with self$orig_data is given, it will be added to self$orig_data. If attributes to construct a plotly object (... argument) are given, a data frame is constructed and added. Options for aggregating data can be set using aggregator and n_out arguments. It is a wrapper of self$set_trace_data and self$set_downsample_options. See these methods for more information. Note that the traces of the figure are not updated with this method and self$update_trace is necessary.

Usage

downsampler$add_trace(..., traces_df = NULL, n_out = NULL, aggregator = NULL)

Arguments

..., traces_df

Arguments passed to self$set_trace_data (see the super class of plotly_datahandler)

n_out, aggregator

Arguments passed to self$set_downsample_options.

Method update_trace()

Update traces of the figure registered in the instance (self$figure$x$data) according to re-layout order (relayout_order argument). Using reset and reload arguments, traces are updated without re-layout orders. It just registers the new traces and returns nothing by default. It returns the new traces if send_trace is TRUE.

Usage

downsampler$update_trace(
  relayout_order = list(NULL),
  reset = FALSE,
  reload = FALSE,
  send_trace = FALSE
)

Arguments

relayout_order

Named list. A list generated by plotlyjs_relayout, which is obtained using plotly::event_data. e.g., If you would like set the range of the 2nd x axis to [10.0, 21.5], list(`xaxis2.range[0]` = 10.0, `xaxis2.range[1]` = 21.5). If you would like reset the range of the 1st x axis, list(xaxis.autorange = TRUE, xaxis.showspike = TRUE).

reset

Boolean. If it is TRUE, all other arguments are neglected and the figure will be reset (all the ranges of x axes are initialized). By default, FALSE.

reload

Boolean. If it is TRUE, the ranges of the figure are preserved but the aggregation will be conducted with the current settings. By default, FALSE.

send_trace

Boolean. If it is TRUE, a named list will be returned, which contains the indexes of the traces that will be updated (trace_idx_update) and the updated traces (new_trace). By default, FALSE.

Method set_downsample_options()

In the instance, options for aggregating data are registered as data frame. (see self$downsample_options.) Using this method, the options can be set.

Usage

downsampler$set_downsample_options(uid = NULL, n_out = NULL, aggregator = NULL)

Arguments

uid

Character, optional. The unique id of the trace. If NULL, all the options registered in this instance are updated. By default, NULL.

n_out

Numeric or integer, optional. The number of samples output by the aggregator. If NULL, the default value registered in this instance is used. By default, NULL.

aggregator

aggregator object, optional. An instance that aggregate the data. If NULL, the default value registered in this instance is used.

Method clone()

The objects of this class are cloneable with this method.

Usage

downsampler$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

data(noise_fluct)

# example 1 : Easy method using shiny_hugeplot
shiny_hugeplot(noise_fluct$time, noise_fluct$f500)

# example 2 : Manual method using a downsampler object
fig <- plot_ly(
  x = noise_fluct$time,
  y = noise_fluct$f500,
  type = "scatter",
  mode = "lines"
  ) %>%
  layout(xaxis = list(type = "date")) %>%
  shinyHugePlot::plotly_build_light()

ds <- downsampler$new(
  figure = fig,
  aggregator = min_max_aggregator$new(interleave_gaps = TRUE)
)

ui <- fluidPage(
  plotlyOutput(outputId = "hp", width = "800px", height = "600px")
)

server <- function(input, output, session) {

  output$hp <- renderPlotly(ds$figure)

  observeEvent(plotly::event_data("plotly_relayout"),{
    updatePlotlyH(session, "hp", plotly::event_data("plotly_relayout"), ds)
  })

}

shinyApp(ui = ui, server = server)


# example 3 : Add another series of which aggregator is different

noise_events <- tibble(
  time = c("2022-11-09 12:25:50", "2022-11-09 12:26:14"),
  level = c(60, 60)
)

ds$add_trace(
  x = noise_events$time, y = noise_events$level, name = "event",
  type = "scatter", mode = "markers",
  aggregator = null_aggregator$new()
)
ds$update_trace(reset = TRUE)

server <- function(input, output, session) {

  output$hp <- renderPlotly(ds$figure)

  observeEvent(plotly::event_data("plotly_relayout"),{
    updatePlotlyH(session, "hp", plotly::event_data("plotly_relayout"), ds)
  })

}

shinyApp(ui = ui, server = server)