---
title: "Using munch with ggplot2"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using munch with ggplot2}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
# R CMD check runs this code without knitr: pdf() can not draw Liberation Sans
if (!isTRUE(getOption("knitr.in.progress"))) ragg::agg_capture()
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  dev = "ragg_png",
  dpi = 300,
  out.width = "100%",
  fig.width = 6,
  fig.height = 4
)
```

```{r setup, message=FALSE}
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'.

## Simple markdown with element_md()

`element_md()` replaces `element_text()` to render markdown in titles,
subtitles, captions, axis titles, axis tick labels and legends.

```{r md-titles, message=FALSE}
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)
  )
```

```{r md-axes}
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()`.

### Long titles

Titles, subtitles and captions wrap to the width of their column, and the plot
keeps the space they need:

```{r long-title, message=FALSE, fig.height=3}
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())
p
```

With '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:

```{r long-title-patchwork, message=FALSE, fig.height=3}
library(patchwork)

p <- p + theme(plot.title = element_md(width = 2.5))
p | p
```

### Axis tick labels

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.

```{r md-ticks, message=FALSE, fig.height=3}
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.

### Legends

`legend.text` and `legend.title` accept `element_md()`, for keys as for
colour bars:

```{r md-legend, message=FALSE, fig.height=3}
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:

```{r md-legend-lines, message=FALSE, fig.height=3}
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())
p
```

The 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:

```{r md-legend-spacing, message=FALSE, fig.height=3}
p + theme(
  legend.key.height = unit(0.5, "lines"),
  legend.key.spacing.y = unit(4, "pt")
)
```

### All texts of a plot

Set `element_md()` on the root element `text` to render all texts of the plot
as markdown: titles, axes, legends and strips.

```{r md-all, message=FALSE, fig.height=3}
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())
```

## Advanced formatting with element_chunks()

`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.

### The as_paragraph() vocabulary

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")` |

```{r chunks-overview, message=FALSE}
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))
```

### Scientific notation

Superscripts and subscripts are essential for scientific text.
`element_chunks()` makes them straightforward:

```{r stats-chunks, message=FALSE}
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:

```{r chemical-chunks, message=FALSE}
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:

```{r units-chunks, message=FALSE}
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))
```

### Colors and highlighting

`colorize()` and `as_highlight()` add color and background highlighting:

```{r color-chunks, message=FALSE}
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)
  )
```

### Images in theme elements

`as_image()` embeds images inside `element_chunks()`. This is useful for
logos or icons in titles:

```{r chunks-image, message=FALSE}
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))
```

### Layout parameters

`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 |

```{r layout-chunks, message=FALSE}
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))
```

## Text annotations with geom_text_md() and geom_label_md()

`geom_text_md()` and `geom_label_md()` render markdown-formatted labels
directly on the plot, similar to `geom_text()` and `geom_label()`.

```{r geom-text-basic, message=FALSE}
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:

```{r geom-label-example, message=FALSE}
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")
  )
```

### Text wrapping

`geom_text_md()` and `geom_label_md()` support the `width` parameter
(in inches) for automatic line wrapping:

```{r geom-text-wrap, message=FALSE, fig.height=3}
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"
  )
```

### Images in labels

Use markdown image syntax `![](path)` to embed images in `geom_label_md()`:

```{r geom-label-image, message=FALSE, fig.height=3}
r_logo <- file.path(R.home("doc"), "html", "logo.jpg")

df <- data.frame(
  x = 20, y = 4,
  label = sprintf("Built with ![](%s) 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")
  )
```

## Alignment accuracy

'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.

## Choosing the right approach

| 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.
