Markdown and code

Quarto

Roland Krause

Rworkshop

Monday, 10 February 2025

Content

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!

Quarto’s documentation is very good!

Combining Markdown and code

Quarto is a tool expanding .Rmd (RMarkdown documents)

Credit: Alison Horst

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

Structure

---
title: "Welcome to Quarto"
author: Horst Krause
format: html
---

# Markdown header

Important text. And more text.

```{r}
#| label: "an image"
ggplot(swiss) +
  aes(x = Agriculture, y = Education) +
  geom_point()
```

Swiss data set has `r nrow(swiss)` lines.
---
YAML header


---

Markdown elements




Code chunks in R (or Python)






Markdown elements with inline R code

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))
```

Figures

![A picture of Jenny Bryan](/img/gap_jbryan.jpg){fig-align="left" width=400}

A picture of Jenny Bryan

See documentation

Tables

Raw tables

Key | Description
---:|------------
One | rownames
Rows| `r nrow(swiss)`

produces

Key Description
swiss Data set of provinces
Has rownames
Rows 47

Tables from data

swiss
             Fertility Agriculture Examination Education Catholic
Courtelary        80.2        17.0          15        12     9.96
Delemont          83.1        45.1           6         9    84.84
Franches-Mnt      92.5        39.7           5         5    93.40
Moutier           85.8        36.5          12         7    33.77
Neuveville        76.9        43.5          17        15     5.16
Porrentruy        76.1        35.3           9         7    90.57
Broye             83.8        70.2          16         7    92.85
Glane             92.4        67.8          14         8    97.16
Gruyere           82.4        53.3          12         7    97.67
Sarine            82.9        45.2          16        13    91.38
Veveyse           87.1        64.5          14         6    98.61
Aigle             64.1        62.0          21        12     8.52
Aubonne           66.9        67.5          14         7     2.27
Avenches          68.9        60.7          19        12     4.43
Cossonay          61.7        69.3          22         5     2.82
Echallens         68.3        72.6          18         2    24.20
Grandson          71.7        34.0          17         8     3.30
Lausanne          55.7        19.4          26        28    12.11
La Vallee         54.3        15.2          31        20     2.15
Lavaux            65.1        73.0          19         9     2.84
Morges            65.5        59.8          22        10     5.23
Moudon            65.0        55.1          14         3     4.52
Nyone             56.6        50.9          22        12    15.14
Orbe              57.4        54.1          20         6     4.20
Oron              72.5        71.2          12         1     2.40
Payerne           74.2        58.1          14         8     5.23
Paysd'enhaut      72.0        63.5           6         3     2.56
Rolle             60.5        60.8          16        10     7.72
Vevey             58.3        26.8          25        19    18.46
Yverdon           65.4        49.5          15         8     6.10
Conthey           75.5        85.9           3         2    99.71
Entremont         69.3        84.9           7         6    99.68
Herens            77.3        89.7           5         2   100.00
Martigwy          70.5        78.2          12         6    98.96
Monthey           79.4        64.9           7         3    98.22
St Maurice        65.0        75.9           9         9    99.06
Sierre            92.2        84.6           3         3    99.46
Sion              79.3        63.1          13        13    96.83
Boudry            70.4        38.4          26        12     5.62
La Chauxdfnd      65.7         7.7          29        11    13.79
Le Locle          72.7        16.7          22        13    11.22
Neuchatel         64.4        17.6          35        32    16.92
Val de Ruz        77.6        37.6          15         7     4.97
ValdeTravers      67.6        18.7          25         7     8.65
V. De Geneve      35.0         1.2          37        53    42.34
Rive Droite       44.7        46.6          16        29    50.43
Rive Gauche       42.8        27.7          22        29    58.33
             Infant.Mortality
Courtelary               22.2
Delemont                 22.2
Franches-Mnt             20.2
Moutier                  20.3
Neuveville               20.6
Porrentruy               26.6
Broye                    23.6
Glane                    24.9
Gruyere                  21.0
Sarine                   24.4
Veveyse                  24.5
Aigle                    16.5
Aubonne                  19.1
Avenches                 22.7
Cossonay                 18.7
Echallens                21.2
Grandson                 20.0
Lausanne                 20.2
La Vallee                10.8
Lavaux                   20.0
Morges                   18.0
Moudon                   22.4
Nyone                    16.7
Orbe                     15.3
Oron                     21.0
Payerne                  23.8
Paysd'enhaut             18.0
Rolle                    16.3
Vevey                    20.9
Yverdon                  22.5
Conthey                  15.1
Entremont                19.8
Herens                   18.3
Martigwy                 19.4
Monthey                  20.2
St Maurice               17.8
Sierre                   16.3
Sion                     18.1
Boudry                   20.3
La Chauxdfnd             20.5
Le Locle                 18.9
Neuchatel                23.0
Val de Ruz               20.0
ValdeTravers             19.5
V. De Geneve             18.0
Rive Droite              18.2
Rive Gauche              19.3

Not ready for your publication!

gt table package

library(gt)
as_tibble(swiss, rownames = "Province") |> 
slice_head(n =10) |> 
gt()
Province Fertility Agriculture Examination Education Catholic Infant.Mortality
Courtelary 80.2 17.0 15 12 9.96 22.2
Delemont 83.1 45.1 6 9 84.84 22.2
Franches-Mnt 92.5 39.7 5 5 93.40 20.2
Moutier 85.8 36.5 12 7 33.77 20.3
Neuveville 76.9 43.5 17 15 5.16 20.6
Porrentruy 76.1 35.3 9 7 90.57 26.6
Broye 83.8 70.2 16 7 92.85 23.6
Glane 92.4 67.8 14 8 97.16 24.9
Gruyere 82.4 53.3 12 7 97.67 21.0
Sarine 82.9 45.2 16 13 91.38 24.4 
as_tibble(swiss, rownames = "Province") |>
slice_head(n = 10) |>
gt() |> 
tab_options(table.font.size = 16) |>
tab_style(list(style = cell_text(size = 20, 
                                 weight = "bold", 
                                 color = "white"), 
               cell_fill(color = "#00A4E1")),
          locations = cells_column_labels(columns = everything()))
Province Fertility Agriculture Examination Education Catholic Infant.Mortality
Courtelary 80.2 17.0 15 12 9.96 22.2
Delemont 83.1 45.1 6 9 84.84 22.2
Franches-Mnt 92.5 39.7 5 5 93.40 20.2
Moutier 85.8 36.5 12 7 33.77 20.3
Neuveville 76.9 43.5 17 15 5.16 20.6
Porrentruy 76.1 35.3 9 7 90.57 26.6
Broye 83.8 70.2 16 7 92.85 23.6
Glane 92.4 67.8 14 8 97.16 24.9
Gruyere 82.4 53.3 12 7 97.67 21.0
Sarine 82.9 45.2 16 13 91.38 24.4

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].

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 PDF , which might be preferred in some application

  • Suggested way to generate “hard” copies of material

HTML output can be printed and thereby converted to PDF

Useful when needed

  • Word (.docx) and Powerpoint (.pptx) output exists

    • Limitations due to the internal structure of these document types and Pandoc
    • Word output works well with collaborators that don’t use git.

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!