The ggiraph package let R users make ggplot interactive. The package is an htmlwidget. The following graphic is produced by calling girafe() function on a ggplot object.

Note that girafe() is a new function but ggiraph() function will be maintained. However, the ggiraph() function is only using girafe() function!

Introduction

It extends ggplot2 with new geom functions:

  • geom_bar_interactive
  • geom_boxplot_interactive
  • geom_histogram_interactive
  • geom_hline_interactive
  • geom_line_interactive
  • geom_map_interactive
  • geom_path_interactive
  • geom_point_interactive
  • geom_polygon_interactive
  • geom_rect_interactive
  • geom_segment_interactive
  • geom_sf_interactive
  • geom_text_interactive
  • geom_tile_interactive
  • geom_vline_interactive

These understand three aesthetics to let you add interactivity:

  • tooltip: column of dataset that contains tooltips to be displayed when mouse is over elements.
  • data_id: column of dataset that contains id to be associated with elements. This aesthetic is mandatory when you want to use an hover effect or when you want to enable selection of points in shiny applications.
  • onclick: column of dataset that contains javascript function to be executed when elements are clicked.

Let’s prepare a ggplot object with the mpg dataset.

## # A tibble: 6 x 11
##   manufacturer model displ  year   cyl trans drv     cty   hwy fl    class
##   <chr>        <chr> <dbl> <int> <int> <chr> <chr> <int> <int> <chr> <chr>
## 1 audi         a4      1.8  1999     4 auto… f        18    29 p     comp…
## 2 audi         a4      1.8  1999     4 manu… f        21    29 p     comp…
## 3 audi         a4      2    2008     4 manu… f        20    31 p     comp…
## 4 audi         a4      2    2008     4 auto… f        21    30 p     comp…
## 5 audi         a4      2.8  1999     6 auto… f        16    26 p     comp…
## 6 audi         a4      2.8  1999     6 manu… f        18    26 p     comp…
g <- ggplot(mpg, aes( x = displ, y = cty, color = hwy) )

tooltips

The first example shows how to add a tooltip:

my_gg <- g + geom_point_interactive(aes(tooltip = model), size = 2) 
girafe(code = print(my_gg) )

hover effects

Now let’s add an hover effect. Elements associated with a data_id will be animated upon mouse over.

my_gg <- g + geom_point_interactive(
    aes(tooltip = model, data_id = model), size = 2) 
x <- girafe(code = print(my_gg))
x

Read more about custom animation effects

Note that data-id can also be reused within a shiny application as a reactive value.

Click actions

Using onclick

Click actions must be a string column in the dataset containing valid javascript instructions.

##                 state Murder Assault UrbanPop Rape
## Alabama       alabama   13.2     236       58 21.2
## Alaska         alaska   10.0     263       48 44.5
## Arizona       arizona    8.1     294       80 31.0
## Arkansas     arkansas    8.8     190       50 19.5
## California california    9.0     276       91 40.6
## Colorado     colorado    7.9     204       78 38.7
# create an 'onclick' column
crimes$onclick <- sprintf("window.open(\"%s%s\")",
  "http://en.wikipedia.org/wiki/", as.character(crimes$state) )

gg_crime <- ggplot(crimes, aes(x = Murder, y = Assault, color = UrbanPop )) + 
  geom_point_interactive(
    aes( data_id = state, tooltip = state, onclick = onclick ), size = 3 ) + 
  scale_colour_gradient(low = "#999999", high = "#FF3333")

girafe(ggobj = gg_crime)

Within shiny

When working with shiny, you can use the data_id aesthetic to associate points, polygons and other graphical elements with a value that will be available in a reactive context. This makes it possible to click on an element and trigger an action. Note that in this case, onclick should not be used, both onclick and data_id will need the “click” event. Read more about shiny integration

Custom animation effects

With ggiraph, you can customize tooltip style, mouse hover effects, toolbarposition… This requires usage of css instructions and options. The function girafe_options() will be used to customize animation effects. These effects will be defined by function calls, i.e. opts_tooltip(), opts_toolbar(), …

Tooltip options

Tooltip can be customized with function opts_tooltip() (that will be used as a parameter in girafe_options() call).

Tooltip position

The arguments offx and offy are used to offset tooltip position.

By default the offset is 10 pixels horizontally to the mouse position (offx=10) and 0 pixels vertically (offy=0).

dataset <- mtcars
dataset$carname <- row.names(dataset)
gg_point_1 <- ggplot(dataset, aes(x = disp, y = qsec, tooltip = carname, data_id = carname, color= wt) ) + 
    geom_point_interactive(size=3)

x <- girafe(ggobj = gg_point_1 )

girafe_options(x, opts_tooltip(offx = 20, offy = 20) )

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

girafe_options(x, opts_tooltip(offx = 60, offy = 60, use_cursor_pos = FALSE) )

Tooltip style

The opts_tooltip function 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

Tooltip opacity can be defined with the argument opacity (default to 0.9).

Let’s custom tooltip as:

  • italic font
  • no background color

Now print the ggiraph:

girafe_options(x, opts_tooltip(css = tooltip_css) )

Now, let’s add a gray rectangle with round borders and a few other details to make it less crude:

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

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_options(x, opts_tooltip(use_fill = TRUE) )

Hover effects

Hover effects occur when the mouse is over elements that have a data-id attribute (resulting from using argument data_id in interactive geom functions). It will only modify SVG element rendering when the mouse is over an element.

Mouse over effects can be configured with the opts_hover() function in the same way opts_tooltip() is used for customizing tooltip rendering.

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

girafe_options(x, opts_hover(css = "fill:red;r:10pt;") )

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.

Toolbar

You can define toolbar position with function opts_toolbar().

girafe_options(x, opts_toolbar(position = "bottomright") )
girafe_options(x, opts_toolbar(position = "topleft") )

Also ‘save as png’ button can be desactivated by using argument saveaspng.

girafe_options(x, opts_toolbar(saveaspng = TRUE) )

Shiny usage

ggiraph is an htmlwidget. It can be used within a Shiny application. In shiny, elements associated with data_id can be selected and the selection (the data_id value) is available in the client and the server side of the application.

The client ui.R

Instead of a plotOutput, use function ggiraphOutput.

The server server.R

Use function ggiraphOutput.

output$plot <- renderggiraph({
    ggiraph(code = print(gg_blahblah) )
  })

Selections

It is possible to work with selected points on a ggiraph plot within a Shiny application.

Selection can be of two types: single or multiple. The ggiraph’s parameter selection_type will let you specify that.

output$myplot <- renderggiraph({
    ggiraph(code = print(gg_blahblah), selection_type = "multiple" )
  })

The selected points will be captured in the input reactive value myplot_selected (name of the input id of the reactive output value + _selected):

You can also modify theses values by using the session$sendCustomMessage method with type myplot_set (name of the input id of the reactive output value + _set).

Examples

The package contains Shiny examples available in the shiny directory of the package (system.file("shiny", package = "ggiraph")).

selections usage (server side)

shiny::runApp(appDir = system.file("examples/shiny/crimes", package = "ggiraph"), display.mode = "showcase")
shiny::runApp(appDir = system.file("examples/shiny/cars", package = "ggiraph"), display.mode = "showcase")

# *group* selection
shiny::runApp(appDir = system.file("examples/shiny/iris", package = "ggiraph"), display.mode = "showcase")

onclick actions (client side).

shiny::runApp(appDir = system.file("examples/shiny/DT", package = "ggiraph"), display.mode = "showcase")