# R6 class for down-sampling data 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`. class ## Format An `R6::R6Class` object ## Examples ```r 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) ``` ## 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 * [list("downsampler$new()")](#method-downsampler-new) * [list("downsampler$add_trace()")](#method-downsampler-add_trace) * [list("downsampler$update_trace()")](#method-downsampler-update_trace) * [list("downsampler$set_downsample_options()")](#method-downsampler-set_downsample_options) * [list("downsampler$clone()")](#method-downsampler-clone) ### 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, formula = NULL, srcs = NULL, srcs_ext = list(), n_out = 1000L, aggregator = min_max_aggregator$new(), tz = Sys.timezone(), use_light_build = TRUE, legend_options = list(name_prefix = "[S] ", name_suffix = "", xdiff_prefix = " ~", xdiff_suffix = ""), verbose = F ) ``` #### Arguments - **`figure, srcs, srcs_ext, formula, 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.

downsampler function