# NeSI R Markdown Webinar

###### tags: `nesi`

Link to this page: https://hackmd.io/@murraycadzow/nesi-rmarkdown-webinar

[toc]

## Resources

[R Markdown - The Definitive Guide](https://bookdown.org/yihui/rmarkdown/)

[R Markdown Cheatsheet](https://www.rstudio.org/links/r_markdown_cheat_sheet)

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

[Rstudio Rmarkdown Introduction](https://rmarkdown.rstudio.com/index.html)

[RMarkdown Driven Development](https://emilyriederer.netlify.com/post/rmarkdown-driven-development/)

[One R Markdown document, fourteen demos](https://resources.rstudio.com/rstudio-conf-2020/one-r-markdown-document-fourteen-demosyihui-xie)

### Follow along prerequisites

- R and Rstudio installed
- R packages `rmarkdown`, `knitr`, `tidyverse`
- Examples: https://github.com/murraycadzow/nesi_rmarkdown_webinar

## Motivation

_Image from [www.phdcomics.com](http://phdcomics.com/comics/archive.php?comicid=1689)_
<br>
**Reproducibility**
Produce a document that includes description of analysis and the code that creates it.
<br>
R Markdown provides a mechanism to create compilable documents

Benefits:
- Markdown formatted text areas
- Code plus results of code embedded
- Linear flow
- Self contained output
- Narative driven code/literate programming
- interactive/animated content (html formats)
- **Plain text file**

Limitations
- Parallelism is limited
- Language of choice might not be supported
- Check pointing

## Components

- YAML
- Markdown
- Code chunks

### YAML

#### Output Formats

RMarkdown let you have a single source document and compile to multiple output formats such as:

- Documents
- html
- pdf
- doc
- Presentations
- ioslides
- slidy
- beamer
- Powerpoint

It is also possible to create multiple formats in a single render call using:

rmarkdown::render(input = "my_file.Rmd", output = "all")

#### Markdown

In the text areas you can use Markdown to format your text. You can also use LaTeX commands or HTML to control formatting.

#### Code chunks

Inside these code chunks is where you can put R code, or other supported languages, such as bash, sql, etc. The language being used in the code chunk goes inside the curly braces.

You can also do 'inline' code in the text area by using a single back tick and "r" such as:
1 + 1 = \`r 1 + 1\`

Where the result would be `1 + 1 = 2` in the compile text.

##### Other Languages

See [R Markdown - The Definitive Guide](https://bookdown.org/yihui/rmarkdown/language-engines.html)

Other language support is available, run `names(knitr::knit_engines$get())` to get a a list of language engines supported.

Using R and Python together with the `reticulate` R package enables some data to be passed between R and python.

## Figures

Code that creates figures such as plots can be executed and the resulting figure embedded in the document. Having the code lets people see how the figure was created, plus if the data changes the figure adapts.

## Tables

For tables, you can either create them using markdown, or you can generate them from the data with R. Using R to generate tables reduces errors due to copy and pasting.

=======
Questions
=======

## Organisation

For a 'one off' analysis this might not be necessary, however, analyses evolve and thinking about how to make your document more maintainable is a good idea.

### RMarkdown driven dev

_Image from [RMarkdown Driven Development](https://emilyriederer.netlify.com/post/rmarkdown-driven-development/)_

An excellent blog from Emily Riederer talks about "RMarkdown Driven Development"

The main stages of this include

1. Removing Troublesome Elements
2. Rearrange the Chunks
3. Reduce Duplication with Functions
4. Migrate from RMarkdown to R Project (Modularize your files!)
5. Convert your R Project to a Package

This is project dependent and each project might have a different stopping point.

## Beyond RMarkdown

- Blogdown
- Bookdown
- Pkgdown

## Another level of reproducibility

Wrap your RMarkdown into a container or as part of a workflow

- Environments
- Docker/singularity
- Workflows

## Useful extra R packages

[here](https://github.com/r-lib/here) - Use relative references based on the project root directory

[kableExtra](https://github.com/haozhu233/kableExtra) - Expands functionality of `knitr::kable()`
[gt](https://github.com/rstudio/gt) - Another table package
[renv](https://github.com/rstudio/renv) - Use environments with R
[rticles](https://github.com/rstudio/rticles) - Rmarkdown templates of journal article LaTeX templates