A ggplot object or gtable object derived from a ggplot object.
label
The label with which the plot should be annotated. Can be a plotmath expression.
x
The x position of the label
y
The y position of the label
hjust
Horizontal justification
vjust
Vertical justification
vpadding
Vertical padding. The total vertical space added to the label, given in grid
units. By default, this is added equally above and below the label. However, by changing the
y and vjust parameters, this can be changed.
fontfamily
The font family
fontface
The font face ("plain", "bold", etc.)
colour
Text color
size
Point size of text
angle
Angle at which text is drawn
lineheight
Line height of text
Details
The exact location where the
label is placed is controlled by the parameters x, y, hjust, and
vjust. By default, all these parameters are set to 0.5, which places the label
centered underneath the plot panel. A value of x = 0 indicates the left boundary
of the plot panel and a value of x = 1 indicates the right boundary. The parameter
hjust works just as elsewhere in ggplot2. Thus, x = 0, hjust = 0 places
the label left-justified at the left boundary of the plot panel, x = 0.5, hjust = 0.5
places the label centered underneath the plot panel, and x = 1, hjust = 1 places
it right-justified at the right boundary of the plot panel. x-values below 0 or
above 1 are allowed, and they move the label beyond the limits of the plot panel.
The y coordinates are relative to the added vertical space that is introduced
underneath the x-axis label to place the annotation. A value of y=0 indicates
the bottom-most edge of that space and a value of y=1 indicates the top-most
edge of that space. The total height of the added space is given by the height needed
to draw the label plus the value of vpadding. Thus, if y=0, vjust=0 then
the extra padding is added entirely above the label, if y=1, vjust=1 then the
extra padding is added entirely below the label, and if y=0.5, vjust=0.5 (the
default) then the extra padding is added equally above and below the label. As is the
case with x, y-values outside the range 0-1 are allowed. In particular,
for sufficiently large values of y, the label will eventually be located inside
the plot panel.
Value
A gtable object holding the modified plot.
Examples
p1 <- ggplot(mtcars, aes(mpg, disp)) + geom_line(colour = "blue") + background_grid(minor='none')
ggdraw(add_sub(p1, "This is an annotation.\nAnnotations can span multiple lines."))
# You can also do this repeatedly. Just be aware that new annotations are added above previous ones:
p2 <- add_sub(p1, expression(paste(a^2+b^2, " = ", c^2)))
p3 <- add_sub(p2, "This formula has no relevance here:", y = 0, vjust = 0)
ggdraw(p3)
#This code also works with faceted plots:
plot.iris <- ggplot(iris, aes(Sepal.Length, Sepal.Width)) +
geom_point() + facet_grid(. ~ Species) + stat_smooth(method = "lm") +
background_grid(major = 'y', minor = "none") + # add thin horizontal lines
panel_border() # and a border around each panel
p2 <- add_sub(plot.iris, "Annotation underneath a faceted plot, left justified.", x = 0, hjust = 0)
ggdraw(p2)
# Finally, it is possible to move the annotation inside of the plot if desired.
ggdraw(add_sub(p1, "Annotation inside plot", vpadding=grid::unit(0, "lines"),
y = 6, x = 0.03, hjust = 0))