30 July, 2023

Rmarkdown

Documentation

  • code (R, python, java, c++ etc)
  • reports, manuscripts, theses (pdf, docx, html etc)

    How do we keep these in sync?

Markdown

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

Pandoc

Markdown - pandoc

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

pdf

Markdown - pandoc

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

html

Markdown - pandoc

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

docx

Markdown - pandoc

Rmarkdown

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

# This is the title

```{r summary, eval=TRUE, results='markup'}
x <- rnorm(10)
summary(x)
`` `

Quarto

---
title: Example markdown
author: D. Author
date: today
date-format: "DD/MM/YYYY"
---

# This is the title

```{r}
#| label: summary
#| eval: true
#| results: "markup"
x <- rnorm(10)
summary(x)
`` `

Quarto - knitr

quarto::quarto_render("file.Rmd", output_format = "html")


Rmarkdown/Quarto templates

Practical Quarto

Chunks

`` `{r}
#| label: readData
#| eval: true
mydata <- read.csv("data/myData.csv")
`` `

A chunk should represent a unit of work

  • read in data
  • perform a single set of processing
  • explore a single exploratory analysis
  • perform a analysis
  • validate model
  • summarise model
  • etc

Practical Quarto

Standalone

---
title: 'Example analysis'
author: D. Author
date: today
date-format: "DD/MM/YYYY"
---

Load the necessary packages.
`` `{r}
#| label: loadLibraries
#| eval: true
library(tidyverse)
`` `

Read in my data
`` `{r}
#| label: readData
#| eval: true
mydata <- read.csv("data/myData.csv")
`` `

Process the data:

- create a log-transformed version of `Var`

`` `{r}
#| label: processData
#| eval: true
mydata <- myData %>% mutate(lVar = log(Var))
`` `

Practical Rmarkdown

From external R script

---
title: 'Example analysis'
author: D. Author
date: today
date-format: "DD/MM/YYYY"
---

`` `{r}
#| label: read_chunks
knitr::read_chunk("script.R")
`` `

Load the necessary packages.
`` `{r}
#| label: loadLibraries
`` `

Read in my data
`` `{r}
#| label: readData
#| eval: true
`` `

Process the data:

- create a log-transformed version of `Var`

`` `{r}
#| label: processData
#| eval: true
`` `
##Load the necessary packages.

## ----loadLibraries
library(tidyverse)
## ----

##Read in my data

## ----readData
mydata <- read.csv("data/myData.csv")
## ----

## Process the data:
## - create a log-transformed version of `Var`

## ----processData
mydata <- myData %>% mutate(lVar = log(Var))
## ----

Showcase

Packages

  • extend functionality
  • installing
install.packages("dplyr")
  • namespaces
install.packages("dplyr::select()")
  • polymorphism
mean
## function (x, ...) 
## UseMethod("mean")
## <bytecode: 0x5565741860d0>
## <environment: namespace:base>
base:::mean.default
## function (x, trim = 0, na.rm = FALSE, ...) 
## {
##     if (!is.numeric(x) && !is.complex(x) && !is.logical(x)) {
##         warning("argument is not numeric or logical: returning NA")
##         return(NA_real_)
##     }
##     if (isTRUE(na.rm)) 
##         x <- x[!is.na(x)]
##     if (!is.numeric(trim) || length(trim) != 1L) 
##         stop("'trim' must be numeric of length one")
##     n <- length(x)
##     if (trim > 0 && n) {
##         if (is.complex(x)) 
##             stop("trimmed means are not defined for complex data")
##         if (anyNA(x)) 
##             return(NA_real_)
##         if (trim >= 0.5) 
##             return(stats::median(x, na.rm = FALSE))
##         lo <- floor(n * trim) + 1
##         hi <- n + 1 - lo
##         x <- sort.int(x, partial = unique(c(lo, hi)))[lo:hi]
##     }
##     .Internal(mean(x))
## }
## <bytecode: 0x556578f15510>
## <environment: namespace:base>

Coding style

lintr