09-text-annotations.Rmd

# Text Annotations {#textann}

## Introduction

In this chapter, we will learn to add text annotations. There are occassions 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")
}
```

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

## 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-serif')
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")
}
```

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

## 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 beign 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)
}
```

## 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 a 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)
}
```

## 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 a 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)
}
```