• Open the supplied RStudio project
• Understand why reproducible reports matter
• See how Markdown and R code work together
• Knit a tiny APA-style RMarkdown report
• Find key parts of a worked report
• Complete a guided RMarkdown exercise
• Transfer the same principles to another dataset
• Know what PDF knitting needs

For this workshop:

1. Download psyc30815-statistics-3.zip from the NOW learning room.
2. Extract/unzip the folder.
3. Open the extracted psyc30815-statistics-3 folder.
4. Double-click psyc30815-statistics-3.Rproj.
5. Work from inside the project that opens in RStudio.

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

An RStudio Project is a folder-based workspace.

It helps because:

• the analysis has one clear home folder
• R opens in the correct working directory
• data, reports, references, and outputs stay together
• file paths start from the project folder

Today we use the project folder that you downloaded from NOW. You do not need to create a new project in class.

With the project open, paths from the project folder look like this:

read_csv("data/my-data.csv")

Without the project open, R may look in the wrong folder.

Check where R is looking:

getwd()
file.exists("data/my-data.csv")

If file.exists() returns FALSE, check that the project is open and the file is inside the data/ folder.

The workshop files use relative file locations, so the data loading code depends on where the RMarkdown file is saved.

The psyc30815-statistics-3 project contains:

psyc30815-statistics-3/
  psyc30815-statistics-3.Rproj
  part-2-tiny-rmarkdown-example.Rmd
  part-2-rmarkdown-worked-blomkvist.Rmd
  part-2-chinese-ldt-transfer.Rmd
  data/
    blomkvist.csv
    chinese_ldt.csv
  references.bib
  apa.csl

The .Rmd files expect the data and reference files to stay in this folder.

For a future independent analysis, the usual route is:

• File > New Project
• choose New Directory or Existing Directory
• create or choose one folder for the analysis
• put raw data in data/
• keep the .Rmd, references.bib, and apa.csl in the project
• reopen the project by double-clicking the .Rproj file

For today, use the project folder supplied on NOW.

Psychology has had serious problems with results that are difficult to reproduce. In the Open Science Collaboration replication project (Open Science Collaboration, 2015):

• 100 published psychology studies were selected for replication
• 97% of the original studies reported statistically significant findings
• 36% of the replications produced statistically significant findings
• replication effects were, on average, much smaller than the original effects
• reproducibility was especially low for social psychology studies, around a quarter of replications

What does this mean for us as Psychologists?

For a statistical report, reproducibility means that another person can see which data were used, how variables were created, which analyses were run, and how tables, figures, and reported values were produced.

This matters because copy-pasting numbers from R into Word is easy to get wrong.

RMarkdown files usually have the file extension .Rmd.

They are different from R scripts, which usually have the file extension .R.

An .Rmd file combines:

• Markdown text for writing the report
• R code chunks for analysis
• inline R code for values inside sentences
• citation information from a bibliography file
• instructions for rendering to PDF, HTML, or Word

So an .Rmd file is not just an R script, but it can contain and run R code.

The idea comes from literate programming: text and code are linked in one document (Knuth, 1984; Xie, 2017).

RMarkdown helps you produce a report where:

• the analysis and report are in the same place
• code is connected to the table, figure, or value it produces
• citations and references can be generated automatically
• the report can be re-run after correcting data or code
• the submitted work can be checked for reproducibility

This is also why the formative assessment asks for the .Rmd, PDF, project file, data, and supporting files.

In an .Rmd file, look for these visual clues:

• YAML header: starts and ends with --- at the top of the file
• Markdown headings: lines that start with #, ##, or ###
• R chunks: code between three backticks, starting with ```{r chunk-label}
• chunk labels: short names after {r, for example {r load-data}
• chunk options: settings inside the chunk header, for example echo=FALSE
• inline R: short code inside text, starting with `r
• citations: citation keys starting with @, for example @blomkvist2017reference
• references section: a final section called ## References

Open part-2-tiny-rmarkdown-example.Rmd.

Working with the person next to you, find and mark these parts:

• the YAML header and the line that asks for PDF output
• the setup chunk and one chunk option inside it
• one sentence that is ordinary Markdown text
• one sentence that contains inline R code
• the chunk that creates the table
• the chunk that creates the figure
• one citation and the ## References section

We will then use this same file to explain the basic parts and knit your first PDF.

To knit the workshop reports to PDF, your computer needs:

• R and RStudio
• an extracted project folder, not a file still inside a zip archive
• the workshop .Rproj file opened in RStudio
• R packages used by the report
• a LaTeX installation for PDF output
• the local data, references.bib, and apa.csl files

Pandoc is usually bundled with RStudio.

The workshop files use these packages:

install.packages(c("rmarkdown", "bookdown", "knitr",
                   "kableExtra", "tinytex"))

You only need to install packages once on a computer.

If a package installation fails, copy the first error message and ask for help. Common causes are old R versions, blocked downloads, or trying to install into a folder without permission.

PDF knitting from RMarkdown needs a LaTeX system.

TinyTeX is usually the easiest option from R:

library(tinytex)
install_tinytex()

This can take time and needs an internet connection.

If TinyTeX installation is blocked on a managed computer, that is a setup problem to solve with support. It is not a statistics problem.

Do not spend the whole session silently fighting setup.

• tell us what the first useful error says
• keep working inside the RStudio project
• use the Knit button in RStudio
• if PDF output fails, we may temporarily switch the YAML output to HTML to check whether the R code runs
• return to PDF once TinyTeX/LaTeX is fixed

For the assessment workflow, the target output is still PDF. HTML is just a troubleshooting step.

Use echo to control whether code is visible.

Use eval to control whether code is run.

Example chunk headers:

• {r setup, echo=FALSE} uses label setup and hides setup code
• {r example-code, echo=TRUE, eval=FALSE} uses label example-code and shows code without running it

For assessment reports, markers also receive the .Rmd file, so the knitted PDF often uses echo=FALSE for most or all code. The report should show the results clearly; the .Rmd file shows how they were produced.

A good chunk has one clear job.

Examples:

• setup: load packages and options
• load-data: read the data file
• inspect-data: check variables and rows
• descriptives: create one table
• raw-data-plot: create one figure

Before submitting, remove code that was only exploratory or did not contribute to the final report.

Do not leave every attempted analysis in one large chunk.

Use this article as the example source:

Whelan, R. (2008). Effective analysis of reaction time data. The Psychological Record, 58, 475-482. https://doi.org/10.1007/BF03395630

Add it to part-2-tiny-rmarkdown-example.Rmd:

1. Open references.bib.
2. Add a BibTeX entry for the Whelan article at the end of the file (see next slide).
3. Use a clear citation key, for example whelan2008reactiontime.
4. In the .Rmd file, replace the comment in Optional Citation Practice with a sentence that uses @whelan2008reactiontime.
5. Knit again and check that the citation appears in the text and in ## References.

Open part-2-rmarkdown-worked-blomkvist.Rmd.

This is a complete worked example. You are not filling in placeholders here.

Your task is to:

• knit the file to PDF
• follow the Your Task: Guided Walkthrough section in the .Rmd file
• identify where the data, inline results, table, figure, citation, and cross-references are created
• ask which parts would need to change for your own dataset

In part-2-rmarkdown-worked-blomkvist.Rmd, find the chunks labelled:

• setup
• project-check
• load-data
• inspect-data

What to notice:

• packages are loaded once in setup
• data are read from data/blomkvist.csv
• variables are selected and renamed before analysis
• missing values are removed before descriptives
• glimpse() is used to inspect the analysis data

In the worked example, find the chunk labelled summary-values.

This chunk creates objects that are used in text:

n_participants <- n_distinct(reaction_time$id)
mean_age <- mean(reaction_time$age)

Then find this sentence in the report text:

The analysis used `r n_participants` participants.

What changes in the PDF when the Rmd is knitted?

In the worked example, find the section Descriptive Statistics.

Tasks:

1. Find the sentence that refers to Table \@ref(tab:descriptives).
2. Find the chunk labelled descriptives.
3. Check where the table caption is written.
4. Check how kable() turns descriptive_table into a table.

For grouped summaries in your own work use .by:

summarise(analysis_data,
          mean_y = mean(y),
          sd_y = sd(y),
          .by = condition)

In the worked example, find the section Figure.

Tasks:

1. Find the sentence that refers to Figure \@ref(fig:raw-data).
2. Find the chunk labelled raw-data.
3. Check where the figure caption is written.
4. Check which variables are used for the x-axis and y-axis.

ggplot(reaction_time, aes(x = age, y = rt)) +
  geom_point(alpha = .35) +
  geom_smooth(method = "lm", se = FALSE)

What would need to change for a different dataset?

This is a start-in-class and continue-after-class task.

Use the same principles for a new dataset:

• if you already have suitable formative assessment data, start adapting the structure to your own data
• if you do not have suitable data yet, open part-2-chinese-ldt-transfer.Rmd and complete the do-it-yourself task with the Chinese lexical decision task data

The aim today is to start the transfer, identify where you get stuck, and ask for help before continuing independently.

Use this time to:

• make your own RMarkdown skeleton
• check your folder structure
• load your own data
• ask for help with knitting errors

Read after the workshop:

• Writing Reproducible Reports Using RMarkdown on the NOW learning room. This is the draft version of Mark Andrews, Doing Data Science in R, Chapter 7: Reproducible Data Analysis (Andrews, 2021). It is a detailed reference, not a list of everything we can cover in one workshop. Some screenshots or interface details may differ from current RStudio.
• RMarkdown lesson 1: https://rmarkdown.rstudio.com/lesson-1.html
• R for Data Science, R Markdown chapter: https://r4ds.had.co.nz/r-markdown.html (Wickham & Grolemund, 2016)

Use these to revise Markdown text, chunks, inline code, figures, tables, and knitting.

Try to arrive with:

• Exercise 5 started, continued, or completed
• a working .Rmd file
• a dataset loaded in the file
• one plot
• one possible continuous outcome variable