• Understand what an .Rmd file is for
• Render an RMarkdown file to HTML
• Recognise YAML, Markdown text, R chunks, and inline R code
• Add a figure, a table, citations, and references
• Use cross-references for figures and tables
• Start a guided individual exercise

We will keep all module work inside one RStudio Project.

In RStudio:

1. Click File > New Project.
2. Choose New Directory.
3. Choose New Project.
4. Name the folder PSYC40940.
5. Choose where to save it on your computer.
6. Click Create Project.

You only need to do this once for the module.

An RStudio Project is a folder-based workspace.

It helps because:

• the module has one clear home folder,
• data, scripts, reports, and outputs stay together,
• file paths are easier to manage,
• the whole analysis is easier to share or submit.

A good workflow is to create one project folder for this module and keep the files you are currently working on inside it. For Week 1, we will move the Week 1 practical files into the project folder.

Download the Week 1 materials.

1. Download psyc40940-week-01-introduction.zip from the Learning Room.
2. Extract/unzip the folder.
3. Open the extracted psyc40940-week-01-introduction folder.
4. Move the contents of that folder into your PSYC40940 project folder.
5. In RStudio, open the Week 1 .Rmd files from the project folder.

Do not work inside the zip file. The folder must be extracted first.

The Week 1 files should now be in your PSYC40940 project folder.

Because the Week 1 .Rmd files are in the same folder as data/, they load data with:

read_csv("data/blomkvist.csv")

If a file cannot be found, first check that data/ is inside your PSYC40940 project folder and that the .Rmd file is saved there too.

After moving the Week 1 files, your module project should contain:

PSYC40940/
  PSYC40940.Rproj
  01_rmarkdown_demo.Rmd
  02_rmarkdown_exercise.Rmd
  README.md
  references.bib
  apa.csl
  data/
    blomkvist.csv

The slide files are uploaded separately. The weekly zip contains the files you need for exercises and practical work.

In this module, you will make visualisations and dashboards from data.

RMarkdown helps because:

• the data, code, figures, tables, and written explanation stay connected
• figures can be regenerated when code or data change
• numbers in the text can be calculated by R
• citations and references can be handled automatically
• the final report can be checked and rerun

This is the practical side of reproducible reporting (Xie, 2017).

An .Rmd file combines:

• a YAML header with document settings
• Markdown text for headings and paragraphs
• R code chunks for code, tables, and figures
• inline R code for values inside sentences
• citation keys linked to a bibliography file

The important workflow is simple: edit the .Rmd, render it, inspect the HTML output, then fix anything that did not work.

Open 01_rmarkdown_demo.Rmd.

Before we go through the next slides, find these parts in the file:

• the YAML header at the top
• Markdown headings and ordinary text
• the setup chunk
• the chunk that loads packages
• the chunk that loads the data
• inline R code inside a sentence
• the chunk that creates a table
• the chunk that creates a figure
• a citation and the references section

Markdown is a simple way to format text using plain-text markers.

# Main heading

## Subheading

This is ordinary text.

This word is **bold** and this word is *italic*.

The markers tell RMarkdown which parts should become headings, paragraphs, bold text, or italic text.

R code chunks start and end with three backticks.

```{r load-data}
# Read the CSV file and store it in an object.
blomkvist <- read_csv("data/blomkvist.csv")
```

The chunk label, here load-data, should be short and unique.

Chunk options change how a chunk behaves in the rendered HTML.

```{r data-preview, echo=FALSE}
slice(blomkvist, 1:6)
```

The most useful option today is echo:

• echo=TRUE: run the code and show the code,
• echo=FALSE: run the code but hide the code,
• use echo=FALSE when the report should show the result but not the code.

During learning, echo=TRUE is useful because it shows what produced the output.

The setup chunk usually goes near the top of the document.

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  message = FALSE,
  warning = FALSE
)
```

Use it for options that should apply to the whole document.

Load packages before using their functions.

# tidyverse gives us read_csv(), select(), drop_na(), summarise(), and ggplot().
library(tidyverse)

# knitr gives us kable(), which creates simple tables.
library(knitr)

If rendering says there is no package called something, install it once in the Console with install.packages().

Do not leave install.packages() in a chunk that runs when the document renders. If you include it in an .Rmd file as a reminder, use eval=FALSE.

The file blomkvist.csv is stored inside the data folder.

This code reads the file and saves it as an R object:

blomkvist <- read_csv("data/blomkvist.csv")

Read the line from right to left:

• read_csv() reads a CSV file,
• "data/blomkvist.csv" tells R where the file is,
• <- assigns the result to a name,
• blomkvist is the object we can use later.

After this line has run, blomkvist should appear in the Environment pane.

Inline R code puts calculated values inside sentences.

In the .Rmd file, write:

The dataset contains `r nrow(blomkvist)` rows.

In the rendered HTML, this becomes:

The dataset contains 267 rows.

With 01_rmarkdown_demo.Rmd open in RStudio:

1. Click Knit.
2. Check that an .html file appears.
3. Open the HTML file.
4. Find the rendered table, figure, citations, and references.

Rendering runs the document from top to bottom in a clean order.

Start by reading the first useful error near the end of the render output.

• file not found: check the file path and folder structure
• there is no package called ...: install the package, then render again
• object not found: create the object before using it
• duplicate chunk label: make every chunk label unique
• citations missing: check the .bib file path and citation key

Write data preparation in small steps.

# Keep only the variables used in this report.
selected_data <- select(
  blomkvist,
  id,
  sex,
  age,
  smoker,
  rt_hand_d,
  rt_hand_nd
)

# Remove rows with missing reaction-time values.
plot_data <- drop_na(selected_data, rt_hand_d, rt_hand_nd)

Readable code is easier to debug than compact code.

A figure is created by an R chunk.

```{r scatter-plot, fig.cap="Reaction times for dominant and non-dominant hand responses."}
ggplot(plot_data, aes(x = rt_hand_d, y = rt_hand_nd, colour = smoker)) +
  geom_point(alpha = 0.75) +
  geom_smooth(method = "lm", se = FALSE) +
  theme_minimal()
```

The chunk label is used for cross-referencing.

With bookdown::html_document2, a labelled figure can be referenced in text.

Write this in the .Rmd file:

Figure \@ref(fig:scatter-plot) shows the relationship between the two reaction-time measures.

The fig: part tells RMarkdown that the reference points to a figure.

Use kable() for simple formatted tables.

summary_table <- summarise(
  plot_data,
  mean_rt = round(mean(rt_hand_d), 1),
  sd_rt = round(sd(rt_hand_d), 1),
  n = n(),
  .by = smoker
)

kable(
  summary_table,
  caption = "Dominant-hand reaction time by smoking status."
)

A table chunk can be referenced in text.

Write this in the .Rmd file:

Table \@ref(tab:summary-table) summarises reaction time by smoking status.

The tab: part tells RMarkdown that the reference points to a table.

Citations come from a .bib file.

The YAML header needs:

bibliography: references.bib
csl: apa.csl

Then cite with the citation key from references.bib:

The data come from a reaction-time study [@blomkvist2017reference].

Add a final heading called # References so the reference list appears.

You have already rendered 01_rmarkdown_demo.Rmd.

For the individual exercise:

1. Open 02_rmarkdown_exercise.Rmd.
2. Replace each ___ blank.
3. Render to HTML.
4. Fix one error at a time if rendering fails.
5. Check the HTML output against the render checklist.

By next week, you should be able to:

• open and render an .Rmd file
• keep data and references in the right folders
• load packages and data
• write short comments in code chunks
• create one figure and one table
• refer to figures and tables in text
• cite a source from a bibliography file
• use inline R for simple reported values

For support with RMarkdown, use:

• Andrews (2021), Chapter 7: reproducible reports with RMarkdown. Chapter link
• Wickham & Grolemund (2016), Chapter 27: R Markdown in R for Data Science. Chapter link

Use these as reference material while completing 02_rmarkdown_exercise.Rmd.