Getting started with the manipulateWidget package

Grouping controls

If you have a large number of inputs, you can easily group them. To do so, simply pass to the function manipulateWidget a list of inputs instead of passing directly the inputs. Here is a toy example. Groups are by default collapsed and user can click on their title to display/collapse then.

mydata <- data.frame(x = 1:100, y = rnorm(100))
manipulateWidget(
  dygraph(mydata[range[1]:range[2], ],
          main = title, xlab = xlab, ylab = ylab),
  range = mwSlider(1, 100, c(1, 100)),
  "Graphical parameters" = list(
    title = mwText("Fictive time series"),
    xlab = mwText("X axis label"),
    ylab = mwText("Y axis label")
  )
)

Grouping inputs

Conditional inputs

Sometimes some inputs are relevant only if other inputs have some value. manipulateWidgetprovides a way to show/hide inputs conditionally to the value of the other inputs thanks to parameter .display. This parameter expects a named list of expressions. The names are the ones of the inputs to show/hide and the expressions can include any input and have to evaluate to TRUE/FALSE. Here is a toy example, using package plot_ly. User can choose points or lines to represent some data. If he chooses lines, then an input appears to let him choose the width of the lines.

mydata <- data.frame(x = 1:100, y = rnorm(100))

myPlot <- function(type, lwd) {
  if (type == "points") {
    plot_ly(mydata, x= ~x, y = ~y, type = "scatter", mode = "markers")
  } else {
    plot_ly(mydata, x= ~x, y = ~y, type = "scatter", mode = "lines", 
            line = list(width = lwd))
  }
}

manipulateWidget(
  myPlot(type, lwd),
  type = mwSelect(c("points", "lines"), "points"),
  lwd = mwSlider(1, 10, 1),
  .display = list(lwd = type == "lines")
)

Conditional inputs

Updating a widget

The “normal” use of manipulateWidget is to provide an expression that always return an htmlwidget. In such case, every time the user changes the value of an input, the current widget is destroyed and a new one is created and rendered. This behavior is not optimal and sometimes it can be painful for the user: consider for instance an interactive map. Each time user changes an input, the map is destroyed and created again, then zoom and location on the map are lost every time.

Some packages provide functions to update a widget that has already been rendered. This is the case for instance for package leaflet with the function leafletProxy. To use such functions, manipulateWidget evaluates the parameter .expr with two extra variables:

• .initial: TRUE if the expression is evaluated for the first time and then the widget has not been rendered yet, FALSE if the widget has already been rendered.

• .session: A shiny session object.

Moreover the ID of the rendered widget is always “output”. Then it is quite easy to write an expression that initializes a widget when it is evaluated the first time and then that updates this widget. Here is an example using package leaflet.

lon <- rnorm(10, sd = 20)
lat <- rnorm(10, sd = 20)

myMapFun <- function(radius, color, initial, session) {
  if (initial) {
    # Widget has not been rendered
    map <- leaflet() %>% addTiles()
  } else {
    # widget has already been rendered
    map <- leafletProxy("output", session) %>% clearMarkers()
  }

  map %>% addCircleMarkers(lon, lat, radius = radius, color = color)
}

manipulateWidget(myMapFun(radius, color, .initial, .session),
                 radius = mwSlider(5, 30, 10),
                 color = mwSelect(c("red", "blue", "green")))

Conditional inputs

Comparison mode

Sometimes one wants to compare two similar charts to visualize the impact of some parameter or to compare different data sets. manipulateWidget has an argument to perform such comparison without writing much code: .compare. One just has to write the code to generate one chart and use this argument to specify which parameters should vary between the two charts. Here is a toy example that uses dygraphs.

mydata <- data.frame(
  timeId = 1:100,
  series1 = rnorm(100),
  series2 = rnorm(100),
  series3 = rnorm(100)
)
manipulateWidget(
  dygraph(mydata[range[1]:range[2], c("timeId", series)], main = title),
  range = mwSlider(1, 100, c(1, 100)),
  series = mwSelect(c("series1", "series2", "series3")),
  title = mwText(),
  .compare = list(
    title = list("First chart", "Second chart"),
    series = NULL
  )
)

Comparison mode

Using manipulateWidget in a document

manipulateWidget uses Shiny, so it does not work in a “normal” Rmarkdown document. If one uses the function in a code chunck, the htmlwidget will be outputed with the default values of the parameters and there will be no interface to modify the parameters.

Nevertheless, it is possible to include a shiny application in a document with the runtime: shiny (see http://rmarkdown.rstudio.com/authoring_shiny.html). In such setting manipulateWidget works normally and the document can be published on a shiny server to let final users play with the parameters of the document.