Agenda

  1. What is R Markdown / Bookdown?
  2. Basic demos of R Markdown and Bookdown, using RStudio Cloud
  3. Tips & tricks

Before we start…

These slides were written in R Markdown, using the ioslides package. (More later.)

Visit https://mpaldridge.github.io/rmarkdown/ for:

Introduction

What is R Markdown / Bookdown?

R Markdown is a system for writing mathematical/statistical documents.

  • R Markdown documents can be produced in numerous formats, including accessible HTML.

Bookdown is a package for R Markdown that provides extra features useful for long documents.

What is Markdown?

Markdown is a “mark-up” language (like LaTeX or HTML), where special characters and commands tell the computer what formatting you want.

  • Markdown is extremely easy for humans to read

Markdown example

Markdown:

# About MATH1710

## Syllabus

This module is **MATH1710 Probability
and Statistics 1** and will last for
*11 weeks*. We will cover three sections:

1. Exploratory data analysis
2. Probability
   - Probability with events
   - Probabiltiy with random variables
3. Bayesian statistics

LaTeX:

\chapter{About MATH1710}

\section{Syllabus}

This module is \textbf{MATH1710 Probability
and Statistics 1} and will last for
\emph{11 weeks}. We will cover three sections:
\begin{enumerate}
  \item Exploratory data analysis
  \item Probability
  \begin{itemize}
    \item Probability with events
    \item Probabiltiy with random variables
  \end{itemize}
  \item Bayesian statistics
\end{enumerate}

What is Markdown?

Markdown is a “mark-up” language (like LaTeX or HTML), where special characters and commands tell the computer what formatting you want.

  • Markdown is extremely easy for humans to read
  • Programs like Pandoc can compile Markdown documents to many different formats:
    • most important: HTML (fully accessible) and PDF
    • also: EPUB ebook, Microsoft Word document, etc.
    • Can be built to multiple formats simultaneously
  • Markdown is simpler than LaTeX…
    • …but much less powerful that LaTeX

What is R Markdown?

R Markdown is a system to write and compile (“knit”) Markdown documents using R…

Wait… what is R?

R is a programming language that is very good at doing statistics.

  • R is used by most statistics academics
  • We teach R to our students (in MATH1710, MATH1712, etc.)

Using the program RStudio is a convenient way to work with the language R (and with R Markdown documents).

Demos later…

What is R Markdown?

R Markdown is a system to write and compile (“knit”) Markdown documents using R.

R Markdown adds to plain-Markdown:

  • Mathematical equations using LaTeX notation
    • When “knitted” to HTML, this displays as fully accessible MathJax
    • Includes standard amsmath extras: mathbb, mathcal, align, align*, cases, pmatrix, etc
    • May not do super-complicated stuff
  • You can include R code (or other programming languages) in cool ways
    • More on this later…

What is Bookdown?

Bookdown is an extra package for R Markdown that is particularly useful for long documents.

  • In HTML format, produces a full website of interlinked pages, one page per chapter
  • Other HTML features: contents bar, search, colour schemes, font size adjustment, etc
  • Adds LaTeX-like theorem/definition/proof environments

Compare earlier demos:

R Markdown v Bookdown

“Plain” R Markdown R Markdown with Bookdown
Good for short documents Good for long documents
Slightly simpler to write Slightly trickier to write
PDF or accessible HTML PDF or accessible HTML
LaTeX equations LaTeX equations
Single HTML page Multi-page website
No theorem environments Theorem environments

My first R Markdown document

R Markdown through RStudio

I strongly recommend using R Markdown via RStudio.

  • (Recall that RStudio is the program to interact with the statistical programming language R)

To install on your own computer:

For a first try, I recommend instead the RStudio Cloud: https://rstudio.cloud

  • Browser-based RStudio – like Google Docs or Overleaf for RStudio.
  • 25 hours per month free – probably won’t work for long-term use

Demo

[demo via RStudio Cloud]

Formatting with (R) Markdown I

Appearance (R) Markdown code
Bold text **Bold text**
Italic text *Italic text*
Fixed width `Fixed width`
Link [Link](https://eps.leeds.ac.uk/maths) 
# Chapter

## Section

### Subsection

Formatting with (R) Markdown II

Writing writing writing writing.

- Leave a spare line
- Dash then space for bulleted lists
  1. Indent for sub-lists
  1. Use number, dot, space for enumerated lists
  1. Markdown will ensure consecutive numbering
- The end.

Writing writing writing writing.

  • Leave a spare line
  • Dash then space for bulleted lists
    1. Indent for sub-lists
    2. Use number, dot, space for enumerated lists
    3. Markdown will ensure consecutive numbering
  • The end.

Or, use the visual editor.

My first Bookdown document

Demo

Bookdown is trickier in RStudio Cloud, so I will revert to RStudio as installed on my computer.

In R Studio:

  • File
  • New Project
  • New Directory
  • Book project using bookdown
  • Create Project

demo

Theorem environments: good news

LaTeX:

\begin{theorem}[Fermat's last theorem] \label{FLT}
No three positive integers $a$, $b$, and $c$ satisfy the equation
$a^n + b^n = c^n$ for any integer value of $n$ greater than $2$.
\end{theorem}

As we saw in Theorem \ref{FLT}\dots

R Markdown, with the Bookdown package:

::: {.theorem #FLT name="Fermat's last theorem"}
No three positive integers $a$, $b$, and $c$ satisfy the equation
$a^n + b^n = c^n$ for any integer value of $n$ greater than $2$.
:::

As we saw in Theorem \@ref(thm:FLT)...

Theorem environments: old news

Previously,

```{theorem}
Your theorem here.
```

had been recommended, but the newer

::: {.theorem}
Your theorem here.
:::

method is better.

Theorem environments: bad news

Theorem-like environments in Bookdown are much less flexible than their LaTeX equivalents.

  • You have theorem, lemma, corollary, proposition, conjecture, definition, example, exercise, hypothesis
    • But, unlike LaTeX, you can’t define your own new environments
  • The numbering is, by force:
    • Theorem 2.1
    • Theorem 2.2
    • Lemma 2.1
    • Definition 2.1
    • Theorem 2.3
  • …although many prefer:
    • Theorem 2.1
    • Theorem 2.2
    • Lemma 2.3
    • Definition 2.4
    • Theorem 2.5

R code in R Markdown

Demo R code

Here is some R code:

data <- rnorm(100)
mean(data)
hist(data)

R experts will know that this:

  • Generates 100 normally distributed random variates
  • Calculates the mean of this data
  • Plots a histogram of this data

R code in R Markdown

I can include that R code it in an R Markdown document like this:

Here is some R code:

```{r}
data <- rnorm(100)
mean(data)
hist(data)
```

Note that the code is preceded with three “backticks” ``` and {r}, then ends with three more backticks.

The result is the following…

Here is some R code:

data <- rnorm(100)
mean(data)
## [1] -0.04438544
hist(data)

R code options

Note that the document displayed both the R commands and the output those commands produced.

Other code languages in R Markdown

It is apparently possible to use other programming languages in R Markdown in the same way I demonstrated R code.

  • Open with, for example: ```{python}

See Chapter 15 of the R Markdown cookbook for details.

I don’t know anyone local who’s tried this out and can advise us – audience?

Tips and tricks

Tables

Tables in (R) Markdown are a bit fiddly…

| "Plain" R Markdown         | RMarkdown with Bookdown    |
|:--------------------------:|:--------------------------:|
| Good for short documents   | Good for long documents    |
| Slightly simpler to write  | Slightly trickier to write |
| PDF or accessible HTML     | PDF or accessible HTML     |
| LaTeX equations            | LaTeX equations            |
| Single HTML page           | Multi-page website         |
| No theorem environments    | Theorem environments       |

… so I recommend this online Markdown table generator.

Alt text

It is good accessibility practice to describe pictures with “alt text”, for those using screenreaders.

Until recently, R Markdown simply re-used the caption as alt text…

  • …but often we want a brief caption for everyone and detailed alt text for screenreaders.

New syntax (as of April 2021):

```{r demo-pic, fig.cap="Histogram of data", fig.alt="Histogram of data, showing a
    bell-shaped symmetric curve around x = 0, dying away at x = -3 and x = +3"}
knitr::include_graphics("/figures/hist.png")
```
  • fig.cap = "..." gives the (short) caption
  • fig.alt = "..." gives the (long) alt text

TikZ pictures

If you use TikZ to draw pictures in LaTeX, you can do this in R Markdown too.

```{tikz demo-tikz, echo=FALSE, fig.cap="Caption", fig.alt="Alt text"}
\begin{tikzpicture}
\draw[thick] (0,0) rectangle (6,4);
\end{tikzpicture}
```

Default picture types:

  • PDF pictures in PDF documents
  • PNG pictures in HTML documents
    • Should be possible to produce SVG pictures – has anyone tried?

Styling

Many of us will want to knit Bookdown documents to both PDF and HTML.

  • LaTeX styling for PDF output can go in preamble.tex
    • You probably have your own favourite LaTeX tweaks
  • CSS styling for HTML output can go in style.css
    • I like to draw boxes around theorems, to make it clearer where the start/end
    • I like to indent new paragraphs like LaTeX does
    • I don’t want embedded videos to fill the whole page width
    • Feel free to copy my style.css file that does these (and some other things)

ClavertonDown

ClavertonDown is a package by the University of Bath, based on Bookdown.

It is arguably the gold standard in making accessible mathematical documents.

  • Knits simultaneously to 7 (seven!) different formats
  • High contrast colour scheme
  • Technologically a bit ramshackle
  • Has anyone local tried this?

Show/Hide

Phil will (I think) demonstrate this shortly.

Slides

R Markdown has a few formats for making slides.

  • The simplest – and least powerful/flexible – is ioslides (it seems to me) which is what these slides use
  • R Markdown source for these slides
  • In RStudio: File — New File — R Markdown and choose “Presentation”
  • This is the first time I’ve done slides in R Markdown – do any of the audience have more experience?

And finally

Should I use R Markdown / Bookdown or LaTeXML?

  • I want R (or other) code executed within my document: R Markdown with optional Bookdown

  • I want a system with a large user base that is under active development: R Markdown with optional Bookdown, probably

  • I want very smart appearance of an HTML website with minimal effort: Bookdown

  • I want to convert existing LaTeX notes with minimal fiddling around: LaTeXML

  • I want to produce HTML notes while learning minimal new stuff: LaTeXML

Read more…

Locals I know of with R Markdown and/or Bookdown experience: Luisa Cutillo, Serguei Komissarov, Richard Mann, Graham Murphy, Jochen Voss, Phil Walker, …

Final reminder

Visit https://mpaldridge.github.io/rmarkdown/ for:

  • These slides (with hyperlinks, and accessible by screenreaders)
  • R Markdown source for these slides
  • A handout, produced from exactly the same R Markdown source that made the slides themselves