INTRODUCTION

The ggiraph is an htmlwidget and a ggplot2 extension. It allows ggplot graphics to be animated.

Animation is made with ggplot geometries that can understand three arguments:

Tooltip: a column of data-sets that contain tooltips to be displayed when the mouse is over elements.
Onclick: a column of data-sets that contain a JavaScript function to be executed when elements are clicked.
Data_id: a column of data-sets that contain an id to be associated with elements.

If it used within a shiny application, elements associated with an id (data_id) can be selected and manipulated on client and server sides.

Installation

Get a development version on github:
devtools::install_github('davidgohel/ggiraph')

Get the CRAN version:
install.packages("ggiraph")

Using Ggiraph

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

It extends ggplot2 with new geom functions:

geom_bar_interactive
geom_boxplot_interactive
geom_histogram_interactive
geom_line_interactive
geom_map_interactive
geom_path_interactive
geom_point_interactive
geom_polygon_interactive
geom_rect_interactive
geom_segment_interactive
geom_text_interactive
geom_tile_interactive

These understand three aesthetics to let you add interactivity:

Tooltip: a column of data-sets that contain tooltips to be displayed when the mouse is over elements.
Onclick: a column of data-sets that contain a JavaScript function to be executed when elements are clicked.
Data_id: a column of data-sets that contain an id to be associated with elements. This aesthetic is mandatory when you want to use a hover effect or when you want to enable the selection of points in shiny applications.
Let’s prepare a ggplot object with the mpg data-set.

library(ggplot2) library(ggiraph) head(mpg) 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) ggiraph(code = print(my_gg) )

Hover Effects

Now let’s add a 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) ggiraph(code = print(my_gg), hover_css = "cursor:pointer;fill:red;stroke:red;")

The default value of the hover css is hover_css = "fill:orange;".

Note that data-id can also be re-used within a shiny application.

Click Actions

Click actions must be a string column in the data-set containing valid JavaScript instructions.

crimes <- data.frame(state = tolower(rownames(USArrests)), USArrests)

head(crimes) # 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") ggiraph(code = print(gg_crime), hover_css = "fill-opacity:.3;cursor:pointer;")

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, on-click should not be used. Both on-click and data_id will need the “click” event.

Custom Animation Effects

With ggiraph, you can customize tooltip styles and mouse hover effects. This requires usage of the css.

Tooltip Position

The arguments tooltip_offx and tooltip_offy are used to offset tooltip position.

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

library(ggplot2) library(ggiraph) theme_set(theme_minimal()) 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)

# htmlwidget call ggiraph(code = {print(gg_point_1)}, tooltip_offx = 20, tooltip_offy = -10 )

Tooltip Style
The ggiraph function has an argument named tooltip_extra_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 ending 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 the tooltip
Padding: the space around the content
Tooltip opacity can be defined with the argument tooltip_opacity (default to 0.9).

Let’s custom the tooltip as:

Italic font
No background color
Tooltip_css <- “background-color:transparent;font-style:italic;”
Now, print the ggiraph:

ggiraph(code = {print(gg_point_1)}, tooltip_extra_css = tooltip_css )

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

tooltip_css <- "background-color:gray;color:white;font-style:italic;padding:10px;border-radius:10px 20px 10px 20px;"

ggiraph(code = {print(gg_point_1)}, tooltip_extra_css = tooltip_css, tooltip_opacity = .75 )

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 elements rendering when the mouse is over an element.

Mouse over effects can be configured with the hover_css argument in the same way tooltip_extra_css 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:

ggiraph(code = {print(gg_point_1)}, hover_css = "fill:red;r:10pt;" )

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

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

ggiraph(code = print(gg_point_1), zoom_max = 5)

Now, let’s move on to the first set of real exercises on the ggiraph package!