Markdown and code

Quarto

Roland Krause

Rworkshop

Tuesday, 6 February 2024

Introduction

Motivation

So you run a computational workflow to ensure reproducibility and then type up the results?

Markdown and code

Computational reproducibility of research findings

  • For analyses you want to combine content and executable code into a finished presentation or document.
  • Numbers and figures in the text are computed in the document context.

Learning objectives

  • Getting started with Markdown document and code blocks
  • Taking a look at Quarto using code in R.
  • See how markdown-driven documents help to make material easier to share and reuse.
  • Include a bibliography in a manuscript

About Quarto

  • Quarto is produced by Posit (previously RStudio)
  • Supports several languages such as Python and R
  • Different execution engines such as Jupyter and knitr
  • Uses pandoc for conversion of Markdown to final products

Why using it for data analysis

  • Quarto is a light-weight tool with little installation requirements

  • Good separation of content and rendering

  • Output formats for manuscripts and presentations

  • You present code that needs to run!

(2:6)**3
[1]   8  27  64 125 216

Take help!

Markdown

Markup and Markdown

Markup languages

  • A coding system used to structure text
  • XML and HTML are prominent examples
  • Uses markup tags e.g. <h1></h1> in HTML

HTML example

<!DOCTYPE html>
<html>
<body>

<h1>This is a heading</h1>

<p>This is some text in a paragraph.</p>

</body>
</html>

Markdown is a lightweight markup language

  • Easy to read and write as it uses simple tags (e.g. #)

Markdown

# This is a heading

This is some text in a paragraph.

Common text formatting tags

Headers

  • Levels are defined using #, ##, ### …

Text style

  • bold (**This will be bold**)
  • italic (*This will be italic*)
  • http://example.com is auto-linked
  • [description](http://example.com)
  • ![](path/to/image.jpg)

Verbatim code

  • code (`coding stuff`)
  • triple backticks are delimiting code blocks:

```
This is *verbatim* code
# Even headers are not interpreted
```

rendered as:

This is *verbatim* code
# Even headers are not interpreted

Quarto

Output formats

  • HTML is the easiest, best supported and most useful display format
    • Allows for the use of CSS in styling
    • revealjs allows to create presentations
  • LaTeX generates , which might be preferred in some application
    • HTML output can be printed and thereby converted to PDF
    • Suggested way to generate “hard” copies of material
  • Word (.docx) and Powerpoint (pptx) output exists
    • Limitations due to the internal structure of Powerpoint

Code chunks

Basic Markup

  • Delimited by triple backticks (```)
  • The engine evaluating the code in curly braces
  • Can be R but also python, bash, …
  • ```{r} is the minimum to define a starting R chunk

Example

```{r}
# code to execute
```

Insert

Insert with Ctrl + Alt + I or use the GUI.

Chunk options

Set options to display or hide code or the results.

Important chunk options

Option Description
message: false Messages not shown (e.g. from package loading)
echo: false Code not shown
include: false No output or code
eval: false Code will not be executed

Example

```{r}
#| eval: false
5 + 5 
```

Enhanced text

Inline code

The swiss set has  `r nrow(swiss)`  rows.

is rendered as:

The swiss set has 47 rows.


Inline foot notes1.

Inline foot notes^[This is the foot note].

Equations in LaTeX

$$
\phi = \frac{1+\sqrt{5}}{2}
$$

is rendered as: \[ \phi = \frac{1+\sqrt{5}}{2} \]

Inline equation

This appears in $\phi = (1+\sqrt{5})/2$ text.

This appears in \(\phi = (1+\sqrt{5})/2\) text.

Include graphics

```{r}
#| output-location: column
library(tidyverse)


ggplot(swiss) +
  geom_point(aes(Agriculture, Education))
```

Bibliography

BibTex

The most common open format for references.

BibTeX example

@article{gerard2018,
    author = {Gérard, Deborah and Schmidt, Florian and Ginolhac, Aurélien and Schmitz, Martine and Halder, Rashi and Ebert, Peter and Schulz, Marcel H and Sauter, Thomas and Sinkkonen, Lasse},
    title = "{Temporal enhancer profiling of parallel lineages identifies AHR and GLIS1 as regulators of mesenchymal multipotency}",
    journal = {Nucleic Acids Research},
    volume = {47},
    number = {3},
    pages = {1141-1163},
    year = {2018},
    month = {12},
    issn = {0305-1048},
    doi = {10.1093/nar/gky1240},
    url = {https://doi.org/10.1093/nar/gky1240},
    eprint = {https://academic.oup.com/nar/article-pdf/47/3/1141/27897368/gky1240.pdf},
}

How to include BibTeX in Quarto

  1. Create a file to hold your reference
  2. Include the file in the yaml header as bibliography: mybib.bib
  3. Include @gerard2018 in the body of the manuscript.

This will generate a reference in the text and include a reference section at the end of your document.

Advanced bibliography management

  • Modify the style of the citation using citation style language (.csl)
  • Use your preferred reference manager (Zotero, Endnote) to create the BibTeX file
  • Convert DOI to BibTex using doi2bib
  • Copy citations from Google Scholar, PubMed and most publishers

Example

---
title: "Our research"
format: html
bibliography: mybib.bib
csl: nature.csl
---
ChiP-seq peaks were discovered[@gerad2018].

Demo

Acknowledgements

Aurélien Ginolhac (Uni Luxembourg)

More in the official Quarto Presentation demo and available code

Thank you for your attention!

Thank you for your attention!