---
title: "La famille *down"
author: "Nathalie Vialaneix, INRA/MIAT"
date: "RUG Toulouse, November 18th 2019"
output:
  xaringan::moon_reader:
    lib_dir: libs
    css: rladies
    seal: true
    nature:
      highlightStyle: github
      highlightLines: true
      countIncrementalSlides: false
---

```{r setup, include=FALSE}
options(htmltools.dir.version = FALSE)
```

## What is Markdown? (*.md files)

According to **Wikipedia**,

> *Markdown is a lightweight markup language with plain text formatting syntax. 
Its design allows it to be converted to many output formats.*

--

<img src="img/markdown.png" alt="markdown syntax" width="800"/>

---

## Why Markdown?

* formatting text and documents is easy

* probably the most used lightweight markup language for numeric documents
(especially technical documentations)

--

**But**: is sometimes a bit limited if you want to have custom outputs

---

## What is **R**Markdown? (*.Rmd files)

* developed by RStudio (and especially by Yihui Xie)

* combines Markdown documents with **R** scripts (or python, C++, bash, ...) to
produce dynamic (and even interactive) documents

--

<img src="img/rmarkdown.png" alt="rmarkdown syntax" width="800"/>

---

## What is **R**Markdown? (*.Rmd files)

* developed by RStudio (and especially by Yihui Xie)

* combines Markdown documents with **R** scripts (or python, C++, bash, ...) to
produce dynamic (and even interactive) documents

* also available as **R** notebooks (similar to Jupyter notebooks)

--

<img src="img/rnotebook.png" alt="rnotebook syntax" width="800"/>

---
class: middle, center, inverse

## Basic RMarkdown documents

---

## What do you need? (certified exact on linux)

* **R**

* RStudio (not mandatory but highly recommended) and if you don't know how to 
install it on linux, please, ask your sysadmin

* **packages**: at least `knitr` but other packages (`rmarkdown`, `markdown`, 
...)

* pandoc to obtain different output types from `*.md` files: Rmd $\rightarrow$ 
md $\rightarrow$ (with pandoc) HTML

* it is best to have $\LaTeX$ installed to render maths or obtain PDF documents

--

### Basic demo...

---

## Yaml headers

<img src="img/yaml1.png" alt="yalm header 1" width="400"/>

---

## Yaml headers

<img src="img/yaml2.png" alt="yalm header 2" width="400"/>

<img src="img/yaml2-out1.png" alt="yalm out 1" width="400"/> &nbsp; &nbsp;
<img src="img/yaml2-out2.png" alt="yalm out 2" width="300"/>

---

## Yaml headers

<img src="img/yaml3.png" alt="yalm header 1" width="400"/>

---

## Text formatting

<img src="img/format_markdown1.png" alt="markdown format 1" width="600"/>

---

## Text formatting

<img src="img/format_markdown2.png" alt="markdown format 2" width="600"/>

---

## Code chunk and options

<img src="img/code_chunk.png" alt="code chunk" width="500"/>

--

Inline code can be included with 

<img src="img/inline_code.png" alt="inline_code" width="100"/>

---

## Code chunk and options

**Types of chunks**:

<img src="img/types_of_chunk.png" alt="types of chunk" width="200"/>

---

## Code chunk and options

**A few useful options**:

* `eval=TRUE/FALSE`: run (or not) the code in the chunk

* `include=TRUE/FALSE`: include (or not) the chunk in the final document

* `echo=TRUE/FALSE`: include (or not) the output of the code in the final 
document

* `results='markup'/'hide'/'asis'/'hold'`: display the output of the code 
normally/not/as it is (useful when combined with `xtable` for HTML outputs of
tables for instance)/all in a row after the code chunk is displayed (and not 
one by one)

* `error/message/warning=TRUE/FALSE`: display (or not) the different types of
messages obtained from the code

* `cache=TRUE/FALSE`: cache the result of the chunk

* `fig.width/height/align/cap/...`: different options on rendering of figures

---

## Run code and output types

**Run the whole document**:

<img src="img/run_normal.png" alt="run normal" width="200"/>

**Run interactively**:

<img src="img/run_interactive.png" alt="run normal" width="300"/> &nbsp; &nbsp;
<img src="img/run_interactive2.png" alt="run normal" width="250"/>

---

## Run code and output types

**Run the whole document externally**:
```{r eval=FALSE}
# render document
knitr::render("mybeautifuldoc.Rmd", output_format = "HTML",
              encoding = "UTF-8")
# extract R code from chunk
knitr::purl("mybeautifuldoc.Rmd")
```

<img src="img/purl_output.png" alt="purl output" width="300"/>

**Useful to run a report with computationally intensive code on a server!** See:
http://www.nathalievialaneix.eu/doc/pdf/tutoR_cluster.pdf

---

## Run code and output types

* HTML: often light and can include interactive graphics (with `ggplotly` for
instance)
  + HTML and $\LaTeX$ equations can be included directly in the document
  + **But**: problems rendering equations without internet connexion, you need
  to copy several folders in addition to the file to make it work
  + problems partially solved with the option: `self_contained: true` (in HTML
  headers)
  
--
  
* PDF: self-contained but often heavier, needs $\LaTeX$ installed
  + usually longer to knit (pandoc produces a TeX document and then $\LaTeX$ is
  run)
  + can account for $\LaTeX$ options in the headers (including bibliography)
  + can use the power of $\LaTeX$ to obtain multiple version documents (student
  and teacher versions for instance)

--

(and, of course, **forget Word**!)

---
class: middle, center, inverse

## Advanced options for RMarkdown documents

---

## Appearance and style in HTML documents

* `theme` (in header) specifies the [Bootswatch](https://bootswatch.com/3/) 
theme to use

* `highlight` (in header) specifies the highlighting style to use (supports
`tango`, `pygments`, `kate`, `monochrome`, `espresso`, `zenburn`, `haddock`, 
`breezedark` and `textmate`)

--

**Or**: you can use your own CSS with `css` (in header)

---

## $\LaTeX$ options in PDF documents

<img src="img/latex_options.png" alt="latex options" width="800"/>

---

## $\LaTeX$ options in PDF documents

**Bibliography** is managed using:

* the citation engine (default is `pandoc-citeproc`): 
  + `citation_package: natbib` (header, in `pdf_document`)
  + `citation_package: biblatex` (header, in `pdf_document`)

* the bibtex file: `bibliograph: mybib.bib` (header, in `pdf_document`)

---

## $\LaTeX$ options in PDF documents

More custom options in headers:

<img src="img/latex_header_includes.png" alt="latex includes in header" width="400"/>

---

## $\LaTeX$ multiple version document

<img src="img/def_version.png" alt="latex def version" width="600"/>

```{tex latexVersions, eval=FALSE}
\if \version1 \\
... in teacher version only
\fi
```

---

## A **very** cool stuff: parameters!

How were useR! invoices generated (and sent)?

<img src="img/params.png" alt="parameters" width="300"/>

and then, used in the Rmd file through `params$participant`, `params$name`, ...

---

## A **very** cool stuff: parameters!

... or passed externally using `render`:

```{r sendInvoices, eval=FALSE}
## loop over users ############################################################
render("invoice-base.Rmd",
       params = list(participant = paste(users$FIRSTNAME[cur], users$LASTNAME[cur]),
                     name = users$"Billing.name"[cur],
                     address1 = users$"Billing.address..street."[cur],
                     address2 = users$"Billing.address..other."[cur],
                     address3 = users$"Billing.address..state..town.and.zip.code."[cur],
                     country = users$"Billing.address..country."[cur],
                     uid = users$UID[cur],
                     date = gsub("-", "/", as.character(as.Date(saved_dates[cur]))),
                     total = users$Amount[cur],
                     method = users$Payment.type[cur],
                     refpaybox = users$transaction[cur]
       ),
       output_file = paste0("invoices/", file_names[cur]))

# send email
send.mail(from = "contact@user2019.fr",
          to = ...,
          attach.files = paste0("invoices/", file_names[cur]))
```

---

## A **very** cool stuff: parameters!

* used to produce automatic report on standard analyses (*e.g.*, differential
analysis of RNAseq data with only two conditions)

* used to run standard analyses on multiple datasets at once

* parameters can be set interactively using the knit buttom

* constrains can be declared for parameters

<img src="img/constrained_parameters.png" alt="constrained params" width="200"/>

---

## Want to know more?

* **R** Markdown [cheatsheet](https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)

* **R** Markdown [reference](https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf)

* **R** Markdown [book](https://bookdown.org/yihui/rmarkdown)

---
class: middle, center, inverse

## Other types of documents

---

## Slides

Using the same approach, you can make:

* **R** presentation (included in **R** studio) but with rather limited features

(my [old class on **R**](http://www.nathalievialaneix.eu/teaching/tide/#/) was made using it)

* `xarigan` slides (HTML), also developed by Yihui Xie (see Chapter 7 of the 
**R** Markdown book): easy to use and includes many options but if you want to
obtain a custom result, you better be an HTML/CSS ninja, can be exported in PDF
with `pagedown::chrome_print` (but I do not recommend it)

this presentation was made with xaringan using the `rladies` css

* `binb` (binb is not beamer) provides functionality to use themes for beamer
directly in RMarkdown: if you want to obtain a custom result, you better be a 
$\LaTeX$ ninja, output PDF, long to compile (as beamer is)

(this [seminar](https://www.slideshare.net/tuxette/a-short-introduction-to-singlecell-rnaseq-analyses)
has been made using binb)

---

## Posters

[drposter](https://github.com/bbucior/drposter) (example is courtesy of Pierre 
Neuvial)

<img src="img/drposter.png" alt="constrained params" width="800"/>

(easy to use: columns are defined by headers and sub-headers) but also a bit
hard to customize

---

## Documentation for packages

`pkgdown`: Generate cool package documentation from your package

Example from [adjclust](~/Private/Travail/Recherche/HiC/adjclust/docs/index.html)

---

## Books

`bookdown`: generate printer ready books and ebooks from **R** Markdown

I never used it so no feedback...

---

## Website

`blogdown`: generate website from RMarkdown pages using 
[hugo](https://gohugo.io/) (python static website generator). 

The [missing data reference website](https://rmisstastic.netlify.com/) is 
generated through `blogdown` and thanks to its hugo support is automatically
published on netlify.

---
class: middle, center, inverse

## Next to come...?

<img src="img/coffee.jpg" width="100"/>

## `coffeedown`... ?



<!-- https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf -->

<!-- https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf -->

<!-- https://github.com/juba/rmdformats -->

<!-- http://larmarange.github.io/analyse-R/rmarkdown-les-rapports-automatises.html -->

<!-- https://bookdown.org/yihui/rmarkdown -->
