Data Visualization with R — Base Graphics

Aravind Hebbali

10 Text Annotations

10.1 Introduction

In this chapter, we will learn to add text annotations. There are occasions when you want to display additional information in a plot. This is usually achieved by adding text either inside the plot or on the margins. For example, you might want to label a line/bar or add formulas to better communicate what is shown in the plot. The idea is to use the available space within/outside the plot to provide additional information that can be useful to the end users. We will learn to add text inside as well as on the margins of the plot. This is accomplished using the following two functions:

text() : add text inside the plot
mtext() : add text on the margins of the plot

10.2 Syntax

Let us take a quick look at the syntax of both the functions:

text(x, y = NULL, labels = seq_along(x$x), adj = NULL,
     pos = NULL, offset = 0.5, vfont = NULL,
     cex = 1, col = NULL, font = NULL, ...)

mtext(text, side = 3, line = 0, outer = FALSE, at = NA,
      adj = NA, padj = NA, cex = NA, col = NA, font = NA, ...)

10.3 Text Inside the Plot

To add text inside a plot, the following arguments must be supplied to the text() function:

labels : the text to be displayed
x : x axis coordinate
y : y axis coordinate

Below is a simple example:

plot(mtcars$disp, mtcars$mpg)
text(x = 340, y = 30, labels = 'Sample Text')

The text appears at the coordinates (340, 30). Ensure that the text is enclosed in single/double quotes and the coordinates provided are within the range of the X and Y axis variables.

10.4 Color

The color of the text can be modified using the col argument in the text() function.

plot(mtcars$disp, mtcars$mpg)
text(x = 340, y = 30, labels = 'Sample Text', col = 'red')

The below plot depicts the appearance of the text for different values of the col argument:

10.5 Font

The font of the text can be modified using the font argument in the text() function.

plot(mtcars$disp, mtcars$mpg)
text(x = 340, y = 30, labels = 'Sample Text', col = 'red', font = 2)

The below plot depicts the appearance of the text for different values of the font argument:

10.6 Font Family

The font family of the text can be modified using the family argument in the text() function.

plot(mtcars$disp, mtcars$mpg)
text(x = 340, y = 30, labels = 'Sample Text', col = 'red', family = 'mono')

The below plot depicts the appearance of the text for different values of the family argument:

10.7 Font Size

The font size of the text can be modified using the cex argument in the text() function.

plot(mtcars$disp, mtcars$mpg)
text(x = 340, y = 30, labels = 'Sample Text', col = 'red', cex = 2)

The below plot depicts the appearance of the text for different values of the cex argument:

10.8 Text on the Margins

The mtext() function allows the user to place the text on the margins of the plot. It allows the user to modify the location of the text in multiple ways and we will explore them one by one. To begin with, let us add text to the plot using the mtext() function. The minimum input you need to provide is the text itself. Below is a simple example:

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text')

As you can see, the text is placed on the margin of the plot and not inside the plot. Next, we will specify the margin on which to place the text.

10.9 Specify Margin

Use the side argument to specify the margin on which you want to place the text. If takes values 1 to 4, each representing one side of the plot.

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text', side = 1)

The below plot displays the appearance of the text when differnt options for side argument are supplied:

10.10 Line

The line argument places the text at a specified distance from the margin. The default value is 0. As the value increases, the text is placed farther from the margin and outside the plot. As the value decreases, the text is placed inside the plot and farther from the margin. Below is an example where the text is placed outside the plot as the value is greater than 1.

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text', line = 1)

When the value is less than 0, the line argument places the text inside the plot.

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text', line = -1)

The below plot displays the appearance of the text when different values are supplied to the line argument:

10.11 Alignment

The adj argument is used for horizontal alignment of the text. It takes values between 0 and 1. If set to 0, the text will be left aligned and at 1, it will be right aligned. Below is an example where the text is left aligned as adj is set to 0.

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text', adj = 0)

When the value is set to 1, the text is right aligned.

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text', adj = 1)

The below plot displays the appearance of the text when different values are supplied to the adj argument:

10.12 Position

The pos argument of the text() function places the text relative to the specified coordinates without needing adj. It takes values 1 to 4, each representing a position around the point:

1: below
2: to the left
3: above
4: to the right

A grid of scatterplots of displacement against miles per gallon. In each panel the same single labelled point is annotated, but the label is placed in a different compass position relative to it, stepping through south-west, west, north-west, north and further around. — Figure 10.1: The pos argument placing text relative to a point

10.13 Offset

The offset argument of the text() function controls how far the text is placed from the coordinates when pos is used. The distance is measured in character widths and the default value is 0.5.

plot(mtcars$disp, mtcars$mpg)
text(x = 340, y = 30, labels = 'Sample Text', pos = 3, offset = 1.5)

A scatterplot of displacement against miles per gallon with one point labelled, where the label is displaced a fixed distance from the point rather than sitting on top of it. — Figure 10.2: The offset argument pushing a label away from its point

10.14 Perpendicular Adjustment

The padj argument of the mtext() function fine-tunes the placement of the text in the direction perpendicular to adj. It takes values between 0 and 1. Compare the two plots below and observe the nudge:

10.15 Outer Margin

By default, mtext() places text on the inner margin of the current plot. Set outer = TRUE to place the text on the outer margin of the whole figure region instead. This is useful with multi-panel layouts, but first reserve outer space with par(oma = ...):

init <- par(no.readonly = TRUE)
par(oma = c(0, 0, 3, 0))
plot(mtcars$disp, mtcars$mpg)
mtext('Outer Margin Text', outer = TRUE)

par(init)

10.16 Exact Position

The at argument of the mtext() function places the text at an exact position along the margin, expressed in the user coordinates of the corresponding axis. Below, the text is anchored at disp = 200 on the bottom margin instead of the default center:

plot(mtcars$disp, mtcars$mpg)
mtext('Sample Text', side = 1, at = 200)

A scatterplot of displacement against miles per gallon with text added to the margin at explicitly chosen positions along the axes, rather than at the default margin locations. — Figure 10.3: The at argument placing margin text at specific coordinates

--- description: "Base R text annotations: text() and mtext() with pos, offset, padj, outer and at, for labelling individual points and adding text to the margins." --- # Text Annotations {#textann} ## Introduction In this chapter, we will learn to add text annotations. There are occasions when you want to display additional information in a plot. This is usually achieved by adding text either inside the plot or on the margins. For example, you might want to label a line/bar or add formulas to better communicate what is shown in the plot. The idea is to use the available space within/outside the plot to provide additional information that can be useful to the end users. We will learn to add text inside as well as on the margins of the plot. This is accomplished using the following two functions: - `text()` : add text inside the plot - `mtext()` : add text on the margins of the plot ## Syntax Let us take a quick look at the syntax of both the functions: ```{r text-syntax, eval=FALSE} text(x, y = NULL, labels = seq_along(x$x), adj = NULL, pos = NULL, offset = 0.5, vfont = NULL, cex = 1, col = NULL, font = NULL, ...) mtext(text, side = 3, line = 0, outer = FALSE, at = NA, adj = NA, padj = NA, cex = NA, col = NA, font = NA, ...) ``` ## Text Inside the Plot To add text inside a plot, the following arguments must be supplied to the `text()` function: - `labels` : the text to be displayed - `x` : x axis coordinate - `y` : y axis coordinate Below is a simple example: ```{r text1, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text') ``` The text appears at the coordinates (340, 30). Ensure that the text is enclosed in single/double quotes and the coordinates provided are within the range of the **X** and **Y** axis variables. ## Color The color of the text can be modified using the `col` argument in the `text()` function. ```{r text2, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red') ``` The below plot depicts the appearance of the text for different values of the `col` argument: ```{r text3, fig.align='center', fig.width=15, fig.height=5, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(1, 3)) values <- c('red', 'blue', 'green') for (i in values) { plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = i) mtext(paste("col = ", i), side = 3, col = "blue") } par(init) ``` ## Font The font of the text can be modified using the `font` argument in the `text()` function. ```{r text4, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red', font = 2) ``` The below plot depicts the appearance of the text for different values of the `font` argument: ```{r text5, fig.align='center', fig.width=10, fig.height=10, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(2, 2)) values <- c(1, 2, 3, 4) for (i in values) { plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red', font = i) mtext(paste("font = ", i), side = 3, col = "blue") } par(init) ``` ## Font Family The font family of the text can be modified using the `family` argument in the `text()` function. ```{r text6, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red', family = 'mono') ``` The below plot depicts the appearance of the text for different values of the `family` argument: ```{r text7, fig.align='center', fig.width=15, fig.height=5, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(1, 3)) values <- c('mono', 'serif', 'sans') for (i in values) { plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red', cex = 1.5, family = i) mtext(paste("family = ", i), side = 3, col = "blue") } par(init) ``` ## Font Size The font size of the text can be modified using the `cex` argument in the `text()` function. ```{r text8, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red', cex = 2) ``` The below plot depicts the appearance of the text for different values of the `cex` argument: ```{r text9, fig.align='center', fig.width=15, fig.height=5, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(1, 3)) values <- c(0.5, 1, 1.5) for (i in values) { plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', col = 'red', cex = i) mtext(paste("cex = ", i), side = 3, col = "blue") } par(init) ``` ## Text on the Margins The `mtext()` function allows the user to place the text on the margins of the plot. It allows the user to modify the location of the text in multiple ways and we will explore them one by one. To begin with, let us add text to the plot using the `mtext()` function. The minimum input you need to provide is the text itself. Below is a simple example: ```{r mtext1, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) mtext('Sample Text') ``` As you can see, the text is placed on the margin of the plot and not inside the plot. Next, we will specify the margin on which to place the text. ## Specify Margin Use the `side` argument to specify the margin on which you want to place the text. If takes values 1 to 4, each representing one side of the plot. ```{r mtext2, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', side = 1) ``` The below plot displays the appearance of the text when differnt options for `side` argument are supplied: ```{r mtext3, fig.align='center', fig.width=10, fig.height=10, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(2, 2)) values <- c(1, 2, 3, 4) for (i in values) { plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', side = i) mtext(paste("side = ", i), side = 3, col = "blue", adj = 1) } par(init) ``` ## Line The `line` argument places the text at a specified distance from the margin. The default value is `0`. As the value increases, the text is placed farther from the margin and outside the plot. As the value decreases, the text is placed inside the plot and farther from the margin. Below is an example where the text is placed outside the plot as the value is greater than 1. ```{r mtext4, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', line = 1) ``` When the value is less than `0`, the line argument places the text inside the plot. ```{r mtext5, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', line = -1) ``` The below plot displays the appearance of the text when different values are supplied to the `line` argument: ```{r mtext6, fig.align='center', fig.width=15, fig.height=10, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(2, 3)) values <- c(-0.5, -1, -1.5, 0.5, 1, 1.5) for (i in values) { plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', line = i) mtext(paste("line = ", i), side = 3, col = "blue", adj = 1) } par(init) ``` ## Alignment The `adj` argument is used for horizontal alignment of the text. It takes values between 0 and 1. If set to `0`, the text will be left aligned and at `1`, it will be right aligned. Below is an example where the text is left aligned as `adj` is set to `0`. ```{r mtext7, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', adj = 0) ``` When the value is set to `1`, the text is right aligned. ```{r mtext8, fig.align='center', fig.width=5, fig.height=5} plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', adj = 1) ``` The below plot displays the appearance of the text when different values are supplied to the `adj` argument: ```{r mtext9, fig.align='center', fig.width=15, fig.height=10, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(2, 3)) values <- c(0, 0.2, 0.4, 0.6, 0.8, 1) for (i in values) { plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', adj = i) mtext(paste("adj = ", i), side = 3, col = "blue", line = -2) } par(init) ``` ## Position The `pos` argument of the `text()` function places the text relative to the specified coordinates without needing `adj`. It takes values 1 to 4, each representing a position around the point: - `1`: below - `2`: to the left - `3`: above - `4`: to the right ```{r, fig.align='center', fig.width=10, fig.height=10, echo=FALSE} #| label: fig-text-pos #| fig-cap: "The pos argument placing text relative to a point" #| fig-alt: "A grid of scatterplots of displacement against miles per gallon. In each panel the same single labelled point is annotated, but the label is placed in a different compass position relative to it, stepping through south-west, west, north-west, north and further around." init <- par(no.readonly = TRUE) par(mfrow = c(2, 2)) values <- c(1, 2, 3, 4) for (i in values) { plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', pos = i) mtext(paste("pos = ", i), side = 3, col = "blue") } par(init) ``` ## Offset The `offset` argument of the `text()` function controls how far the text is placed from the coordinates when `pos` is used. The distance is measured in character widths and the default value is `0.5`. ```{r, fig.align='center', fig.width=5, fig.height=5} #| label: fig-text-offset #| fig-cap: "The offset argument pushing a label away from its point" #| fig-alt: "A scatterplot of displacement against miles per gallon with one point labelled, where the label is displaced a fixed distance from the point rather than sitting on top of it." plot(mtcars$disp, mtcars$mpg) text(x = 340, y = 30, labels = 'Sample Text', pos = 3, offset = 1.5) ``` ## Perpendicular Adjustment The `padj` argument of the `mtext()` function fine-tunes the placement of the text in the direction perpendicular to `adj`. It takes values between 0 and 1. Compare the two plots below and observe the nudge: ```{r mtextpadj, fig.align='center', fig.width=10, fig.height=5, echo=FALSE} init <- par(no.readonly = TRUE) par(mfrow = c(1, 2)) values <- c(0, 1) for (i in values) { plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', side = 3, padj = i) mtext(paste("padj = ", i), side = 3, col = "blue", line = -2) } par(init) ``` ## Outer Margin By default, `mtext()` places text on the inner margin of the current plot. Set `outer = TRUE` to place the text on the outer margin of the whole figure region instead. This is useful with multi-panel layouts, but first reserve outer space with `par(oma = ...)`: ```{r mtextouter, fig.align='center', fig.width=5, fig.height=5} init <- par(no.readonly = TRUE) par(oma = c(0, 0, 3, 0)) plot(mtcars$disp, mtcars$mpg) mtext('Outer Margin Text', outer = TRUE) par(init) ``` ## Exact Position The `at` argument of the `mtext()` function places the text at an exact position along the margin, expressed in the user coordinates of the corresponding axis. Below, the text is anchored at `disp = 200` on the bottom margin instead of the default center: ```{r, fig.align='center', fig.width=5, fig.height=5} #| label: fig-mtext-at #| fig-cap: "The at argument placing margin text at specific coordinates" #| fig-alt: "A scatterplot of displacement against miles per gallon with text added to the margin at explicitly chosen positions along the axes, rather than at the default margin locations." plot(mtcars$disp, mtcars$mpg) mtext('Sample Text', side = 1, at = 200) ```