scatterD3 : a Visual Guide

Categorical x and y

If the x or y variable is not numeric or is a factor, then an ordinal scale is used for the corresponding axis. Note that zooming is then not possible along this axis.

mtcars$cyl_fac <- paste(mtcars$cyl, "cylinders")
scatterD3(data = mtcars, x = cyl_fac, y = mpg)

You can use the left_margin argument when using a categorical y variable if the axis labels are not entirely visible :

scatterD3(data = mtcars, x = wt, y = cyl_fac, left_margin = 80)

Axes settings

Use fixed = TRUE to force a fixed 1:1 ratio between the two axes :

scatterD3(data = mtcars, x = wt, y = mpg,
          fixed = TRUE)

x_log and y_log allow to use logarithmic scales. Note that there must not be any value inferior or equal to zero in this case :

scatterD3(data = mtcars, x = wt, y = mpg,
          x_log = TRUE, y_log = TRUE)

x_lim and y_lim manually specify the x or y axis limits :

scatterD3(data = mtcars, x = wt, y = mpg, xlim = c(0, 10), ylim = c(10, 35))

xlab and ylab allow to set the axes labels :

scatterD3(data = mtcars, x = wt, y = mpg,
          xlab = "Weight", ylab = "Mpg")

This also changes the default tooltips labels.

You can also change the font size of axes text with axes_font_size :

scatterD3(data = mtcars, x = wt, y = mpg,
          xlab = "Weight", ylab = "Mpg",
          axes_font_size = "160%")

You can provide any CSS compatible value, wether a fixed size such as 2em or a relative one like 95%.

Adding labels

You can add text labels to the points by passing a character vector to the lab parameter.

mtcars$names <- rownames(mtcars)
scatterD3(data = mtcars, x = wt, y = mpg,
          lab = names)

Note that text labels are fully movable : click and drag a label with your mouse to place it where you want. Custom positions are preserved while zooming/panning. A leader line between the point and its label is automaticcaly drawn when the distance between both is above a certain threshold.

Use labels_size to modify the labels size.

mtcars$names <- rownames(mtcars)
scatterD3(data = mtcars, x = wt, y = mpg,
          lab = names, labels_size = 12)

Automatic labels position

By using labels_positions = "auto", labels positions can be computed to minimize overlapping.

scatterD3(data = mtcars, x = wt, y = mpg, lab = names,
          labels_positions = "auto")

The computation is made in JavaScript, and can be quite intensive. It is automatically disabled with a warning if there are more than 500 points.

Custom labels positions export

The “gear menu” allows to export the current custom labels position as a CSV file for later reuse.

For example, if you change the labels placement in the following plot :

mtcars$names <- rownames(mtcars)
scatterD3(data = mtcars, x = wt, y = mpg, lab = names)

You can then open the menu and select Export labels positions to save them into a CSV file. If you want to reuse these positions, you can use the labels_positions argument from scatterD3 :

labels <- read.csv("scatterD3_labels.csv")
scatterD3(data = mtcars, x = wt, y = mpg, lab = names, labels_positions = labels)

You can also use this file to reuse coordinates in a plot from a different package. The following example should work with ggplot2 :

labels <- read.csv("scatterD3_labels.csv")
library(ggplot2)
ggplot() +
  geom_point(data = mtcars, aes(x = wt, y = mpg)) +
  geom_text(data = labels,
            aes(x = lab_x,
                y = lab_y,
                label = lab))

Color

Pass a vector to col_var to map points color to the vector values.

scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl)

You can specify custom colors by passing a vector of hexadecimal strings to the colors argument. If the vector is named, then the colors will be associated with their names within col_var.

scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl,
          colors = c("4" = "#ECD078", "8" = "#C02942", "6" = "#53777A"))

You can also specify a custom color palette by giving the colors argument the name of a d3-scale-chromatic function, either sequential or categorical.

Example for a continuous variable :

scatterD3(data = mtcars, x = wt, y = mpg, col_var = disp, colors = "interpolatePuRd")

Example for a categorical variable :

scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl, colors = "schemeTableau10")

If your original R vector is a factor, its level orders should be preserved in the legend.

mtcars$cyl_o <- factor(mtcars$cyl, levels = c("8", "6", "4"))
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl_o)

If col_var is numeric, not a factor, and has more than 6 unique values, it is considered as continuous, and drawn accordingly using the Veridis d3 interpolator.

scatterD3(data = mtcars, x = wt, y = mpg, col_var = disp)

You can force col_var to be considered as continuous with col_continuous = TRUE.

When col_var is considered as continuous,

Size

Pass a vector to size_var to map points size to its values.

scatterD3(data = mtcars, x = wt, y = mpg, size_var = hp)

size_range allows to customize the sizes range.

scatterD3(data = mtcars, x = wt, y = mpg, size_var = hp,
          size_range = c(10, 1000), point_opacity = 0.7)

By passing a named vector to sizes, you can specify a custom size-value mapping.

scatterD3(data = mtcars, x = mpg, y = wt, size_var = cyl,
  sizes = c("4" = 10, "6" = 100, "8" = 1000))

Symbol

Pass a vector to symbol_var to map points symbol to its values.

scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl, symbol_var = gear)

If your original R vector is a factor, its level orders should be preserved in the legend.

mtcars$cyl_o <- factor(mtcars$cyl, levels = c("8", "6", "4"))
scatterD3(data = mtcars, x = wt, y = mpg, symbol_var = cyl_o)

You can specify custom symbol-value mapping by passing a vector of symbol names to the symbols argument. If the vector is named, then the symbols will be associated with their names within symbol_var. Available symbol names are : "circle", "cross", "diamond", "square", "star", "triangle", and "wye".

scatterD3(data = mtcars, x = wt, y = mpg, symbol_var = cyl,
          symbols = c("4" = "wye", "8" = "star", "6" = "triangle"))

Opacity

Pass a vector to opacity_var to map point opacity to its values. Note that for now no legend for opacity is added, though.

scatterD3(data = mtcars, x = mpg, y = wt, opacity_var = drat)

You can specify custom opacity-value mapping by passing a named vector to opacities.

scatterD3(data = mtcars, x = mpg, y = wt, opacity_var = cyl,
  opacities = c("4" = 1, "6" = 0.1, "8" = 0.5))

Open URLs when clicking points

Use url_var to specify a character vectors of URLs, associated to each point, and which will be opened when the point is clicked.

mtcars$urls <- paste0("https://www.duckduckgo.com/?q=", rownames(mtcars))
scatterD3(data = mtcars, x = wt, y = mpg, lab = names, url_var = urls)

JavaScript callback on clicking point

The click_callback argument is a character string defining a JavaScript function to be called when a dot is clicked. It must accept two arguments : id (the unique id of the current scatterplot), and d (the datum of the clicked point). You can use the d.key_var property to identify which point has been clicked : its value will be either the corresponding key_var value, or the point index if key_var has not been defined.

scatterD3(data = mtcars, x = wt, y = mpg,
   click_callback = "function(id, d) {
      alert('scatterplot ID: ' + id + ' - Point key_var: ' + d.key_var)
   }")

One usage can be to pass the index of the clicked point back to Shiny when scatterD3 is run inside a Shiny app. The following implementation can do it by using Shiny.onInputChange() :

scatterD3(data = mtcars, x = wt, y = mpg,
  click_callback = "function(id, d) {
  if(id && typeof(Shiny) != 'undefined') {
      Shiny.onInputChange('selected_point', d.key_var);
  }
}")

You could then add something like this in your Shiny app ui :

textOutput("click_selected")

And this in server :

output$click_selected <- renderText(paste0("Clicked point : ", input$selected_point))

Thanks to detule and harveyl888 for the code.

Note that url_var and click_callback cannot be used at the same time.

JavaScript zoom callback

The zoom_callback argument is a character string defining a JavaScript function to be called when a zoom event is triggered. It must accept two arguments xmin, xmax, ymin and ymax (in this order), which give the new x and y domains after zooming.

scatterD3(data = mtcars, x = wt, y = mpg,
   zoom_callback = "function(xmin, xmax, ymin, ymax) {
    var zoom = '<strong>Zoom</strong><br />xmin = ' + xmin + '<br />xmax = ' + xmax + '<br />ymin = ' + ymin + '<br />ymax = ' + ymax;
    document.getElementById('zoomExample').innerHTML = zoom;
   }")

JavaScript init callback

The init_callback argument allows to pass a JavaScript function that will be applied after the plot has been created or updated, with the JavaScript scatter object as this.

This is not documented yet, and you’ll have to dig into the JS package code to use it.

Here is a bad but potentially useful example that formats the x axis as percentages :

scatterD3(data = mtcars, x = wt, y = mpg,
  init_callback = "function() {
    var scales = this.scales();
    var svg = this.svg();
    new_x_axis = scales.xAxis.tickFormat(d3.format(',.0%'));
    svg.select('.x.axis').call(new_x_axis);
  }"
)

Gear menu

The “gear menu” is a small menu which can be displayed by clicking on the “gear” icon on the top-right corner of the plot. It allows to reset the zoom, export the current graph to SVG, and toggle lasso selection.

It is displayed by default, but you can hide it with the menu = FALSE argument.

scatterD3(data = mtcars, x = wt, y = mpg, menu = FALSE)

Lasso selection tool

Thanks to the d3-lasso-plugin integration made by @timelyportfolio, you can select and highlight points with a lasso selection tool. To activate it, just add a lasso = TRUE argument. The tool is used by shift-clicking and dragging on the plot area (if it doesn’t activate, click on the chart first to give it focus).

mtcars$names <- rownames(mtcars)
scatterD3(data = mtcars, x = wt, y = mpg, lab = names, lasso = TRUE)

To undo the selection, just shift-click again.

You can specify a custom JavaScript callback function to be called by passing it to the lasso_callback argument as a character string. This function should accept a sel argument, which is a d3 selection of selected points.

Here is an example which shows an alert with selected point labels :

mtcars$names <- rownames(mtcars)
scatterD3(data = mtcars,
          x = wt, y = mpg, lab = names,
          lasso = TRUE,
          lasso_callback = "function(sel) {alert(sel.data().map(function(d) {return d.lab}).join('\\n'));}")

Disabling mousewheel zoom

You can also disable mouse wheel zooming (for example when it is interfering with page scrolling) by using the disable_wheel = TRUE argument.

Sample app and source code

The sample scatterD3 shiny app allows you to see the different features described here. You can check its source code on GitHub for a better understanding of the different arguments.

Transitions

Like every R HTML widget, shiny integration is straightforward. But as a D3 widget, scatterD3 is updatable : changes in settings or data can be displayed via smooth transitions instead of a complete chart redraw, which can provide interesting visual clues.

For a small demonstration of these transitions, you can take a look at the sample scatterD3 shiny app.

Enabling transitions in your shiny app is quite simple, you just have to add the transitions = TRUE argument to your scatterD3 calls in your shiny server code. There’s only one warning : if your shiny application may filter on your dataset rows via a form control, then you must provide a key_var variable that uniquely and persistently identify your rows.

Programmatic zooming

By passing the zoom_on and zoom_on_level arguments to scatterD3, you can programmatically zoom on specific coordinates :

• zoom_on takes a vector of x,y coordinates to zoom on
• zoom_on_level takes a number, the zoom scale value

When used outside of a shiny app, they just center the viewport on the specified point :

scatterD3(data = mtcars, x = wt, y = mpg, zoom_on = c(1.615, 30.4), zoom_on_level = 6, lab = names)

Inside a shiny app, these arguments allow to zoom on a specific point programmatically with transitions. See the sample scatterD3 shiny app for a demonstration.

Additional controls : Reset zoom, SVG export, lasso toggle

Furthermore, scatterD3 provides some additional handlers for three interactive features : SVG export, zoom resetting and lasso selection. Those are already accessible via the “gear menu”, but you may want to replace it with custom form controls.

By default, you just have to give the following id to the corresponding form controls :

• #scatterD3-reset-zoom : reset zoom to default on click
• #scatterD3-svg-export : link to download the currently displayed figure as an SVG file
• #scatterD3-lasso-toggle : toggle lasso selection

If you are not happy with these ids, you can specify their names yourself with the arguments dom_id_svg_export, dom_id_reset_zoom and dom_id_toggle.