R Markdown Workshop

Learning objectives

Figure sizes
Figure captions
Inserting images

library(tidyverse)

knitr::opts_chunk$set(
  fig.path   ='figure/',
  fig.align  ='center',
  fig.retina = 2
)

There is a data set called cars that is loaded into R. You can have a look at the data set by typing cars into R.

cars

##    speed dist
## 1      4    2
## 2      4   10
## 3      7    4
## 4      7   22
## 5      8   16
## 6      9   10
## 7     10   18
## 8     10   26
## 9     10   34
## 10    11   17
## 11    11   28
## 12    12   14
## 13    12   20
## 14    12   24
## 15    12   28
## 16    13   26
## 17    13   34
## 18    13   34
## 19    13   46
## 20    14   26
## 21    14   36
## 22    14   60
## 23    14   80
## 24    15   20
## 25    15   26
## 26    15   54
## 27    16   32
## 28    16   40
## 29    17   32
## 30    17   40
## 31    17   50
## 32    18   42
## 33    18   56
## 34    18   76
## 35    18   84
## 36    19   36
## 37    19   46
## 38    19   68
## 39    20   32
## 40    20   48
## 41    20   52
## 42    20   56
## 43    20   64
## 44    22   66
## 45    23   54
## 46    24   70
## 47    24   92
## 48    24   93
## 49    24  120
## 50    25   85

I can get a scatter plot of the speed vs dist using ggplot2 (which was loaded with tidyverse):

ggplot(cars, aes(dist, speed)) + 
  geom_point()

Figure sizes

By default the figure width is 7 inches and figure width is 5 inches for html_document output. You can change this to say 1 inch by setting the chunk options fig.height = 1, fig.width = 1. The values for fig.height and fig.width are required to be both numeric (measured in inches).

ggplot(cars, aes(dist, speed)) + 
  geom_point()

Another way to scale your image is using out.width and out.height. These two options can only take character as values and this may depend on the output format. E.g. you can use ".8\\linewidth"for pdf output (\linewidth is a LaTeX command) or "300px" for html output. You may also use percentage which scales appropriately for both html and pdf outputs. Below figure we use out.width = "60%", out.height = "60%".

ggplot(cars, aes(dist, speed)) + 
  geom_point()

We can use fig.width and fig.height with out.width and out.height. Below we have fig.width = 3, fig.height = 3, out.width = "60%", out.height = "60%".

ggplot(cars, aes(dist, speed)) + 
  geom_point()

Getting the figure to “look” right usually requires playing around with these options.

❓ What happens if your code chunk generates multiple figures?

Figure alignment

You may have noticed but in the global chunk I have set fig.align = "center" so that the figures will be centered as default.

The other valid values are default (no alignment), left and right. Below figure has fig.align = "left".

ggplot(cars, aes(dist, speed)) + 
  geom_point()

🔧 Try changing the above figure so that the alignment is on the right instead.

Figure caption

You can include a figure caption by using the chunk option fig.cap.

ggplot(cars, aes(dist, speed)) + 
  geom_point()

This is a boring scatter plot

Chunk options must be written in one line. This means that you cannot add a line break. This can make the line awkwardly long when you need to write a long caption.

Remember that chunk option values accept valid R expressions. As one work around, you can define a string variable, say cap, that contains the long caption as an inline R command. Then you can set option as fig.cap = cap. This is how the below caption was generated. Study the Rmd source code for how the caption was generated.

ggplot(cars, aes(dist, speed)) + 
  geom_point()

This is some really long text that may be hard to fit within the chunk option.

If using bookdown output formats then there is another way to deal with these long captions as described in the bookdown book. We’ll come back to this later.

Exporting the figures

If you want to save the figures that you created from your code, these can be saved by setting fig.path. Globally we have set fig.path = "figures/" so you can find all figures generated in the folder figures already.

❓ Do you notice something about the figure names in the figure folder? Don’t fret if you don’t. We’ll come back to this point later.

Inserting images

To insert images in markdown, you can use ![](/path/to/your/image). The following logo is inserted using markdown syntax:

However to apply captions and images resizing as before, you want to insert the image via a chunk using knitr::include_graphics() as below.

knitr::include_graphics("images/rlogo.svg")

The logo of statistical software R

Plot & image customisation takes a number of tries to get it to look right. The huge advantage of R Markdown is that if you want to change the look of an image generated by code, this is easy - only requires some parameter change and knit again.

In the past, I had to

go to the script (which was separate to the document) that generated the figures;
change the parameter there;
generate the figures;
go back to document; and
compile the document.

Now I

go to my document;
change parameter setting; and
compile the document.

While it seems a small thing, there’s friction in my workflow. It’s worth investing to make your workflow smoother even if it takes time to learn initially. In the long term, you have more time on more important matters.