• Results are communicated through reports such as peer reviewed scientific articles.
• Analysis and results should be reproducible.
• Data and code should be made publically available.
• Often difficult to relate code to figures, tables, numbers in text.
• Copy-pasting numbers from software into the text can be error prone.

• Setup
• Examples
• YAML preamble and chunk options
• Headers
• Figures and tables
• Cross-referencing
• Referencing
• In-line R output
• Mathematical typesetting

• Go to github.com/jensroes/bristol-ws-2025
• Click on: Code > Download ZIP > unzip directory on your machine.
• Open project by double clicking on bristol-ws-2025.Rproj
• Use slides for code

• Test that rmarkdown will render pdf documents:

writeLines('Hello $x^2$', 'test.Rmd')
rmarkdown::render('test.Rmd', output_format = 'pdf_document')

• writeLines creates an .Rmd file named test.Rmd.
• rmarkdown::render renders .Rmd as pdf named test.pdf.

• Open rmarkdown/examples/example.Rmd
• You’ll see an R chunk and two pieces of inline R code.
• Remainder is plain Markdown.
• Knit > Knit to PDF to compile .Rmd to .pdf. Wow!!!
• Notice how the code was interpreted in pdf.
• Important: R code is executed from top down.
• Other demos and examples are provided.

• Open rmarkdown/examples/apa7_template.Rmd
• To run this, you might need to install a few packages so instead
• Check out the file rmarkdown/examples/apa7_template.pdf that was rendered with this .Rmd file

• Open rmarkdown/examples/robobook.Rmd
• To run this, you might need to install a few packages so instead
• Check out the file rmarkdown/examples/robobook.html that was rendered with this .Rmd file

• Click on File > New File > R Markdown
• Document (PDF, WORD, HTML)
• output: pdf_document: use pdfs for writing manuscripts
  
• Name your RMarkdown: my-practice-markdown.Rmd
• Save in same directory as .Rproj file.
• YAML header between '---'s
• YAML = YAML Ain’t a Markup Language (o Yet Another Markup Language)

• Create a new R chunk: try CTRL+ALT+I or CMD+ALT+I (i.e. the letter “i”)
• Create a chunk called packages and load libraries needed:

library(tidyverse)

• Create a new chunk called loaddata and load Martin et al. (2010) data:

data <- read_csv("data/martin-etal-2010-exp3a.csv") 

• Note ```{r setup, echo=FALSE}
• setup is a label of this chunk (optional; useful for cross-referencing of figures and tables).
• Chunk configuration option echo = FALSE: don’t display chunk in output; echo = TRUE: display chunk.

knitr::opts_chunk$set(message = FALSE, # don't return messages
                      warning = FALSE, # don't return warnings
                      comment = NA, # don't comment output
                      echo = TRUE, # display chunk (is default)
                      eval = TRUE, # evaluate chunk (is default)
                      out.width = '45%',  # figure width
                      fig.align='center') # figure alignment

# This is a section header

## This is a subsection header

# This is another section header

## This is another subsection header

### This is a subsubsection header

• Create a new R chunk with label mydensplot
• Set echo = F cause we only need the figure.
• Add a figure caption fig.cap = "A density plot." in the chunk configurations.

ggplot(data, aes(x = rt, colour = nptype, fill = nptype)) +
    geom_density(alpha = .25) +
    scale_x_log10() +
    theme_classic()

• Change the default size to out.width = 50%.
• Cross-reference figure using \ref{fig:mydensplot} in the text.

"A density plot of reaction time visualised by NP type can be found in Figure \ref{fig:mydensplot}."

header-includes:
- \usepackage{booktabs}

• We just need booktabs to improve type setting.

• Reporting results in tables formatted to a high standard.
• Calculate descriptive summary stats:

(rt_stats <- summarise(data, across(rt, list(mean = mean, sd = sd)), .by = nptype))

# A tibble: 2 × 3
  nptype    rt_mean rt_sd
  <chr>       <dbl> <dbl>
1 conjoined   1109.  296.
2 simple      1076.  267.

• This format isn’t good enough for papers.

library(kableExtra)
kable(rt_stats,
      format = 'latex',
      booktabs = TRUE,
      digits = 2,
      align = 'c', # centre value in each column
      caption = 'Descriptive summary statistics of reaction time by NP type.') %>% 
  kable_styling(position = 'center') # centre position of table

Also, label your chunk “rtstats” and cross-reference the table in the text using Table \ref{tab:rtstats}.

Add to the YAML preamble:

bibliography: refs.bib
biblio-style: apalike

Create a file (in RStudio) called refs.bib (save in same working directory as your .Rmd file)

• Get the .bib entry for Martin et al. (2010) from Google Scholar and paste it into refs.bib:
  • Copy the title “Planning in sentence production: Evidence for the phrase as a default planning scope” into Google Scholar
  • Click cite and BibTeX
  • Copy the .bib entry into refs.bib
• Note the citation key martin2010planning
• Cite Martin et al. (2010) using @martin2010planning or [@martin2010planning].
• At the end of your document create a section “# References”

# Fit model and get the summary
library(lmerTest)
model <- lmer(rt ~ nptype + (nptype|ppt) + (nptype|item), data = data)
model_summary <- summary(model)$coefficients

Task: Use the tab_model function of the sjPlot package to create a nicely formatted table of the model object. Use cross-referencing as before to refer to the table from the text.

# Extract t statistic
t_val <- model_summary[2, 4]
# Extract df
df <- model_summary[2, 3]
# Extract p value
p_val <- model_summary[2, 5]

The hypothesis test for the rt effect can be summarised like so: 
*t*(`r round(df, 1)`) = `r round(t_val, 1)`, *p* `r format.pval(p_val, eps = 0.05)`.

Which renders to: “The hypothesis test for the slope coefficient can be summarised like so: t(125.7) = -2.2, p <0.05.”

# Extract slope coefficient
est <- model_summary[2, 1]

The $\hat\beta$ coefficient of this model shows a slowdown of `r round(est, 1)` ms.

Renders “The \(\hat\beta\) coefficient of this model shows a slowdown of -33.6 ms.”

Task: Use confint(model) to obtain the 95% CI of the effect and add it to the text. Don’t copy paste the numbers but use inline R code.

# Extract slope coefficient
est <- model_summary[2, 1]
ci <- as.numeric(confint(model, parm = "nptypesimple"))

The $\hat\beta$ coefficient of this model shows a slowdown of `r round(est, 1)` ms;
95% CI: `r ci[1]`, `r ci[2]`.

Renders “The \(\hat\beta\) coefficient of this model shows a slowdown of -33.6 ms; 95% CI: -63.83, -2.94.”

• Strings are parsed using \(\LaTeX\) and typeset accordingly when used between '$' symbols for inline mode.
• For example $\beta$ renders \(\beta\).
• Subscripts: $\beta_0$ is \(\beta_0\) and using '{}' for more than one symbol as in $\beta_{01}$ which is \(\beta_{01}\)
• How would you write \(\beta_{0_1}\)?
• Superscripts: '^' as in $\sigma^2$ which is \(\sigma^2\).
• How would you write \(\sigma^{2^2}\)?
• How about \(\sigma_e^2\)?

The observed variable is modeled as coming from a normal distribution $y_i \sim \mathcal{N}(\mu_i, \sigma^2)$, with $\mu_i = \beta_0 + \beta_1 \cdot x_i$ where each $i \in 1 \dots N$ .

Renders

The observed variable is modeled as coming from a normal distribution \(y_i \sim \mathcal{N}(\mu_i, \sigma^2)\), with \(\mu_i = \beta_0 + \beta_1 \cdot x_i\) where each \(i \in 1 \dots N\).

$$
y_i \sim \mathcal{N}(\mu_i, \sigma^2)
$$

Renders

\[ y_i \sim \mathcal{N}(\mu_i, \sigma^2) \]

• Using \(\LaTeX\)’s aligned environment to align multiple mathematical statements.
• We will get back to what this means.

$$
\begin{aligned}
  y_i &\sim N(\mu_i, \sigma^2),\\
  \mu_i &= \beta_0 + \beta_1 \cdot x_i + beta_2 \cdot z_i
\end
$$

• The '&' is used to align the lines so that ‘\(\sim\)’ (\sim) and ‘\(=\)’ are aligned.
• '$\\$' forces a line break.

install.packages("rmdformats")

• Create from template:
  • File > New File > R Markdown (e.g. readthedown or robobook for documents)
  • rmdshower::shower_presentations and ioslides_presentation for slides
• Online sharing on RPubs (“Publish”): RMarkdown example

• Example: https://osf.io/vayhq/ published in Roeser, De Maeyer, et al. (2024)
• Installation: https://github.com/crsh/papaja

• Never copy numbers from output into text.
• Don’t produce citations or cross-reference manually.
• Be selective with which output and code you do and do not show your audience.
• Don’t use RMarkdown instead of or like R-scripts.
• Run more complex statistical models in a separate script, save the model output and read it into your script.

• Chapter 7 in “Doing Data Science in R” (Andrews 2021)
• Chapter 27 in “R for Data Science” (Wickham and Grolemund 2016)
• For formatting tables using kableExtra check here
• Check the rmarkdown website.