Key motivation

Avoid repetitive and error-prone tasks.

You should use RMarkdown if you want to …

• concentrate on content rather than formatting
• share one document in many different formats (Markdown, PDF, Word, HTML)
• ensure correct citations and bibliographies
• switch between different citation formats
• integrate your data analysis automatically, not statically
• … and much more

Markdown vs markup

Markdown allows us to concentrate on document structure and content. We can then worry about styling and presentation later.

Markdown is a type of markup language (like HTML), but it is lightweight and more readable.

Markup samples

<p>This is a list:</p>
<ul>
<li>with some <strong>bold</strong> and</li>
<li>some <em>italic</em> text.</li>
</ul>
<p>And a <a href="https://bookdown.org/yihui/rmarkdown/">hyperlink</a>
for good measure.</p>

This is a list:

\begin{itemize}
\tightlist
\item
  with some \textbf{bold} and
\item
  some \emph{italic} text.
\end{itemize}

And a \href{https://bookdown.org/yihui/rmarkdown/}{hyperlink} for good
measure.

The same with Markdown

This is a list:

* with some **bold** and 
* some *italic* text.

And a [hyperlink](https://bookdown.org/yihui/rmarkdown/) for good measure.

Basic formatting and structuring

Lists and links

Even tables

An overview of core markdown syntax can be found in this RMarkdown book chapter and even more options in a condensed form as an RMarkdown cheat sheet.

‘R Markdown’ vs ‘Markdown’

• Purpose: dynamically weave together text, data and analysis workflows.
• This is accomplished with the knitr package, an R package conveniently integrated into the R Studio UI.

Differences to basic Markdown

• R Markdown files use the file extension .Rmd instead of .md.
• R Markdown files must start with a so-called YAML header section.

YAML - Yet Another Markup Language?

The YAML header must be placed at the beginning of a document and is enclosed by three dashes ---.

---
title: "Untitled"
output: html_document
date: '2022-06-14'
---

Above is the default YAML header when generating an RMarkdown file in R Studio.

YAML Ain’t Markup Language!

The YAML header contains meta-data (e.g. title, date, author(s) etc) as well as information about the output format and style.

A YAML header with more options might look like this:

---
title: "R Course SRC"
subtitle: "Module 3"
date: "`r Sys.Date()`"
author: 'Stefan Daume' 
output: 
  html_document:
    toc: yes
bibliography: references.bib 
link-citations: yes
---

Exercise

R Markdown: data-driven documents

• You can now integrate your analysis as R code into the document
• The analysis (i.e. the R code) is executed and the results updated when you knit the document.
• Text and code are interspersed.
• Code sections are included in code chunks like this.

```{r some-explanatory-label, echo=FALSE}
# here goes your R code
```

An example from the previous sessions

```{r life-expectancy, echo=FALSE}
library(gapminder)

gapminder %>% 
    group_by(year) %>%
    summarise(ale = mean(lifeExp)) %>%
    ggplot(aes(x = year, y = ale)) +
    geom_line(color = "orange") +
    labs(x = "Year", 
         y = "Average life expectancy") +
    theme_classic(base_size = 16)
```

Plots in R Markdown

```{r life-expectancy, echo=FALSE}
library(gapminder)

gapminder %>% 
    group_by(year) %>%
    summarise(ale = mean(lifeExp)) %>%
    ggplot(aes(x = year, y = ale)) +
    geom_line(color = "orange") +
    labs(x = "Year", 
         y = "Average life expectancy") +
    theme_classic(base_size = 16)
```

Remember the Markdown table format?

Dynamic tables with R Markdown

```{r}
# summarize gapminder data by continent
gapminder_latest <- gapminder %>% 
  filter(year == year_of_interest) %>%
  group_by(continent) %>%
  summarise(avrg_le = mean(lifeExp),
            avrg_gdp = mean(gdpPercap))
              
# print the results as a table
gapminder_latest %>%
  knitr::kable()
```

Customizing kable tables

```{r}
# summarize gapminder data by continent
gapminder_latest <- gapminder %>% 
  filter(year == year_of_interest) %>%
  group_by(continent) %>%
  summarise(avrg_le = mean(lifeExp),
            avrg_gdp = mean(gdpPercap))
              
# print the results as a table
gapminder_latest %>%
  knitr::kable(digits = c(0,1,2))
```

More expressive tables with kableExtra

Central ‘Setup’ code section

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)

library(readr)
library(dplyr)
library(ggplot2)
library(gapminder)

year_of_interest <- 2007
```

Simplify library import and prepare datasets for reference in the whole document.

Citations and bibliographies

One of the most useful and powerful features for researchers using R Markdown.

Requires a BibTeX database

A BibTeX database is simply a text file with the extension .bib and entries such as:

@misc{XieAllaire_et_2022,
  author = {Xie, Yihui and Allaire, J. J. and Grolemund, Garrett},
  title = {{R Markdown: The Definitive Guide}},
  url = {https://bookdown.org/yihui/rmarkdown/},
  urldate = {2022-06-07},
  year = {2022}
}

No need to write those. Export from your reference manager or journal pages.

Include citations

---
title: "R Course SRC"
subtitle: "Module 3"
date: "2022-06-16"
author: 'Stefan Daume' 
output: 
  html_document:
    toc: yes
bibliography: references.bib 
link-citations: yes
---

Include a bibliography

After presenting all results we have now reached the end of the document. Here should follow the bibliograpy.

# References

Add the header # References at the end of your document, knit and the complete bibliography is added to the output document.

Include a bibliography

After presenting all results we have now reached the end of the manuscript. As a final section should follow the bibliography.

# References

Switch citation and bibliography styles dynamically

---
title: "R Course SRC"
subtitle: "Module 3"
date: "2022-06-16"
author: 'Stefan Daume' 
output: 
  html_document:
    toc: yes
bibliography: references.bib 
link-citations: yes
csl: ecology-and-society.csl
---

Easy sharing and online publishing

1. knit your R Mardown document to HTML
2. push the HTML to Github (next part of this module)
3. enable sharing of Github Pages

This is how this presentation works (and the others before).

“Continous Analysis” as the ultimate goal

Key Resources

• R Markdown
  • R Markdown: The Definitive Guide (Xie, Allaire, and Grolemund 2022)
  • Cheatsheet: Dynamic documents with rmarkdown cheatsheet
• Git/Github:
  • Happy Git and GitHub for the useR (Bryan 2021)
  • “Excuse me, do you have a moment to talk about version control?” (Bryan 2017)
  • Advanced git use: Pro Git book (Chacon and Straub 2014)
  • How to write a great commit message

References

You need git and Github if … (non-exhaustive list)

• … you have files like this, but realise that this is not efficient
  • my_paper_draft_2021_05_16.docx
  • my_paper_draft_2021_05_18.docx
  • my_paper_draft_2021_05_19.docx
  • my_paper_draft_2021_05_19_v1.docx
  • my_paper_draft_2021_05_19_v2.docx
  • my_paper_draft_2021_05_19_v3_with_comments.docx
• … you are not creating regular backups of your work
• … you want to collaborate with others
• … you want to maintain projects rather than a single file (Google Doc)
• … you want to be able to easily revert back to previous versions of your work

Git history

• linux development, started 2005
• a version management system, i.e. tracks changes in project resources
• git takes snapshots of a managed project (image)
• distributed version control system (that means you always have a complete copy of your version history on your local computer)

Key concepts

• repo
• staging
• commit
• diff
• push
• pull
• branch (advanced)
• remote origin

Useful things

• .gitignore

Do this once:

• install git locally (see (Bryan 2021))
• sign up for a Github account
• create a personal access token
  • either via Github (https://github.com/settings/tokens)
  • or via R with: usethis::create_github_token()
  • and then store it with gitcreds::gitcreds_set()

Do this for every new project:

• create a Github repo first (follow the New project, Github first workflow in (Bryan 2021))
  • say yes to creating a README
  • why? its easiest! you have everything in place to create remote backups!
• copy the HTTPS link of your new repo
• then create an R Studio project with the option from “version control > git”

When your new project is set up

• make a change to the README.md (a useful project description)
• commit the changes of the README file
• and push to the remote Github repo
• check the Github repo