Introduction to the extensions
Data labels, annotations and insets
Data labels add textual information directly related to individual data points (shown as glyphs). Text position in this case is dependent on the scales used to represent data points. Text is usually displaced so that it does not occlude the glyph representing the data point and when the link to the data point is unclear, this link is signaled with a line segment or arrow. Data labels are distinct from annotations but instead contribute to the representation of data on a plot or map.
References are lines, shading or marks used to help the reading of a plot. These elements are used to highlight specific values on an axis or a region in a plot. They, like data labels, are positioned relative to the scales used for data. The position of data labels and lines, glyphs or shading used as reference cannot be altered by the designer of a plot, as the position conveys information. I will use the term data labels irrespective if the “labels” are textual or graphical, like icons and small plots and simple tables linked to data points or map features.
According to Koponen and Hildén (2019), in a statistical chart “annotations can be used to draw reader attention to relevant detail”. These authors use as an example a text box in a plot to highlight a data point that is off-scale and has been “squeezed” to a position immediately outside the plotting area.
Annotations differ from data labels, in that their position is decoupled from their meaning. Insets can be thought as larger, but still self-contained annotations. In most cases the reading of inset tables and plots depends only weakly on the plot or map in which they are included.
In the case of annotations and insets the designer of a data visualization has the freedom to locate them anywhere, as long they do not occlude features used to describe data. I will use the term annotation irrespective if the “labels” are textual or graphical. Insets are similar to annotations, but the term inset is used when an annotation’s graphical or textual element is complex and occupies more space within the plotting area. Insets can be moved from within the main plotting area to being adjacent to it, e.g., as a smaller panel, without any loss of meaning .
That the position of annotations and insets is independent of the plotted data cannot be expressed using the grammar of graphics (GG) as implemented in package ‘ggplot2’.
Annotations in ‘ggplot2’
The plotting of data using package ‘ggplot2’ is described by Wickham (2016) and several other books. Chapter 7 in Aphalo (2020) not only describes the grammar used by ‘ggplot2’ but also several extensions to it, including those provided by packages ‘ggpp’ and ‘ggpmisc’.
In The Layered Grammar of Graphics (Wickham 2000) as implemented in package ‘ggplot2’ (Wickham 2016) annotations are “second class” features. As layers they behave differently than data layers: Only constant values can be mapped to aesthetics and do no support faceting into panels. In essence annotate() disconnects the resulting plot elements from the data source and faceting, but not from the scales used to graphically display the data values.
From the data visualization perspective the main practical and conceptual difference between data labels and annotations is in the scales used to position them within the plotting area. Instead of using an annotate() function that deviates from the grammar of graphics to implement annotations, we could retain the use of the grammar of graphics for annotations but add support of native plot coordinates (npc). Support of annotations done in this way would allow “annotation layers” to behave almost identically to “data layers”, and use the same grammar. The x and y position aesthetics used for data could be supplemented with pseudo-aesthetics without any translation relative to the native plotting coordinates of the plotting area or viewport. Doing so, would allow the graphic design flexibility conceptually inherent to annotations within a user-friendly syntax.
Extending ‘ggplot2’
Based on this insight, a new approach to adding annotations and insets was implemented in package ‘ggpmisc’ (>= 0.3.1) through two new x and y pseudo-aesthetics, npcx and npcy, and corresponding dumb scales and various geometries that make use of them. These scales and geometries were implemented as an extension to package ‘ggplot2’ and are in package ‘ggpp’.
Before showing how this works in practice, we load the package and set an uncluttered theme as default.
library(ggpp)
theme_set(theme_bw() + theme(panel.grid = element_blank()))Native plot coordinates have range 0..1. However, the “npc” geoms also recognize some positions by name with the same character strings as used for text justification in ‘ggplot2’. The default justification is "inward", as this protects from clipping at the edges the plotting area irrespective the arguments passed to the witdth and height parameters of R’s graphic devices.
p1 <- ggplot(mtcars, aes(factor(cyl), mpg)) +
geom_point() +
geom_text_npc(data = data.frame(x = c("left", "left"),
y = c("top", "bottom"),
label = c("Most\nefficient",
"Least\nefficient")),
mapping = aes(npcx = x, npcy = y, label = label),
size = 3)
p1
The advantage of this approach becomes apparent when the limits of the y scale are unknown or vary. When a script or user defined plotting function sets the scale limits based on the input data, in the absence of the extensions proposed here, setting annotations consistently within the plotting area becomes laborious. The example below, shows how the annotations remain at the desired position when the y scale limits are expanded.
p1 + expand_limits(y = 0)
To support the existing syntax for annotations using the new geometries, function ggplot2::annotate() is overridden when package ‘ggpp’ is loaded. The new definition adds support for the new pseudo-aesthetics npcx and npcy retaining its original ‘ggplot2’ behaviour in all other respects.
ggplot(mtcars, aes(factor(cyl), mpg)) +
geom_point() +
annotate(geom = "text_npc",
npcx = c("left", "left"),
npcy = c("top", "bottom"),
label = c("Most\nefficient",
"Least\nefficient"),
size = 3)
Inset plots can be added with the same syntax using geom_plot_npc(). They can be thought also as being annotations. Here we use annotate() but geom_plot() can be also used directly, in which case the inset plots can be different for each panel.
p2 <- ggplot(mtcars, aes(factor(cyl), mpg, colour = factor(cyl))) +
stat_boxplot() +
labs(y = NULL) +
theme_bw(9) +
theme(legend.position = "none",
panel.grid = element_blank())
ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
geom_point() +
annotate("plot_npc", npcx = "left", npcy = "bottom", label = p2) +
expand_limits(y = 0, x = 0)
A simple example with facets, labelling of panels in a traditional way as required by some book and journal styles. In this case panel tags are added within the plotting area at a consistent “npc” location with free scale limits in panels.
ggplot(mtcars, aes(wt, mpg)) +
geom_point() +
geom_text_npc(data = data.frame(cyl = levels(factor(mtcars$cyl)),
label = LETTERS[seq_along(levels(factor(mtcars$cyl)))],
x = 0.90,
y = 0.95),
mapping = aes(npcx = x, npcy = y, label = label),
size = 4) +
facet_wrap(~factor(cyl), scales = "free") +
theme(strip.background = element_blank(),
strip.text = element_blank())
This approach was first implemented in ‘ggpmisc’ version 0.3.1 released in April 2919. The implementation now in package ‘ggpp’ can be considered stable. However, this implementation is to an extent dependent on undocumented behaviour of ‘ggplot2’ functions, which means that future updates to ‘ggplot2’ could break this functionality.
When to use annotations and when insets
Package ‘ggpmisc’ adds support for various plot annotations and reference guides based on model fits and other statistics. It also adds support for some data labels related to data features. While developing these statistics in ‘ggpmisc’, it became clear that expanding the grammar of graphics’s support for annotations would simplify the new code considerably and also more cleanly separate the computations on data from the positioning of annotations. These extensions to the grammar are now in ‘ggpp’.
Table. Geometries useful for data labels and annotations. Currently implemented ordinary geometries and their npc versions. The rightmost column shows the expected class of the objects mapped to the label aesthetic. When using annotate() to add a single plot, table or grob as an inset, enclosing them in a list is allowed, but not a requirement. All those geoms whose names are highlighted in italics support plotting of connecting segments or arrows when a the coordinates have been modified by a position function.
| Data labels | Annotations (npc) | label aes. |
|---|---|---|
ggplot2::geom_text() |
geom_text_npc() |
character |
ggplot2::geom_label() |
geom_label_npc() |
character |
ggrepel::geom_text_repel() |
character |
|
ggrepel::geom_label_repel() |
character |
|
geom_text_s() |
character |
|
geom_label_s() |
character |
|
geom_point_s() |
||
geom_plot() |
geom_plot_npc() |
list(<ggplot>) |
geom_table() |
geom_table_npc() |
list(<data.frame>) |
geom_grob() |
geom_grob_npc() |
list(<grob>) |
geom_img() (planned) |
geom_img_npc() |
list(<raster>) |
When adding an informative element to a plot, assess whether it is an annotation or a data label. To decide on the best approach, consider if the location of the element is more “naturally” expressed in the original data units or as position relative to the edges or centre of the plotting area. In the second case, prefer the “npc” geoms as you are dealing with annotations, otherwise, use the ordinary geometries as you are dealing with data labels or data points.
Positioning data labels
Nudging is normally used to displace text labels so that they do not overlap the points or lines representing the data being labelled. Two enhanced versions of position_nudge() are provided, position_nudge_center() and position_nudge_line(). These functions make it possible to apply nudging that varies automatically according to the relative position of points with respect to arbitrary points or lines, or with respect to a polynomial or smoothing spline fitted on-the-fly to the the observations.
A limitation of ‘ggplot2’ is that only one position function can be used in a layer. This makes it difficult to add text labels to stacked or dodged bars or columns, or the labelling of points that have been jittered. The solution provided by ‘ggpp’ are wrappers on these position functions that add support for nudging.
All these new position functions, instead of deleting the original positions, they rename the variables in data containing these coordinates. This makes it possible for geometries to draw connecting segments or arrows between old and new positions. These functions are backwards compatible and can be used in place of those from ‘ggplot2’. The geometries from ‘ggrepel’ (> 0.9.1) and many of those from ‘ggpp’ can make use of the original coordinates kept in data.
| Position (origin kept) | Position (origin discarded) |
|---|---|
position_nudge_keep() |
ggplot2::position_nudge() |
ggrepel::postion_nudge_repel() |
ggplot2::position_nudge() |
position_nudge_centre() |
|
position_nudge_line() |
|
position_jitter_keep() |
ggplot2::position_jitter() |
position_dodge_keep() |
ggplot2::position_dodge() |
position_dodge2_keep() |
ggplot2::position_dodge2() |
position_stack_keep() |
ggplot2::position_stack() |
position_fill_keep() |
ggplot2::position_fill() |
position_jitterdodge_keep() (planned) |
ggplot2::position_jitterdodge() |
position_jitternudge() |
|
position_dodgenudge() |
|
position_dodge2nudge() |
|
position_stacknudge() |
|
position_fillnudge() |
|
position_jitterdodgenudge() (planned) |
Highlighting data features
If maxima or minima are to be labelled in a plot, this can be automated so that the feature and its labelling is automated. This is possible with stat_peaks() and stat_valleys(). Marginal annotations with symbols and vertical and horizontal lines can be used to highlight summary values or events/conditions. The geoms geom_quadrant_lines(), geom_vhlines(), geom_x_margin_arrow(), geom_x_margin_grob(), geom_x_margin_point(), geom_y_margin_arrow(), geom_y_margin_grob() and geom_y_margin_point() make such labelling easy.
Local density of observations
There are two aspects to this: highlighting with colours dense or sparse regions, or using density to decide which observations to label. In this cases we can use stat_dens1d_labels() and stat_dens2d_labels(), stat_dens1d_filter() and stat_dens2d_filter(), and stat_dens1d_filter_g() and stat_dens2d_filter_g().
Summary statistics
With some types of data it is common to compute a summary per quadrant, rather than based on a prior grouping. The stat stat_quadrant_counts() can de used to annotate plots with the number of observations in each quadrant. stat_summary_xy() is similar to stat_summary() from ‘ggplot2’ but useful when both x and y are continuous variables. It allows the use the same, or different functions to summarise the data over x and y. In contrast stat_centroid() always applies the same function over x and y.
ggplot methods
Being ggplot() defined as a generic method in ‘ggplot2’ makes it possible to define specializations, and we provide two for time series stored in objects of classes ts and xts which automatically convert these objects into tibbles and set by default the aesthetic mappings for x and y automatically. A companion function try_tibble() is also exported.
Thoughts for the future
Although we have discussed data independent scales only for x and y aesthetics, the same consideration applies to other aesthetics like colour. It seems generally useful to allow aesthetics to use a different scale for annotations than for data. Defining pseudo-aesthetics for annotations instead of allowing multiple scales for each aesthetic in a plot would add flexibility while still keeping the guarantee that the meaning of aesthetics’ values remains consistent across all plot elements representing data.
List of references
Aphalo, Pedro J. (2020) Learn R: As a Language. The R Series. Boca Raton and London: Chapman and Hall/CRC Press. ISBN: 978-0-367-18253-3. 350 pp.
Koponen, J; Hildén, J. (2019) Data visualization handbook. Aalto ARTS books, Espoo. ISBN 978-952-60-7449-8.
Wickham H. (2010) A Layered Grammar of Graphics. Journal of Computational and Graphical Statistics 19: 3–28.
Wickham H. (2016) ggplot2: Elegant Graphics for Data Analysis. Springer International Publishing. ISBN 978-3-319-24275-0.
