The scatterD3
package provides an HTML widget based on
the htmlwidgets
package and allows to produce interactive
scatterplots by using the d3
javascript visualization
library.
Starting with the sample mtcars
dataset, we can produce
a basic scatterplot with the following command :
You can pass data arguments as vectors, like above, or give a data
frame as data
argument and then provide variable names
which will be evaluated inside this data frame :
This will display a simple visualization with the given variables as
x
and y
axis. There are several interactive
features directly available :
x
and y
valuespoint_size
allows to change the global size of all
pointspoint_opacity
allows to change the global opacity of
all pointscolors
, when given a single HTML color code (starting
with #
), allows to change the global color of all
pointsscatterD3(data = mtcars, x = wt, y = mpg,
point_size = 200, point_opacity = 0.5,
colors = "#A94175")
hover_size
and hover_opacity
change size
and opacity of points when hoveringIf the default tooltips don’t suit your needs, you can customize them
by providing a character vector to the tooltip_text
argument. This can contain HTML tags for formatting.
tooltips <- paste(
"This is an incredible <strong>", rownames(mtcars), "</strong><br />with ",
mtcars$cyl, "cylinders !"
)
scatterD3(data = mtcars, x = wt, y = mpg, tooltip_text = tooltips)
tooltip_position
allows to customize the tooltip
placement. It can take as value a combination of "top"
or
"bottom"
and "left"
or "right"
(the default is "bottom right"
) :
Use tooltips = FALSE
to disable tooltips entirely.
x
and y
axesx
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.
You can use the left_margin
argument when using a
categorical y
variable if the axis labels are not entirely
visible :
Use fixed = TRUE
to force a fixed 1:1 ratio between the
two axes :
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 :
x_lim
and y_lim
manually specify the
x
or y
axis limits :
xlab
and ylab
allow to set the axes labels
:
This also changes the default tooltips labels.
You can also change the font size of axes text with
axes_font_size
:
You can provide any CSS compatible value, wether a fixed size such as
2em
or a relative one like 95%
.
You can add text labels to the points by passing a character vector
to the lab
parameter.
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.
By using labels_positions = "auto"
, labels positions can
be computed to minimize overlapping.
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.
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 :
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
:
You can map points size, color, symbol and opacity with variables values.
Pass a vector to col_var
to map points color to the
vector values.
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 :
Example for a categorical variable :
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.
You can force col_var
to be considered as continuous
with col_continuous = TRUE
.
When col_var
is considered as continuous,
Pass a vector to size_var
to map points size to its
values.
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.
Pass a vector to symbol_var
to map points symbol to its
values.
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"
.
Pass a vector to opacity_var
to map point opacity to its
values. Note that for now no legend for opacity is added, though.
You can specify custom opacity-value mapping by passing a named
vector to opacities
.
In addition to your data points, you can add lines to your
scatterplot. This is done by passing a data frame to the
lines
argument. This data frame must have at least
two columns called slope
and intercept
, and as
many rows as lines you want to draw.
You can style your lines by adding stroke
,
stroke_width
and stroke_dasharray
columns.
These columns values will be added as corresponding
styles to the generated SVG line. So if you want a wide dashed red
horizontal line :
scatterD3(data = mtcars, x = wt, y = mpg,
lines = data.frame(slope = 0,
intercept = 30,
stroke = "red",
stroke_width = 5,
stroke_dasharray = "10,5"))
If you want to draw a vertical line, pass the Inf
value
to slope
. The value of intercept
is then
interpreted as the intercept along the x axis.
By default, if no lines
argument is provided two dashed
horizontal and vertical lines are drawn through the origin, which is
equivalent to :
Use ellipses = TRUE
to draw a confidence ellipse around
the points :
Or around the different groups of points defined by
col_var
:
Ellipses are computed by the ellipse.default()
function
of the ellipse
package. The confidence level can be changed with the
ellipse_level
argument (0.95
by default).
For more specific use cases, you can represent some points as an
arrow starting from the origin instead of a dot by using the
type_var
argument.
df <- data.frame(x = c(1, 0.9, 0.7, 0.2, -0.4, -0.5),
y = c(1, 0.1, -0.5, 0.5, -0.6, 0.7),
type_var = c("point", rep("arrow", 5)),
lab = LETTERS[1:6])
scatterD3(data = df, x = x, y = y,
type_var = type_var, lab = lab,
fixed = TRUE, xlim = c(-1.2, 1.2), ylim = c(-1.2, 1.2))
Use unit_circle = TRUE
to add a unit circle to your
plot.
A legend is automatically added when a color, size or symbol mapping is used. Note that when hovering over a legend item with your mouse, the corresponding points are highlighted. Also note that the mapped variables values are automatically added to the default tooltips.
legend_width
allows to set the legend width. Use
legend_width = 0
to disable legends entirely.
col_lab
, symbol_lab
and
size_lab
allow to specify legends titles.
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl, symbol_var = gear,
xlab = "Weight", ylab = "Mpg", col_lab = "Cylinders",
symbol_lab = "Gears")
You can remove a color, symbol or size legend entirely by specifying
NA
as its corresponding _lab
value :
You can also change the font size of legend text with
legend_font_size
:
You can provide any CSS compatible value, wether a fixed size such as
2em
or a relative one like 95%
.
If the left plot margin is not big enough and your y axis labels are
truncated, you can adjust it with the left_margin
argument
:
Use url_var
to specify a character vectors of URLs,
associated to each point, and which will be opened when the point is
clicked.
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
:
And this in server
:
Thanks to detule and harveyl888 for the code.
Note that url_var
and click_callback
cannot
be used at the same time.
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;
}")
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 :
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 :
You can also disable mouse wheel zooming (for example when it is
interfering with page scrolling) by using the
disable_wheel = TRUE
argument.
You can check the sample scatterD3 shiny app and its source code on GitHub for a better understanding of the different arguments.
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.
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.
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 onzoom_on_level
takes a number, the zoom scale valueWhen used outside of a shiny app, they just center the viewport on the specified point :
Inside a shiny app, these arguments allow to zoom on a specific point programmatically with transitions.
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 selectionIf 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
.