Quarto

.title[
# Quarto
]
.author[
### Visualizing and communicating data with R <a href='https://therbootcamp.github.io'> The R Bootcamp @ Bern </a> <a href='https://therbootcamp.github.io/DataViz_2024Bern/'> </a>  <a href='https://therbootcamp.github.io'> </a>  <a href='therbootcamp@gmail.com'> </a>  <a href='https://www.linkedin.com/company/27090302'> </a>
]
.date[
### June 2024
]

---

<div class="my-footer">
 
 
 <img src="https://raw.githubusercontent.com/therbootcamp/therbootcamp.github.io/master/_sessions/_image/by-sa.png" height=14 style="vertical-align: middle"/>
 
 <a href="https://therbootcamp.github.io/">
 
 
 https://therbootcamp.github.io
 
 
 </a>
 <a href="https://therbootcamp.github.io/">
 
 The R Bootcamp | June 2024
 
 </a>
 
 </div>

---

# What is Quarto?

<ul>
 <li class="m1">Open-source scientific and technical <high>publishing system</high>. 
 <li class="m2">Simple <high>syntax for formatting</high> documents.</li> 
 <ul>
 <li>create <high>dynamic, reproducible content</high> with R, Python, Julia ...</li> 
 <li>publish to <high>different output formats</high> (articles, presentations, dashboards, websites, books)</li> 
 <li>write using <high>simple (R)Markdown</high></li> 
 </ul>
</ul>

]

<img src="image/quarto.png" width=400px> 
 from <a href="https://quarto.org">quarto.org</a>

]

---

# What is Markdown?

<ul>
 <li class="m1">Developed by John Gruber and Aaron Swartz in 2004. 
 "<high>easy-to-read</high> and <high>easy-to-write</high> plain text format, [...] convert it to structurally valid XHTML (or HTML)"</li> 
 <li class="m2">Simple <high>syntax for formatting</high> documents.</li> 
 <ul>
 <li>highlight text with bold and italic</li> 
 <li>lists</li> 
 <li>headers</li> 
 <li>hyperlinks</li>
 <li>images</li>
 </ul>
</ul>

]

<img src="image/markdown.png" width=400px> 
 from <a href="https://de.wikipedia.org/wiki/Markdown">wikipedia.org</a>

]

---

# What is R Markdown?

<ul>
 <li class="m1">Uses Markdown for <high>formatting dynamic reports</high> that include ...</li> 
 <ul>
 <li><high>R code chunks</high></li>
 <li><high>R inline Code</high></li> 
 <li><high>Visualizations</high></li>
 <li>Statistical outputs</li>
 <li>Tables</li>
 <li>etc.</li>
 </ul>
</ul>

]

<img src="image/hex.png" height=300> 
 from <a href="https://rmarkdown.rstudio.com/docs/">rmarkdown.rstudio.com</a>

]

---

# R Markdown elements

<ul>
 <li class="m1">RMarkdown scripts consist of several <high>elements</high>.</li>
</ul>

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Element
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>YAML</mono>
 </td>
 <td bgcolor="white">
 YAML Ain't Markup Language 
 <high>general document settings</high>
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>Initial chunk</mono>
 </td>
 <td bgcolor="white">
 load <high>packages</high> 
 load <high>data</high>
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>Markdown</mono>
 </td>
 <td bgcolor="white">
 <high>header</high> 
 <high>text</high> highlighting
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>Code chunk</mono>
 </td>
 <td bgcolor="white">
 R <high>Code</high> 
 R <high>Outputs<high>
 </td> 
</tr>
</table>

]

]

---

# Pipeline

<ul>
 <li class="m1">Quarto (.qmd) files are translated (rendered) into different <high>document types</high>.</li> 
 <ul>
 <li>HTML</li> 
 <li>Word</li>
 <li>PowerPoint</li>
 <li>PDF</li>
 </ul> 
 <li class="m2">To this end, <high>several translation steps</high> are necessary.</li> 
</ul>

]

.pull-right5[
 

 <img src="image/pipeline.png" width=800px> 
 from <a href="https://quarto.org">quarto.org</a>

]

---

# Rendering your file

<high>Rendering</high> (translating) your .qmd file into the <high>final document type</high>: 
<ul>
 <li class="m1">Using the <high>Render-button</high> in RStudio.</li>

<li class="m2">Selecting <high>'Render on save'</high> - rendering will automatically be executed once you save your file.</li>

<li class="m3">In the <high>Terminal</high>.</li>
 
 <li class="m4">On the <high>R console</high>.</li>
</ul>

]

]

---

# HTML Pipeline

<ul>
 <li class="m1">HTML is a <high>universal framework</high> for documents, presentations, websites and dashboards</li>
 <li class="m2">HTML <high>export to PDF</high> is often straightforward.</li> 
</ul>

]

]

---

# HTML

<ul>
 <li class="m1">HyperText Markup Language.</li>
 <li class="m2">The format of the <high>World Wide Web</high>s.</li>
 <li class="m3">Affords flexible styling through <high>CSS</high> (Cascading Style Sheets).</li>
</ul>

]

]

---

# Displaying HTML

<ul>
 <li class="m1">HTML gets <high>interpreted</high> in RStudio (or browsers) so that a well-formatted document emerges.</li>
 <li class="m2"><high>Rstudio</high> also shows rendered documents (rather than the raw html). </li> 
</ul>

]

]

---

# Headers

<ul>
 <li class="m1">Headers on different <high>levels</high> can be set using <mono>#</mono>.</li>
</ul>

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:20px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Markdown
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono># text</mono>
 </td>
 <td bgcolor="white">
 level 1
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>## text</mono>
 </td>
 <td bgcolor="white">
 level 2
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>...</mono>
 </td>
 <td bgcolor="white">
 ...
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>##### txt</mono>
 </td>
 <td bgcolor="white">
 level 5
 </td> 
</tr>
</table>

]

]

---

# Headers

<ul>
 <li class="m1">Headers on different <high>levels</high> can be set using <mono>#</mono>.</li>
</ul>

]

]

---

# Highlighting

<ul>
 <li class="m1">Various operators enable <high>text- and code</high> highlighting.</li>
</ul>

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:20px" width=100%>
 <col width="50%">
 <col width="50%">
<tr>
 <td bgcolor="white">
 Markdown
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 &ast;<mono>text</mono>&ast;
 </td>
 <td bgcolor="white">
 italic
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 &ast;&ast;<mono>text</mono>&ast;&ast;
 </td>
 <td bgcolor="white">
 bold
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 &ast;&ast;&ast;<mono>text</mono>&ast;&ast;&ast;
 </td>
 <td bgcolor="white">
 italic and bold 
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 &grave;<mono>text</mono>&grave;
 </td>
 <td bgcolor="white">
 code
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 &grave;<mono>r "text"</mono>&grave;
 </td>
 <td bgcolor="white">
 inline code
 </td> 
</tr>
</table>

]

]

---

# Highlighting

<ul>
 <li class="m1">Various operators enable <high>text- and code</high> highlighting.</li>
</ul>

]

]

---

# Highlighting

<ul>
 <li class="m1">Various operators enable <high>text- and code</high> highlighting.</li>
</ul>

]

]

---

# Inline code

<ul>
 <li class="m1"><high>Numbers or labels</high> in text can be parameterized using inline code.</li>
 <li class="m2">Inline code can include <high>any</high> type/length of R code.</li>
</ul>

]

]

---

# Chunks

<ul>
 <li class="m1">A <high>code chunk</high> can contain any R code.</li>
 <li class="m2">The behavior of code chunks can be controlled using <high>chunk arguments</high>.</li>
 <li class="m3">Add a new chunk with: <mono>Cmd+Shift+I (Mac) Strg+Shift+I (Windows)</mono>.</li>
 
</ul>

]

]

---

# Chunks

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:60px" width=100%>
 <col width="60%">
 <col width="40%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>echo=T/F</mono>
 </td>
 <td bgcolor="white">
 Show/hide <high>code</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>eval=T/F</mono>
 </td>
 <td bgcolor="white">
 Run/not-run <high>code</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>include=T/F</mono>
 </td>
 <td bgcolor="white">
 Include/exclude all <high>output</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>message=T/F</mono>
 </td>
 <td bgcolor="white">
 Include/exclude <highm>messages</highm> in output.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>warning=T/F</mono>
 </td>
 <td bgcolor="white">
 Include/exclude <highm>warnings</highm>.
 </td> 
</tr>
</table>

<mono>T/F = TRUE/FALSE</mono>

]

]

---

# Chunks

<mono>T/F = TRUE/FALSE</mono>

]

]

---

# Chunks

<mono>T/F = TRUE/FALSE</mono>

]

]

---

# Initial chunk

<ul>
 <li class="m1">Load packages and data in the <high>initial chunk</high>.</li>
 <li class="m2">Additional <high>global behavior</high> is set in the YAML header.</li>
</ul>

]

]

---

# YAML

<ul>
 <li class="m1">YAML A'int Markup Language.</li>
 <li class="m2">Enables the definition of general <high>properties of a document</high> and code inclusions.</li>
</ul>
<table style="cellspacing:0; cellpadding:0; border:none; padding-top:px" width=100%>
 <col width="60%">
 <col width="40%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>echo=T/F</mono>
 </td>
 <td bgcolor="white">
 Show/hide <high>code</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>eval=T/F</mono>
 </td>
 <td bgcolor="white">
 Run/not-run <high>code</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>include=T/F</mono>
 </td>
 <td bgcolor="white">
 Include/exclude all <high>output</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>message=T/F</mono>
 </td>
 <td bgcolor="white">
 Include/exclude <high>messages</high>.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>warning=T/F</mono>
 </td>
 <td bgcolor="white">
 Include/exclude <highm>warnings</highm>.
 </td> 
</tr>
</table>

<mono>T/F = TRUE/FALSE</mono>

]

]

---

# YAML

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Argument 
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>toc</mono> 
 </td>
 <td bgcolor="white">
 Table Of Contents.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>toc_depth</mono> 
 </td>
 <td bgcolor="white">
 <high>Depth</high> of the Table Of Contents.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>theme</mono> 
 </td>
 <td bgcolor="white">
 <high>Properties</high> of the layout.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>includes</mono> 
 </td>
 <td bgcolor="white">
 <high>Code inclusions</high> before (<mono>before_body</mono>), after (<mono>after_body</mono>) <mono>body</mono>, or <mono>in_header</mono>.
 </td> 
</tr>
</table>

]

````
</div>
<img src="image/yaml_2q.png" width=400px>

]

---

# YAML

]

.pull-right5[
 
<div style="width:400px">
````markdown
---
format:
 html:
 toc: true
 toc-location: body
---

````
</div>
<img src="image/yaml_3q.png" width=400px>

]

---

# YAML

]

.pull-right5[
 
<div style="width:400px">
````markdown
---
format:
 html:
 toc: true
 toc-location: body
 toc-depth: 4
---

````
</div>
<img src="image/yaml_4q.png" width=400px>

]

---

# YAML

]

.pull-right5[
 
<div style="width:400px">
````markdown
---
format:
 html:
 toc: true
 toc-location: body
 toc-depth: 4
 theme: lumen
---

````
</div>
<img src="image/yaml_5q.png" width=400px>

]

---

# Relative path

<ul>
 <li class="m1">When rendered, Quarto documents do not use the current <high>working directory</high>.</li> 
 <li class="m2">Paths need to be defined <high>relative to the position of the .qmd file</high>.</li>
</ul>

```R
# load data
read_csv("../1_data/data.csv")

```

]

]

---

# Scale graphs

<ul>
 <li class="m1">The general <high>appearance</high> of graphs can be modified in the <mono>chunk</mono>-settings or globally in the <mono>YAML header</mono>.</li> 
 <li class="m2">The arguments (normally) start with <highm>fig-*</highm>.</li> 
</ul>

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-width</mono>, <mono>fig-height</mono>
 </td>
 <td bgcolor="white">
 <high>Width</high> and <high>height</high> in inches.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-asp</mono>
 </td>
 <td bgcolor="white">
 <high>Aspect ratio</high>: Height relative to width. 
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>dpi</mono> 
 </td>
 <td bgcolor="white">
 <high>Resolution</high> of the graph (dots per inch).
 </td> 
</tr>
</table>
]

]

---

# Scale graphs

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-width</mono>, <mono>fig-height</mono>
 </td>
 <td bgcolor="white">
 <high>Width</high> and <high>height</high> in inches.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-asp</mono>
 </td>
 <td bgcolor="white">
 <high>Aspect ratio</high>: Height relative to width. 
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>dpi</mono> 
 </td>
 <td bgcolor="white">
 <high>Resolution</high> of the graph (dots per inch).
 </td> 
</tr>
</table>
]

]

---

# Scale graphs

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-width</mono>, <mono>fig-height</mono>
 </td>
 <td bgcolor="white">
 <high>Width</high> and <high>height</high> in inches.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-asp</mono>
 </td>
 <td bgcolor="white">
 <high>Aspect ratio</high>: Height relative to width. 
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>dpi</mono> 
 </td>
 <td bgcolor="white">
 <high>Resolution</high> of the graph (dots per inch).
 </td> 
</tr>
</table>
]

]

---

# Scale graphs

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-width</mono>, <mono>fig-height</mono>
 </td>
 <td bgcolor="white">
 <high>Width</high> and <high>height</high> in inches.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-asp</mono>
 </td>
 <td bgcolor="white">
 <high>Aspect ratio</high>: Height relative to width. 
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>dpi</mono> 
 </td>
 <td bgcolor="white">
 <high>Resolution</high> of the graph (dots per inch).
 </td> 
</tr>
</table>
]

]

---

# Scale graphs

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Argument
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-width</mono>, <mono>fig-height</mono>
 </td>
 <td bgcolor="white">
 <high>Width</high> and <high>height</high> in inches.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>fig-asp</mono>
 </td>
 <td bgcolor="white">
 <high>Aspect ratio</high>: Height relative to width. 
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>dpi</mono> 
 </td>
 <td bgcolor="white">
 <high>Resolution</high> of the graph (dots per inch).
 </td> 
</tr>
</table>
]

]

---

# Captions

<ul>
 <li class="m1">Add captions with <highm>fig-cap</highm>.</li> 
 <li class="m2">Define captions <high>within each chunk</high> starting with <mono>#|</mono>.</li> 
</ul>

]

]

---

# Links, footnotes

<ul>
 <li class="m1">There is specific <high>markdown syntax</high> to include links and footnotes.</li>
</ul>

<table style="cellspacing:0; cellpadding:0; border:none; padding-top:10px" width=100%>
 <col width="40%">
 <col width="60%">
<tr>
 <td bgcolor="white">
 Markdown
 </td>
 <td bgcolor="white">
 Description
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>&lsqb;Name&rsqb;(URL)</mono>
 </td>
 <td bgcolor="white">
 <high>Link</high>. Name is displayed in the text, the URL is not displayed.
 </td> 
</tr>
<tr>
 <td bgcolor="white">
 <mono>^&lsqb;Text&rsqb;</mono>
 </td>
 <td bgcolor="white">
 <high>Footnotes</high> are included after the end of the text. 
 </td> 
</tr>
</table>

]

]

---

<h1><a href="Quarto_report.html">Practical</a></h1>