2 Customizing girafe animations

You can customize tooltip style, mouse hover effects, toolbar position and many details.

This requires usage of css instructions and options. The function girafe has an argument options, a list of options to customize the rendering with calls to dedicated functions, i.e. opts_tooltip(), opts_toolbar(), opts_hover(), …

We will use the following graphic to illustrate available options:

library(tidyverse)

mtcars_db <- rownames_to_column(mtcars, var = "carname")

gg_scatter <- ggplot(
  data = mtcars_db,
  mapping = aes(
    x = disp, y = qsec, color = wt,
    # here we add iteractive aesthetics
    tooltip = carname, data_id = carname
  )
) + 
  geom_point_interactive(size = 3, hover_nearest = TRUE)
gg_scatter

2.1 Global option definition

Default values are frequently used when creating “girafe” objects. It is recommended to specify them only once in the R session in order to obtain homogeneous interactive graphics.

When a ‘girafe’ is created (when function girafe() is called), some default values are used as the css for hover effects or css for tooltips.

User can read them with function get_flextable_defaults().

z <- girafe_defaults()
z$opts_hover$css

[1] ".hover_data_SVGID_ { fill:#f24f26;stroke:#333333;cursor:pointer; }\ntext.hover_data_SVGID_ { stroke:none;fill:#f24f26; }\ncircle.hover_data_SVGID_ { fill:#f24f26;stroke:#333333; }\nline.hover_data_SVGID_, polyline.hover_data_SVGID_ { fill:none;stroke:#f24f26; }\nrect.hover_data_SVGID_, polygon.hover_data_SVGID_, path.hover_data_SVGID_ { fill:#f24f26;stroke:none; }\nimage.hover_data_SVGID_ { stroke:#f24f26; }"

These default properties will be used when creating the graphics. They can be updated with function set_girafe_defaults().

To set global options that apply to all graphics and get homogeneous interactive behavior and design, call set_girafe_defaults() at the beginning of your R Markdown document or R script.

css_default_hover <- girafe_css_bicolor(primary = "yellow", secondary = "red")

set_girafe_defaults(
  opts_hover = opts_hover(css = css_default_hover),
  opts_zoom = opts_zoom(min = 1, max = 4),
  opts_tooltip = opts_tooltip(css = "padding:3px;background-color:#333333;color:white;"),
  opts_sizing = opts_sizing(rescale = TRUE),
  opts_toolbar = opts_toolbar(saveaspng = FALSE, position = "bottom", delay_mouseout = 5000)
)

girafe(ggobj = gg_scatter)

2.2 Graphic size

The width and height of the graphics region are defined with arguments width_svg and height_svg, unit is inches. The default values are 6 and 5 inches. The ratio width/height defines the aspect ratio of the graphic. It is used to define viewbox attribute of the SVG result and to produce the original SVG file.

The displayed graphics can be resized only in relation to the width and inside the HTML container. Once the graphic is produced, two options are available, allow resizing or freeze the size of the displayed graphic to its exact size. The ability to change the aspect ratio must be done in the girafe() function call using the width_svg and height_svg arguments. This of course causes some problems with ‘flexdashboard’ which can be solved by defining an aspect ratio close to the one of its container.

If you use girafe() in an ‘R Markdown’ document, we recommend to let these arguments unset so that the knitr options fig.width and fig.height are used instead.

2.2.1 Size options

By default the size of the graph is automatically adjusted to 100% of the width of the web page containing it. Graphic will be resized if its container is resized.

This behavior can be controlled by using the opts_sizing() function:

The percentage of the width to be used can be defined with the width parameter which takes a value between 0 and 1.
The resizing can also be cancelled using argument rescale=FALSE. In this case, the use of width will have no effect.

girafe(
  ggobj = gg_scatter, 
  options = list(opts_sizing(rescale = TRUE, width = .5))
)

girafe(
  ggobj = gg_scatter, 
  options = list(opts_sizing(rescale = FALSE))
)

2.3 Tooltip options

Tooltip visual aspect and position can be defined with function opts_tooltip().

2.3.1 Tooltip position

The arguments offx and offy of function opts_tooltip() are used to offset tooltip position. Default offset is 10 pixels horizontally to the mouse position (offx=10) and 0 pixels vertically (offy=0).

girafe(
  ggobj = gg_scatter,
  options = list(
    opts_tooltip(offx = 20, offy = 20)
  )
)

If argument use_cursor_pos is set to FALSE, the tooltip will be fixed at offx and offy.

girafe(
  ggobj = gg_scatter,
  options = list(opts_tooltip(
    offx = 60,
    offy = 60, use_cursor_pos = FALSE
  ))
)

2.3.2 Tooltip style

The function opts_tooltip() has an argument named css. It can be used to add css declarations to customize tooltip rendering.

Each css declaration includes a property name and an associated value. Property names and values are separated by colons and name-value pairs always end with a semicolon. For example color:gray;text-align:center;. Common properties are :

background-color: background color

color: elements color

border-style, border-width, border-color: border properties

width, height: size of tooltip

padding: space around content

opacity: background opacity (default to 0.9)

Let’s add a pink rectangle with round borders and a few other details to make it nice:

tooltip_css <- "background-color:#d8118c;color:white;padding:5px;border-radius:3px;"
girafe(
  ggobj = gg_scatter,
  options = list(
    opts_tooltip(css = tooltip_css, opacity = 1),
    opts_sizing(width = .7)
  )
)

Do not surround css value by curly braces, girafe function takes care of that.

2.3.3 Auto coloring

In function opts_tooltip(), set argument use_fill to TRUE and the background color of tooltip will always use use elements’fill property to color tooltip. Argument use_stroke is to be used to apply the same to the border color of the tooltip.

girafe(
  ggobj = gg_scatter + scale_color_viridis_c(),
  options = list(
    opts_tooltip(use_fill = TRUE),
    opts_sizing(width = .7)
  )
)

Package ggiraph enable elements to be dynamic when mouse is hovering over them. This is possible when an element is associated with a data_id.

The dynamic aspect of elements can be defined with css code by the user. There are several ways to define these settings.

2.4 Hover effects

The elements that are associated with a data_id are animated when the mouse hovers over them. Clicks and hover actions on these elements are also available as reactive values in shiny applications.

These animations can be configured using the following functions:

opts_hover() for the animation of panel elements
opts_hover_key() for the animation of the elements of the legends
opts_hover_theme() for the animation of the elements of the theme

These functions all have a css argument that defines via CSS instructions the style to use when the mouse passes over them. css here is relative to SVG elements. SVG attributes are listed here. Common properties are:

fill: background color
stroke: color
stroke-width: border width
r: circle radius (no effect if Firefox is used).

To fill elements in yellow and add a black stroke, opts_hover call should be used as below:

girafe(
  ggobj = gg_scatter,
  options = list(
    opts_hover(css = "fill:yellow;stroke:black;stroke-width:3px;")
  )
)

Another option can be used to alter aspect of non hovered elements. It is very useful to highlight hovered elements when the density of the elements is high by fixing less opacity on the other elements.

dat <- readRDS("data/species-ts.RDS")

gg <- ggplot(dat, aes(x = date, y = score, 
                      colour = species, group = species)) +
  geom_line_interactive(aes(tooltip = species, data_id = species)) +
  scale_color_viridis_d() + 
  labs(title = "move mouse over lines")

x <- girafe(ggobj = gg, width_svg = 8, height_svg = 6,
  options = list(
    opts_hover_inv(css = "opacity:0.1;"),
    opts_hover(css = "stroke-width:2;")
  ))
x

2.4.1 Detailled control

Now there are cases where css expressions will have to be configured with more caution.

Let’s have a look at the following example ; if you put your mouse hover points or text, you will see that the animation is not adapted to the text. Text should instead be animated with another css property.

gg <- ggplot(head(mtcars_db), aes(
  x = disp, y = qsec, label = carname,
  data_id = carname, color = wt
)) +
  geom_text_interactive(vjust = 2) +
  theme_minimal()

girafe(
  ggobj = gg,
  options = list(
    opts_hover(css = "fill:red;stroke:black;")
  )
)

Function girafe_css is to be used in that case, it allows to specify individual styles for various SVG elements.

girafe(
  ggobj = gg,
  options = list(
    opts_hover(
      css = girafe_css(
        css = "fill:purple;stroke:black;",
        text = "stroke:none;fill:red;"
      )
    )
  )
)

2.5 Zoom

You can activate zoom; set zoom_max (maximum zoom factor) to a value greater than 1. If the argument is greater than 1, a toolbar will appear when mouse will be over the graphic.

Click on the icons in the toolbar to activate or desactivate the zoom.

girafe(
  ggobj = gg_scatter,
  options = list(
    opts_sizing(width = .7),
    opts_zoom(max = 5)
  )
)

2.6 Toolbar

A toolbar is added by default to the graphs at the top right. It contains at least the download button for the PNG version of the graph.

It will contain other elements depending on the options used. If a zoom has been configured, the zoom options will be added to it. If a selection is configured and the graph is in a shiny application, the selection options will be added to it, i.e. selection and anti-selection.

Toolbar position cann be defined with function opts_toolbar() and argument position.

girafe(
  ggobj = gg_scatter,
  options = list(
    opts_sizing(width = .7),
    opts_toolbar(position = "bottomright")
  )
)

Also ‘save as png’ button can be desactivated by using argument saveaspng.
saveaspng relies on JavaScript promises, so any browsers that don’t natively support the standard Promise object will need to have a polyfill (e.g. Internet Explorer with version less than 11 will need it).

girafe(
  ggobj = gg_scatter,
  options = list(
    opts_sizing(width = .7),
    opts_toolbar(saveaspng = FALSE)
  )
)