library(munch)
library(ggplot2)
library(flextable)
library(gdtools)
fset <- font_set_liberation()
set_theme(theme_minimal(base_family = "Liberation Sans", base_size = 11))This vignette covers formatting in ‘ggplot2’ theme elements and text annotations using ‘munch’.
element_md() replaces element_text() to
render markdown in titles, subtitles, captions, axis titles, axis tick
labels and legends.
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
labs(
title = "**Fuel Consumption** vs *Weight*",
subtitle = "Data from the `mtcars` dataset",
caption = "Source: *Motor Trend* (1974)"
) +
theme(
plot.title = element_md(size = 16),
plot.subtitle = element_md(size = 12, code_font_family = "Liberation Mono"),
plot.caption = element_md(size = 9)
)ggplot(mtcars, aes(hp, mpg)) +
geom_point() +
labs(
x = "Horsepower (*hp*)",
y = "Miles per gallon (**mpg**)"
) +
theme(
axis.title.x = element_md(),
axis.title.y = element_md()
)For advanced markdown rendering (images, spans, custom CSS), see also
marquee::element_marquee().
Titles, subtitles and captions wrap to the width of their column, and the plot keeps the space they need:
long_title <- paste(
"A **long title** that needs several lines, because it is wider",
"than the *panel* of the plot"
)
p <- ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
labs(title = long_title) +
theme(plot.title = element_md())
pWith ‘patchwork’, or with a fixed aspect ratio such as
coord_fixed(), this width is not known when the height of
the title is computed. The text may need more lines than the space kept
for it, and its first lines are cut. Set the maximum width of the text
with width, in inches:
The labels of axis ticks are markdown too: give them with the
labels of the scale. Each label is placed as
element_text() places it, with its angle and
justification.
species <- aggregate(Sepal.Length ~ Species, data = iris, FUN = mean)
ggplot(species, aes(Species, Sepal.Length)) +
geom_col(fill = "grey70") +
scale_x_discrete(
labels = c("*Iris setosa*", "*Iris versicolor*", "*Iris virginica*")
) +
theme(axis.text.x = element_md(angle = 30, hjust = 1))This works for all labels that ‘ggplot2’ draws as a set: axis ticks,
labels of colour bars, polar axes. element_chunks() can not
be used there: it draws one fixed text.
legend.text and legend.title accept
element_md(), for keys as for colour bars:
ggplot(mtcars, aes(wt, mpg, colour = hp)) +
geom_point() +
labs(colour = "**Power**") +
scale_colour_continuous(labels = function(x) paste0("**", x, "** hp")) +
theme(
legend.title = element_md(),
legend.text = element_md()
)Legend labels do not wrap, as with element_text(): a
long label is written on one line. Write a line break in the label (two
spaces then \n, or a backslash then \n) to put
it on several lines:
cyl_labels <- c(
"**4** cylinders",
"**6** cylinders",
"**8** cylinders \n*the most powerful*"
)
p <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
geom_point() +
scale_colour_discrete(labels = cyl_labels) +
theme(legend.text = element_md())
pThe keys are then unevenly spaced. This comes from ‘ggplot2’, with
element_text() too: a row of the legend has the height of
its key (legend.key.size) or of its label, whichever is
larger. A label on one line is lower than the key and is centred in the
row; a label on two lines is higher and fills its row. For even spacing,
make the keys lower than a label, so that each row has the height of its
label, and set the space between rows:
Set element_md() on the root element text
to render all texts of the plot as markdown: titles, axes, legends and
strips.
ggplot(mtcars, aes(wt, mpg, colour = factor(am))) +
geom_point() +
facet_wrap(~ paste0("**", cyl, "** cylinders")) +
labs(
title = "*Weight* and **consumption**",
x = "Weight (*1000 lbs*)",
y = "Miles per gallon",
colour = "*Transmission*"
) +
scale_colour_discrete(labels = c("**automatic**", "**manual**")) +
theme(text = element_md())element_chunks() uses ‘flextable’ formatting functions
(as_paragraph(), as_chunk(), etc.) to build
rich text with superscripts, subscripts, colors, and highlighting,
features that markdown does not support.
Build text by combining chunks inside
as_paragraph():
| Function | Description | Example |
|---|---|---|
as_chunk() |
Plain text | as_chunk("text") |
as_b() |
Bold | as_b("bold") |
as_i() |
Italic | as_i("italic") |
as_sup() |
Superscript | as_sup("2") |
as_sub() |
Subscript | as_sub("2") |
colorize() |
Colored text | colorize(as_chunk("red"), color = "red") |
as_highlight() |
Highlighted | as_highlight(as_chunk("text"), color = "yellow") |
chunks <- as_paragraph(
as_b("Bold"), as_chunk(", "),
as_i("italic"), as_chunk(", "),
as_chunk("x"), as_sup("2"), as_chunk(", "),
as_chunk("H"), as_sub("2"), as_chunk("O")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
theme(plot.title = element_chunks(chunks))Superscripts and subscripts are essential for scientific text.
element_chunks() makes them straightforward:
title_chunks <- as_paragraph(
as_chunk("Analysis: "),
as_b("R"), as_sup("2"),
as_chunk(" = 0.87, "),
as_i("p"), as_chunk(" < 0.001")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
geom_smooth(method = "lm", se = FALSE) +
theme(plot.title = element_chunks(title_chunks))Chemical formulas:
subtitle_chunks <- as_paragraph(
as_chunk("Concentration of "),
as_b("H"), as_sub("2"),
as_b("SO"), as_sub("4"),
as_chunk(" in solution")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
theme(plot.subtitle = element_chunks(subtitle_chunks))Units with exponents:
caption_chunks <- as_paragraph(
as_chunk("Units: mol\u00B7L"), as_sup("-1"),
as_chunk(" | Speed: m\u00B7s"), as_sup("-2")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
theme(plot.caption = element_chunks(caption_chunks))colorize() and as_highlight() add color and
background highlighting:
title_chunks <- as_paragraph(
as_chunk("Results: "),
colorize(as_chunk("significant"), color = "#E63946"),
as_chunk(" difference")
)
subtitle_chunks <- as_paragraph(
as_chunk("Compare "),
as_highlight(as_chunk(" Group A "), color = "yellow"),
as_chunk(" vs "),
as_highlight(as_chunk(" Group B "), color = "cyan")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
theme(
plot.title = element_chunks(title_chunks),
plot.subtitle = element_chunks(subtitle_chunks)
)as_image() embeds images inside
element_chunks(). This is useful for logos or icons in
titles:
r_logo <- file.path(R.home("doc"), "html", "logo.jpg")
title_chunks <- as_paragraph(
as_image(src = r_logo, width = 0.25, height = 0.2),
as_chunk(" "),
as_b("R Project"),
as_chunk(" - fuel consumption data")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
theme(plot.title = element_chunks(title_chunks))element_chunks() accepts the same layout parameters as
element_md():
| Parameter | Description |
|---|---|
hjust |
Horizontal justification (0-1) |
vjust |
Vertical justification (0-1) |
angle |
Text rotation angle |
lineheight |
Line height multiplier |
margin |
Margins around text |
width |
Maximum width of the text, in inches |
chunks <- as_paragraph(
as_chunk("Centered: R"), as_sup("2"),
as_chunk(" = 0.75")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
theme(plot.title = element_chunks(chunks, hjust = 0.5))geom_text_md() and geom_label_md() render
markdown-formatted labels directly on the plot, similar to
geom_text() and geom_label().
annotations <- data.frame(
x = c(15, 25, 30),
y = c(4, 3, 2),
label = c("**Group A**", "*Group B*", "`Group C`")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point(alpha = 0.5) +
geom_text_md(
data = annotations,
aes(x = x, y = y, label = label),
size = 4,
code_font_family = "Liberation Mono"
)geom_label_md() adds a background rectangle for better
readability:
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
geom_smooth(method = "lm", se = FALSE) +
geom_label_md(
label = "**R\u00B2 = 0.75**\n\n*p < 0.001*",
x = 28, y = 5,
hjust = 0, vjust = 1,
fill = "white",
label.padding = unit(0.5, "lines")
)geom_text_md() and geom_label_md() support
the width parameter (in inches) for automatic line
wrapping:
df <- data.frame(
x = c(15, 30),
y = c(4, 2.5),
label = c(
"This is a **long annotation** that will be *wrapped* automatically when it exceeds the specified `width`.",
"A shorter **note**."
)
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point(alpha = 0.3) +
geom_text_md(
data = df,
aes(x = x, y = y, label = label),
width = 2, hjust = 0, size = 3.5,
code_font_family = "Liberation Mono"
)Use markdown image syntax  to embed images in
geom_label_md():
r_logo <- file.path(R.home("doc"), "html", "logo.jpg")
df <- data.frame(
x = 20, y = 4,
label = sprintf("Built with  and **ggplot2**", r_logo)
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
geom_label_md(
data = df,
aes(x = x, y = y, label = label),
fill = "white",
label.padding = unit(0.5, "lines")
)‘munch’ measures text with ‘gdtools’, from the font file: the advance
widths of the glyphs and the kerning stored in the font, the adjustment
of the space between some pairs of letters such as “AV”, “To” or “WA”.
Devices such as ‘ragg’, ‘svglite’ or ‘ggiraph’ apply the same kerning
when they draw the text, so words are drawn with the width measured, and
right-aligned lines (hjust = 1) end at the right edge.
Ligatures and other substitutions of glyphs made by some fonts are not measured: a word using them can be drawn slightly narrower than measured.
The default png() device of macOS (Quartz) does not
kern: words such as “AVATAR” are drawn wider than measured (up to about
7%), and can touch the next word. The Cairo devices
cairo_pdf() and png(type = "cairo") do not
kern on Windows either, where R draws their text without the library
‘Pango’. Use ‘ragg’ instead.
| Feature | element_md() |
element_chunks() |
geom_*_md() |
|---|---|---|---|
| Bold / Italic | **text** / *text* |
as_b() / as_i() |
**text** / *text* |
| Inline code | `text` |
x | `text` |
| Superscript | x^2^ |
as_sup() |
x^2^ |
| Subscript | H~2~O |
as_sub() |
H~2~O |
| Colors | x | colorize() |
x |
| Highlighting | x | as_highlight() |
x |
| Use case | Theme elements | Theme elements | Text annotations |
element_md(), simple markdown in theme
elements (titles, captions, axes).element_chunks(), rich formatting with
superscripts, subscripts, colors. Uses the same vocabulary as
‘flextable’, making it easy to reuse patterns across plots and
tables.geom_text_md() /
geom_label_md(), markdown annotations placed at
specific coordinates on the plot.