Title: | Improved Text Rendering Support for 'ggplot2' |
---|---|
Description: | A 'ggplot2' extension that enables the rendering of complex formatted plot labels (titles, subtitles, facet labels, axis labels, etc.). Text boxes with automatic word wrap are also supported. |
Authors: | Claus O. Wilke [aut] , Brenton M. Wiernik [aut, cre] (<https://orcid.org/0000-0001-9560-6336>, @bmwiernik) |
Maintainer: | Brenton M. Wiernik <[email protected]> |
License: | GPL-2 |
Version: | 0.1.2 |
Built: | 2024-10-14 05:49:09 UTC |
Source: | https://github.com/wilkelab/ggtext |
Theme element that enables markdown text.
element_markdown( family = NULL, face = NULL, size = NULL, colour = NULL, fill = NULL, box.colour = NULL, linetype = NULL, linewidth = NULL, hjust = NULL, vjust = NULL, halign = NULL, valign = NULL, angle = NULL, lineheight = NULL, margin = NULL, padding = NULL, r = NULL, color = NULL, box.color = NULL, align_widths = NULL, align_heights = NULL, rotate_margins = NULL, debug = FALSE, inherit.blank = FALSE )
element_markdown( family = NULL, face = NULL, size = NULL, colour = NULL, fill = NULL, box.colour = NULL, linetype = NULL, linewidth = NULL, hjust = NULL, vjust = NULL, halign = NULL, valign = NULL, angle = NULL, lineheight = NULL, margin = NULL, padding = NULL, r = NULL, color = NULL, box.color = NULL, align_widths = NULL, align_heights = NULL, rotate_margins = NULL, debug = FALSE, inherit.blank = FALSE )
family |
Font family |
face |
Font face |
size |
Font size |
colour , color
|
Text color |
fill |
Fill color of the enclosing box |
box.colour , box.color
|
Line color of the enclosing box (if different from the text color) |
linetype |
Line type of the enclosing box (like |
linewidth |
Line width of the enclosing box (measured in mm, just like |
hjust |
Horizontal justification |
vjust |
Vertical justification |
halign |
Horizontal justification |
valign |
Vertical justification |
angle |
Angle (in degrees) |
lineheight |
Line height |
padding , margin
|
Padding and margins around the text box.
See |
r |
Unit value specifying the corner radius of the box |
align_widths , align_heights
|
Should multiple elements be aligned by their
widths or height? See |
rotate_margins |
Should margins get rotated in frame with rotated text?
If |
debug |
Draw a debugging box around each label |
inherit.blank |
See |
A ggplot2 theme element that can be used inside a ggplot2::theme()
call.
gridtext::richtext_grob()
, element_textbox()
, geom_richtext()
The theme elements element_textbox()
and element_textbox_simple()
enable Markdown text in a box, with
word wrap. Both functions implement exactly the same functionality; they only differ in the default values
for the various element values. element_textbox()
sets all values that are not specified to NULL
, as is
the usual practice in ggplot2 themes. These missing values are usually completed by inheritance from
parent theme elements. By contrast, element_textbox_simple()
provides meaningful default values for many of
the values that are not usually defined in ggplot2 themes. This makes it simpler to use a textbox element
in the context of an existing theme.
element_textbox( family = NULL, face = NULL, size = NULL, colour = NULL, fill = NULL, box.colour = NULL, linetype = NULL, linewidth = NULL, hjust = NULL, vjust = NULL, halign = NULL, valign = NULL, lineheight = NULL, margin = NULL, padding = NULL, width = NULL, height = NULL, minwidth = NULL, maxwidth = NULL, minheight = NULL, maxheight = NULL, r = NULL, orientation = NULL, color = NULL, box.color = NULL, debug = FALSE, inherit.blank = FALSE ) element_textbox_simple( family = NULL, face = NULL, size = NULL, colour = NULL, fill = NA, box.colour = NULL, linetype = 0, linewidth = 0.5, hjust = 0.5, vjust = 0.5, halign = 0, valign = 1, lineheight = 1.2, margin = ggplot2::margin(0, 0, 0, 0), padding = ggplot2::margin(0, 0, 0, 0), width = grid::unit(1, "npc"), height = NULL, minwidth = NULL, maxwidth = NULL, minheight = NULL, maxheight = NULL, r = grid::unit(0, "pt"), orientation = "upright", color = NULL, box.color = NULL, debug = FALSE, inherit.blank = FALSE )
element_textbox( family = NULL, face = NULL, size = NULL, colour = NULL, fill = NULL, box.colour = NULL, linetype = NULL, linewidth = NULL, hjust = NULL, vjust = NULL, halign = NULL, valign = NULL, lineheight = NULL, margin = NULL, padding = NULL, width = NULL, height = NULL, minwidth = NULL, maxwidth = NULL, minheight = NULL, maxheight = NULL, r = NULL, orientation = NULL, color = NULL, box.color = NULL, debug = FALSE, inherit.blank = FALSE ) element_textbox_simple( family = NULL, face = NULL, size = NULL, colour = NULL, fill = NA, box.colour = NULL, linetype = 0, linewidth = 0.5, hjust = 0.5, vjust = 0.5, halign = 0, valign = 1, lineheight = 1.2, margin = ggplot2::margin(0, 0, 0, 0), padding = ggplot2::margin(0, 0, 0, 0), width = grid::unit(1, "npc"), height = NULL, minwidth = NULL, maxwidth = NULL, minheight = NULL, maxheight = NULL, r = grid::unit(0, "pt"), orientation = "upright", color = NULL, box.color = NULL, debug = FALSE, inherit.blank = FALSE )
family |
Font family |
face |
Font face |
size |
Font size (in pt) |
colour , color
|
Text color |
fill |
Fill color of the enclosing box |
box.colour , box.color
|
Line color of the enclosing box (if different from the text color) |
linetype |
Line type of the enclosing box (like |
linewidth |
Line width of the enclosing box (measured in mm, just like |
hjust |
Horizontal justification |
vjust |
Vertical justification |
halign |
Horizontal justification |
valign |
Vertical justification |
lineheight |
Line height, in multiples of the font size |
padding , margin
|
Padding and margins around the text box.
See |
width , height
|
Unit objects specifying the width and height
of the textbox, as in |
minwidth , minheight , maxwidth , maxheight
|
Min and max values for width and height. Set to NULL to impose neither a minimum nor a maximum. |
r |
Unit value specifying the corner radius of the box |
orientation |
Orientation of the text box. See |
debug |
Not implemented. |
inherit.blank |
See |
A ggplot2 theme element that can be used inside a ggplot2::theme()
call.
gridtext::textbox_grob()
, element_markdown()
, geom_textbox()
library(ggplot2) ggplot(mtcars, aes(disp, mpg)) + geom_point() + labs( title = "<b><span style = 'font-size:13pt'>Fuel economy vs. engine displacement</span></b><br> Lorem ipsum *dolor sit amet,* consectetur adipiscing elit, **sed do eiusmod tempor incididunt** ut labore et dolore magna aliqua. <span style = 'color:red;'>Ut enim ad minim veniam,</span> quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", x = "displacement (in<sup>3</sup>)", y = "Miles per gallon (mpg)<br><span style = 'font-size:8pt'>A measure of the car's fuel efficiency.</span>" ) + theme( plot.title.position = "plot", plot.title = element_textbox_simple( size = 10, padding = margin(5.5, 5.5, 5.5, 5.5), margin = margin(0, 0, 5.5, 0), fill = "cornsilk" ), axis.title.x = element_textbox_simple( width = NULL, padding = margin(4, 4, 4, 4), margin = margin(4, 0, 0, 0), linetype = 1, r = grid::unit(8, "pt"), fill = "azure1" ), axis.title.y = element_textbox_simple( hjust = 0, orientation = "left-rotated", minwidth = unit(1, "in"), maxwidth = unit(2, "in"), padding = margin(4, 4, 2, 4), margin = margin(0, 0, 2, 0), fill = "lightsteelblue1" ) )
library(ggplot2) ggplot(mtcars, aes(disp, mpg)) + geom_point() + labs( title = "<b><span style = 'font-size:13pt'>Fuel economy vs. engine displacement</span></b><br> Lorem ipsum *dolor sit amet,* consectetur adipiscing elit, **sed do eiusmod tempor incididunt** ut labore et dolore magna aliqua. <span style = 'color:red;'>Ut enim ad minim veniam,</span> quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.", x = "displacement (in<sup>3</sup>)", y = "Miles per gallon (mpg)<br><span style = 'font-size:8pt'>A measure of the car's fuel efficiency.</span>" ) + theme( plot.title.position = "plot", plot.title = element_textbox_simple( size = 10, padding = margin(5.5, 5.5, 5.5, 5.5), margin = margin(0, 0, 5.5, 0), fill = "cornsilk" ), axis.title.x = element_textbox_simple( width = NULL, padding = margin(4, 4, 4, 4), margin = margin(4, 0, 0, 0), linetype = 1, r = grid::unit(8, "pt"), fill = "azure1" ), axis.title.y = element_textbox_simple( hjust = 0, orientation = "left-rotated", minwidth = unit(1, "in"), maxwidth = unit(2, "in"), padding = margin(4, 4, 2, 4), margin = margin(0, 0, 2, 0), fill = "lightsteelblue1" ) )
This geom draws text labels similar to ggplot2::geom_label()
, but formatted
using basic markdown/html. Parameter and aesthetic names follow the conventions
of ggplot2::geom_label()
, and therefore the appearance of the frame around
the label is controlled with label.colour
, label.padding
, label.margin
,
label.size
, label.r
, even though the same parameters are called box.colour
,
box.padding
, box.margin
, box.size
, and box.r
in geom_textbox()
. Most
styling parameters can be used as aesthetics and can be applied separately to
each text label drawn. The exception is styling parameters that are specified
as grid units (e.g., label.padding
or label.r
), which can only be specified
for all text labels at once. See examples for details.
geom_richtext( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., nudge_x = 0, nudge_y = 0, label.padding = unit(c(0.25, 0.25, 0.25, 0.25), "lines"), label.margin = unit(c(0, 0, 0, 0), "lines"), label.r = unit(0.15, "lines"), na.rm = FALSE, show.legend = NA, inherit.aes = TRUE )
geom_richtext( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., nudge_x = 0, nudge_y = 0, label.padding = unit(c(0.25, 0.25, 0.25, 0.25), "lines"), label.margin = unit(c(0, 0, 0, 0), "lines"), label.r = unit(0.15, "lines"), na.rm = FALSE, show.legend = NA, inherit.aes = TRUE )
mapping |
Set of aesthetic mappings created by |
data |
The data to be displayed in this layer. There are three options: If A A |
stat |
The statistical transformation to use on the data for this layer, as a string. |
position |
Position adjustment, either as a string, or the result of
a call to a position adjustment function. Cannot be jointy specified with
|
... |
Other arguments passed on to |
nudge_x |
Horizontal and vertical adjustment to nudge labels by.
Useful for offsetting text from points, particularly on discrete scales.
Cannot be jointly specified with |
nudge_y |
Horizontal and vertical adjustment to nudge labels by.
Useful for offsetting text from points, particularly on discrete scales.
Cannot be jointly specified with |
label.padding |
Amount of padding around label. Defaults to 0.25 lines. |
label.margin |
Unit vector of length four specifying the margin outside the text label. |
label.r |
Radius of rounded corners. Defaults to 0.15 lines. |
na.rm |
If |
show.legend |
logical. Should this layer be included in the legends?
|
inherit.aes |
If |
A ggplot2 layer that can be added to a plot created with
ggplot2::ggplot()
.
geom_richtext()
understands the following aesthetics (required
aesthetics are in bold; select aesthetics are annotated):
x
y
label
alpha
angle
colour
Default color of label text and label outline.
family
fontface
fill
Default fill color of label background.
group
hjust
label.colour
Color of label outline. Overrides colour
.
label.size
Width of label outline.
lineheight
size
Default font size of label text.
text.colour
Color of label text. Overrides colour
.
vjust
geom_textbox()
, element_markdown()
library(ggplot2) df <- data.frame( label = c( "Some text **in bold.**", "Linebreaks<br>Linebreaks<br>Linebreaks", "*x*<sup>2</sup> + 5*x* + *C*<sub>*i*</sub>", "Some <span style='color:blue'>blue text **in bold.**</span><br>And *italics text.*<br> And some <span style='font-size:18pt; color:black'>large</span> text." ), x = c(.2, .1, .5, .9), y = c(.8, .4, .1, .5), hjust = c(0.5, 0, 0, 1), vjust = c(0.5, 1, 0, 0.5), angle = c(0, 0, 45, -45), color = c("black", "blue", "black", "red"), fill = c("cornsilk", "white", "lightblue1", "white") ) ggplot(df) + aes( x, y, label = label, angle = angle, color = color, fill = fill, hjust = hjust, vjust = vjust ) + geom_richtext() + geom_point(color = "black", size = 2) + scale_color_identity() + scale_fill_identity() + xlim(0, 1) + ylim(0, 1) # labels without frame or background are also possible ggplot(df) + aes( x, y, label = label, angle = angle, color = color, hjust = hjust, vjust = vjust ) + geom_richtext( fill = NA, label.color = NA, # remove background and outline label.padding = grid::unit(rep(0, 4), "pt") # remove padding ) + geom_point(color = "black", size = 2) + scale_color_identity() + xlim(0, 1) + ylim(0, 1)
library(ggplot2) df <- data.frame( label = c( "Some text **in bold.**", "Linebreaks<br>Linebreaks<br>Linebreaks", "*x*<sup>2</sup> + 5*x* + *C*<sub>*i*</sub>", "Some <span style='color:blue'>blue text **in bold.**</span><br>And *italics text.*<br> And some <span style='font-size:18pt; color:black'>large</span> text." ), x = c(.2, .1, .5, .9), y = c(.8, .4, .1, .5), hjust = c(0.5, 0, 0, 1), vjust = c(0.5, 1, 0, 0.5), angle = c(0, 0, 45, -45), color = c("black", "blue", "black", "red"), fill = c("cornsilk", "white", "lightblue1", "white") ) ggplot(df) + aes( x, y, label = label, angle = angle, color = color, fill = fill, hjust = hjust, vjust = vjust ) + geom_richtext() + geom_point(color = "black", size = 2) + scale_color_identity() + scale_fill_identity() + xlim(0, 1) + ylim(0, 1) # labels without frame or background are also possible ggplot(df) + aes( x, y, label = label, angle = angle, color = color, hjust = hjust, vjust = vjust ) + geom_richtext( fill = NA, label.color = NA, # remove background and outline label.padding = grid::unit(rep(0, 4), "pt") # remove padding ) + geom_point(color = "black", size = 2) + scale_color_identity() + xlim(0, 1) + ylim(0, 1)
Draw boxes of defined width and height containing word-wrapped text. Multiple
boxes can be drawn at once. Most styling parameters can be used as aesthetics
and can be applied separately to each text box drawn. The exception is styling
parameters that are specified as grid units (e.g., box.padding
or box.r
),
which can only be specified for all text boxes at once. See examples for details.
geom_textbox( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., nudge_x = 0, nudge_y = 0, box.padding = unit(c(5.5, 5.5, 5.5, 5.5), "pt"), box.margin = unit(c(0, 0, 0, 0), "pt"), box.r = unit(5.5, "pt"), width = unit(2, "inch"), minwidth = NULL, maxwidth = NULL, height = NULL, minheight = NULL, maxheight = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE )
geom_textbox( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., nudge_x = 0, nudge_y = 0, box.padding = unit(c(5.5, 5.5, 5.5, 5.5), "pt"), box.margin = unit(c(0, 0, 0, 0), "pt"), box.r = unit(5.5, "pt"), width = unit(2, "inch"), minwidth = NULL, maxwidth = NULL, height = NULL, minheight = NULL, maxheight = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE )
mapping |
Set of aesthetic mappings created by |
data |
The data to be displayed in this layer. There are three options: If A A |
stat |
The statistical transformation to use on the data for this layer, as a string. |
position |
Position adjustment, either as a string, or the result of
a call to a position adjustment function. Cannot be jointy specified with
|
... |
Other arguments passed on to |
nudge_x , nudge_y
|
Horizontal and vertical adjustment to nudge text boxes by.
Useful for offsetting text from points, particularly on discrete scales.
Cannot be jointly specified with |
box.padding |
Unit vector of length four specifying the padding inside the text box. |
box.margin |
Unit vector of length four specifying the margin outside the text box. |
box.r |
Unit vector of length one specifying the radius of the box. |
width , height
|
Unit values specifying the width and height of
the text box (including margins!). If |
minwidth , maxwidth , minheight , maxheight
|
Unit values specifying
the minimum and maximum values for |
na.rm |
If |
show.legend |
logical. Should this layer be included in the legends?
|
inherit.aes |
If |
A ggplot2 layer that can be added to a plot created with
ggplot2::ggplot()
.
geom_textbox()
understands the following aesthetics (required
aesthetics are in bold; select aesthetics are annotated):
x
y
label
alpha
box.colour
Color of box outline. Overrides colour
.
box.size
Width of box outline.
colour
Default color of box text and box outline.
family
fontface
fill
Default fill color of box background.
group
halign
Horizontal alignment of text inside box.
hjust
Horizontal alignment of box.
lineheight
orientation
One of "upright"
, "left-rotated"
,
"right-rotated"
, "inverted"
.
size
Default font size of box text.
text.colour
Color of box text. Overrides colour
.
valign
Vertical alignment of text inside box.
vjust
Vertical alignment of box.
geom_richtext()
, element_textbox()
library(ggplot2) df <- data.frame( label = rep("Lorem ipsum dolor **sit amet,** consectetur adipiscing elit, sed do *eiusmod tempor incididunt* ut labore et dolore magna aliqua.", 2), x = c(0, .6), y = c(1, .6), hjust = c(0, 0), vjust = c(1, 0), orientation = c("upright", "right-rotated"), color = c("black", "blue"), fill = c("cornsilk", "white") ) ggplot(df) + aes( x, y, label = label, color = color, fill = fill, hjust = hjust, vjust = vjust, orientation = orientation ) + geom_textbox(width = unit(0.4, "npc")) + geom_point(color = "black", size = 2) + scale_discrete_identity(aesthetics = c("color", "fill", "orientation")) + xlim(0, 1) + ylim(0, 1)
library(ggplot2) df <- data.frame( label = rep("Lorem ipsum dolor **sit amet,** consectetur adipiscing elit, sed do *eiusmod tempor incididunt* ut labore et dolore magna aliqua.", 2), x = c(0, .6), y = c(1, .6), hjust = c(0, 0), vjust = c(1, 0), orientation = c("upright", "right-rotated"), color = c("black", "blue"), fill = c("cornsilk", "white") ) ggplot(df) + aes( x, y, label = label, color = color, fill = fill, hjust = hjust, vjust = vjust, orientation = orientation ) + geom_textbox(width = unit(0.4, "npc")) + geom_point(color = "black", size = 2) + scale_discrete_identity(aesthetics = c("color", "fill", "orientation")) + xlim(0, 1) + ylim(0, 1)
The ggtext package implements both geoms (geom_richtext()
, geom_textbox()
)
and theme elements (element_markdown()
, element_textbox()
) for improved
text rendering with ggplot2.