29 April, 2022

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)
`` `

Rmarkdown - knitr

rmarkdown::render("file.Rmd", output_format = "html_document")


Rmarkdown templates

plos

pnas

elsevier

Practical Rmarkdown

Chunks

`` `{r 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 Rmarkdown

Standalone

---
title: 'Example analysis'
author: D. Author
date: 24-07-2021
---

Load the necessary packages.
`` `{r loadLibraries, eval=TRUE}
library(tidyverse)
`` `

Read in my data
`` `{r readData, eval=TRUE}
mydata <- read.csv('data/myData.csv')
`` `

Process the data:

- create a log-transformed version of `Var`

`` `{r processData, eval=TRUE}
mydata <- myData %>% mutate(lVar = log(Var))
`` `

Practical Rmarkdown

From external R script

---
title: 'Example analysis'
author: D. Author
date: 24-07-2021
---

`` `{r, eval=TRUE}
knitr::read_chunk('script.R')
`` `

Load the necessary packages.
`` `{r loadLibraries, eval=TRUE}
`` `

Read in my data
`` `{r readData, eval=TRUE}
`` `

Process the data:

- create a log-transformed version of `Var`

`` `{r 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: 0x5558fffa0230>
## <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 (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: 0x555904f50750>
## <environment: namespace:base>

Coding style

lintr