Enhancing geom_text() and geom_label()

ggplot2 pkg
ggrepel pkg
ggpp pkg

Pedro J. Aphalo



I have defined in package ‘ggpp’ enhanced versions of geom_text() and geom_label() under the names of geom_text_s() and geom_label_s() . The s is for segment, at least it was when I thought of these names. The versions described are included in version 0.5.0 and later.

The idea of better supporting the use of data labels in plot created with R package ‘ggplot2’ is not new. I have been for a long time a user of the repulsive geometries geom_text_repel() and geom_label_repel() from package ‘ggrepel’. I have even contributed some code to ‘ggrepel’. However, some time back when designing some new position functions, the idea of developing non-repulsive geometries suitable for data labels started growing on me.

Considering data visualization principles, and the philosophy of the grammar of graphics the proliferation of multiple versions of the same aesthetics is to be avoided. Colour and mappings of colours to values using a single scale per plot ensure that there is a single meaning for each value of an aesthetic values. Aesthetics linewidth and linetype can be applied to the border of label boxes provide an approach for highlighting or distinguishing individual data labels, when colour is not available.

In geom_text() transparency set with alpha affects the text while in geom_label() it affects only fill . In geom_label() the colour aesthetics controls at the same time the colour of the text and the line bordering the label; label.size controls the size of the border line, but it is a parameter rather than an aesthetic. This means that it is not possible to use the border width, its abscence or its colour to highlight selected data labels. Lack of support for the linetype aesthetic of the borber, makes it dificult to highlight individual data labels in black and white printing.

I aimed from the start to keep the use of any new geometries simple, and as consistent with the grammar of graphics as possible. The interfaces of geom_text_s() and geom_label_s() are still not stable. However, some features can be considered rather stable: by default they behave (almost?) as the equivalent geometries from ‘ggplot2’. They do not make use of any new aesthetic, they have additional formal parameters instead.

The enhancements are: 1) if used with one of the position functions from ‘ggpp’, which keep the original position, segments are drawn connecting the text or label to the observation. The justification, vjust and hjust and thus the anchoring point of the segment to the text or label are computed automatically based on the direction of displacement. 2) A new formal parameter colour.target makes it possible to select to which elements to apply the mapped colour and to which elements to apply the default colour. 3) Similarly a new formal parameter alpha.target allows similar control of to what elements to apply the mapped alpha values and to which ones the default alpha. Currently supported elements are "text", "segment", "box.line" and "box.fill" in any combination, and "box" and "all" as aliases to save typing. 4) Support linewidth and linetype aesthetics in geom_label_s() .

The use of segments or arrows to make clear to which data observation data labels are linked is frequent except in very sparse clouds of observations. Using by default automatic justification based on the direction of displacement by nudging, dodging, etc., to select the anchor point ensures that short segments will not cause difficulties even with long text labels. Of course, the vjust and hjust aesthetics otherwise work as usual when overridden with the usual values.

In this example using geom_label_s() , intead of applying colour aesthetic to the text, we apply it to the box border and the arrows. (The default legend still needs improvement.)


Plot using geom_label_s() from R package ‘ggpp’.

A second example using geom_text_s() we apply the colour aesthetic to both the text and arrows.


Plot using geom_text_s() from package ‘ggpp’.