1 Introduction

So far, you have learned how to make plots and do basic manipulations in RStudio. But how do we export the plots created and the numbers crunched? The first idea might be to do this manually i.e. we copy the numbers from the console output to a Google document, and save the plot as an image on the computer and paste it in the same document.

But there are problems with this approach. If your code changes because you are modifying your analysis, you will have to update the results manually. Likewise if the data is updated from time to time, or if a different data set is used. There must be a better way than manually doing everything every time.

If there’s a way that allows us to create a document from the code, make the plots directly from the code, with the changes updated accordingly whenever our code changes, that would be perfect. Good news is that this approach exists and has been perfected over the years.

During the practical, you will learn about R Markdown, which is best explained by live demonstration. This document is a useful guide after you have learned the basics of working with R Markdown. It shows you how to control the behaviour of R code chunks in R Markdown documents. Understanding chunk options is essential for creating professional reports where you need precise control over what code, output, and figures are displayed. Don’t worry if you don’t understand anything described so far – come back to it after the practical to gauge your understanding.

Important: You need to write your first assignment in this approach.

1.1 Enabling PDF output (one-off setup)

To generate PDF documents from R Markdown, you need a LaTeX distribution installed on your computer. The easiest way to do this is to use the tinytex package, which installs a lightweight TeX distribution:

# Run these commands ONCE in your R console (not in an Rmd file)
install.packages("tinytex")
tinytex::install_tinytex()

This is a one-off operation — you only need to do it once per computer. After installation, R Markdown will automatically use this distribution to compile PDF documents. If you only need HTML output, you can skip this step.

2 R Markdown basics

An R Markdown file (.Rmd) combines:

  1. YAML header: Document metadata (title, author, output format)
  2. Markdown text: Narrative content with formatting
  3. Code chunks: R code that gets executed

Code chunks are delimited by triple backticks with {r}:

```{r}
# Your R code here
x <- 1:10
mean(x)
```

3 Chunk options

Chunk options control how each code chunk behaves. They are specified inside the curly braces after r:

```{r chunk-name}
#| echo: FALSE
#| fig.width: 8
# Code here
```

Here are the most frequently used chunk options:

Option Default Effect
echo TRUE Show the R code in output
eval TRUE Run the code
include TRUE Include chunk output in document
message TRUE Show messages from code
warning TRUE Show warnings from code
error FALSE Continue even if code errors
results "markup" How to display text results
fig.cap NULL Figure caption
fig.align "left" Alignment of figure; "center" recommended
fig.width 7 Figure width in inches
fig.height 7 Figure height in inches
out.width NULL Output width (e.g., "80%")

3.1 General options for code & results

Hide the code: Use echo: FALSE to hide the code but show the output. This is useful for reports where readers care about results, not code:

```{r}
#| echo: FALSE
plot(1:10)
```

Hide the output: Use results: 'hide' to run code but hide text output:

```{r}
#| results: 'hide'
summary(mtcars)  # Runs but output not shown
```

For figures, use fig.show: 'hide':

```{r}
#| fig.show: 'hide'
plot(1:10)  # Runs but figure not shown
```

Running code silently: Use include: FALSE to run code without showing anything (code, output, or messages). This is useful for setup chunks:

```{r setup}
#| include: FALSE
library(here)
```

Suppressing messages and warnings: When loading packages, you often get messages. Suppress them with message: FALSE and warning: FALSE:

```{r}
#| message: FALSE
#| warning: FALSE
library(MASS)
```

3.2 Figure options

Control figure size with fig.width, fig.height, and out.width:

```{r}
#| fig.width: 6
#| fig.height: 4
#| out.width: "70%"
plot(mtcars$wt, mtcars$mpg, xlab = "Weight", ylab = "MPG")
```

Add captions with fig.cap:

```{r}
#| fig.cap: "Scatterplot of weight vs fuel efficiency."
plot(mtcars$wt, mtcars$mpg, xlab = "Weight", ylab = "MPG")
```

3.3 Naming chunks

Give chunks descriptive names for easier navigation and debugging:

```{r scatter-weight-mpg}
#| fig.cap: "Weight vs MPG."
plot(mtcars$wt, mtcars$mpg, xlab = "Weight", ylab = "MPG")
```

Chunk names must be unique within a document and should not contain spaces.

4 Examples

4.1 Example 1: Setup chunk

A typical setup chunk loads packages and sets global options:

```{r setup}
#| include: FALSE
knitr::opts_chunk$set(
  echo = TRUE,
  fig.width = 6,
  fig.height = 4
)
```

4.2 Example 2: Analysis with hidden code

Show only results to a non-technical audience:

```{r analysis}
#| echo: FALSE
#| message: FALSE
# Data preparation
mean_mpg <- aggregate(mpg ~ cyl, data = mtcars, FUN = mean)

# Display table
knitr::kable(mean_mpg, caption = "Mean MPG by cylinder count")
```

4.3 Example 3: Figure with caption

Create a figure with proper caption and size:

```{r mpg-histogram}
#| echo: FALSE
#| fig.cap: "Distribution of fuel efficiency."
#| fig.width: 5
#| fig.height: 3
#| out.width: "60%"
hist(mtcars$mpg, breaks = seq(10, 34, by = 2), col = "steelblue",
     main = "", xlab = "Miles per Gallon", ylab = "Count")
```

5 Summary

5.1 The R Markdown workflow

Working with R Markdown in RStudio follows an iterative cycle:

  1. Create a new document: Click File > New File > R Markdown…, choose your output format (HTML, PDF, or Word), and give it a title.

  2. Edit the document: Write your narrative text using Markdown formatting, and add R code chunks to perform calculations and create visualisations.

  3. Knit the document: Click the Knit button (or press Ctrl+Shift+K / Cmd+Shift+K). The first time you knit, you will be prompted to save the .Rmd file.

  4. Examine the output: Review the generated document (HTML, PDF, or Word) to check that everything appears as intended.

  5. Iterate: Return to step 2 to refine your text, code, or chunk options, then knit again. Repeat until you are satisfied with the result.

This cycle of edit-knit-examine is the core of reproducible report writing. Each time you knit, R Markdown re-runs all your code, ensuring that your output always reflects your current code and data.

5.2 Chunk options quick reference

Goal Chunk options
Hide code, show output echo: FALSE
Run code, hide everything include: FALSE
Show code, hide output results: 'hide'
Suppress package messages message: FALSE
Suppress warnings warning: FALSE
Set figure size fig.width, fig.height
Set output width out.width: "70%"
Add figure caption fig.cap: "..."

A note on the #| syntax: The #| prefix is special—it is treated by R as a comment (so R ignores it), but R Markdown recognises it as a chunk option. This means lines starting with #| will not be executed as R code, but will instead control the chunk’s behaviour. This syntax is compatible with both R Markdown and Quarto, and is the recommended way to specify chunk options.

6 Exercises

In this practical, you will create plots in an R Markdown document and use chunk options to make them look professional. The focus is on learning how different chunk options affect the appearance of your output.

6.1 General settings

  1. Create a new R Markdown document in RStudio:

    • Go to File > New File > R Markdown…
    • Choose “Document” and “pdf” output
    • Save it as practical02_exercises.Rmd

    The setup chunk at the top can be left as is, or you can add any packages or settings you need later:

    ```{r setup}
#| include: FALSE
knitr::opts_chunk$set(echo = TRUE)
```

Analysis of mtcars dataset

  1. Create a histogram of mtcars$mpg (miles per gallon) using base R’s hist() function. First, create the plot without any chunk options (just the default {r}). Knit the document and observe the output.

    hist(mtcars$mpg, col = "steelblue",
     main = "Distribution of Fuel Efficiency",
     xlab = "Miles per Gallon", ylab = "Frequency")

    Now improve the same plot by adding chunk options:

    • Hide the code using #| echo: false
    • Add a figure caption using #| fig.cap: "Distribution of fuel efficiency."
    • Set the figure width to 5 inches using #| fig.width: 5
    • Set the output width to 70% using #| out.width: "70%"

    Knit the document again. How does the output differ?

    Distribution of fuel efficiency.

    Figure 6.1: Distribution of fuel efficiency.

    Answer: Hiding the code makes it professional when it is not needed in the actual output. The plot takes less space but the axis labels are kept pretty much the same size. The figure caption saves the need of including it in the plot.

  2. Create a scatterplot of mtcars$mpg (\(y\)-axis) vs mtcars$wt (\(x\)-axis). Configure the chunk with:

    • #| echo: false to hide the code
    • #| fig.cap: "Fuel efficiency decreases with vehicle weight."

    In the first chunk, set #| fig.width: 4. In the second chunk, set #| fig.width: 8 but also #| out.width: "50%". Compare the results:

    • Which has larger text relative to the plot area?
    • Which has a higher resolution appearance?

    Answer: fig.width controls the actual size when the figure is created. A smaller fig.width means text and points appear larger relative to the plot area. out.width controls how much space the figure takes in the document. A fig.width of 8 with out.width of 50% creates a high-resolution figure that is then scaled down, resulting in crisp text. For professional reports, using a larger fig.width with a smaller out.width often produces better quality output. A rule of thumb is to set out.width between 50% and 80%, then adjust fig.width so that the font size of the plot is similar to that of normal text.

  3. Create a boxplot of mtcars$mpg grouped by mtcars$cyl (number of cylinders). Experiment with different fig.width values (try between 5 and 9). Which width works best for showing all the category labels clearly?

    Answer: A width of 6 works well for this plot because it gives enough space for all category labels to be readable without being too spread out.

    Fuel efficiency by number of cylinders.

    Figure 6.2: Fuel efficiency by number of cylinders.

Analysis of airquality dataset

  1. Using the airquality dataset (built into R), create a line plot showing Temp (temperature) over the observation number. Configure the chunk with appropriate options for a professional report.

    Answer: Your plot should look similar to the Figure below:

    Temperature in New York from May to September 1973.

    Figure 6.3: Temperature in New York from May to September 1973.

Analysis of penguins dataset

  1. Using the penguins dataset, create a short analysis using the following plots:
    • scatterplot of body_mass (\(y\)-axis) vs flipper_len (\(x\)-axis)
    • A histogram of bill_len
    • A boxplot of bill_len by species
    • A scatterplot of bill_len vs bill_dep
    For each plot, configure the chunk to:
    • Hide the code (echo: false)
    • Add an informative figure caption
    • Use appropriate figure dimensions
    • Suppress any warning messages (hint: there are missing values)
    • Add a sentence or two of interpretation after each plot
    Answer: This is left as an exercise. Some points observed: the bill length ranges from about 32 to 60 mm; The distribution appears bimodal, suggesting differences between species.