ggiraph-book

Preface

What is ‘ggiraph’

The ‘ggiraph’ package lets you create dynamic and interactive graphics:

• dynamic with animations and tooltips in HTML documents produced by Quarto or ‘R Markdown’,
• interactive in ‘shiny’ applications where events/interactions with ggiraph graphic are made available as reactive values.

Package ‘ggiraph’ is a ‘ggplot2’ extension, you can use your ‘ggplot’ skills but must only use functions whose names are ‘ggplot’ functions suffixed with ’_interactive’.

The package is also containing an R graphic device dedicated to SVG, it’s beeing used to produce ‘ggiraph’ graphics but can be used to produce standard SVG graphics.

‘ggiraph’ is an ‘htmlwidget’ and a ‘ggplot2’ extension. Its main purpose is to work easily in ‘shiny’ applications and HTML documents produced with ‘R Markdown’ and ‘Quarto’.

Why using ‘ggiraph’

• You want to provide your readers with more information than the basic information available; you can display a tooltip when the user’s mouse is on a graphical element, you can also visually animate elements with the same attribute when the mouse passes over a graphical element, and finally you can link a JavaScript action to the click, such as opening a hypertext link.
• You want to allow users of a Shiny application to select graphical elements; for example, you can make the points of a scatter plot selectable and available as a reactive value from the server part of your application. With Shiny, ‘ggiraph’ allows interaction with graph elements, legends elements, titles and ggplot theme elements from the server part; each selection is available as a reactive value.

Dow does it work

It extends ggplot2 with:

• interactive geom functions: geom_point_interactive(), geom_col_interactive, etc.
• interactive scale functions: scale_color_continuous_interactive(), scale_fill_manual_interactive(), etc.
• interactive facet functions: facet_wrap_interactive() and facet_grid_interactive() that both work with labeller_interactive().
• interactive guide functions: guide_colorbar_interactive(), guide_colourbar_interactive(), guide_legend_interactive().
• interactive theme elements: element_line_interactive(), element_rect_interactive(), element_text_interactive(), label_interactive.

These understand three main 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.

library(ggplot2)
library(ggiraph)
g <- ggplot(mpg, aes(x = displ, y = cty))

The first example shows how to add a tooltip:

my_gg <- g + 
  geom_point_interactive(aes(tooltip = model, data_id = model), 
    size = 3, hover_nearest = TRUE)
girafe(ggobj = my_gg)