background-image: url(images/bg1.jpg)
background-size: cover
class: hide-slide-number

:::::::::: { .grid grid: 50% 50% / 1fr;} 
::: item center

# <span style="text-shadow: 2px 2px 30px white;">Communicating with Data <br> via R Markdown</span>

<br><br>
## <span style="color:#f9af2b;text-shadow: 2px 2px 30px black;">Reproducible Reports</span>

:::

::: item center shade_black animated bounceInUp slower

Presented by Emi Tanaka

School of Mathematics and Statistics

<img src="assets/USydLogo-white.svg" style="width:200px"><br>
<span><i class="fas  fa-envelope faa-float animated "></i></span>  dr.emi.tanaka@gmail.com
<span><i class="fab  fa-twitter faa-float animated faa-fast "></i></span>  @statsgen

4th October 2019 | COMBINE | Sydney, Australia

:::

::::::::::

::: { .shade_black .pos .font_small width:20%;right:10px;bottom:20%;padding:5px;border: solid 5px white;}

<i class="fas fa-exclamation-circle"></i> These slides are viewed best by Chrome and occasionally need to be refreshed if elements did not load properly. See here for <a href=session2.pdf style="color:white!important"/>PDF <i class="fas fa-file-pdf"></i></a>.

:::

---

# In a nutshell 🥜

.font_large[
R Markdown integrates .yellow[**text**] + .yellow[`code`] in one source document with ability to knit to many output formats (via Pandoc).

]

---

::: grid

::: item 
# Text in Markdown

```markdown
# Header 1
## Header 2

- Unordered list 1 
- Unordered list 2
 
1. Ordered list 1
1. Ordered list 2
 
_This is italic._ *This too.*
__This is bold.__ **This too.**
_**This is bold & italic.**_
```

<p></p>

:::

::: item

[Output]{.header .bg-blue .white padding:10px; border: solid 2px black;}

# Header 1
## Header 2

* Unordered list 1 
* Unordered list 2

1. Ordered list 1
1. Ordered list 2
 
_This is italic._ *This too.*
__This is bold.__ **This too.**
_**This is bold & italic.**_

:::

::: {.bottom_abs .width100 .bg-indigo .white padding-left:10px;}
Go to RStudio > Help > Markdown Quick Reference
:::

---

# Shortcut for inserting code chunk

::: grid

::: item

In RStudio .Rmd <i class="far fa-file"></i> press

* Mac: <kbd>⌘</kbd> + <kbd>⌥</kbd> + <kbd>i</kbd>

* PC: <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>i</kbd>

to insert a chunk of R code

::: font_large

````markdown
```{r}

```
````

:::
:::

::: item

:::

---

# Chunk options: <code>echo</code> & <code>eval</code>

::: grid 
::: item

````markdown
```{r, echo = FALSE}
plot(speed ~ dist, cars)
```
````
<center>
<i class="fas fa-arrow-down"></i>
</center>

<p></p>

:::

::: item

````markdown
```{r, eval = FALSE}
plot(speed ~ dist, cars)
```
````

```r
plot(speed ~ dist, cars)
```

<p></p>

:::

---

There are many more .yellow[chunk options].

Can you name 5 other ones?

Hint: https://yihui.name/knitr/options/

(We'll explore some later.)

---

# Valid chunk options

* Chunk options must be written in **one line**, i.e. no line break.

* All option values must be **valid R expressions**. Exception is the chunk name. E.g.
   * `fig.path = figures/` is not valid but <br>`fig.path = "figures/"` is valid
   * `eval = true` is not valid but<br> `eval = runif(1) > 0.5` is valid

---

# Chunk names (or labels)

The chunk below is called `plot1`.
````markdown
```{r plot1}
ggplot(cars, aes(dist, speed)) + geom_point()
```
````

All chunks have a label regardless of whether it is explicitly supplied or not.

<i class="fa fa-exclamation-triangle"></i> Do not include spaces, "_" or punctuation marks in your chunk name!

---

::: pad10

# Inline R Commands

```markdown
Today's date is `r Sys.Date()`.
```

Today's date is 2019-10-03.

```markdown
The value of $\pi$ is `r pi`.
```

The value of `$\pi$` is 3.1415927.

* Note: the inline command needs to be R commands.

* Inline command does *not* `echo` and always `eval`uates.

<p></p>

:::

---

# Go through

* `challenge-02.Rmd`
* `challenge-03.Rmd`
* `challenge-04.Rmd`
* `challenge-05.Rmd`
* `challenge-06.Rmd`

---

# R Markdown is not just for R

::: grid

::: item

````markdown
```{python, echo = FALSE}
a = [1, 2, 3]
a[0]
```
````

```
## 1
```
<p></p>

:::

::: item

````markdown
```{bash, echo = FALSE}
date +%B
```
````
<center>
<i class="fas fa-arrow-down"></i>
</center>

```
## October
```
<p></p>
::::

::::

---

Can you name some other engines?

Hint: https://yihui.name/knitr/demo/engines/

---

# YAML - YAML Ain't Markup Language

:::: grid

::: item

Basic format
```markdown
---
key: value
---
```
:::

::: item

Example

```
---
title: "Communicating with Data via R Markdown"
subtitle: "Reproducible Reports"
author: "Emi Tanaka"
date: "`r Sys.Date()`"
output: html_document
---
```

There must be a space after "`:`"!
<p></p>
:::

:::

---

# Metadata

All YAML data are stored in `rmarkdown::metadata` as list.

```r
rmarkdown::metadata$title
```

```
## [1] "Communicating with Data via R markdown"
```

```r
rmarkdown::metadata$author
```

```
## [1] "Emi Tanaka"
```

---

# Default (minimal) html output

```
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta name="author" content="Emi Tanaka" />
<meta name="date" content="2019-10-04" />
<title>Communicating with Data via R Markdown</title>
</head>

<body>
<h1 class="title toc-ignore">Communicating with Data via R Markdown</h1>
<h3 class="subtitle">Reproducible Reports</h3>
<h4 class="author">Emi Tanaka</h4>
<h4 class="date">2019-10-04</h4>
</body>
</html>
```
<p></p>

::: { .bubble1 .pos width:300px;left:70%;top:48%;}

html meta data

:::

::: { .bubble1 .pos width:650px;left:43%;top:75%;}

Default html template add special YAML key values to file automatically

:::

::: {.pos top:10px; right:20px;}
output<br>
<img src = "images/minimal-html-output.png" width = "250px" style="border: solid 3px black;"/>

:::

---

::: pad10

# YAML structure

* White spaces indicate structure in YAML - don't use tabs though!
* Same as R, you can comment lines by starting with `#`.
* YAML is case sensitive.
* A `key` can hold multiple values.

```markdown
key: 
  - value 1
  - value 2
```

```markdown
key: [value 1, value 2]
```

:::

---

# YAML with multiple key values

```
---
title: "Communicating with Data via R Markdown"
author: 
 - "Emi Tanaka"
 - "Accomplice"
output: html_document
---
```

```
<body>
<h1 class="title toc-ignore">Communicating with Data via R Markdown</h1>
<h4 class="author">Emi Tanaka</h4>
*<h4 class="author">Accomplice</h4> 
</body>
```

<p></p>

::: {.pos top:10px; right:20px;}
output<br>
<img src = "images/minimal-html-output2.png" width = "250px" style="border: solid 3px black;"/>

:::

---

::: {text-align: left;}

# `key` can contain `key`s

```
---
output: 
  html_document:
    toc: true
    toc_float: true
---
```
<p></p>
What does this do?

:::

(Note: white space is important)

---

# Values spanning multiple lines

```markdown
---
title: >
  this is a\ 
  single line\
  
abstract: |
  this value spans\
  many lines and\
  appears as it is\
  
output: pdf_document
---

`r rmarkdown::metadata$title`
`r rmarkdown::metadata$abstract`
```

::: {.pos top:80px; right:20px;}
output<br>
<img src = "images/minimal-pdf-output.png" width = "800px" style="border: solid 3px black;"/>

:::

---

# Go through

`challenge-07.Rmd`

---

# Parametrized Report

````markdown
---
title: "Parameterized Report"
params:
  species: setosa
output: html_document
---

```{r, message = FALSE, fig.dim = c(3,2)}
library(tidyverse)
iris %>% 
*  filter(Species==params$species) %>% 
   ggplot(aes(Sepal.Length, Sepal.Width)) +
   geom_point(aes(color=Species))
```
````

::: {.pos top:10px; right:10px;}
output<br>
<img src = "images/parameterised-report-eg1.png" width = "550px" style="border: solid 3px black;"/>

:::

---

::: grid
::: item 
# Knit with Parameters
```markdown
---
title: "Parameterized Report"
params:
  species: 
    label: "Species"
    value: setosa
    input: select
    choices: [setosa, versicolor, virginica]
  color: red
  max:
    label: "Maximum Sepal Width"
    value: 4
    input: slider
    min: 4
    max: 5
    step: 0.1
output: html_document
---
```

:::

::: item

````markdown
```{r, message = params$printmsg, fig.dim = c(3,2)}
library(tidyverse)
iris %>% 
  filter(Species==params$species) %>% 
  filter(Sepal.Width < params$max) %>% 
  ggplot(aes(Sepal.Length, Sepal.Width)) +
  geom_point(aes(color=Species), 
             color = params$color)
```
````

:::

---

# Shiny Report Generator
::: grid
::: item 
```markdown
---
title: "Parameterized Report"
params:
  species: 
    label: "Species"
    value: setosa
    input: select
    choices: [setosa, versicolor, virginica]
  color: red
  max:
    label: "Maximum Sepal Width"
    value: 5
    input: slider
    min: 4
    max: 5
    step: 0.05
output: html_document
---
```

:::

::: item

# &nbsp;

:::

---

# R Markdown via Command Line

::: grid

::: item

`demo-render.Rmd`

````markdown
---
title: "Parameterized Report"
params:
  species: setosa
output: html_document
---

```{r, message = FALSE, fig.dim = c(3,2)}
library(tidyverse)
iris %>% 
*  filter(Species==params$species) %>% 
   ggplot(aes(Sepal.Length, Sepal.Width)) +
   geom_point(aes(color=Species))
```
````

:::

::: item

You can knit this file via R command by using `render` function:

```r
library(rmarkdown)
render("demo-render.Rmd")
```

You can overwrite the YAML values by supplying arguments to `render`:

```r
library(rmarkdown)
render("demo-render.Rmd", 
       output_format = "pdf_document",
       params = list(species = "virginica"))
```

:::

---

# Go through

`challenge-08.Rmd` and `challenge-09.Rmd`

---

# Themes: `html_document`

<div id="myModal" class="modal">
  <div id="caption"></div>
  <span class="close" onclick="document.getElementById('myModal').style.display='none'">&times;</span>
  <iframe class="modal-content" id="img01"></iframe><br>
</div>

You can change the look of the html document by specifying themes:
::: grid

::: item

* `default` <img class="modalImg" alt="default"/> 
* `cerulean` <img class="modalImg" alt="cerulean"/> 
* `journal`  <img class="modalImg" alt="journal"/> 
* `flatly` <img class="modalImg" alt="flatly"/> 
* `darkly` <img class="modalImg" alt="darkly"/> 
* `readable` <img class="modalImg" alt="readable"/> 
* `spacelab` <img class="modalImg" alt="spacelab"/> 
* `united` <img class="modalImg" alt="united"/>

:::

::: item

* `cosmo` <img class="modalImg" alt="cosmo"/> 
* `lumen` <img class="modalImg" alt="lumen"/> 
* `paper` <img class="modalImg" alt="paper"/> 
* `sandstone` <img class="modalImg" alt="sandstone"/> 
* `simplex` <img class="modalImg" alt="simplex"/> 
* `yeti` <img class="modalImg" alt="yeti"/> 
* `NULL`  <img class="modalImg" alt="null"/>

:::

::: item

```markdown
output: 
  html_document:
    theme: cerulean
```

These [bootswatch](https://bootswatch.com/) themes attach the whole bootstrap library which makes your html file size larger.

:::

---

# `prettydoc`

<div id="myModal2" class="modal">
  <div id="caption2"></div>
  <span class="close" onclick="document.getElementById('myModal2').style.display='none'">&times;</span>
  <iframe class="modal-content" id="img02"></iframe><br>
</div>

::: grid

::: item

`prettydoc` 📦 is a community contributed `theme` that is light-weight:

* `cayman` <img class="modalImg2" alt="cayman"/> 
* `tactile` <img class="modalImg2" alt="tactile"/> 
* `architect` <img class="modalImg2" alt="architect"/> 
* `leonids` <img class="modalImg2" alt="leonids"/> 
* `hpstr` <img class="modalImg2" alt="hpstr"/>

:::

::: item

```markdown
output: 
  prettydoc::html_pretty:
    theme: cayman
```

See more about it below:

https://prettydoc.statr.me/

:::

---

# `rmdformats`

<div id="myModal3" class="modal">
  <div id="caption3"></div>
  <span class="close" onclick="document.getElementById('myModal3').style.display='none'">&times;</span>
  <iframe class="modal-content" id="img03"></iframe><br>
</div>

::: grid

::: item

`rmdformats` 📦 contains four built-in `html` formats:

* `readthedown` <img class="modalImg3" alt="readthedown"/> 
* `html_clean` <img class="modalImg3" alt="html_clean"/> 
* `html_docco` <img class="modalImg3" alt="html_docco"/> 
* `material` <img class="modalImg3" alt="material"/>

:::

::: item

You can use these formats by simply specifying the output in YAML as below:

```markdown
output: rmdformats::readthedown
```

See more about it below:

https://github.com/juba/rmdformats

:::

---

# `rticles` - LaTeX Journal Article Templates

<div id="myModal4" class="modal">
  <div id="caption4"></div>
  <span class="close" onclick="document.getElementById('myModal4').style.display='none'">&times;</span>
  <iframe class="modal-content" id="img04"></iframe><br>
</div>
::: grid
::: item 
* `acm` <img class='modalPdf' alt='acm_article'/>
* `acs` <img class='modalPdf' alt='acs_article'/>
* `aea` <img class='modalPdf' alt='aea_article'/>
* `agu` <img class='modalPdf' alt='agu_article'/>
* `amq` <img class='modalPdf' alt='amq_article'/>
* `ams` <img class='modalPdf' alt='ams_article'/>
* `asa` <img class='modalPdf' alt='asa_article'/>
* `biometrics` <img class='modalPdf' alt='biometrics_article'/>
* `copernicus` <img class='modalPdf' alt='copernicus_article'/>

:::

::: item

* `elsevier` <img class='modalPdf' alt='elsevier_article'/>
* `frontiers` <img class='modalPdf' alt='frontiers_article'/>
* `ieee` <img class='modalPdf' alt='ieee_article'/>
* `jss` <img class='modalPdf' alt='jss_article'/>
* `mdpi` <img class='modalPdf' alt='mdpi_article'/>
* `mnras` <img class='modalPdf' alt='mnras_article'/>
* `peerj` <img class='modalPdf' alt='peerj_article'/>
* `plos` <img class='modalPdf' alt='plos_article'/>

:::

::: item 
* `pnas` <img class='modalPdf' alt='pnas_article'/>
* `rjournal` <img class='modalPdf' alt='rjournal_article'/>
* `rsos` <img class='modalPdf' alt='rsos_article'/>
* `rss` <img class='modalPdf' alt='rss_article'/>
* `sage` <img class='modalPdf' alt='sage_article'/>
* `sim` <img class='modalPdf' alt='sim_article'/>
* `springer` <img class='modalPdf' alt='springer_article'/>
* `tf` <img class='modalPdf' alt='tf_article'/>

::::

::: {.bottom_abs .width100 .bg-indigo .white padding-left:10px;}
Go to RStudio > File > New File > R Markdown ... > From Template
:::

---

# External Files in Templating

::: grid

::: item

* When using `rticles`, each journal usually require external files (e.g. `cls` or image files).
* These external components are stored within the package.
* If you are drafting an Rmd template with external components then you need to extract these to your folder first.

:::

::: item bg-gray

**GUI**

* `RStudio > File > New File > R Markdown ... > From Template`

**Command line**

```r
rmarkdown::draft("file.Rmd", 
 template = "biometrics_article",
 package = "rticles")
```

:::

---

# More customisation needed?

<br>

Default templates for many output are found at

<br>

<a href="https://github.com/jgm/pandoc-templates">https://github.com/jgm/pandoc-templates</a>

</center>

<br>

We'll go through the latex template.

---

I found this nice latex template online.

::: grid

::: item

You can see it at `main.pdf`.

:::

::: item

It was compiled from `main.tex`.

:::

::::

::: {.bottom_abs .width100 .bg-indigo .white padding-left:10px;}
Find `main.tex` and `main.pdf` in `demo` folder.
:::

---

How do I use this template so that I can write contents from an Rmd file instead?

---

# Templating

We will use

```markdown 
---
output: 
  pdf_document: 
    template: main.tex
---

But nothing written in the body shows up in the output!
```

You need to add `$body$` in the latex template file where you want the body of the md file to appear.

---

# Templating: few more tweaks

* R Markdown needs a few more special tweaks before `\begin{document}` in latex template:

```latex
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
$if(highlighting-macros)$
$highlighting-macros$
$endif$
```

* These are *minimum* tweaks needed for a LaTeX template.
* You can find common tweaks (including for beamer) at 
<a href="https://github.com/jgm/pandoc-templates">https://github.com/jgm/pandoc-templates</a>
* You can define your own tweaks but it is better practice to use the ones defined in pandoc template rather than trying to reinvent the wheel.

---

# How pandoc template works: `key`

::: grid

::: item

`Rmd` <i class="fas fa-file"></i>

```markdown
---
title: "COMBINE 2019"
author: "Emi Tanaka"
output:
  pdf_document: 
    template: "template.tex"
---
```

YAML meta data can be used by surrounding `key` with $.

:::

::: item

`template.tex` <i class="fas fa-file"></i>

```latex

\documentclass{article}
\title{$title$}
\author{$author$}
\date{}

\begin{document}

\maketitle

\end{document}

```

::: {.center font-family:"Computer Modern"!important;}

:::

---

# How pandoc template works: if statements

::: grid

::: item

`Rmd` <i class="fas fa-file"></i>

```markdown
---
title: "COMBINE 2019"
author: "Emi Tanaka"
output:
  pdf_document: 
    template: "template.tex"
---
```

Simple "if null statements".

:::

::: item

`template.tex` <i class="fas fa-file"></i>

```latex

\documentclass[
$if(fontsize)$
$fontsize$,
$endif$
]{article}
\title{$title$}
\author{$author$}
\date{}

\begin{document}

\maketitle

\end{document}

```

:::

---

# How pandoc template works: accessing list

::: grid

::: item

`Rmd` <i class="fas fa-file"></i>

```markdown
---
title: "COMBINE 2019"
author:
 - name: "Rachel Wang"
   email: "rachel.wang@sydney.edu.au"
 - name: "Connor Smith"
   email: "connor.smith@sydney.edu.au"
output:
  pdf_document: 
    template: "template.tex"
---
```

Here it will become

:::

::: item

`template.tex` <i class="fas fa-file"></i>

```latex

\documentclass{article}
\title{$title$}
\author{
$for(author)$
$author.name$$sep$ \and 
$endfor$
}
\date{}

\begin{document}

\maketitle

\end{document}

```

:::

---

# Go through

`challenge-10.Rmd`

---

# Cross Reference

::: grid

::: item

* When you make a header via Rmd
```
# Some Header
```
 an id is created automatically.
* The id is created by replacing .red[space with `-`] and making it .red[all lower case].
* Now you can link to this header by `[some text](#some-header)`.
* Cross references work for both pdf and html outputs.

:::

::: item

:::

---

# Direct Reference for `html`

::: grid

::: item

* For `html` output, you can also give a link directly to the relevant section.
* E.g. open `demo-header.html` in the `demo` folder in a web browser. 
* Append say `#chicken-data` to the url. It should look like 
.center[
`demo-header.html#chicken-data`
]
* It should have taken you to straight to the corresponding header.

:::

::: item

:::

---

# User-defined id

::: grid

::: item

* You can define your own id by appending `{#your-id}`.

```markdown
# Some header {#header1}
```
* Now you can link to this header with the id `header1`.
* Note there should be no space in the id name!

:::

::: item

:::

---

# Bibliography

* BibTeX citation style format is used to store references in `.bib` files.
* Remember that you can get most BibTeX citation for R packages `citation` function. (Scroll below to see the BibTeX citation).

```r
citation("xaringan")
```

```
## 
## To cite package 'xaringan' in publications use:
## 
##   Yihui Xie (2019). xaringan: Presentation Ninja. R package
##   version 0.9. https://CRAN.R-project.org/package=xaringan
## 
## A BibTeX entry for LaTeX users is
## 
##   @Manual{,
##     title = {xaringan: Presentation Ninja},
##     author = {Yihui Xie},
##     year = {2019},
##     note = {R package version 0.9},
##     url = {https://CRAN.R-project.org/package=xaringan},
##   }
```
]

---

# Citations

::: grid

::: item

* You can include BibTeX by specifying the `bib` file at YAML as:

```markdown
bibliography: bibliography.bib
```

[@bibtex-key] <i class="fas fa-arrow-right"></i> (Author et al. 2019)

@bibtex-key <i class="fas fa-arrow-right"></i> Author et al. 2019

* See `demo-citation.Rmd` in the demo folder.

:::

::: item

:::

---

.yellow[R Markdown] is such an *indispensible tool* for making documents, especially if you have plan to *include statistical output*.

How do you use (or plan to use) <br>R Markdown?

---

# People that made R Markdown possible

The development of R Markdown is largely thanks to

* .yellow[Yihui Xie] <br>*Software Engineer at RStudio*<br> for `knitr`

* .yellow[John MacFarlane] <br>*Professor of Philosophy at UC Berkeley*<br> for `pandoc`

* and .yellow[many contributors] behind the development of these tools.

---

background-image: url(images/bg1.jpg)
background-size: cover
class: hide-slide-number

::: grid

::: {.item .shade_black .animated .slideInLeft border-right-style:solid; border-right-color:white; }

# That's it!

These slides are made using `xaringan` R-package.

The workshop materials are licensed under [<img src="images/cc.svg" style="height:1em"/><img src="images/by.svg" style="height:1em"/><img src="images/sa.svg" style="height:1em"/>](https://creativecommons.org/licenses/by-sa/3.0/au/).

Emi Tanaka

<i class="fas fa-envelope faa-float animated"></i> dr.emi.tanaka@gmail.com<br>
<i class="fab fa-twitter faa-float animated faa-fast"></i>  @statsgen

:::

::: {.item .shade_black .checklist .animated .slideInRight border-left-style: solid; border-right-color: white;}

# Check that you can:

<ul>
<li>Understand how YAML changes .Rmd</li><li>Understand how to manipulate chunks in .Rmd</li><li>Understand how to change the template in .Rmd</li><li>Understand how to cross-reference and do citations</li>
</ul>

:::

Notes for current slide

Notes for next slide

Communicating with Data
via R Markdown

Reproducible Reports

Presented by Emi Tanaka

School of Mathematics and Statistics

dr.emi.tanaka@gmail.com @statsgen

4th October 2019 | COMBINE | Sydney, Australia

These slides are viewed best by Chrome and occasionally need to be refreshed if elements did not load properly. See here for PDF .

1/47

In a nutshell 🥜

R Markdown integrates text + code in one source document with ability to knit to many output formats (via Pandoc).

2/47

Text in Markdown

# Header 1
## Header 2
- Unordered list 1 
- Unordered list 2
1. Ordered list 1
1. Ordered list 2
_This is italic._ *This too.*
__This is bold.__ **This too.**
_**This is bold & italic.**_

Output

Header 1

Header 2

Unordered list 1
Unordered list 2

Ordered list 1
Ordered list 2

This is italic. This too. This is bold. This too. This is bold & italic.

Go to RStudio > Help > Markdown Quick Reference

3/47

Shortcut for inserting code chunk

In RStudio .Rmd press

Mac: ⌘ + ⌥ + i

PC: Ctrl + Alt + i

to insert a chunk of R code

```{r}
```

4/47

Chunk options: `echo` & `eval`

```{r, echo = FALSE}
plot(speed ~ dist, cars)
```

```{r, eval = FALSE}
plot(speed ~ dist, cars)
```

plot(speed ~ dist, cars)

5/47

There are many more chunk options.

Can you name 5 other ones?

Hint: https://yihui.name/knitr/options/

(We'll explore some later.)

6/47

Valid chunk optionsChunk options must be written in one line, i.e. no line break. 
All option values must be valid R expressions. Exception is the chunk name. E.g.fig.path = figures/ is not valid but 
fig.path = "figures/" is valid
eval = true is not valid but
 eval = runif(1) > 0.5 is valid

7/47

Chunk names (or labels)

The chunk below is called plot1.

```{r plot1}
ggplot(cars, aes(dist, speed)) + geom_point()
```

All chunks have a label regardless of whether it is explicitly supplied or not.

Do not include spaces, "_" or punctuation marks in your chunk name!

8/47

Inline R Commands

Today's date is `r Sys.Date()`.

Today's date is 2019-10-03.

The value of $\pi$ is `r pi`.

The value of is 3.1415927.

Note: the inline command needs to be R commands.

Inline command does not echo and always evaluates.

9/47

Go throughchallenge-02.Rmd
challenge-03.Rmd
challenge-04.Rmd
challenge-05.Rmd
challenge-06.Rmd

25:00
10/47

R Markdown is not just for R```{python, echo = FALSE}
a = [1, 2, 3]
a[0]
```

## 1

```{bash, echo = FALSE}
date +%B
```

## October

11/47

Can you name some other engines?

Hint: https://yihui.name/knitr/demo/engines/

12/47

YAML - YAML Ain't Markup Language

Basic format

---
key: value
---

Example

---
title: "Communicating with Data via R Markdown"
subtitle: "Reproducible Reports"
author: "Emi Tanaka"
date: "`r Sys.Date()`"
output: html_document
---

There must be a space after ":"!

13/47

Metadata

All YAML data are stored in rmarkdown::metadata as list.

rmarkdown::metadata$title

## [1] "Communicating with Data via R markdown"

rmarkdown::metadata$author

## [1] "Emi Tanaka"

14/47

Default (minimal) html output

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="author" content="Emi Tanaka" />
<meta name="date" content="2019-10-04" />
<title>Communicating with Data via R Markdown</title>
</head>
<body>
<h1 class="title toc-ignore">Communicating with Data via R Markdown</h1>
<h3 class="subtitle">Reproducible Reports</h3>
<h4 class="author">Emi Tanaka</h4>
<h4 class="date">2019-10-04</h4>
</body>
</html>

html meta data

Default html template add special YAML key values to file automatically

output

15/47

YAML structure
White spaces indicate structure in YAML - don't use tabs though!
Same as R, you can comment lines by starting with #.
YAML is case sensitive.
A key can hold multiple values. 

key: 
  - value 1
  - value 2

key: [value 1, value 2]

16/47

YAML with multiple key values

---
title: "Communicating with Data via R Markdown"
author: 
 - "Emi Tanaka"
 - "Accomplice"
output: html_document
---

<body>
<h1 class="title toc-ignore">Communicating with Data via R Markdown</h1>
<h4 class="author">Emi Tanaka</h4>
<h4 class="author">Accomplice</h4> 
</body>

output

17/47

`key` can contain `key`s

---
output: 
  html_document:
    toc: true
    toc_float: true
---

What does this do?

(Note: white space is important)

18/47

Values spanning multiple lines

---
title: >
  this is a\ 
  single line\
abstract: |
  this value spans\
  many lines and\
  appears as it is\
output: pdf_document
---
`r rmarkdown::metadata$title`
`r rmarkdown::metadata$abstract`

output

19/47

Go through

challenge-07.Rmd

10:00

20/47

Parametrized Report

---
title: "Parameterized Report"
params:
  species: setosa
output: html_document
---
```{r, message = FALSE, fig.dim = c(3,2)}
library(tidyverse)
iris %>% 
   filter(Species==params$species) %>% 
   ggplot(aes(Sepal.Length, Sepal.Width)) +
   geom_point(aes(color=Species))
```

output

21/47

Knit with Parameters

---
title: "Parameterized Report"
params:
  species: 
    label: "Species"
    value: setosa
    input: select
    choices: [setosa, versicolor, virginica]
  color: red
  max:
    label: "Maximum Sepal Width"
    value: 4
    input: slider
    min: 4
    max: 5
    step: 0.1
output: html_document
---

```{r, message = params$printmsg, fig.dim = c(3,2)}
library(tidyverse)
iris %>% 
  filter(Species==params$species) %>% 
  filter(Sepal.Width < params$max) %>% 
  ggplot(aes(Sepal.Length, Sepal.Width)) +
  geom_point(aes(color=Species), 
             color = params$color)
```

22/47

Shiny Report Generator

---
title: "Parameterized Report"
params:
  species: 
    label: "Species"
    value: setosa
    input: select
    choices: [setosa, versicolor, virginica]
  color: red
  max:
    label: "Maximum Sepal Width"
    value: 5
    input: slider
    min: 4
    max: 5
    step: 0.05
output: html_document
---

23/47

R Markdown via Command Line

demo-render.Rmd

---
title: "Parameterized Report"
params:
  species: setosa
output: html_document
---
```{r, message = FALSE, fig.dim = c(3,2)}
library(tidyverse)
iris %>% 
   filter(Species==params$species) %>% 
   ggplot(aes(Sepal.Length, Sepal.Width)) +
   geom_point(aes(color=Species))
```

You can knit this file via R command by using render function:

library(rmarkdown)
render("demo-render.Rmd")

You can overwrite the YAML values by supplying arguments to render:

library(rmarkdown)
render("demo-render.Rmd", 
       output_format = "pdf_document",
       params = list(species = "virginica"))

24/47

Go through

challenge-08.Rmd and challenge-09.Rmd

10:00

25/47

Themes: `html_document`

You can change the look of the html document by specifying themes:

default
cerulean
journal
flatly
darkly
readable
spacelab
united

cosmo
lumen
paper
sandstone
simplex
yeti
NULL

output: 
  html_document:
    theme: cerulean

These bootswatch themes attach the whole bootstrap library which makes your html file size larger.

26/47

`prettydoc`

prettydoc 📦 is a community contributed theme that is light-weight:

cayman
tactile
architect
leonids
hpstr

output: 
  prettydoc::html_pretty:
    theme: cayman

See more about it below:

https://prettydoc.statr.me/

27/47

`rmdformats`

rmdformats 📦 contains four built-in html formats:

readthedown
html_clean
html_docco
material

You can use these formats by simply specifying the output in YAML as below:

output: rmdformats::readthedown

See more about it below:

https://github.com/juba/rmdformats

28/47

`rticles` - LaTeX Journal Article Templates

acm
acs
aea
agu
amq
ams
asa
biometrics
copernicus

elsevier
frontiers
ieee
jss
mdpi
mnras
peerj
plos

pnas
rjournal
rsos
rss
sage
sim
springer
tf

Go to RStudio > File > New File > R Markdown ... > From Template

29/47

External Files in Templating

When using rticles, each journal usually require external files (e.g. cls or image files).
These external components are stored within the package.
If you are drafting an Rmd template with external components then you need to extract these to your folder first.

GUI

RStudio > File > New File > R Markdown ... > From Template

Command line

rmarkdown::draft("file.Rmd", 
 template = "biometrics_article",
 package = "rticles")

30/47

More customisation needed?

Default templates for many output are found at

https://github.com/jgm/pandoc-templates

We'll go through the latex template.

31/47

I found this nice latex template online.

You can see it at main.pdf.

It was compiled from main.tex.

Find main.tex and main.pdf in demo folder.

32/47

How do I use this template so that I can write contents from an Rmd file instead?

33/47

Templating

We will use

---
output: 
  pdf_document: 
    template: main.tex
---
But nothing written in the body shows up in the output!

34/47

Templating

We will use

---
output: 
  pdf_document: 
    template: main.tex
---
But nothing written in the body shows up in the output!

You need to add $body$ in the latex template file where you want the body of the md file to appear.

34/47

Templating: few more tweaks

R Markdown needs a few more special tweaks before \begin{document} in latex template:

\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
$if(highlighting-macros)$
$highlighting-macros$
$endif$

These are minimum tweaks needed for a LaTeX template.
You can find common tweaks (including for beamer) at https://github.com/jgm/pandoc-templates
You can define your own tweaks but it is better practice to use the ones defined in pandoc template rather than trying to reinvent the wheel.

35/47

How pandoc template works: `key`

Rmd

---
title: "COMBINE 2019"
author: "Emi Tanaka"
output:
  pdf_document: 
    template: "template.tex"
---

YAML meta data can be used by surrounding key with $.

template.tex


\documentclass{article}
\title{$title$}
\author{$author$}
\date{}
\begin{document}
\maketitle
\end{document}

COMBINE 2019
Emi Tanaka

36/47

How pandoc template works: if statements

Rmd

---
title: "COMBINE 2019"
author: "Emi Tanaka"
output:
  pdf_document: 
    template: "template.tex"
---

Simple "if null statements".

template.tex


\documentclass[
$if(fontsize)$
$fontsize$,
$endif$
]{article}
\title{$title$}
\author{$author$}
\date{}
\begin{document}
\maketitle
\end{document}

37/47

How pandoc template works: accessing list

Rmd

---
title: "COMBINE 2019"
author:
 - name: "Rachel Wang"
   email: "rachel.wang@sydney.edu.au"
 - name: "Connor Smith"
   email: "connor.smith@sydney.edu.au"
output:
  pdf_document: 
    template: "template.tex"
---

Here it will become

\author{Rachel Wang \and Connor Smith}

template.tex


\documentclass{article}
\title{$title$}
\author{
$for(author)$
$author.name$$sep$ \and 
$endfor$
}
\date{}
\begin{document}
\maketitle
\end{document}

38/47

Go through

challenge-10.Rmd

05:00

39/47

Cross ReferenceWhen you make a header via Rmd# Some Header
an id is created automatically.
The id is created by replacing space with - and making it all lower case.
Now you can link to this header by [some text](#some-header).
Cross references work for both pdf and html outputs.

40/47

Direct Reference for `html`

For html output, you can also give a link directly to the relevant section.
E.g. open demo-header.html in the demo folder in a web browser.
Append say #chicken-data to the url. It should look like
demo-header.html#chicken-data
It should have taken you to straight to the corresponding header.

41/47

User-defined idYou can define your own id by appending {#your-id}.

# Some header {#header1}

Now you can link to this header with the id header1.
Note there should be no space in the id name!

42/47

BibliographyBibTeX citation style format is used to store references in .bib files.
Remember that you can get most BibTeX citation for R packages citation function. (Scroll below to see the BibTeX citation).
citation("xaringan")

## 
## To cite package 'xaringan' in publications use:
## 
##   Yihui Xie (2019). xaringan: Presentation Ninja. R package
##   version 0.9. https://CRAN.R-project.org/package=xaringan
## 
## A BibTeX entry for LaTeX users is
## 
##   @Manual{,
##     title = {xaringan: Presentation Ninja},
##     author = {Yihui Xie},
##     year = {2019},
##     note = {R package version 0.9},
##     url = {https://CRAN.R-project.org/package=xaringan},
##   }
43/47

Citations

You can include BibTeX by specifying the bib file at YAML as:

bibliography: bibliography.bib

[@bibtex-key] (Author et al. 2019)

@bibtex-key Author et al. 2019

See demo-citation.Rmd in the demo folder.

44/47

R Markdown is such an indispensible tool for making documents, especially if you have plan to include statistical output.

How do you use (or plan to use)
R Markdown?

45/47

People that made R Markdown possible

The development of R Markdown is largely thanks to

Yihui Xie
Software Engineer at RStudio
for knitr

John MacFarlane
Professor of Philosophy at UC Berkeley
for pandoc

and many contributors behind the development of these tools.

46/47

That's it!

These slides are made using xaringan R-package.

The workshop materials are licensed under .

Emi Tanaka

dr.emi.tanaka@gmail.com
@statsgen

Check that you can:

Understand how YAML changes .Rmd
Understand how to manipulate chunks in .Rmd
Understand how to change the template in .Rmd
Understand how to cross-reference and do citations

47/47

In a nutshell 🥜

R Markdown integrates text + code in one source document with ability to knit to many output formats (via Pandoc).

2/47

Paused

Help

Keyboard shortcuts

↑, ←, Pg Up, k	Go to previous slide
↓, →, Pg Dn, Space, j	Go to next slide
Home	Go to first slide
End	Go to last slide
Number + Return	Go to specific slide
b / m / f	Toggle blackout / mirrored / fullscreen mode
c	Clone slideshow
p	Toggle presenter mode
t	Restart the presentation timer
?, h	Toggle this help

Esc	Back to slideshow

Communicating with Data via R Markdown

Reproducible Reports

In a nutshell 🥜

Text in Markdown

Header 1

Header 2

Shortcut for inserting code chunk

Chunk options: echo & eval

Valid chunk options

Chunk names (or labels)

Inline R Commands

Go through

R Markdown is not just for R

YAML - YAML Ain't Markup Language

Metadata

Default (minimal) html output

YAML structure

YAML with multiple key values

key can contain keys

Values spanning multiple lines

Go through

Parametrized Report

Knit with Parameters

Shiny Report Generator

R Markdown via Command Line

Go through

Themes: html_document

prettydoc

rmdformats

rticles - LaTeX Journal Article Templates

External Files in Templating

More customisation needed?

Templating

Templating

Templating: few more tweaks

How pandoc template works: key

How pandoc template works: if statements

How pandoc template works: accessing list

Go through

Cross Reference

Direct Reference for html

User-defined id

Bibliography

Citations

People that made R Markdown possible

That's it!

Check that you can:

In a nutshell 🥜

Help

Communicating with Data
via R Markdown

Chunk options: `echo` & `eval`

`key` can contain `key`s

Themes: `html_document`

`prettydoc`

`rmdformats`

`rticles` - LaTeX Journal Article Templates

How pandoc template works: `key`

Direct Reference for `html`