When inheriting a module

Usual file structure

Some .tex files & the generated .pdf
- verbatim R code & output in .tex
figures/ or graphics/:
- generated for \includegraphics in .tex
- .eps, .ps, .png, .jpg, .pdf, .gif
R-related files:
- .R that generates the output & figures
- .RData, .rds, .Rd
“By-products”:
- .out, .log, .dvi, .blg, .bbl, .aux, .synctex.gz
Miscellaneous:
- .csv, .txt, .stan, .sty
- .pdf of scanned solutions
But no README
- maybe a makefile

$~$

Scope

A single set of source scripts

Code + text combined
- Reproducible
- No more separate R scripts
Both HTML & PDF outputs
- Accessible
- Alternative to Chirun
Both questions/gaps & solutions
- A parameter that toggles between the two
Script-based
- Easy to version control
- As little scaffolding as possible
Language agnostic
- Less painful to switch from R to Python?
Initial time cost
- Lower priority
- Focus on future savings

This talk

R Markdown basics
Bookdown for notes
Practical considerations

1. R Markdown basics

LaTeX

The source file (.tex)

\begin{itemize}
  \item $\pi=3.1415927\dots$ is \textit{irrational} \& \textbf{transcendental}
  \item Type \texttt{pi} in \verb'R' console for numerical value
\end{itemize}

\begin{verbatim}
2 * pi

  ## [1] 6.283185
\end{verbatim}

Question: Show that $e^{i\pi}+1=0$.\\
Solution:
\begin{align*}
  e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\
  &=-1+i\times0+1=0
\end{align*}

% A comment that won't appear in the output.

The output (.pdf)

$\pi=3.1415927\dots$ is irrational & transcendental
Type pi in R console for numerical value

$\quad$

2 * pi

## [1] 6.283185

$\quad$
Question: Show that $e^{i\pi}+1=0$.
Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\qquad\qquad\qquad\qquad\\ &=-1+i\times0+1=0 \end{align*}\]

R Sweave

The source file (.Rnw)

\begin{itemize}
  \item $\pi=\Sexpr{pi}\dots$ is \textit{irrational} \& \textbf{transcendental}
  \item Type \texttt{pi} in \verb'R' console for numerical value
\end{itemize}

<<>>=
2 * pi
@

Question: Show that $e^{i\pi}+1=0$.\\
Solution:
\begin{align*}
  e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\
  &=-1+i\times0+1=0
\end{align*}

% A comment that won't appear in the output.

The output (.pdf)

$\pi=3.1415927\dots$ is irrational & transcendental
Type pi in R console for numerical value

$\quad$

2 * pi

## [1] 6.283185

$\quad$
Question: Show that $e^{i\pi}+1=0$.
Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\qquad\qquad\qquad\qquad\\ &=-1+i\times0+1=0 \end{align*}\]

R Markdown

The source file (.Rmd)


* $\pi=`r pi`\dots$ is *irrational* & **transcendental**
* Type `pi` in `R` console for numerical value

```{r}
2 * pi

  
```

Question: Show that $e^{i\pi}+1=0$.  
Solution:
\begin{align*}
  e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\
  &=-1+i\times0+1=0
\end{align*}

<!-- A comment that won't appear in the output. -->

The output (.pdf / .html)

$\pi=3.1415927\dots$ is irrational & transcendental
Type pi in R console for numerical value

$\quad$

2 * pi

## [1] 6.283185

$\quad$
Question: Show that $e^{i\pi}+1=0$.
Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\qquad\qquad\qquad\qquad\\ &=-1+i\times0+1=0 \end{align*}\]

Chunk options

For displaying / hiding code / plots

  
  
  
  
  
  
```{r, out.width = "70%"}
plot(cars)
```

The output (.pdf / .html)

plot(cars)

Chunk options

Hide the code

  
  
  
  
  
  
```{r, out.width = "70%", echo = FALSE}
plot(cars)
```

The output (.pdf / .html)

Chunk options

Don’t evaluate

  
  
  
  
  
  
```{r, out.width = "70%", eval = FALSE}
plot(cars)
```

Also useful when showing code that doesn’t work

The output (.pdf / .html)

plot(cars)

Chunk options

Hide the plots (but still evaluate)

  
  
  
  
  
  
```{r, out.width = "70%", fig.show = "hide"}
plot(cars)
```

The output (.pdf / .html)

plot(cars)

Chunk options

Hide the code & results (but still evaluate)

  
  
  
  
  
  
```{r, out.width = "70%", include = FALSE}
plot(cars)
```

The output (.pdf / .html)

Toggle for questions & solutions

Question version






1. Plot the `cars` dataset in `R`.
```{r, out.width = "70%", include = FALSE}
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{r, include = FALSE}
round(2 * pi, 4)
```

The output (.pdf / .html)

Plot the cars dataset in R.
Find the numerical value of $2\pi$, to 4 decimal places.

Toggle for questions & solutions

Solution version






1. Plot the `cars` dataset in `R`.
```{r, out.width = "70%", include = TRUE}
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{r, include = TRUE}
round(2 * pi, 4)
```

The output (.pdf / .html)

Plot the cars dataset in R.

plot(cars)

Find the numerical value of $2\pi$, to 4 decimal places.

round(2 * pi, 4)

## [1] 6.2832

Parametrise the toggle

Between the triple dashes: YAML similar to LaTeX preamble

---
title: "MAS9999 Practical 1"
params:
  solution: ""
---
1. Plot the `cars` dataset in `R`.
```{r, out.width = "70%", include = params$solution}
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{r, include = params$solution}
round(2 * pi, 4)
```

Call this file Practical1.Rmd

$~$

One script to render them all

Run the commands (interactively) in R

library(rmarkdown)
render("Practical1.Rmd", params = list(solution = FALSE),
       output_format = "html_document", 
       output_file = "Practical1_questions.html")
                   
render("Practical1.Rmd", params = list(solution = FALSE),
       output_format = "pdf_document", 
       output_file = "Practical1_questions.pdf")
                   
render("Practical1.Rmd", params = list(solution = TRUE),
       output_format = "html_document", 
       output_file = "Practical1_solutions.html")
                   
render("Practical1.Rmd", params = list(solution = TRUE),
       output_format = "pdf_document", 
       output_file = "Practical1_solutions.pdf")

Or run non-interactively in a terminal, or put them in a makefile
Intermediate files gone, unless you specify them to be kept

$~$

What about text & equations?

Originally

Question: Show that $e^{i\pi}+1=0$.  

Solution:
\begin{align*}
  e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\
  &=-1+i\times0+1=0
\end{align*}

No native solution environment AFAIK

The output (.pdf / .html)

Question: Show that $e^{i\pi}+1=0$.

Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\ &=-1+i\times0+1=0 \end{align*}\]

What about text & equations?

Making solution text a string in R

Question: Show that $e^{i\pi}+1=0$.  

```{r, results = "asis", echo = FALSE, include = TRUE}
cat("Solution:
     \\begin{align*}
       e^{i\\pi}+1&=\\cos\\pi+i\\sin\\pi+1\\\\
       &=-1+i\\times0+1=0
     \\end{align*}", "\n")
```

Double the backslashes

https://xkcd.com/1638/

The output (.pdf / .html)

Question: Show that $e^{i\pi}+1=0$.

Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\ &=-1+i\times0+1=0 \end{align*}\]

What about text & equations?

The question version

Question: Show that $e^{i\pi}+1=0$.  

```{r, results = "asis", echo = FALSE, include = FALSE}
cat("Solution:
     \\begin{align*}
       e^{i\\pi}+1&=\\cos\\pi+i\\sin\\pi+1\\\\
       &=-1+i\\times0+1=0
     \\end{align*}", "\n")
```

The output (.pdf / .html)

Question: Show that $e^{i\pi}+1=0$.

Full example, the questions

Practical1.Rmd

---
title: "MAS9999 Practical 1"
params:
  solution: ""
---
1. Write `R` code to plot the `cars` dataset.
```{r, include = params$solution, fig.show = "hide"}
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{r, include = params$solution}

round(2 * pi, 4)
```
3. Show that $e^{i\pi}+1=0$.  
```{r, results = "asis", echo = FALSE, include = params$solution}
cat("Solution:
     \\begin{align*}
       e^{i\\pi}+1&=\\cos\\pi+i\\sin\\pi+1\\\\
       &=-1+i\\times0+1=0
     \\end{align*}", "\n")
```

library(rmarkdown)
render("Practical1.Rmd", params = list(solution = FALSE),
       output_format = "html_document", 
       output_file = "Practical1_questions.html")

The output (Practical1_questions.html)
$\qquad$
$\qquad$
$\qquad\qquad$ MAS9999 Practical 1

Write R code to plot the cars dataset.
Find the numerical value of $2\pi$, to 4 decimal places.
Show that $e^{i\pi}+1=0$.

Full example, the solutions

Practical1.Rmd

---
title: "MAS9999 Practical 1"
params:
  solution: ""
---
1. Write `R` code to plot the `cars` dataset.
```{r, include = params$solution, fig.show = "hide"}
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{r, include = params$solution}

round(2 * pi, 4)
```
3. Show that $e^{i\pi}+1=0$.  
```{r, results = "asis", echo = FALSE, include = params$solution}
cat("Solution:
     \\begin{align*}
       e^{i\\pi}+1&=\\cos\\pi+i\\sin\\pi+1\\\\
       &=-1+i\\times0+1=0
     \\end{align*}", "\n")
```

library(rmarkdown)
render("Practical1.Rmd", params = list(solution = TRUE),
       output_format = "html_document", 
       output_file = "Practical1_solutions.html")

The output (Practical1_solutions.html)
$\qquad$
$\qquad$
$\qquad\qquad$ MAS9999 Practical 1

Write R code to plot the cars dataset.

plot(cars)

Find the numerical value of $2\pi$, to 4 decimal places.

round(2 * pi, 4)

## [1] 6.2832

Show that $e^{i\pi}+1=0$.
Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\ &=-1+i\times0+1=0 \end{align*}\]

Language agnostic(-ish)

R, Python and maths questions

---
title: "MAS9999 Practical 1"
params:
  solution: ""
---
1. Write `R` code to plot the `cars` dataset.
```{r, include = params$solution, fig.show = "hide"}
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{python, include = params$solution}
import math
round(2 * math.pi, 4)
```
3. Show that $e^{i\pi}+1=0$.  
```{r, results = "asis", echo = FALSE, include = params$solution}
cat("Solution:
     \\begin{align*}
       e^{i\\pi}+1&=\\cos\\pi+i\\sin\\pi+1\\\\
       &=-1+i\\times0+1=0
     \\end{align*}", "\n")
```

library(rmarkdown)
render("Practical1.Rmd", params = list(solution = TRUE),
       output_format = "html_document", 
       output_file = "Practical1_solutions.html")

The output (Practical1_solutions.html)
$\qquad$
$\qquad$
$\qquad\qquad$ MAS9999 Practical 1

Write R code to plot the cars dataset.

plot(cars)

Find the numerical value of $2\pi$, to 4 decimal places.

import math
round(2 * math.pi, 4)

## 6.2832

Show that $e^{i\pi}+1=0$.
Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\ &=-1+i\times0+1=0 \end{align*}\]

Quarto

Practical1.qmd

---
title: "MAS9999 Practical 1"
params:
  solution: ""
---
1. Write `R` code to plot the `cars` dataset.
```{r}
#| include: !expr params$solution
#| fig.show: "hide"
plot(cars)
```
2. Find the numerical value of $2\pi$, to 4 decimal places.
```{r}
#| include: !expr params$solution
round(2 * pi, 4)
```
3. Show that $e^{i\pi}+1=0$.  
```{r}
#| results: "asis"
#| echo: FALSE
#| include: !expr params$solution
cat("Solution:
     \\begin{align*}
       e^{i\\pi}+1&=\\cos\\pi+i\\sin\\pi+1\\\\
       &=-1+i\\times0+1=0
     \\end{align*}", "\n")
```

library(quarto)
quarto_render("Practical1.qmd", execute_params = list(solution = "true"),
              output_format = "html", 
              output_file = "Practical1_solutions.html")

The output (Practical1_solutions.html)
$\qquad$
$\qquad$
$\qquad\qquad$ MAS9999 Practical 1

Write R code to plot the cars dataset.

plot(cars)

Find the numerical value of $2\pi$, to 4 decimal places.

round(2 * pi, 4)

## [1] 6.2832

Show that $e^{i\pi}+1=0$.
Solution: \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\ &=-1+i\times0+1=0 \end{align*}\]

2. Bookdown for lecture notes

R Markdown upgrade

A collection of .Rmd files

index.Rmd
01-multivariate-data.Rmd
02-pca.Rmd
03-cluster.Rmd
04-regression.Rmd
05-regularisation.Rmd
06-classification.Rmd
07-matrix.Rmd
08-factorisation.Rmd
09-references.Rmd

index.Rmd

---
title: "MAS8383 Statistical Learning Methodology"
author: "Clement Lee"
date: Semester 1, 2023/2024  
output: bookdown::gitbook
documentclass: book
papersize: a4
geometry:
- margin=1in
fontsize: 12pt
bibliography: [references.bib]
biblio-style: apalike
link-citations: yes
params:
  solution: ""
---

library(bookdown)
render_book("index.Rmd", param = list(solution = FALSE),
            output_format = c("bookdown::gitbook", "bookdown::pdf_book"))

{gaps, solutions} $\times$ {.pdf, .html}

The parameter solution (again)

solution = FALSE: version with gaps
solution = TRUE: version with solutions
As before, make solutions to examples / exercises strings in R

The output format

bookdown::pdf_book: A single PDF with all chapters
bookdown::gitbook: Multiple HTML pages
Numbering of sections / figures / tables same across both formats
- Needs a way that works for both

Labelling & referencing

Equations

\begin{equation}
  e^{i\pi}+1=0
  (\#eq:euler)
\end{equation}
Equation \@ref(eq:euler) is the Euler's identity.

(\#eq:euler) instead of \label{eq:euler}
\@ref(eq:euler) instead of \eqref(eq:euler)
- The latter doesn’t exist
- The prefix eq: suffices

The output

\[\begin{equation} e^{i\pi}+1=0\qquad\qquad\qquad (1) \end{equation}\] Equation (1) is the Euler’s identity.

Labelling & referencing

Figures

```{r plot-cars, out.width = "70%", fig.cap = "Cars dataset".}
plot(cars)
```

A positive correlation between `speed` and `dist`
can be seen in Figure \@ref(fig:plot-cars).

Code chunk label utilised
No prefix fig: when labelling
No underscores; error if plot_cars

The output

plot(cars)

Figure 1: Cars dataset.

A positive correlation between speed and dist can be seen in Figure 1.

Labelling & referencing

Theorems & proofs

::: {.theorem name="Euler's identity" #euler-identity}
$e^{i\pi}+1=0$
:::

The proof of Theorem \@ref(thm:euler-identity) is as below:

::: {.proof}
\begin{align*}
  e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\
  &=-1+i\times0+1=0
\end{align*}
:::

As before, no prefix thm: when labelling

The output

Theorem 1 (Euler’s identity) $e^{i\pi}+1=0$

The proof of Theorem 1 is as below:

Proof. \[\begin{align*} e^{i\pi}+1&=\cos\pi+i\sin\pi+1\\ &=-1+i\times0+1=0 \end{align*}\]

Labelling & referencing

Other environments

::: {.lemma name="Lemon" #two}
:::
::: {.corollary name="Coriander" #three}
:::
::: {.proposition name="Pepper" #four}
:::
::: {.conjecture name="Confit" #five}
:::
::: {.definition name="Daffodil" #six}
:::
::: {.example name="Exotic" #seven}
:::
::: {.exercise name="Extract" #eight}
:::
::: {.hypothesis name="Hazelnut" #nine}
:::

Lemma \@ref(lem:two), Corollary \@ref(cor:three),
Proposition \@ref(prp:four), Conjecture \@ref(cnj:five),
Definition \@ref(def:six), Example \@ref(exm:seven),
Exercise \@ref(exr:eight), Hypothesis \@ref(hyp:nine)

The output

Lemma 2 (Lemon)

Corollary 3 (Coriander)

Proposition 4 (Pepper)

Conjecture 5 (Confit)

Definition 6 (Daffodil)

Example 7 (Exotic)

Exercise 8 (Extract)

Hypothesis 9 (Hazelnut)

Lemma 2, Corollary 3, Proposition 4, Conjecture 5, Definition 6, Example 7, Exercise 8, Hypothesis 9

What about LaTeX environments & commands?

Some work

equation
align
aligned
eqnarray
array
(and their * versions)
$$ $$
\[ \]

Some don’t (for HTML)

center
tabular
displaymath
\intertext
\textcolor
\medskip
\bigskip
\hfill
\newpage

Some have been taken care of

enumerate: (R)markdown can do lists
itemize: (R)markdown can do lists
quote: (R)markdown can do quotes
solution: The hack using strings in R
verbatim: Backticks ``
example: Environment extended by bookdown
exercise: Environment extended by bookdown
figure

```{r, echo = FALSE}
## for figures not generated by R
knitr::include_graphics("backslashes.png")
```

Canvas integration

Using iframe
Let’s have a look

3. Practical considerations

Converting existing materials

Cons

Fewer environments that work $\qquad\qquad\quad\longrightarrow$
- And have to adapt to new environments
Have to check both formats back and forth $\quad\longrightarrow$
- Experiment what works and what doesn’t
You don’t have fewer script files $~\quad\qquad\quad\longrightarrow$
- Notes
- Practicals
- Slides
- Assignments
Time cost & manual work $~\qquad\quad\quad\qquad\longrightarrow\quad?$

Pros

Scripts usually reproducible
- Subject to package version changes
Checks the accessibility box once & for all
Separates content creation from formatting
A tidier set of files
- ~~.out, .log, .dvi, .blg, .bbl, .aux, .synctex.gz~~
- ~~figures/, .R, .RData~~

A list of tasks (in this order)

Move \label{} outside (sub)(sub)section headings
Replacements with regular expressions (regex)
Replacements with strings
Remove LaTeX commands: \textcolor, \medskip, \bigskip, \hfill, \newpage, \intertext
Edit section & equation labels & \eqref{}
Edit “other” environments in conjunction with their labels
Edit itemize & enumerate environments
Convert environments to R code chunks:
- solution: the string hack
- figure: knitr::include_graphics() (& convert .pdf to .png)
- verbatim: actual R code without hardcoded results
- tabular: knitr::kable() (or markdown syntax for tables)
Fix code chunk labels ("_" $\rightarrow$ “-”) & options: dev, out.width
Add space in solution code chunks for PDF version, in conjunction with figure positions

Previously

R Sweave

\section{Properties of $\pi$} \label{sect:pi_properties}

\begin{itemize}
  \item $\pi=\Sexpr{pi}\dots$ is \textit{irrational} \& \textbf{transcendental}
  \item Type \texttt{pi} in \verb'R' console for numerical value
\end{itemize}

<<>>=
2 * pi
@

<<plot_digits, fig.cap = "Digits of $\\pi$ after the decimal place.">>=
plot(strsplit(sprintf("%.16f", pi), "")[[1]][-(1:2)])
@
  
The pattern in Figure~\ref{fig:plot_digits}
seems random\footnote{in some sense}.

% A comment that won't appear in the output.

R Markdown

## Properties of $\pi$ {#sect:pi-properties}
  

* $\pi=`r pi`\dots$ is *irrational* & **transcendental**
* Type `pi` in `R` console for numerical value  
  

```{r}
2 * pi
```  

```{r, plot-digits, fig.cap = "Digits of $\\pi$ after the decimal place."}
plot(strsplit(sprintf("%.16f", pi), "")[[1]][-(1:2)])
```

The pattern in Figure \@ref(fig:plot-digits)
seems random^[in some sense].

<!-- A comment that won't appear in the output. -->

Replacements (in this order)

Before	After	Remarks
`\label{([^}]+)_([^}]+)_([^}]+)}`	`{#\1-\2-\3}`	Similar for those with fewer "_"
`\ref{([^}]+)_([^}]+)_([^}]+)}`	`\@ref(\1-\2-\3)`	Ditto
`\section{([^}]+)}`	`## \1`	One # fewer for single document
`\section*{([^}]+)}`	`## \1 {-}`	Ditto; similar for (sub)(sub)sections
`\textit{([^}]+)}`	`\1`	Same for `\emph{([^}]+)}`
`\textbf{([^}]+)}`	`\1`
`\texttt{([^}]+)}`	`\1`	Same for `\verb`
`\Sexpr{([^}]+)}`	`r \1`
`\footnote{([^}]+)}`	`^[\1]`
` `(.*)''	`"\1"`	Before below replacments with `
`^<<>>=$`	```{r}
`^<<(.*)>>=`	```{r, \1}
`^@[\s]?`	```
`^%(.*)`	`<!-- \1 -->`	After fixing environments commented out
(self-defined LaTeX commands)	(Markdown replacements)	(or just original LaTeX commands)

Figure~	Figure	Not regex; with space at the end;
		same for Chapter, Section, etc.
`\_`	`_`	Not regex; same for `\$`, `\%` and `\&`

Preach what you practise

Ask students to write assignments using R Markdown / Quarto
Submit the .Rmd / .qmd for you to reproduce the .pdf / .html
Also write the assignments questions / solutions in the same way
Make sure LaTeX works on university computers
- Those in the USB behave differently

Scaffolding

R(Studio)
For standalone documents via R Markdown:
- R package rmarkdown (all lowercase)
For standalone documents via Quarto:
- R package quarto
For lecture notes via bookdown
- R packages rmarkdown & bookdown
The R packages required for your module
- Most likely in the R script
LaTeX distribution & packages required for PDF outputs
- Installation outside R, or
- R package tinytex $\rightarrow$ tinytex::install_tinytex()
- tinytex::tlmgr_install()
For Python content
- R package reticulate
- Python (3)

YMMV

Even though they are meant for reproducibility
Quarto in active development, R Markdown more stable
Labelling & referencing that works in bookdown doesn’t automatically work in R Markdown

Creating accessible & reproducible teaching materials with bookdown

When inheriting a module

Scope

1. R Markdown basics

LaTeX

R Sweave

R Markdown

Chunk options

Chunk options

Chunk options

Chunk options

Chunk options

Toggle for questions & solutions

Toggle for questions & solutions

Parametrise the toggle

One script to render them all

What about text & equations?

What about text & equations?

What about text & equations?

Full example, the questions

Full example, the solutions

Language agnostic(-ish)

Quarto

2. Bookdown for lecture notes

R Markdown upgrade

{gaps, solutions} \(\times\) {.pdf, .html}

Labelling & referencing

Labelling & referencing

Labelling & referencing

Labelling & referencing

What about LaTeX environments & commands?

Canvas integration

3. Practical considerations

Converting existing materials

A list of tasks (in this order)

Previously

Replacements (in this order)

Preach what you practise

Scaffolding

Summary

Some useful sites (that I’ve visited 400 times)