Writing reproducible manuscripts in R Markdown

class: center, middle, inverse, title-slide

.title[
# Writing reproducible manuscripts in R Markdown
]
.author[
### Camille Landesvatter<br>.font90[Mannheim Centre for European Research (MZES), University of Mannheim]<br><svg viewBox="0 0 512 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M502.3 190.8c3.9-3.1 9.7-.2 9.7 4.7V400c0 26.5-21.5 48-48 48H48c-26.5 0-48-21.5-48-48V195.6c0-5 5.7-7.8 9.7-4.7 22.4 17.4 52.1 39.5 154.1 113.6 21.1 15.4 56.7 47.8 92.2 47.6 35.7.3 72-32.8 92.3-47.6 102-74.1 131.6-96.3 154-113.7zM256 320c23.2.4 56.6-29.2 73.4-41.4 132.7-96.3 142.8-104.7 173.4-128.7 5.8-4.5 9.2-11.5 9.2-18.9v-19c0-26.5-21.5-48-48-48H48C21.5 64 0 85.5 0 112v19c0 7.4 3.4 14.3 9.2 18.9 30.6 23.9 40.7 32.4 173.4 128.7 16.8 12.2 50.2 41.8 73.4 41.4z"></path></svg> <a href="mailto:camille.landesvatter@uni-mannheim.de"><code>camille.landesvatter@uni-mannheim.de</code></a><br><svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M336.5 160C322 70.7 287.8 8 248 8s-74 62.7-88.5 152h177zM152 256c0 22.2 1.2 43.5 3.3 64h185.3c2.1-20.5 3.3-41.8 3.3-64s-1.2-43.5-3.3-64H155.3c-2.1 20.5-3.3 41.8-3.3 64zm324.7-96c-28.6-67.9-86.5-120.4-158-141.6 24.4 33.8 41.2 84.7 50 141.6h108zM177.2 18.4C105.8 39.6 47.8 92.1 19.3 160h108c8.7-56.9 25.5-107.8 49.9-141.6zM487.4 192H372.7c2.1 21 3.3 42.5 3.3 64s-1.2 43-3.3 64h114.6c5.5-20.5 8.6-41.8 8.6-64s-3.1-43.5-8.5-64zM120 256c0-21.5 1.2-43 3.3-64H8.6C3.2 212.5 0 233.8 0 256s3.2 43.5 8.6 64h114.6c-2-21-3.2-42.5-3.2-64zm39.5 96c14.5 89.3 48.7 152 88.5 152s74-62.7 88.5-152h-177zm159.3 141.6c71.4-21.2 129.4-73.7 158-141.6h-108c-8.8 56.9-25.6 107.8-50 141.6zM19.3 352c28.6 67.9 86.5 120.4 158 141.6-24.4-33.8-41.2-84.7-50-141.6h-108z"></path></svg> <a href="https://www.mzes.uni-mannheim.de/d7/de/profiles/camille-marie-landesvatter"><code>MZES Website</code></a><br><svg viewBox="0 0 384 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <g groupmode="layer" id="layer6" label="icon"> <path style="stroke-width:0.0647871" d="M 343.75868,106.66243 V 79.430205 L 363.52365,63.999997 H 149.63354 L 20.476345,176.2736 h 85.656075 c -0.15534,2.12494 -0.21914,4.04644 -0.21914,6.22563 0,20.84472 7.2192,38.08662 21.67203,51.86089 14.45284,13.79702 32.25124,20.64784 53.32651,20.64784 4.92319,0 9.75059,-0.36794 14.43842,-1.02419 -2.90722,6.50082 -4.37457,12.52302 -4.37457,18.14228 0,9.87526 4.49924,20.4304 13.46715,31.6418 -39.23377,2.6705 -68.06112,9.73264 -86.43702,21.16322 -10.53108,6.49907 -19.000207,14.70396 -25.390349,24.5311 -6.390569,9.89933 -9.577754,20.51525 -9.577754,31.9616 0,9.64822 2.062375,18.33611 6.21907,26.06233 4.156694,7.7263 9.577757,14.07047 16.312223,18.98408 6.71825,4.96781 14.46899,9.10088 23.219,12.46874 8.73429,3.34378 17.40643,5.71858 26.06106,7.06258 8.62707,1.34222 17.20471,1.9985 25.70579,1.9985 13.46887,0 26.95353,-1.73428 40.54711,-5.18707 13.56165,-3.48461 26.28022,-8.64143 38.17105,-15.4927 11.85935,-6.80488 21.51545,-16.0865 28.9219,-27.7183 7.39024,-11.67998 11.09457,-24.80499 11.09457,-39.33613 0,-11.01584 -2.24964,-21.03852 -6.7502,-30.14073 -4.46864,-9.07202 -9.93785,-16.54102 -16.45271,-22.34403 -6.5008,-5.81263 -12.99987,-11.15539 -19.51512,-15.9679 -6.50083,-4.84488 -12.00021,-9.75058 -16.46884,-14.8129 -4.4848,-5.04657 -6.73444,-10.05419 -6.73444,-14.98395 0,-4.92145 1.73422,-9.67183 5.21588,-14.26559 3.45451,-4.6095 7.67376,-9.04795 12.60967,-13.30571 4.93756,-4.24944 9.87523,-8.96788 14.79665,-14.13302 4.92147,-5.14719 9.14072,-11.82739 12.60971,-20.00822 3.48467,-8.17907 5.20318,-17.44489 5.20318,-27.75679 0,-13.4527 -2.54714,-24.46065 -7.54735,-33.31348 -0.59369,-1.02243 -1.21757,-1.80338 -1.87511,-3.02225 l 56.90745,-46.672136 v 17.118526 c -7.39373,0.92969 -6.62422,5.34582 -6.62422,10.6352 v 128.66719 c 0,5.95832 4.8751,10.83382 10.83386,10.83382 h 3.98869 c 5.95835,0 10.83386,-4.87506 10.83386,-10.83382 V 117.29282 c 0,-5.27669 0.77741,-9.68801 -6.56167,-10.63039 z M 236.39865,329.14114 c 1.14099,0.7503 3.7039,2.78075 7.7184,6.03838 4.0495,3.24319 6.797,5.69582 8.26567,7.41432 1.43851,1.66381 3.5792,4.16501 6.37617,7.54734 2.81268,3.3744 4.7184,6.30394 5.71853,8.73425 1.00016,2.4767 2.01603,5.46089 3.04636,8.94556 0.98567,3.44488 1.48486,6.97595 1.48486,10.56169 0,17.04813 -6.56338,29.68007 -19.65604,37.85915 -13.125,8.18083 -28.76651,12.27368 -46.93767,12.27368 -9.18709,0 -18.2031,-1.09289 -27.06247,-3.1951 -8.84322,-2.11665 -17.31192,-5.3362 -25.39035,-9.60185 -8.07846,-4.25771 -14.57754,-10.20337 -19.50072,-17.79659 -4.93764,-7.64012 -7.40645,-16.41464 -7.40645,-26.24962 0,-10.32022 2.79692,-19.28987 8.42233,-26.90588 5.59343,-7.62564 12.93774,-13.3919 22.03208,-17.3154 9.0624,-3.94582 18.24946,-6.74232 27.56166,-8.39827 9.31221,-1.7023 18.79679,-2.555 28.43842,-2.555 4.46862,0 7.93582,0.25115 10.40465,0.69607 0.45456,0.21918 3.03188,2.07025 7.73456,5.56326 4.70401,3.46237 7.62565,5.59519 8.75047,6.38401 z m -3.35823,-100.5779 c -7.40648,8.85938 -17.73454,13.2882 -30.95363,13.2882 -11.85933,0 -22.29766,-4.76482 -31.26554,-14.31195 -8.99984,-9.52309 -15.42235,-20.32803 -19.34408,-32.43061 -3.93752,-12.10871 -5.90585,-23.98423 -5.90585,-35.648 0,-13.6942 3.59542,-25.35184 10.7809,-34.97598 7.18727,-9.64952 17.49915,-14.48477 30.93786,-14.48477 11.87507,0 22.37423,5.03825 31.43704,15.15677 9.09434,10.08482 15.60961,21.41303 19.5169,33.96799 3.92176,12.5392 5.87345,24.52979 5.87345,35.98399 0,13.44658 -3.70256,24.60984 -11.07663,33.45436 z" id="path2"></path> </g></svg> <a href="https://scholar.google.de/citations?user=S-lC2DgAAAAJ&hl=de"><code>Camille Landesvatter</code></a><br><br>
]
.date[
### Mannheim Open Science Office, Online Event<br /> June 21, 2023
]

---

# What is a Reproducible Manuscript?

.pull-left[
<blockquote><font size="5">A reproducible manuscript is a research document that includes all the necessary information and code to reproduce the reported findings and results.</font size></blockquote>

<blockquote><font size="5">It combines the traditional elements of a manuscript (text, figures, tables) with the computational code used for data analysis and visualizations.</font size></blockquote>
]

.pull-right[
- Reproducible Manuscripts versus "Traditional Workflows"?

<div class="figure" style="text-align: center">
<img src="./figures/screenshot-workflow.png" alt="A 'traditional' workflow with 3 open tabs" width="100%" />
<p class="caption">A 'traditional' workflow with 3 open tabs</p>
</div>
]
---
class: center, middle
<font size="6">
How do you currently incorporate your research findings into your paper manuscript?

Let us know on Slido:<br>
https://app.sli.do/event/m8n4VwLfmo1a9yHT6NViyH
</font size>

---

# Why Reproducible Manuscripts?

- .cyan[Trust and Credibility]: Reproducible manuscripts enhance the integrity of research, as it allows for thorough scrutiny of methods, data, and analyses. They allow others to independently verify and replicate the reported results.

- .cyan[Efficiency]: Adopting reproducible workflows improves efficiency, as researchers can easily update and modify their work, easily spot errors and save time in the long run.

* .cyan[Sharing and Collaboration]: By providing transparent and accessible documentation of methods, data, and code, reproducible manuscripts promote collaboration and allow others to build upon and replicate the research findings. This efficient sharing of knowledge fosters faster progress in scientific discovery and innovation.
---

# How to create Reproducible Manuscripts...

- ... using R Markdown?

<div class="figure" style="text-align: center">
<img src="slides_files/figure-html/unnamed-chunk-2-1.png" alt="Coding Language // Framework // R Markdown related packages" width="80%" />
<p class="caption">Coding Language // Framework // R Markdown related packages</p>
</div>
---

# How to create Reproducible Manuscripts...

Repositories on GitHub:

<font size = "4">
- https://github.com/rstudio/rmarkdown

- https://github.com/rstudio/bookdown

- https://github.com/rstudio/pagedown

- https://github.com/rstudio/blogdown

- https://github.com/yihui/xaringan

- https://github.com/rstudio/rticles

- https://github.com/cjvanlissa/worcs

- https://github.com/ClaudioZandonella/trackdown

</font size>

---
# R Markdown

- R Markdown is a powerful tool that allows you to blend text, code, and output in a single document.
- essential tool for reproducible research and creating dynamic reports, manuscripts, presentations and many more.

**rmarkdown** package (Allaire et al. 2023)

- the powerhouse behind R Markdown, providing the tools and functions to render your documents into different formats like HTML, PDF, Word, and more.
- allows you to effortlessly switch between output formats, making it easy to share your work with collaborators, supervisors, or even publish it online.
  - but also consider documenting your data analysis process with Rmd
- using R Markdown eliminates the need for manual updates or copy-pasting code and results into different documents, saving you time and reducing the chances of errors.

---
# R Markdown: Template (Bauer & Landesvatter 2023)

OSF: https://osf.io/q395s

.pull-left[

<div class="figure" style="text-align: center">
<img src="./figures/osf-rmd.png" alt="Bauer, P.; Landesvatter, C. 2023" width="100%" />
<p class="caption">Bauer, P.; Landesvatter, C. 2023</p>
</div>

]

.pull-right[
How can you use this templates?
  * download all available files: 
    * 'paper.rmd'
    * 'references.bib'
    * 'data.csv'
    * 'american-sociological-association.csl'
  * open .Rproj
  * start creating your first manuscript in rmd, use our working paper (wp) style or modify the styling sheets
]

---
# Pagedown (Xie et al. 2022)

* R Markdown based extension
* create paginated HTML reports that are converted into PDF format
* add headers, footers, page numbers, and more to your documents
* by specifying YAML metadata, you can customize various aspects of your document's style, such as fonts, colors, margins, and page dimensions
  * HTML and CSS styling sheets
* pagedown offers a range of pre-built templates for different purposes, such as CVs, theses, letters, and journal articles, making it easy to get started
* create professional-looking documents without the need for complex LaTeX formatting or advanced CSS knowledge
* greate choice for generating polished reports or preparing documents that require a print-ready PDF format

---
# Pagedown: Template (Bauer & Landesvatter 2023)

.pull-left[
<font size="4">

OSF: https://osf.io/k8jhx/

<div class="figure" style="text-align: center">
<img src="./figures/osf-pagedown.png" alt="Bauer, P.; Landesvatter, C. 2023" width="100%" />
<p class="caption">Bauer, P.; Landesvatter, C. 2023</p>
</div>
]

</font size>

.pull-right[
<img src="./figures/pagedown-wp-style.png" width="100%" style="display: block; margin: auto;" />
]

---
# Pre-Requisites for R Markdown and Pagedown

Both require: installation of R + recommended: Rstudio IDE

* R Markdown: 
  * rmarkdown package + other dependencies, e.g. knitr package
  * for working without Rstudio: Pandoc Installation
  * for PDF output: a LaTeX distribution, e.g. tinytex (a lightweight, cross-platform LaTeX distribution)

```r
install.packages(c('tinytex', 'rmarkdown'))
tinytex::install_tinytex()
```

* Pagedown:
  * rmarkdown package + other dependencies, e.g. knitr 
  * pagedown package
  * no LaTeX!

```r
remotes::install_github('rstudio/pagedown')
```

---
class: center, middle

# Structure of a Reproducible Manuscript (.Rmd)

Demonstration in R Studio<br>
<svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg">  <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg>: [/paulcbauer/Writing_a_reproducable_paper_in_rmarkdown](https://github.com/paulcbauer/Writing_a_reproducable_paper_in_rmarkdown)

---
class: center, middle

# Some more packages (Xaringan, Trackdown, Quarto)

---
# Xaringan (Xie 2021)

- R Markdown extension that enables the creation of stylish and interactive slideshows using HTML and CSS

- R Studio add-in Infinite Moon Reader

- preview live changes while editing your files or even manuscript

- avoids manually knitting your document each time

```r
xaringan::inf_mr()
```

- launches a local web server via the servr package (Xie 2021) and displays your pages in the RStudio viewer

- each time you save your document (Ctrl/Cmd+S) xaringan updates your pages in the viewer

---
# Xaringans' Infinite Moon Reader

---
# Trackdown

- R trackdown package for improving collaborative writing

- collaborative workflow for the writing and editing process with R Markdown
- upload local .Rmd (or .Rnw) file as a plain-text file to Google Drive
- use Markdown (or LaTeX) syntax and Google Docs options (e.g. suggest edits, add comments)
- review and integrate all contributions
- the final document can be downloaded and rendered locally

---
# R trackdown package for improving collaborative writing

```r
remotes::install_github("claudiozandonella/trackdown",
                        build_vignettes = TRUE)
```

```r
upload_file(file = "trackdown_example.Rmd",
            gpath = "trackdown_example",
            hide_code = TRUE)
```

- `download_file()`
- `update_file()`
- `render_file()`

---
# Quarto

- Quarto is often referred to as "the next generation of R Markdown"

- main goal: seamlessly integrate narrative text and code, allowing for the generation of nicely formatted output documents

- like R Markdown, Quarto utilizes Knitr to execute R code, which means that most existing Rmd files can be rendered in Quarto without requiring extensive modifications

---
# Rmd versus Quarto

- Quarto comes with enhanced support for interactive and dynamic documents (versus static documents)

- Quarto supports multiple programming languages (e.g. R, Python, Julia, and Observable JS) - by adding Lua filters to the pandoc metadata, it achieves a cross-language standardization of outputs

- Template? OSF: https://osf.io/ur4xn

<div class="figure" style="text-align: center">
<img src="./figures/osf-quarto.png" alt="Bauer, P.; Landesvatter, C. 2023" width="50%" />
<p class="caption">Bauer, P.; Landesvatter, C. 2023</p>
</div>

---
class: center, middle

# Thank you!

Xaringan Presentation on GitHub Pages: https://clandesv.github.io/reproducible-manuscripts-with-rmarkdown/slides.html