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 as 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’ at the time of writing.
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 can retain the use of the grammar
of graphics for annotations but add support for native plot coordinates
(npc). Support of annotations done in this way allows “annotation
layers” to behave almost identically to “data layers”, and use the same
syntax. The x and y position aesthetics used for data
can be supplemented with pseudo-aesthetics without any translation
relative to the native plotting coordinates of the plotting area or
viewport. Doing so, allows the graphic design flexibility conceptually
inherent to annotations within a user-friendly syntax.
Support of native plot coordinates
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 are currently in package ‘ggpp’ and still used in package ‘ggpmisc’.
Native plot coordinates have range 0..1. However, the “npc” geoms
from ‘ggpp’ also recognize certain 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 of 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.
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_text_pairwise() |
character |
|
geom_label_pairwise() |
character |
|
geom_point_s() |
not supported | |
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>) |
Highlighting data features
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. These
work similarly to geoms geom_hline() and
geom_vline() from ‘ggplot2’ and plays a similar role. Of
course, they can also be used to add annotations not derived from the
observations.
| Marginal marks | Location aesthetic | label aes. |
|---|---|---|
geom_x_margin_arrow() |
xintercept |
not supported |
geom_y_margin_arrow() |
yintercept |
not supported |
geom_x_margin_grob() |
xintercept |
list(<grob>) |
geom_y_margin_grob() |
yintercept |
list(<grob>) |
geom_x_margin_point() |
xintercept |
not supported |
geom_y_margin_point() |
yintercept |
not supported |
geom_quadrant_lines() |
not supported | |
geom_vhlines() |
xintercept yintercept |
not supported |
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.
Summary statistics
Frequently, maxima or minima are features of interest that may need
to be labelled or highlighted in a plot. This can be done easily with
functions stat_peaks() and stat_valleys().
With some types of data it is common to compute a summary per plot
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, selected quadrants, or
quadrants pooled along x and/or y. Similarly,
stat_group_counts() and stat_panel_counts()
can be used to annotate plots with the number of observations per panel,
or per group within each panel.
In many cases, such as rug plots or other representations on plot
margins, x and y summaries can be computed in separate
plot layers using the statistics from ‘ggplot2’. In contrast, in other
cases, such as when showing the x and y position of
the means in the plotting area itself, it is necessary to compute
summaries for both x and y in the same plot layer.
Function stat_summary_xy() is similar to
stat_summary() from ‘ggplot2’ but useful when both
x and y are continuous variables. It allows the use of
the same, or different functions to summarize the data over x
and y. In contrast, its simpler counterpart,
stat_centroid(), always applies the same function over
x and y.
An additional variation is statistic stat_apply_group,
which can apply functions to x and y values in
parallel, which is most useful for accumulating or differencing
consecutive data values.
Positioning data labels
Nudging is normally used to displace text labels so that data labels
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 data 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 from ‘ggplot2’. These wrappers add support for nudging.
The position functions defined in ‘ggpp’, instead of deleting the
original positions, 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. For
consistency, positions equivalent to all those defined in ‘ggplot2’ are
defined in ‘ggpp’. These functions are backwards compatible with those
from ‘ggplot2’ and can be used in place of them. The geometries from
‘ggrepel’ (>= 0.9.2) 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_stack_minmax() |
|
position_fill_keep() |
ggplot2::position_fill() |
position_jitternudge() |
|
position_dodgenudge() |
|
position_dodge2nudge() |
|
position_stacknudge() |
|
position_fillnudge() |
|
position_jitterdodge_keep() (planned) |
ggplot2::position_jitterdodge() |
position_jitterdodgenudge() (planned) |
There is a storage-use cost in saving the original position, by
making the data member stored in the ggplot object bigger.
This may need to be taken into consideration when data has
many rows. In such cases, when a counterpart position function that does
not keep the original coordinates exists, it is wise not to use the new
“keep” position functions in combination with geometries that cannot
make use of the additional information stored by them. Alternatively,
and when using those new position functions with no counterpart in
‘ggplot2’ the keeping of the original position can be disabled by
passing kept.position = "none" as an additional argument
when they are called.
Local density of observations
With stats from ‘ggplot2’ it is common to plot estimates of empirical density curves or empirical density surfaces. There are other uses for density estimates: 1) highlighting dense or sparse regions in clouds of observations plotted as points, and 2) using density to decide which observations to label and which not to label. _If the highlighting or labeling is to be interpreted as meaningful as a description of properties of the population then the fitted curve of surface should not be too flexible, it should not track local anomalies in the distribution of observations. In contrast if the use of the density estimate is only used as a way of avoiding overlaps among labels with no intent of describing properties of the data, much more flexible curves and surfaces are most effective.
Functions stat_dens1d_filter() and
stat_dens2d_filter(), and
stat_dens1d_filter_g() and
stat_dens2d_filter_g() can be used to filter/subset data
based on local density estimates.
Functions stat_dens1d_labels() and
stat_dens2d_labels() instead of removing rows from data,
replace or edit the values mapped to the label aesthetic
before they are passed to the geometry. This is especially useful in
combination with the repulsive geometries from package ‘ggrepel’ because
by retaining all observations in data these geometries can repulse
labels away from observations with and without data labels attached.
Although useful for diverse types of plots, these statistics are most useful when creating volcano and quadrant plots. A case where the observations near the edges of a cloud of observations are of special interest.
The density estimates used for the “filtering” of data rows or labels can be of interest both when selecting the parameters for the fit of the empirical density function or possibly even for mapping to an aesthetic. These are optionally returned.
One final twist is that even if the density estimate is in all cases
obtained from the whole of data, the selection criteria can
be applied separately, and even be different, for each quadrant or tail.
For example, we can highlight or label the same fraction of
observations, or alternatively the same number of observations in each
quadrant or tail even if the overall density of observations is
different between tails or among quadrants.
ggplot methods
That ggplot() is defined as a generic method in
‘ggplot2’ makes it possible to define specializations. We provide two
ggplot() methods for time series stored in objects of
classes ts and xts. These methods
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.
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.
Pooling quadrants along the x-axis.
(
Highlight 1/4 of observations from lowest density areas in each quadrant
of the plot. We also highlight the boundaries of the quadrants. Compare
the plot above to that below.
Highlight a given fraction of observations in each quadrant, by setting
A more elaborate example, 50% of observations, with color representing
the local empirical density, only for them.
This function also supports distributing the positions in the available
space, with action `“spread”.
