---
title: "scatterD3 : a Visual Guide"
author: "Julien Barnier"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    fig_width: 5
    toc: true
vignette: >
  %\VignetteIndexEntry{scatterD3 : a Visual Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<style>
.scatterD3 .legend .label {
  font-size: 100%;
  font-weight: 400;
}
</style>

```{r, include=FALSE}
library(scatterD3)
knitr::opts_chunk$set(screenshot.force = FALSE)
```


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.

## Basic scatterplot

Starting with the sample `mtcars` dataset, we can produce a basic scatterplot with the following command :

```{r basic, eval=FALSE}
library(scatterD3)
scatterD3(x = mtcars$wt, y = mtcars$mpg)
```

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 :

```{r basic_nse}
scatterD3(data = mtcars, x = wt, y = mpg)
```


This will display a simple visualization with the given variables as `x` and `y` axis. There are several interactive features directly available :

- you can zoom in and out with the mouse wheel while the mouse cursor is on the plot
- you can pan the plot by dragging with your mouse
- hovering over a point displays a small tooltip window giving the `x` and `y` values


## Global points settings

- `point_size` allows to change the global size of all points
- `point_opacity` allows to change the global opacity of all points
- `colors`, when given a single HTML color code (starting with `#`), allows to change the global color of all points

```{r basic_cust}
scatterD3(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 hovering

```{r hover_cust}
scatterD3(data = mtcars, x = wt, y = mpg,
          point_size = 100, point_opacity = 0.5,
          hover_size = 4, hover_opacity = 1)
```

## Tooltips

If 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.

```{r cust_tooltips}
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"`) :

```{r tooltips_position}
scatterD3(data = mtcars, x = wt, y = mpg, tooltip_position = "top left")
```

Use `tooltips = FALSE` to disable tooltips entirely.



## `x` and `y` axes

### 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.

```{r categorical}
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 :

```{r categorical_left_margin}
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 :

```{r fixed}
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 :

```{r log_scales}
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 :

```{r 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 :

```{r cust_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` :

```{r cust_labels_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%`.

## Points labels

### Adding labels

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

```{r labels}
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.

```{r 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.

```{r labels_auto}
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 :

```{r labels_export}
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` :

```{r labels_export_scatterD3, eval = FALSE}
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` :

```{r labels_export_ggplot2, eval = FALSE}
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))
```

## Mapping variables

You can map points size, color, symbol and opacity with variables values.

### Color

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

```{r mapping_color}
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`.

```{r map_custom_colors}
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](https://github.com/d3/d3-scale-chromatic#sequential-single-hue) or [categorical](https://github.com/d3/d3-scale-chromatic#categorical).

Example for a continuous variable :

```{r custom_continuous_color}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = disp, colors = "interpolatePuRd")
```

Example for a categorical variable :

```{r custom_categorical_color}
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.

```{r map_factor_levels_color}
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.

```{r map_continuous_color}
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.

```{r map_size}
scatterD3(data = mtcars, x = wt, y = mpg, size_var = hp)
```

`size_range` allows to customize the sizes range.

```{r map_size_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.

```{r custom_sizes}
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.


```{r mapping}
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.

```{r map_factor levels}
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"`.

```{r map_custom_symbols}
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.

```{r opacity_var}
scatterD3(data = mtcars, x = mpg, y = wt, opacity_var = drat)
```

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

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




## Adding lines

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.

```{r lines}
scatterD3(data = mtcars, x = wt, y = mpg,
          lines = data.frame(slope = -5.344, intercept = 37.285))
```

You can style your lines by adding `stroke`, `stroke_width` and `stroke_dasharray` columns. These columns values will be added as [corresponding styles](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Fills_and_Strokes) to the generated SVG line. So if you want a wide dashed red horizontal line :

```{r lines_style}
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 :

```{r lines_default}
scatterD3(data = mtcars, x = wt, y = mpg, fixed = TRUE,
          lines = data.frame(slope = c(0, Inf),
                             intercept = c(0, 0),
                             stroke = "#000",
                             stroke_width = 1,
                             stroke_dasharray = 5))
```

## Confidence ellipses

Use `ellipses = TRUE` to draw a confidence ellipse around the points :

```{r ellipses}
scatterD3(data = mtcars, x = wt, y = mpg, ellipses = TRUE)
```

Or around the different groups of points defined by `col_var` :

```{r ellipses_col}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl, ellipses = TRUE)
```

Ellipses are computed by the  `ellipse.default()` function of the [ellipse package](https://cran.r-project.org/package=ellipse). The confidence level can be changed with the `ellipse_level` argument (`0.95` by default).


## Arrows and unit circle

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.

```{r cust_arrows}
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.

```{r unit_circle}
scatterD3(data = df, x = x, y = y,
          type_var = type_var,
          unit_circle = TRUE, fixed = TRUE,
          xlim = c(-1.2, 1.2), ylim = c(-1.2, 1.2))
```



## Legends

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.

```{r cust_labels2}
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 :

```{r rm_legend}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl, col_lab = NA)
```

You can also change the font size of legend text with `legend_font_size` :

```{r cust_labels_legend_size}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl,
          legend_font_size = "16px")
```

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 :

```{r cust_left_margin}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl,
          left_margin = 80)
```

## Caption

You can add an optional caption which will be shown when
clicking on a "info sign" icon in the top right of your plot.

To do so, use the `caption` argument with either a single character string :

```{r caption_character}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl,
          caption = "Lorem ipsum dolor sit amet, <strong>consectetur adipiscing
          elit</strong>. Nullam aliquam egestas pretium. Donec auctor semper
          vestibulum. Phasellus in tempor lacus. Maecenas vehicula, ipsum id
          malesuada placerat, diam lorem aliquet lectus, non lacinia quam leo
          quis eros.")
```

Or a list with the `title`, `subtitle` and `text` elements :

```{r caption_list}
scatterD3(data = mtcars, x = wt, y = mpg, col_var = cyl,
          caption = list(title = "Caption title",
                         subtitle = "Caption subtitle",
                         text = "Lorem ipsum dolor sit amet, <strong>consectetur 
                         adipiscing elit</strong>. Nullam aliquam egestas pretium. 
                         Donec auctor semper vestibulum. Phasellus in tempor lacus. 
                         Maecenas vehicula, ipsum id malesuada placerat, diam lorem 
                         aliquet lectus, non lacinia quam leo quis eros."))
```

## Callbacks


### 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.

```{r urls}
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.

```{r click_callback}
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()` :

```{r, click_callback_shiny, eval=FALSE}
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` :

```{r click_callback_shiny_ui, eval = FALSE}
textOutput("click_selected")
```

And this in `server` :

```{r click_callback_shiny_server, eval = FALSE}
output$click_selected <- renderText(paste0("Clicked point : ", input$selected_point))
```

Thanks to [detule](https://github.com/detule) and [harveyl888](https://github.com/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.

```{r zoom_callback}
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;
   }")
```

<div id="zoomExample" style="font-size: 80%; background-color: #F9F9F9; padding: 5px; margin-left: 5em; width: 15em;"><strong>Zoom</strong><br /> None yet !</div>


### 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 :

```{r init_callback}
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);
  }"
)
```



## Utilities


### 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.

```{r nomenu}
scatterD3(data = mtcars, x = wt, y = mpg, menu = FALSE)
```


### Lasso selection tool

Thanks to the [d3-lasso-plugin](https://github.com/skokenes/D3-Lasso-Plugin) integration made by @[timelyportfolio](https://github.com/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).

```{r lasso}
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 :

```{r lasso_callback}
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.


## Shiny integration

### Sample app and source code

The
[sample scatterD3 shiny app](https://data.nozav.org/app/scatterD3/) allows you to see the different features described here. You can [check its source code on GitHub](https://github.com/juba/scatterD3_shiny_app) 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](https://data.nozav.org/app/scatterD3/).

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 :

```{r zoom_on}
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](https://data.nozav.org/app/scatterD3/) 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`.